SPI传输与驱动框架的实现
本文章相关专栏往期内容，SPI子系统专栏：
- SPI通信协议与Linux设备驱动框架解析
PCI/PCIe子系统专栏：
- 专栏地址：PCI/PCIe子系统
- PCIe设备MSI/MSI-X中断源码分析与驱动编写
– 末片，有专栏内容观看顺序Uart子系统专栏：
- 专栏地址：Uart子系统
- Linux内核早期打印机制与RS485通信技术
– 末片，有专栏内容观看顺序interrupt子系统专栏：
- 专栏地址：interrupt子系统
- Linux 链式与层级中断控制器讲解：原理与驱动开发
– 末片，有专栏内容观看顺序pinctrl和gpio子系统专栏：
专栏地址：pinctrl和gpio子系统
编写虚拟的GPIO控制器的驱动程序：和pinctrl的交互使用
– 末片，有专栏内容观看顺序
input子系统专栏：
- 专栏地址：input子系统
- input角度：I2C触摸屏驱动分析和编写一个简单的I2C驱动程序
– 末片，有专栏内容观看顺序I2C子系统专栏：
- 专栏地址：IIC子系统
- 具体芯片的IIC控制器驱动程序分析：i2c-imx.c-CSDN博客
– 末篇，有专栏内容观看顺序总线和设备树专栏：
- 专栏地址：总线和设备树
- 设备树与 Linux 内核设备驱动模型的整合-CSDN博客
– 末篇，有专栏内容观看顺序
目录
- 1. spi传输函数
-
- 1.1 接口API
- 1.2 传输单位spi_transfer
- 1.3 传输示例
- 2.怎么编写？？
-
- 2.1 框架图
- 2.2 编写设备树
- 2.3 编写驱动框架
1. spi传输函数
1.1 接口API
接口函数都在这个内核文件里：include\linux\spi\spi.h
- 简易函数
include\linux\spi\spi.h：
/**
* SPI同步写
* @spi: 写哪个设备
* @buf: 数据buffer
* @len: 长度
* 这个函数可以休眠
*
* 返回值: 0-成功, 负数-失败码
*/
static inline int
spi_write(struct spi_device *spi, const void *buf, size_t len);
/**
* SPI同步读
* @spi: 读哪个设备
* @buf: 数据buffer
* @len: 长度
* 这个函数可以休眠
*
* 返回值: 0-成功, 负数-失败码
*/
static inline int
spi_read(struct spi_device *spi, void *buf, size_t len);
/**
* spi_write_then_read : 先写再读, 这是一个同步函数
* @spi: 读写哪个设备
* @txbuf: 发送buffer
* @n_tx: 发送多少字节
* @rxbuf: 接收buffer
* @n_rx: 接收多少字节
* 这个函数可以休眠
*
* 这个函数执行的是半双工的操作: 先发送txbuf中的数据，在读数据，读到的数据存入rxbuf
*
* 这个函数用来传输少量数据(建议不要操作32字节), 它的效率不高
* 如果想进行高效的SPI传输，请使用spi_{async,sync}(这些函数使用DMA buffer)
*
* 返回值: 0-成功, 负数-失败码
*/
extern int spi_write_then_read(struct spi_device *spi,
const void *txbuf, unsigned n_tx,
void *rxbuf, unsigned n_rx);
/**
* spi_w8r8 - 同步函数，先写8位数据，再读8位数据
* @spi: 读写哪个设备
* @cmd: 要写的数据
* 这个函数可以休眠
*
*
* 返回值: 成功的话返回一个8位数据(unsigned), 负数表示失败码
*/
static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd);
/**
* spi_w8r16 - 同步函数，先写8位数据，再读16位数据
* @spi: 读写哪个设备
* @cmd: 要写的数据
* 这个函数可以休眠
*
* 读到的16位数据:
* 低地址对应读到的第1个字节(MSB)，高地址对应读到的第2个字节(LSB)
* 这是一个big-endian的数据
*
* 返回值: 成功的话返回一个16位数据(unsigned), 负数表示失败码
*/
static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd);
/**
* spi_w8r16be - 同步函数，先写8位数据，再读16位数据，
* 读到的16位数据被当做big-endian，然后转换为CPU使用的字节序
* @spi: 读写哪个设备
* @cmd: 要写的数据
* 这个函数可以休眠
*
* 这个函数跟spi_w8r16类似，差别在于它读到16位数据后，会把它转换为"native endianness"
*
* 返回值: 成功的话返回一个16位数据(unsigned, 被转换为本地字节序), 负数表示失败码
*/
static inline ssize_t spi_w8r16be(struct spi_device *spi, u8 cmd);
- 复杂的函数
/**
* spi_async - 异步SPI传输函数，简单地说就是这个函数即刻返回，它返回后SPI传输不一定已经完成
* @spi: 读写哪个设备
* @message: 用来描述数据传输，里面含有完成时的回调函数(completion callback)
* 上下文: 任意上下文都可以使用，中断中也可以使用
*
* 这个函数不会休眠，它可以在中断上下文使用(无法休眠的上下文)，也可以在任务上下文使用(可以休眠的上下文)
*
* 完成SPI传输后，回调函数被调用，它是在"无法休眠的上下文"中被调用的，所以回调函数里不能有休眠操作。
* 在回调函数被调用前message->statuss是未定义的值，没有意义。
* 当回调函数被调用时，就可以根据message->status判断结果: 0-成功,负数表示失败码
* 当回调函数执行完后，驱动程序要认为message等结构体已经被释放，不能再使用它们。
*
* 在传输过程中一旦发生错误，整个message传输都会中止，对spi设备的片选被取消。
*
* 返回值: 0-成功(只是表示启动的异步传输，并不表示已经传输成功), 负数-失败码
*/
extern int spi_async(struct spi_device *spi, struct spi_message *message);
/**
* spi_sync - 同步的、阻塞的SPI传输函数，简单地说就是这个函数返回时，SPI传输要么成功要么失败
* @spi: 读写哪个设备
* @message: 用来描述数据传输，里面含有完成时的回调函数(completion callback)
* 上下文: 能休眠的上下文才可以使用这个函数
*
* 这个函数的message参数中，使用的buffer是DMA buffer
*
* 返回值: 0-成功, 负数-失败码
*/
extern int spi_sync(struct spi_device *spi, struct spi_message *message);
/**
* spi_sync_transfer - 同步的SPI传输函数
* @spi: 读写哪个设备
* @xfers: spi_transfers数组，用来描述传输
* @num_xfers: 数组项个数
* 上下文: 能休眠的上下文才可以使用这个函数
*
* 返回值: 0-成功, 负数-失败码
*/
static inline int
spi_sync_transfer(struct spi_device *spi, struct spi_transfer *xfers,
unsigned int num_xfers);
1.2 传输单位spi_transfer
在SPI子系统中，用spi_transfer结构体描述一个传输，用spi_message管理过个传输。下面是对该结构体的描述
//include\linux\spi\spi.h：
//内核当中有对这个结构体的详细描述，建议去看看，由于给的太多就不摘抄出来了
struct spi_transfer {
/* it's ok if tx_buf == rx_buf (right?)
* for MicroWire, one buffer must be null
* buffers must work with dma_*map_single() calls, unless
* spi_message.is_dma_mapped reports a pre-existing mapping
*/
const void *tx_buf;//指向发送缓冲区的指针（如果只接收数据，可以为 NULL）。
void *rx_buf;//指向接收缓冲区的指针（如果只发送数据，可以为 NULL）
unsigned len;//tx_buf 和 rx_buf 缓冲区的大小，单位为字节。SPI 传输时发送和接收的数据长度是相同的。
dma_addr_t tx_dma;//如果使用 DMA 进行传输，tx_buf 的 DMA 地址。
dma_addr_t rx_dma;//如果使用 DMA 进行传输，rx_buf 的 DMA 地址。
struct sg_table tx_sg; //用于发送的 Scatterlist，暂时不对客户端开放使用。
struct sg_table rx_sg;//用于接收的 Scatterlist，暂时不对客户端开放使用。
unsigned cs_change:1;//如果设置为 1，则在此传输完成后更改片选信号。用于在多次传输之间控制片选信号。
unsigned tx_nbits:3;//传输时使用的位数（例如单线模式、双线模式或四线模式）。
unsigned rx_nbits:3;//接收时使用的位数（同样支持单线、双线或四线模式）。
//可选择的模式内核已经宏定义给我么了：
#define SPI_NBITS_SINGLE 0x01 /* 1bit transfer */ //单线传输（默认）。
#define SPI_NBITS_DUAL 0x02 /* 2bits transfer */ //双线传输。
#define SPI_NBITS_QUAD 0x04 /* 4bits transfer */ //四线传输。
u8 bits_per_word; //每个传输字的位数。如果为 0，则使用设备默认值。
u16 delay_usecs;//传输完成后，在（可选地）更改片选状态之前，延迟的微秒数。
u32 speed_hz;//传输速度，单位为赫兹。若为 0，则使用设备的默认速度。
struct list_head transfer_list;//在一个 spi_message 中，传输通过链表进行排序和处理。
};
- SPI 传输是全双工的，也就是说，发送时也会同时接收数据。如果不需要发送，可以将
tx_buf设置为NULL，此时会发送 0；如果不需要接收，可以将rx_buf设置为NULL，接收到的数据将被丢弃。 - 在一些情况下，可能需要 DMA 进行高效的数据传输，这时可以使用
tx_dma和rx_dma指定 DMA 地址
可以构造多个spi_transfer结构体，把它们放入一个spi_message里面，spi_message结构体如下：
struct spi_message {
struct list_head transfers;//一个链表，包含了该事务中所有的传输段（spi_transfer）。
struct spi_device *spi;//指向执行此次事务的 SPI 设备（spi_device）。
unsigned is_dma_mapped:1;//如果为 true，表示调用者已经为每个传输缓冲区提供了 DMA 和 CPU 虚拟地址。
/* REVISIT: we might want a flag affecting the behavior of the
* last transfer ... allowing things like "read 16 bit length L"
* immediately followed by "read L bytes". Basically imposing
* a specific message scheduling algorithm.
*
* Some controller drivers (message-at-a-time queue processing)
* could provide that as their default scheduling algorithm. But
* others (with multi-message pipelines) could need a flag to
* tell them about such special cases.
*/
/* completion is reported through a callback */
void (*complete)(void *context);//一个回调函数，在事务完成后会调用它以通知上层驱动程序传输的完成。
void *context;//传递给 complete() 回调函数的参数，通常是用于回调函数内部的上下文信息。
unsigned frame_length;//消息中所有传输段的总字节数。
unsigned actual_length;//所有成功传输的字节总数。
int status;//传输的状态，0 表示成功，其他负值表示错误号。
/* for optional use by whatever driver currently owns the
* spi_message ... between calls to spi_async and then later
* complete(), that's the spi_master controller driver.
*/
struct list_head queue;//用于管理消息队列，由控制 SPI 事务的驱动程序使用。
void *state;//供控制消息的驱动程序使用的状态信息。
/* list of spi_res reources when the spi message is processed */
struct list_head resources;//当 SPI 消息被处理时，资源管理的链表。
};
spi_message 表示一次多段传输操作的事务，它将多个 spi_transfer 组成一个完整的 SPI 传输操作。通常情况下，该事务是“原子”的，即在该事务完成之前，SPI 总线上不会进行其他设备的传输。
1.3 传输示例
\Linux-4.9.88\drivers\spi\spidev.c：
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_messgae
spi_message_add_tail(&t, &m); //把spi_transfer放入spi_message
return spidev_sync(spidev, &m); //发起传输
}
static inline ssize_t
spidev_sync_read(struct spidev_data *spidev, size_t len)
{
struct spi_transfer t = {
.rx_buf = spidev->rx_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);
}
2.怎么编写？？
主要去参考\Linux-4.9.88\drivers\spi\spidev.cspidev.c
2.1 框架图
2.2 编写设备树
设备树示例：
&ecspi1 {
pinctrl-names = "default";
pinctrl-0 = <&pinctrl_ecspi1>;
fsl,spi-num-chipselects = <2>;
cs-gpios = <&gpio4 26 GPIO_ACTIVE_LOW>, <&gpio4 24 GPIO_ACTIVE_LOW>;
status = "okay";
dac: dac {
compatible = "100ask,dac";
reg = <0>;
spi-max-frequency = <10000000>;
};
};
找到SPI控制器的节点，在其下面添加SPI设备的节点即可，关于设备树的编写暂时不用深究，后面会讲设备树的具体内容
2.3 编写驱动框架
框架：spi_drv.c
参考内核提供的spidev.c中的内容，主要就是注册一个spi_driver，至于传输的那些函数上面已经讲过：
static const struct of_device_id spidev_dt_ids[] = {
{ .compatible = "rohm,dh2228fv" },
{ .compatible = "lineartechnology,ltc2488" },
{},
};
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,
};