SPI接口及驱动

1. 简介

• SPI接口是Motorola 首先提出的全双工三线同步串行外围接口，采用主从模式（Master Slave）架构。支持多slave模式应用，一般仅支持单Master。时钟由Master控制，在时钟移位脉冲下，数据按位传输，高位在前，低位在后（MSB first）。SPI接口有2根单向数据线，为全双工通信，目前应用中的数据速率可达几Mbps的水平。
• SPI接口优点：
  • 支持全双工操作
  • 操作简单
  • 数据传输速率较高（相对的）
• SPI接口缺点：
  • 多个spi设备需要占用主机较多的管脚（每个从机都需要一根片选线）
  • 只支持单个主机
  • 没有指定的流控制，没有应答机制确认是否接收到数据

2. 接口

2.1 总线结构

2.2 硬件接口

• SPI接口共有4根信号线，分别是：设备选择线、时钟线、串行输出数据线、串行输入数据线。
  • MOSI：主器件数据输出，从器件数据输入
  • MISO：主器件数据输入，从器件数据输出
  • SCLK： 时钟信号，由主器件产生
  • $\overline{SS}$： 从器件使能信号，由主器件控制

2.3 SPI工作模式

• SPI有四种工作模式,具体由CPOL(Clock Polarity 时钟极性)，CPHA(Clock Phase时钟相位)决定
  • 当CPOL为0时，空闲的时候SCLK电平是低电平
  • 当CPOL为1时，空闲的时候SCLK电平是高电平
  • 当CPHA为0时，采集数据发生在时钟周期的前边缘（第一个边缘，可能是上升缘也可能是下降缘，由CPOL决定），这同时意味着输出数据发生在后边缘
  • 当CPHA为1时，采集数据发生在时钟周期的后边缘（第二个边缘，可能是上升缘也可能是下降缘，由CPOL决定），这同时意味着输出数据发生在前边缘

3. Linux驱动代码

• Linux SPI驱动框架主要分为：

  • 核心层
  • 控制器驱动层
  • 设备驱动层
    

• 最下层是硬件空间，SPI总线控制器，总线控制器负责硬件上的数据交互。内核空间中，需要有对应的控制器驱动，对硬件进行操作。

• 核心层的作用：向控制器驱动层提供注册SPI控制器驱动的接口，并提供一些需要控制器驱动实现的回调函数。核心层向上，对SPI设备驱动，提供标准的SPI收发API，以及设备注册函数。

• 当有SPI设备驱动发起一次传输时，设备驱动会调用SPI核心层的收发函数(spi_sync/spi_async)，核心层的收发函数，会回调控制器驱动层实现的硬件相关的发送回调函数。从而实现SPI数据的收发。

• 我们编写SPI接口的设备驱动程序的时候，最需要关心的就是SPI控制器的部分和SPI设备采用的是那种模式，确定模式后，我们得将SPI控制器配置成一样的模式才能正常工作

• SPI驱动代码：位于 kernel/drivers/spi目录下 (这个目录和一些层次比较明显的驱动目录布局不同，全放在这个文件夹下，因此还是只好通过看Kconfig 和 Makefile来找找思路)

• 相关数据结构：

  • spi_master：SPI控制器
  • spi_driver：SPI设备驱动
  • spi_device：SPI设备
  • spi_message：SPI传输数据结构体
  • spi_transfer：该结构体是spi_message下的子单元

• spi_driver和spi_device的关系

  • spi_driver对应一套驱动方法，包含probe,remove等方法。spi_device对应真实的物理设备，每个spi设备都需要一个spi_device来描述。spi_driver与spi_device是一对多的关系，一个spi_driver上可以支持多个同类型的spi_device

• spi_master和spi_device

  • spi_master 与 spi_device 的关系和硬件上控制器与设备的关系一致，即spi_device依附于spi_master

• spi_message和spi_transfer

  • spi传输数据是以 spi_message 为单位的，我们需要传输的内容在 spi_transfer 中。spi_transfer是spi_message的子单元
  • 将本次需要传输的 spi_transfer 以 spi_transfer->transfer_list 为链表项，连接成一个transfer_list链表，挂接在本次传输的spi_message spi_message->transfers链表下
  • 将所有等待传输的 spi_message 以 spi_message->queue 为链表项，连接成个链表挂接在queue下
    

