SPI驱动(七) -- 编写SPI设备驱动程序

---

参考资料：

参考资料：

• 内核头文件：include\linux\spi\spi.h
• 内核文档：Documentation\spi\spidev
• DAC芯片手册：TLC5615.pdf

一、SPI驱动程序框架

SPI驱动分为SPI控制器驱动和SPI设备驱动。

• SPI控制器驱动

SPI控制器驱动基于"平台总线设备驱动"模型实现，platform_devide使用设备树生成，platform_driver使用 .c 文件实现，二者匹配成功后，调用platform_driver中的probe函数，probe函数会分配、设置、注册一个spi_master结构体，并且解析设备树的spi子节点，生成spi_device。

• SPI设备驱动

SPI设备驱动基于"SPI总线设备驱动"模型实现，spi_device来自设备树（由SPI控制器驱动解析完成），spi_driver使用 .c 文件实现。

下面介绍SPI设备驱动的编写过程。

二、 如何编写SPI设备驱动程序

2.1 编写设备树（spi_device）

• 查看原理图，确定设备挂在哪个SPI控制器下面
• 在设备树中找到SPI控制器节点
• 在这个节点下面，创建子节点，用来表示SPI设备
• 示例如下：

&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>;
    };
};

2.2 编写驱动（spi_driver）

SPI设备的设备树节点会被转换为一个spi_device结构体，我们需要编写一个spi_driver支持它，示例如下

static const struct of_device_id dac_of_match[] = {
	{.compatible = "100ask,dac"},
	{}
};

static struct spi_driver dac_driver = {
	.driver = {
		.name	= "dac",
		.of_match_table = dac_of_match,
	},
	.probe		= dac_probe, //在这里面完成字符设备注册
	.remove		= dac_remove,
	//.id_table	= dac_spi_ids,
};

三、内核中的SPI数据传输接口

接口函数都在这个内核文件里：include\linux\spi\spi.h

注意：SPI传输时，发出N个字节，就可以同时得到N个字节，
即使只想读N个字节，也必须发出N个字节：可以发出0xff，
即使只想发出N个字节，也会读到N个字节：可以忽略读到的数据。

• 接口说明

/**
 * 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或spi_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);

• 传输数据结构解析
  在SPI子系统中，用spi_transfer结构体描述一个传输，用spi_message管理过个传输。如果要传输多个spi_transfer可以，可以定义多个spi_transfer由spi_message中的链表来链接在一起。
  

• spi_message结构体:

struct spi_message {
	struct list_head	transfers; //链表，用来管理多个spi_transfer
	struct spi_device	*spi;
	unsigned		is_dma_mapped:1;

	void			(*complete)(void *context);
	void			*context;
	unsigned		frame_length;
	unsigned		actual_length;
	int			status;
	struct list_head	queue;
	void			*state;
	struct list_head        resources;
};

• spi_transfer 结构体:

struct spi_transfer {

	const void	*tx_buf;  //发送buf
	void		*rx_buf;  //结构buf
	unsigned	len;     //长度

	dma_addr_t	tx_dma;
	dma_addr_t	rx_dma;
	struct sg_table tx_sg;
	struct sg_table rx_sg;

	unsigned	cs_change: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;
	u16		delay_usecs;
	u32		speed_hz;

	struct list_head transfer_list;
};

• SPI传输示例

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
    * spi_message 里面有一个或多个spi_transfer
    */
	spi_message_init(&m);//初始化spi_message
	spi_message_add_tail(&t, &m);//把spi_transfer放入spi_message
	return spidev_sync(spidev, &m);//开始传输
}

四、SPI设备驱动程序框架

#include <linux/init.h>
#include <linux/module.h>
#include <linux/ioctl.h>
#include <linux/fs.h>
#include <linux/device.h>
#include <linux/err.h>
#include <linux/list.h>
#include <linux/errno.h>
#include <linux/mutex.h>
#include <linux/slab.h>
#include <linux/compat.h>
#include <linux/of.h>
#include <linux/of_device.h>
#include <linux/acpi.h>
#include <linux/spi/spi.h>
#include <linux/spi/spidev.h>

#include <linux/uaccess.h>

#define SPI_IOC_WR 123


static struct spi_device *dac;
static struct class *spidev_class;
static int major;

static long spidev_ioctl(struct file *filp, unsigned int cmd, unsigned long arg)
{
	
	return 0;
}


static int spidev_open(struct inode *inode, struct file *file) 
{
	
	return 0;
}

static ssize_t spidev_read(struct file* file, char __user *buf,
        size_t count, loff_t* fpos)
{

    return 0;
}

static ssize_t spidev_write(struct file *filp, const char __user *buf,
        size_t count, loff_t *f_pos)
{
    return 0;
}

static const struct file_operations spidev_fops = {
	.owner =	THIS_MODULE,
	.unlocked_ioctl = spidev_ioctl,
	.read = spidev_read,	
	.write = spidev_write,
	.open = spidev_open,
};


static int spidev_probe(struct spi_device *spi)
{
	/* 1. 记录spi_device */
	dac = spi;

	/* 2. 注册字符设备 */
	major = register_chrdev(0, "100ask_dac", &spidev_fops);
	spidev_class = class_create(THIS_MODULE, "100ask_dac");
	device_create(spidev_class, NULL, MKDEV(major, 0), NULL, "100ask_dac");	

	return 0;
}

static int spidev_remove(struct spi_device *spi)
{
	/* 反注册字符设备 */
	device_destroy(spidev_class, MKDEV(major, 0));
	class_destroy(spidev_class);
	unregister_chrdev(major, "100ask_dac");

	return 0;
}

static const struct of_device_id spidev_dt_ids[] = {
	{ .compatible = "100ask,dac" },
	{},
};


static struct spi_driver spidev_spi_driver = {
	.driver = {
		.name =		"100ask_spi_dac_drv",
		.of_match_table = of_match_ptr(spidev_dt_ids),
	},
	.probe =	spidev_probe,
	.remove =	spidev_remove,
};


static int __init spidev_init(void)
{
	int status;

	status = spi_register_driver(&spidev_spi_driver);
	if (status < 0) {
	}
	return status;
}
module_init(spidev_init);

static void __exit spidev_exit(void)
{
	spi_unregister_driver(&spidev_spi_driver);
}
module_exit(spidev_exit);

MODULE_LICENSE("GPL");