SPI驱动(二) -- SPI驱动程序模型

---

参考资料：

• 内核头文件：include\linux\spi\spi.h

一、SPI驱动重要数据结构

如下图，SPI 子系统中包含有 SPI控制器和SPI设备两类硬件。内核对此抽象出了三个数据结构：

• spi_master：用来表示一个SPI控制器；
• spi_device：用来表示一个SPI设备；
• spi_driver：与SPI设备对应的SPI驱动。
  

1.1 SPI控制器数据结构

spi_master结构中最重要的成员是transfer函数指针，由它实现SPI控制器的数据传输功能。

struct spi_master {
	struct device	dev;
	struct list_head list;
    u32 slave;
	s16			bus_num;  //第几条总线
	u16			num_chipselect; //支持的片选引脚个数
	u16			dma_alignment;
	u16			mode_bits;   //SPI控制器支持的工作模式
	u32			bits_per_word_mask; //一次传输几位
#define SPI_BPW_MASK(bits) BIT((bits) - 1)
#define SPI_BIT_MASK(bits) (((bits) == 32) ? ~0U : (BIT(bits) - 1))
#define SPI_BPW_RANGE_MASK(min, max) (SPI_BIT_MASK(max) - SPI_BIT_MASK(min - 1))

	/* 最大/最小传输速率 */
	u32			min_speed_hz;
	u32			max_speed_hz;

	/* other constraints relevant to this driver */
	u16			flags;
#define SPI_MASTER_HALF_DUPLEX	BIT(0)		/* can't do full duplex */
#define SPI_MASTER_NO_RX	BIT(1)		/* can't do buffer read */
#define SPI_MASTER_NO_TX	BIT(2)		/* can't do buffer write */
#define SPI_MASTER_MUST_RX      BIT(3)		/* requires rx */
#define SPI_MASTER_MUST_TX      BIT(4)		/* requires tx */

	/* lock and mutex for SPI bus locking */
	spinlock_t		bus_lock_spinlock;
	struct mutex		bus_lock_mutex;

	/* flag indicating that the SPI bus is locked for exclusive use */
	bool			bus_lock_flag;
	/*设置spi总线工作模式，频率等*/
	int			(*setup)(struct spi_device *spi);
	/*spi 传输方法*/
	int			(*transfer)(struct spi_device *spi,
						struct spi_message *mesg);

	void			(*cleanup)(struct spi_device *spi);

	bool			(*can_dma)(struct spi_master *master,
					   struct spi_device *spi,
					   struct spi_transfer *xfer);

	bool				queued;
	struct kthread_worker		kworker;
	struct task_struct		*kworker_task;
	struct kthread_work		pump_messages;
	spinlock_t			queue_lock;
	struct list_head		queue;
	struct spi_message		*cur_msg;  
	bool				idling;  //空闲
	bool				busy;    //忙
	bool				running; //运行中
	bool				rt;
	bool				auto_runtime_pm;
	bool                            cur_msg_prepared;
	bool				cur_msg_mapped;
	struct completion               xfer_completion;
	size_t				max_dma_len;

	int (*prepare_transfer_hardware)(struct spi_master *master);
	int (*transfer_one_message)(struct spi_master *master,
				    struct spi_message *mesg);
	int (*unprepare_transfer_hardware)(struct spi_master *master);
	int (*prepare_message)(struct spi_master *master,
			       struct spi_message *message);
	int (*unprepare_message)(struct spi_master *master,
				 struct spi_message *message);

	void (*set_cs)(struct spi_device *spi, bool enable);
	int (*transfer_one)(struct spi_master *master, struct spi_device *spi,
			    struct spi_transfer *transfer);
	void (*handle_err)(struct spi_master *master,
			   struct spi_message *message);

	/* gpio chip select */
	int			*cs_gpios;

	/* statistics */
	struct spi_statistics	statistics;

	/* DMA channels for use with core dmaengine helpers */
	struct dma_chan		*dma_tx;
	struct dma_chan		*dma_rx;

	/* dummy data for full duplex devices */
	void			*dummy_rx;
	void			*dummy_tx;
};

1.2 SPI设备数据结构

spi_device结构体里面记录有设备的片选引脚、频率、挂在哪个SPI控制器下面等信息。