• 相关API函数

//分配一个spi_master
struct spi_master *spi_alloc_master(struct device *dev, unsigned size)

//注册和注销spi_master
int spi_register_master(struct spi_master *master)
void spi_unregister_master(struct spi_master *master)

//注册和注销spi_driver
int spi_register_driver(struct spi_driver *sdrv)
void spi_unregister_driver(struct spi_driver *sdrv)

//初始化spi_message
void spi_message_init(struct spi_message *m)
//向spi_message添加transfers
void spi_message_add_tail(struct spi_transfer *t, struct spi_message *m)
//异步发送spi_message
int spi_async(struct spi_device *spi, struct spi_message *message)
//同步发送spi_message
int spi_sync(struct spi_device *spi, struct spi_message *message)

//spi同步写(封装了上面的函数)
int spi_write(struct spi_device *spi, const void *buf, size_t len)
//spi同步读(封装了上面的函数)
int spi_read(struct spi_device *spi, void *buf, size_t len)
//同步写并读取(封装了上面的函数)
int spi_write_then_read(struct spi_device *spi,
    const void *txbuf, unsigned n_tx,
    void *rxbuf, unsigned n_rx)

3.1 SPI核心层

• 实现代码：kernel/drivers/spi/spi.c (头文件位于: kernel/include/linux/spi/spi.h)
• 功能：(实现函数：spi_init)
  • 对SPI子系统进行初始化工作
  • 注册SPI总线
  • 注册一个spi master（控制器）类
  • 提供SPI设备驱动对SPI总线进行操作的API

struct bus_type spi_bus_type = {
	.name		= "spi",
	.dev_groups	= spi_dev_groups,
	.match		= spi_match_device,
	.uevent		= spi_uevent,
};

static struct class spi_master_class = {
	.name		= "spi_master",
	.owner		= THIS_MODULE,
	.dev_release	= spi_master_release,
	.dev_groups	= spi_master_groups,
};

• spi_bus_type为spi总线类型，通过bus_register()函数将SPI 总线注册进总线，成功注册后，在/sys/bus 下即可找到spi 文件目录
• spi_master_class为spi控制器设备类，通过调用class_register()函数注册设备类，成功注册后，在/sys/class目录下即可找到spi_master文件目录
• spi子系统初始化函数spi_init，仅仅是注册了spi bus，以及spi_master class。

static int __init spi_init(void)
{
	int	status;

	buf = kmalloc(SPI_BUFSIZ, GFP_KERNEL);
	if (!buf) {
		status = -ENOMEM;
		goto err0;
	}
	status = bus_register(&spi_bus_type);			/*注册spi bus*/
	if (status < 0)
		goto err1;
	status = class_register(&spi_master_class);		/* 注册spi_master类 */
	if (status < 0)
		goto err2;
	if (IS_ENABLED(CONFIG_OF_DYNAMIC))
		WARN_ON(of_reconfig_notifier_register(&spi_of_notifier));
	if (IS_ENABLED(CONFIG_ACPI))
		WARN_ON(acpi_reconfig_notifier_register(&spi_acpi_notifier));
	return 0;
err2:
	bus_unregister(&spi_bus_type);
err1:
	kfree(buf);
	buf = NULL;
err0:
	return status;
}

3.2 SPI控制器驱动

