SPI

SPI 控制器驱动程序

SPI 主机驱动就是 SOC 的 SPI 控制器驱动，SPI 控制器不用关心设备的具体功能，它只负责把上层协议驱动准备好的数据按 SPI 总线的时序要求发送给 SPI 设备，同时把从设备收到的数据返回给上层的协议驱动，因此，内核把 SPI 控制器的驱动程序独立出来。

SPI 控制器驱动负责控制具体的控制器硬件，诸如 DMA 和中断操作等等，因为多个上层的协议驱动可能会通过控制器请求数据传输操作，所以，SPI 控制器驱动同时也要负责对这些请求进行队列管理，保证先进先出的原则。

  1. 申请必要的硬件资源，比如中断、DMA 通道、DMA 内存缓冲区等等

  2. 配置 SPI 控制器的工作模式和参数，使之可以和相应的设备进行正确的数据交换

  3. 向通用接口层提供接口，使得上层的协议驱动可以通过通用接口层访问控制器驱动

  4. 配合通用接口层，完成数据消息队列的排队和处理，直到消息队列变空为止

SPI 主机驱动的核心就是申请 spi_master，然后初始化 spi_master，最后向 Linux 内核注册spi_master。

1
2
3
4
5
6
7
8
spi_alloc_master 函数：申请 spi_master。
spi_master_put 函数：释放 spi_master。

spi_register_master函数：注册 spi_master。
spi_unregister_master 函数：注销 spi_master。

spi_bitbang_start函数：注册 spi_master。
spi_bitbang_stop 函数：注销 spi_master

SPI 通用接口封装层

为了简化 SPI 驱动程序的编程工作，同时也为了降低【协议驱动程序】和【控制器驱动程序】的耦合程度，内核把控制器驱动和协议驱动的一些通用操作封装成标准的接口，加上一些通用的逻辑处理操作，组成了 SPI 通用接口封装层。

这样的好处是，对于控制器驱动程序，只要实现标准的接口回调 API，并把它注册到通用接口层即可，无需直接和协议层驱动程序进行交互。而对于协议层驱动来说，只需通过通用接口层提供的 API 即可完成设备和驱动的注册，并通过通用接口层的 API 完成数据的传输，无需关注 SPI 控制器驱动的实现细节。

  1. SPI 通用接口层把具体的 SPI 设备的协议驱动和 SPI 控制器驱动连接在一起。

  2. 负责 SPI 系统与 Linux 设备模型相关的初始化工作。

  3. 为协议驱动和控制器驱动提供一系列的标准接口 API 及其数据结构。

  4. SPI 设备、SPI 协议驱动、SPI 控制器的数据抽象

  5. 协助数据传输而定义的数据结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
//重要数据结构
struct spi_device						//描述一个 spi 从机设备
struct spi_driver						//描述一个 spi 设备驱动
struct spi_board_info					//描述一个 spi 从机设备板级信息，无设备树时使用
struct spi_controller/spi_master		//描述一个 spi 主机设备
struct spi_transfer						//描述 spi 传输的具体数据
struct spi_message						//描述一次 spi 传输的信息，是一次 SPI 数据交换的原子操作
//重要API
spi_message_init
spi_message_add_tail
spi_sync
spi_async
spi_write
spi_read

SPI 协议驱动程序

SPI 设备的具体功能是由 SPI 协议驱动程序完成的，SPI 协议驱动程序了解设备的功能和通信数据的协议格式。向下，协议驱动通过通用接口层和控制器交换数据，向上，协议驱动通常会根据设备具体的功能和内核的其它子系统进行交互。

例如，和 MTD 层交互以便把 SPI 接口的存储设备实现为某个文件系统，和 TTY 子系统交互把 SPI 设备实现为一个 TTY 设备，和网络子系统交互以便把一个 SPI 设备实现为一个网络设备。如果是一个专有的 SPI 设备，我们也可以按设备的协议要求，实现自己的专有协议驱动。