struct spi_device {
	struct device		dev;
	struct spi_master	*master; //设备挂在的对应控制器
	u32			max_speed_hz;   //该设备能支持的SPI时钟最大值
	u8			chip_select;    //是这个spi_master下的第几个设备
	u8			bits_per_word; //每次传输的位数,bits_per_word是可以大于32的，也就是每次SPI传输可能会发送多于32位的数据，这适用于DMA突发传输
	u16			mode;  //工作模式
#define	SPI_CPHA	0x01			/* 在第1个周期采样，在第2个周期采样？ */
#define	SPI_CPOL	0x02			/* 平时时钟极性 */
#define	SPI_MODE_0	(0|0)			/* (original MicroWire) */
#define	SPI_MODE_1	(0|SPI_CPHA)
#define	SPI_MODE_2	(SPI_CPOL|0)
#define	SPI_MODE_3	(SPI_CPOL|SPI_CPHA)
#define	SPI_CS_HIGH	0x04			/* 一般来说片选引脚时低电平有效，SPI_CS_HIGH表示高电平有效 */
#define	SPI_LSB_FIRST	0x08	    /* 一般来说先传输MSB(最高位)，SPI_LSB_FIRST表示先传LSB(最低位),很多SPI控制器并不支持SPI_LSB_FIRST */
#define	SPI_3WIRE	0x10			/* SO、SI共用一条线 */
#define	SPI_LOOP	0x20			/* 回环模式，就是SO、SI连接在一起 */
#define	SPI_NO_CS	0x40			/* 只有一个SPI设备，没有片选信号，也不需要片选信号 */
#define	SPI_READY	0x80			/* SPI从设备可以拉低信号，表示暂停、表示未就绪 */
#define	SPI_TX_DUAL	0x100			/* 发送数据时有2条信号线 */
#define	SPI_TX_QUAD	0x200			/* 发送数据时有4条信号线 */
#define	SPI_RX_DUAL	0x400			/* 接收数据时有2条信号线 */
#define	SPI_RX_QUAD	0x800			/* 接收数据时有4条信号线 */
#define SPI_SLAVE_MODE 0x1000       /* enabled spi slave mode */
	int			irq;
	void			*controller_state;
	void			*controller_data;
	char			modalias[SPI_NAME_SIZE];
	int			cs_gpio;	//这是可选项，也可以把spi_device的片选引脚记录在这里

	/* the statistics */
	struct spi_statistics	statistics;
};

1.3 SPI驱动数据结构

spi_driver 结构体是”SPI总线设备驱动模型”中的一部分。

struct spi_driver {
	const struct spi_device_id *id_table;
	int			(*probe)(struct spi_device *spi);
	int			(*remove)(struct spi_device *spi);
	void			(*shutdown)(struct spi_device *spi);
	struct device_driver	driver;
};

二、SPI 驱动框架

SPI 子系统中包含有 SPI控制器和SPI设备两类硬件。对应就有SPI控制器驱动和SPI设备驱动，SPI控制器驱动提供SPI的传输能力。SPI设备驱动提供对SPI设备的访问能力，它知道怎么访问这个设备，知道这个设备的数据含义是什么， 它会调用SPI控制器的函数来收发数据。

2.1 SPI控制器驱动程序

SPI控制器的驱动程序可以基于"平台总线设备驱动"模型来实现：

• 在设备树里描述SPI控制器的硬件信息，在设备树子节点里描述挂在下面的SPI设备的信息
• 在platform_driver中提供一个probe函数
  • 它会注册一个spi_master
  • 还会解析设备树子节点，创建spi_device结构体

2.2 SPI设备驱动程序

跟"平台总线设备驱动模型"类似，Linux中也有一个"SPI总线设备驱动模型"：

• 左边是spi_driver，使用C文件实现，里面有id_table表示能支持哪些SPI设备，有probe函数
• 右边是spi_device，用来描述SPI设备，比如它的片选引脚、频率
  • 可以来自设备树：比如由SPI控制器驱动程序解析设备树后创建、注册spi_device
  • 可以来自C文件：比如使用spi_register_board_info创建、注册spi_device

SPI驱动模型：
右边”平台总线设备驱动模型”，左边“SPI总线设备驱动模型”。

三、总结

本文描述了SPI驱动程序模型。