• SPI控制器驱动：即SPI硬件控制器对应的驱动，核心部分需要实现硬件SPI数据收发功能。这样SPI设备驱动，才能通过SPI读写数据
• SPI是一种平台特定的资源，所以它是以platform device的方式注册进内核的，因此它的struct platform_device结构是已经静态定义好了的，现在只待它的struct platform_driver注册，然后和platform_device匹配。
• 描述SPI控制器的设备树节点：

		spi0: spi@0xA5004000 {
			compatible = "my,my-spi";   /* 描述,和驱动匹配 */
			reg = <0 0xA5004000 0 0x1000>; /* 控制器IO地址 */
			clocks = <&spi0_mclk>;  /* 控制器时钟 */
			clock-names = "spi_mclk";  /* 时钟名 */
			interrupt-parent = <&gic>;
			interrupts = <0 33 4>;   /* 控制器中断 */
			resets = <&rst 0x50 4>;  /* 复位寄存器 */
			reset-names = "spi0";     
			pinctrl-names = "default";
			pinctrl-0 = <&spi0_func>;   /* 引脚复用功能配置 */
			status = "disabled";     /* 暂时disable */
			#address-cells = <1>;
			#size-cells = <0>;
		};

• 实现一个platform_driver

static struct platform_driver my_spi_driver = {
    .probe = my_spi_probe,
    .remove = my_spi_remove,
    .driver = {
        .name = MY_SPI_NAME,
        .of_match_table = my_spi_of_match,
		.pm = &my_spi_dev_pm_ops,
    },
};

3.2.1 probe函数功能

• 申请struct spi_master内存以及私有数据内存（struct my_spi）
• 将struct spi_master设置为platform_device的private_data
• 从设备树获取IO地址，对应设备树reg节点
• 将IO内存映射为虚拟地址
• 从设备树获取中断，对应设备树interrupts节点
• 申请中断，设置中断服务函数
• 设置核心层回调的片选使能函数，设置spi_master的transfer_one函数，如果控制器驱动不实现transfer和transfer_one_message，内核会自动填充默认的，最终控制器驱动只需要实现transfer_one。
• 根据时钟名，从设备树获取时钟
• 根据设备树的reset节点，操作寄存器spi控制器对应的BIT进行复位
• 调用devm_spi_register_master，把spi_master->device注册到设备模型中。核心层篇中以及详细介绍了devm_spi_register_master函数，

3.2.2 数据收发

• 数据收发部分主要有两个函数
• 1）控制收发的函数，即spi_master的spi_transfer_one函数
  - 以看到全志这里代码的逻辑，一个是初始化完成量。然后进行一系列硬件操作后，睡眠等待完成信号，同时设置超时时间，超时了没有得到信号量，证明硬件出问题了，不应该一直等待，应该返回错误。
  - 这个完成信号由中断来发送，硬件上会有发送完成中断。
• 2）配合发送的中断服务函数
  • 读取中断状态寄存器，判断发送完成的BIT是否置位，如果置位，则表示硬件已经发送完数据了，那么发送完成信号量，给正在睡眠等待的spi_transfer_one函数。spi_transfer_one函数接收到信号量后被唤醒，知道硬件以及发送完数据了，返回0（表示发送成功）

3.3 SPI设备驱动

• 实现一个spi_driver, 并注册到SPI核心层
• 直接调用spi核心层提供的函数注册，也就是说它不需要关心是哪个控制器来实现最终的spi数据传输。从这里也可以看出核心层的作用，分隔了控制器和设备驱动的关联性，主要两边的驱动都容易实现
• 以内核中spidev设备驱动为例，对基于设备树的SPI设备驱动进行说明
• spidev驱动代码位于kernel/drivers/spi/spidev.c
• 设备树部分

dac0: dh2228@2 {
	compatible = "rohm,dh2228fv";
	reg = <2>;
	spi-max-frequency = <100000>;
};

• 设备树部分很简单，只是写了compatible描述，用于和驱动匹配。这里reg的意思是spi cs引脚序号。并不像其他平台设备一样是IO地址，或者像I2C一样是从机地址

3.3.1 spidev_init

static int __init spidev_init(void)
{
	int status;

	/* Claim our 256 reserved device numbers.  Then register a class
	 * that will key udev/mdev to add/remove /dev nodes.  Last, register
	 * the driver which manages those device numbers.
	 */
	BUILD_BUG_ON(N_SPI_MINORS > 256);
	status = register_chrdev(SPIDEV_MAJOR, "spidev_test", &spidev_fops);
	if (status < 0)
		return status;

	spidev_class = class_create(THIS_MODULE, "spidev");
	if (IS_ERR(spidev_class)) {
		unregister_chrdev(SPIDEV_MAJOR, spidev_spi_driver.driver.name);
		return PTR_ERR(spidev_class);
	}

	status = spi_register_driver(&spidev_spi_driver);
	if (status < 0) {
		class_destroy(spidev_class);
		unregister_chrdev(SPIDEV_MAJOR, spidev_spi_driver.driver.name);
	}
	return status;
}
module_init(spidev_init);