SPI 通用设备驱动程序

考虑到连接在 SPI 控制器上的设备的可变性，在内核没有配备相应的协议驱动程序，对于这种情况，内核为我们准备了通用的 SPI 设备驱动程序，该通用设备驱动程序向用户空间提供了控制 SPI 控制的控制接口，具体的协议控制和数据传输工作交由用户空间根据具体的设备来完成，在这种方式中，只能采用同步的方式和 SPI 设备进行通信，所以通常用于一些数据量较少的简单 SPI 设备。

在Linux内核中spi的函数存放位置

1
2
3
kernel-4.15/drivers/spi/spi.c  Linux 提供的通用接口封装层驱动
kernel-4.15/drivers/spi/spidev.c  linux 提供的 SPI 通用设备驱动程序
kernel-4.15/include/linux/spi/spi.h  linux 提供的包含 SPI 的主要数据结构和函数

SPI 数据传输可以有两种方式：同步方式和异步方式。

同步方式：数据传输的发起者必须等待本次传输的结束，期间不能做其它事情，用代码来解释就是，调用传输的函数后，直到数据传输完成，函数才会返回。

异步方式：数据传输的发起者无需等待传输的结束，数据传输期间还可以做其它事情，用代码来解释就是，调用传输的函数后，函数会立刻返回而不用等待数据传输完成，我们只需设置一个回调函数，传输完成后，该回调函数会被调用以通知发起者数据传送已经完成。

spi_async函数是发起一个异步传输的API，它会把spi_message结构挂在spi_master的queue字段下，然后启动专门为spi传输准备的内核工作线程，由该工作线程来实际处理message的传输工作，因为是异步操作，所以该函数会立刻返回，不会等待传输的完成，这时，协议驱动程序（可能是另一个协议驱动程序）可以再次调用该API，发起另一个message传输请求，结果就是，当工作线程被唤醒时，spi_master下面可能已经挂了多个待处理的spi_message结构，工作线程会按先进先出的原则来逐个处理这些message请求，每个message传送完成后，对应spi_message结构的complete回调函数就会被调用，以通知协议驱动程序准备下一帧数据。这就是spi_message的队列化。工作线程唤醒时，spi_master、spi_message和spi_transfer之间的关系可以用下图来描述：

SPI驱动结构

spi_driver 注册示例程序如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
/* probe 函数 */
static int xxx_probe(struct spi_device *spi)
{
/* 具体函数内容 */
	return 0;
}
/* remove 函数 */
static int xxx_remove(struct spi_device *spi)
{
/* 具体函数内容 */
	return 0;
}
/* 传统匹配方式 ID 列表 */
static const struct spi_device_id xxx_id[] = {
	{"xxx", 0},
	{}
};
/* 设备树匹配列表 */
static const struct of_device_id xxx_of_match[] = {
	{ .compatible = "xxx" },
	{ /* Sentinel */ }
};

/* SPI 驱动结构体 */
static struct spi_driver xxx_driver = {
	.probe = xxx_probe,
	.remove = xxx_remove,
    .driver = {
		.owner = THIS_MODULE,
		.name = "xxx",
		.of_match_table = xxx_of_match,
	},
	.id_table = xxx_id,
};
/* 驱动入口函数 */
static int __init xxx_init(void)
{
	return spi_register_driver(&xxx_driver);
}

/* 驱动出口函数 */
static void __exit xxx_exit(void)
{
	spi_unregister_driver(&xxx_driver);
}
module_init(xxx_init);
module_exit(xxx_exit);

设备驱动的编写流程