static void __exit spidev_exit(void)
{
	spi_unregister_driver(&spidev_spi_driver);
	class_destroy(spidev_class);
	unregister_chrdev(SPIDEV_MAJOR, spidev_spi_driver.driver.name);
}
module_exit(spidev_exit);

• 这里设置的spidev的file_operations(spidev_fops)，设备操作函数后文详细介绍。然后创建了spidev的class，创建完成后在用户空间/sys/class/下可以看到spidev目录结构。然后调用spi_register_driver注册spi从设备。

3.3.2 spi_driver

static const struct of_device_id spidev_dt_ids[] = {
	{ .compatible = "rohm,dh2228fv" },
	{ .compatible = "lineartechnology,ltc2488" },
	{ .compatible = "ge,achc" },
	{ .compatible = "semtech,sx1301" },
	{},
};
MODULE_DEVICE_TABLE(of, spidev_dt_ids);
static struct spi_driver spidev_spi_driver = {
	.driver = {
		.name =		"spidev",
		.of_match_table = of_match_ptr(spidev_dt_ids),
		.acpi_match_table = ACPI_PTR(spidev_acpi_ids),
	},
	.probe =	spidev_probe,
	.remove =	spidev_remove,

	/* NOTE:  suspend/resume methods are not necessary here.
	 * We don't do anything except pass the requests to/from
	 * the underlying controller.  The refrigerator handles
	 * most issues; the controller driver handles the rest.
	 */
};

• 描述，与设备树相对应，会调用probe函数
• probe函数，匹配时调用

3.3.3 probe

static int spidev_probe(struct spi_device *spi)
{
	struct spidev_data	*spidev;
	int			status;
	unsigned long		minor;

	/*
	 * spidev should never be referenced in DT without a specific
	 * compatible string, it is a Linux implementation thing
	 * rather than a description of the hardware.
	 */
	if (spi->dev.of_node && !of_match_device(spidev_dt_ids, &spi->dev)) {
		dev_err(&spi->dev, "buggy DT: spidev listed directly in DT\n");
		WARN_ON(spi->dev.of_node &&
			!of_match_device(spidev_dt_ids, &spi->dev));
	}

	spidev_probe_acpi(spi);

	/* Allocate driver data */
	spidev = kzalloc(sizeof(*spidev), GFP_KERNEL);
	if (!spidev)
		return -ENOMEM;

	/* Initialize the driver data */
	spidev->spi = spi;
	spin_lock_init(&spidev->spi_lock);
	mutex_init(&spidev->buf_lock);

	INIT_LIST_HEAD(&spidev->device_entry);

	/* If we can allocate a minor number, hook up this device.
	 * Reusing minors is fine so long as udev or mdev is working.
	 */
	mutex_lock(&device_list_lock);
	minor = find_first_zero_bit(minors, N_SPI_MINORS);
	if (minor < N_SPI_MINORS) {
		struct device *dev;

		spidev->devt = MKDEV(SPIDEV_MAJOR, minor);
		dev = device_create(spidev_class, &spi->dev, spidev->devt,
				    spidev, "spidev%d.%d",
				    spi->master->bus_num, spi->chip_select);
		status = PTR_ERR_OR_ZERO(dev);
	} else {
		dev_dbg(&spi->dev, "no minor number available!\n");
		status = -ENODEV;
	}
	if (status == 0) {
		set_bit(minor, minors);
		list_add(&spidev->device_entry, &device_list);
	}
	mutex_unlock(&device_list_lock);

	spidev->speed_hz = spi->max_speed_hz;

	if (status == 0)
		spi_set_drvdata(spi, spidev);
	else
		kfree(spidev);

	return status;
}

• spidev的probe函数，申请了私有结构体spidev的内存空间，初始化了spidev的一些成员，自旋锁、互斥锁等。并将spidev指针设置为struct spi_device的私有数据（private_data）
• 调用device_create创建了/dev/下的spidev节点，如spi总线0上cs1设备，则设备名为/dev/spidev0.1，其他以此类推
• 在编写spi、i2c等驱动时，所做的操作也和spidev相差无几。初始化一些自己需要的资源等。但是一般情况下，这类涉及外设的驱动，会读取一下SPI、I2C从设备的ID寄存器等，来判断硬件是否就位，spi总线能否读写数据

3.3.4 spidev_fops

static const struct file_operations spidev_fops = {
	.owner =	THIS_MODULE,
	.write =	spidev_write,
	.read =		spidev_read,
	.unlocked_ioctl = spidev_ioctl,
	.compat_ioctl = spidev_compat_ioctl,
	.open =		spidev_open,
	.release =	spidev_release,
	.llseek =	no_llseek,
};

• open和release：判断是否申请txbuff和rxbuff内存，如果没申请就申请。并维护了一个user count，用户空间每打开一次就+1，关闭一次就-1。所有都关闭后release释放申请的内存。

3.3.4.1 spidev_write

static ssize_t
spidev_write(struct file *filp, const char __user *buf,
		size_t count, loff_t *f_pos)
{
	struct spidev_data	*spidev;
	ssize_t			status = 0;
	unsigned long		missing;

	if (count > bufsiz)
		return -EMSGSIZE;
	spidev = filp->private_data;
	
	mutex_lock(&spidev->buf_lock);
	missing = copy_from_user(spidev->tx_buffer, buf, count);		(1)
	if (missing == 0)
		status = spidev_sync_write(spidev, count);					(2)
	else
		status = -EFAULT;
	mutex_unlock(&spidev->buf_lock);

	return status;
}

static inline ssize_t
spidev_sync_write(struct spidev_data *spidev, size_t len)
{
	struct spi_transfer	t = {
			.tx_buf		= spidev->tx_buffer,
			.len		= len,
			.speed_hz	= spidev->speed_hz,
		};
	struct spi_message	m;

	spi_message_init(&m);
	spi_message_add_tail(&t, &m);
	return spidev_sync(spidev, &m);									(3)
}

static ssize_t
spidev_sync(struct spidev_data *spidev, struct spi_message *message)
{
	int status;
	struct spi_device *spi;
	spin_lock_irq(&spidev->spi_lock);
	spi = spidev->spi;
	spin_unlock_irq(&spidev->spi_lock);
	if (spi == NULL)
		status = -ESHUTDOWN;
	else
		status = spi_sync(spi, message);							(4)
	if (status == 0)
		status = message->actual_length;
	return status;
}

• copy_from_user：从用户空间拷贝要发送的数据到内核空间
• 调用spidev_sync_write函数发送数据，这个函数实现代码也在上面贴出来了
• spidev_sync_write代码实现，定义spi_transfer和spi_message，然后通过spidev_sync发送
• spidev_sync中仅仅是判断了spi_device是否为空，不为空则调用spi_sync函数将spi_message发送出去
• spidev_read函数与write函数如出一辙，不同的是write先从用户空间拷贝数据，然后调用发送函数发出去。struct spi_transfer填充的是tx_buff。而read则是先调用接受函数，struct spi_transfer填充的是rx_buff，然后将接收到的rx_buff，通过copy_to_user拷贝给用户空间。

3.3.4.2 ioctl

#define SPI_IOC_MAGIC			'k'

/* Read / Write of SPI mode (SPI_MODE_0..SPI_MODE_3) (limited to 8 bits) */
#define SPI_IOC_RD_MODE			_IOR(SPI_IOC_MAGIC, 1, __u8)
#define SPI_IOC_WR_MODE			_IOW(SPI_IOC_MAGIC, 1, __u8)

/* Read / Write SPI bit justification */
#define SPI_IOC_RD_LSB_FIRST		_IOR(SPI_IOC_MAGIC, 2, __u8)
#define SPI_IOC_WR_LSB_FIRST		_IOW(SPI_IOC_MAGIC, 2, __u8)