SPI使用的API函数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
603 struct spi_transfer {
604 /* it's ok if tx_buf == rx_buf (right?)
605 * for MicroWire, one buffer must be null
606 * buffers must work with dma_*map_single() calls, unless
607 * spi_message.is_dma_mapped reports a pre-existing mapping
608 */
609 const void *tx_buf;	//发送数据
610 void *rx_buf;		//接收数据
611 unsigned len;		//len 是要进行传输的数据长度
612
613 dma_addr_t tx_dma;
614 dma_addr_t rx_dma;
615 struct sg_table tx_sg;
616 struct sg_table rx_sg;
617
618 unsigned cs_change:1;
619 unsigned tx_nbits:3;
620 unsigned rx_nbits:3;
621 #define SPI_NBITS_SINGLE 0x01 /* 1bit transfer */
622 #define SPI_NBITS_DUAL 0x02 /* 2bits transfer */
623 #define SPI_NBITS_QUAD 0x04 /* 4bits transfer */
624 u8 bits_per_word;
625 u16 delay_usecs;
626 u32 speed_hz;
627
628 struct list_head transfer_list;
629 };

spi_transfer 需要组织成 spi_message， spi_message 也是一个结构体 。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
struct spi_message {
661 struct list_head transfers;
662
663 struct spi_device *spi;
664
665 unsigned is_dma_mapped:1;
......
678 /* completion is reported through a callback */
679 void (*complete)(void *context);
680 void *context;
681 unsigned frame_length;
682 unsigned actual_length;
683 int status;
684
685 /* for optional use by whatever driver currently owns the
686 * spi_message ... between calls to spi_async and then later
687 * complete(), that's the spi_master controller driver.
688 */
689 struct list_head queue;
690 void *state;
691 };

在使用spi_message之前需要对其进行初始化， spi_message初始化函数为spi_message_init，

1
2
3
void spi_message_init(struct spi_message *m)
/*m： 要初始化的 spi_message。
	返回值： 无。*/

spi_message 初始化完成以后需要将 spi_transfer 添加到 spi_message 队列中，这里我们要用到 spi_message_add_tail 函数。

1
2
3
4
5
6
void spi_message_add_tail(struct spi_transfer *t, struct spi_message *m)
/*
t： 要添加到队列中的 spi_transfer。
m： spi_transfer 要加入的 spi_message。
返回值： 无。
*/

spi_message 准备好以后就可以进行数据传输了，数据传输分为同步传输和异步传输，同步传输会阻塞的等待 SPI 数据传输完成，同步传输函数为 spi_sync，函数原型如下：

1
2
3
4
int spi_sync(struct spi_device *spi, struct spi_message *message)
/*	spi： 要进行数据传输的 spi_device。
	message：要传输的 spi_message。
	返回值： 无。*/

异步传输不会阻塞的等到 SPI 数据传输完成，异步传输需要设置 spi_message 中的 complete成员变量， complete 是一个回调函数，当 SPI 异步传输完成以后此函数就会被调用。 SPI 异步传输函数为 spi_async。

1
2
3
4
int spi_async(struct spi_device *spi, struct spi_message *message)
/*	spi： 要进行数据传输的 spi_device。
	message：要传输的 spi_message。
	返回值： 无。 */

同步传输通过 SPI 进行 n 个字节的数据发送和接收的示例代码 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
/* SPI 多字节发送 */
static int spi_send(struct spi_device *spi, u8 *buf, int len)
{
	int ret;
	struct spi_message m;
	struct spi_transfer t = {
		.tx_buf = buf,
		.len = len,
	};
	spi_message_init(&m); /* 初始化 spi_message */
	spi_message_add_tail(t, &m);/* 将 spi_transfer 添加到 spi_message 队列 */
	ret = spi_sync(spi, &m); /* 同步传输 */
	return ret;
}
/* SPI 多字节接收 */
static int spi_receive(struct spi_device *spi, u8 *buf, int len)
{
	int ret;
	struct spi_message m;
	struct spi_transfer t = {
		.rx_buf = buf,
		.len = len,
	};
	spi_message_init(&m); /* 初始化 spi_message */
	spi_message_add_tail(t, &m);/* 将 spi_transfer 添加到 spi_message 队列 */
	ret = spi_sync(spi, &m); /* 同步传输 */
	return ret;
}