/* Read / Write SPI device word length (1..N) */
#define SPI_IOC_RD_BITS_PER_WORD	_IOR(SPI_IOC_MAGIC, 3, __u8)
#define SPI_IOC_WR_BITS_PER_WORD	_IOW(SPI_IOC_MAGIC, 3, __u8)

/* Read / Write SPI device default max speed hz */
#define SPI_IOC_RD_MAX_SPEED_HZ		_IOR(SPI_IOC_MAGIC, 4, __u32)
#define SPI_IOC_WR_MAX_SPEED_HZ		_IOW(SPI_IOC_MAGIC, 4, __u32)

/* Read / Write of the SPI mode field */
#define SPI_IOC_RD_MODE32		_IOR(SPI_IOC_MAGIC, 5, __u32)
#define SPI_IOC_WR_MODE32		_IOW(SPI_IOC_MAGIC, 5, __u32)

3.3.5 spidev总结

• spidev是内核中用来测试spi的驱动，不是专门针对某一SPI硬件设备做的驱动，只是简单的注册字符设备，用户空间通过read、write、ioctl，直接对spi进行操作，相当于是用户空间和spi设备的桥梁
• 用户空间操作时，打开设备节点，然后通过IOCTL设置模式、速度等参数，然后就可以调用read、write进行操作了
• 根据设备树获取节点信息

spi_register_master->
	of_register_spi_devices->
		of_register_spi_device->
			of_spi_parse_dt

static int of_spi_parse_dt(struct spi_controller *ctlr, struct spi_device *spi,
			   struct device_node *nc)
{
	u32 value;
	int rc;

	/* Mode (clock phase/polarity/etc.) */
	if (of_property_read_bool(nc, "spi-cpha"))
		spi->mode |= SPI_CPHA;
	if (of_property_read_bool(nc, "spi-cpol"))
		spi->mode |= SPI_CPOL;
	if (of_property_read_bool(nc, "spi-cs-high"))
		spi->mode |= SPI_CS_HIGH;
	if (of_property_read_bool(nc, "spi-3wire"))
		spi->mode |= SPI_3WIRE;
	if (of_property_read_bool(nc, "spi-lsb-first"))
		spi->mode |= SPI_LSB_FIRST;

	/* Device DUAL/QUAD mode */
	if (!of_property_read_u32(nc, "spi-tx-bus-width", &value)) {
		switch (value) {
		case 1:
			break;
		case 2:
			spi->mode |= SPI_TX_DUAL;
			break;
		case 4:
			spi->mode |= SPI_TX_QUAD;
			break;
		default:
			dev_warn(&ctlr->dev,
				"spi-tx-bus-width %d not supported\n",
				value);
			break;
		}
	}

	if (!of_property_read_u32(nc, "spi-rx-bus-width", &value)) {
		switch (value) {
		case 1:
			break;
		case 2:
			spi->mode |= SPI_RX_DUAL;
			break;
		case 4:
			spi->mode |= SPI_RX_QUAD;
			break;
		default:
			dev_warn(&ctlr->dev,
				"spi-rx-bus-width %d not supported\n",
				value);
			break;
		}
	}

	if (spi_controller_is_slave(ctlr)) {
		if (strcmp(nc->name, "slave")) {
			dev_err(&ctlr->dev, "%pOF is not called 'slave'\n",
				nc);
			return -EINVAL;
		}
		return 0;
	}

	/* Device address */
	rc = of_property_read_u32(nc, "reg", &value);
	if (rc) {
		dev_err(&ctlr->dev, "%pOF has no valid 'reg' property (%d)\n",
			nc, rc);
		return rc;
	}
	spi->chip_select = value;

	/* Device speed */
	rc = of_property_read_u32(nc, "spi-max-frequency", &value);
	if (rc) {
		dev_err(&ctlr->dev,
			"%pOF has no valid 'spi-max-frequency' property (%d)\n", nc, rc);
		return rc;
	}
	spi->max_speed_hz = value;

	return 0;
}