linux SPI总线驱动

一.SPI子系统综述

       SPI子系统从上到下分为：spi设备驱动层，核心层和master驱动层。其中master驱动抽象出spi控制器的相关操作，而spi设备驱动层抽象出了用户空间调用的相关函数。

        主控制器(master)和主控制器驱动将挂载到platform总线上。在platform_driver的probe函数中将注册spi_master，同时将会获取在板级信息中添加的spi设备，将该信息转换成spi_device，然后注册spi_device到spi总线上。   

        spi_driver结构用于描述spi设备驱动，也将挂载到spi总线上。spi_driver注册的是字符设备，该字符设备将提供5个API给用户空间。

         Linux内核中的几个文件:spi.c也就是spi子系统的核心了（核心层），spi_s3c24xx_gpio.c，spi_s3c24xx.c是s3c24xx系列芯片的SPI controller驱动（master驱动层），它向更上层的SPI核心层(spi.c)提供接口用来控制芯片的SPI controller，是一个被其他驱动使用的驱动。嵌入式微处理器访问SPI设备有两种方式：使用GPIO模拟SPI接口的工作时序(spi_s3c24xx_gpio.c)或者使用SPI控制器(spi_s3c24xx.c)。使用GPIO模拟SPI接口的工作时序是非常容易实现的，但是会导致大量的时间耗费在模拟SPI接口的时序上，访问效率比较低，容易成为系统瓶颈。而spidev.c是在核心层基础之上将SPI controller模拟成一个字符型的驱动，向文件系统提供标准的文件系统接口，用来操作对应的SPI controller（spi设备驱动层）。

二.关键数据结构

1 spi_master：该结构用于描述SOC的SPI控制器，S3C2440共有两个SPI控制器

struct spi_master {
struct device    dev;/*总线编号，从0开始*/
s16  bus_num;/*支持的片选的数量，从设备的片选号不能大于这个数量*/
u16  num_chipselect;
u16  dma_alignment;/*改变spi_device的特性如：传输模式，字长，时钟频率*/
int  (*setup)(struct spi_device *spi);/*添加消息到队列的方法，这个函数不可睡眠，他的任务是安排发生的传送并且调用注册的回调函数complete()*/
int  (*transfer)(struct spi_device *spi,struct spi_message *mesg);
void (*cleanup)(struct spi_device *spi);
};

       bus_num为该控制器对应的SPI总线号。num_chipselect 控制器支持的片选数量，即能支持多少个spi设备 setup函数是设置SPI总线的模式，时钟等的初始化函数， 针对设备设置SPI的工作时钟及数据传输模式等。spi_add_device函数中调用。 transfer函数是实现SPI总线读写方法的函数。实现数据的双向传输，可能会睡眠。cleanup注销时候调用

2 spi_device

该结构用于描述SPI设备，也就是从设备的相关信息。SPI子系统只支持主模式，也就是说S3C2440的SPI只能工作在master模式，外围设备只能为slave模式.

struct spi_device {
struct device        dev;
struct spi_master   *master;       //对应的控制器指针u32    
max_speed_hz;  //spi通信的时钟u8       
chip_select;   //片选，用于区分同一总线上的不同设备
u8  mode;
#define    SPI_CPHA    0x01            /* clock phase */
#define    SPI_CPOL    0x02            /* clock polarity */
#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            /* chipselect active high? */
#define    SPI_LSB_FIRST   0x08            /* per-word bits-on-wire */
#define  SPI_3WIRE   0x10            /* SI/SO signals shared */
#define   SPI_LOOP    0x20            /* loopback mode */
u8      bits_per_word;    //每个字长的比特数
int      irq;              //使用的中断
void     *controller_state;
void     *controller_data;
char     modalias[32];    //名字
};  

3 spi_board_info，s3c2410_spi_info 

两个板级的结构，其中spi_board_info用来初始化spi_device，s3c2410_spi_info用来初始化spi_master。这两个板级的结构需要在移植的时候在arch/arm/mach-s3c2440/mach-smdk2440.c中初始化。

struct spi_board_info {
char     modalias[32];   //设备与驱动匹配的唯一标识
const void    *platform_data;
void     *controller_data;
int        irq;
u32     max_speed_hz;
u16        bus_num;       //设备所归属的总线编号
u16      chip_select;
u8      mode;
};
struct s3c2410_spi_info {
int     pin_cs;         //芯片选择管脚
unsigned int    num_cs;         //总线上的设备数
int        bus_num;        //总线号
void (*gpio_setup)(struct s3c2410_spi_info *spi, int enable);     //spi管脚配置函数
void (*set_cs)(struct s3c2410_spi_info *spi, int cs, int pol);
};  

4 spi_driver

     该结构用于描述SPI设备驱动。驱动核心将根据driver.name和spi_board_info 的modalias进行匹配，如过modalia和name相等，则绑定驱动程序和SPI设备。 

struct spi_driver {
int   (*probe)(struct spi_device *spi);
int   (*remove)(struct spi_device *spi);
void  (*shutdown)(struct spi_device *spi);
int   (*suspend)(struct spi_device *spi, pm_message_t mesg);
int   (*resume)(struct spi_device *spi);
struct device_driver  driver;
}; 

5.s3c24xx_spi，spi_bitbang。s3c24xx_spi是S3C2440的SPI控制器在Linux内核中的具体描述，该结构包含spi_bitbang内嵌结构，控制器时钟频率和占用的中断资源等重要成员，其中spi_bitbang具体负责SPI数据的传输。

struct s3c24xx_spi {
/* bitbang has to be first */
struct spi_bitbang  bitbang;
struct completion   done;
void __iomem      *regs;
int            irq;
int             len;
int             count;
void         (*set_cs)(struct s3c2410_spi_info *spi,  int cs, int pol);
/* data buffers */const unsigned char *tx;
unsigned char       *rx;
struct clk      *clk;
struct resource        *ioarea;
struct spi_master   *master;
struct spi_device   *curdev;
struct device       *dev;
struct s3c2410_spi_info *pdata;
};

struct spi_bitbang {
struct workqueue_struct *workqueue;      //工作队列头
struct work_struct  work;            //每一次传输都传递下来一个spi_message，都向工作队列头添加一个
workspinlock_t     lock;
struct list_head   queue;           //挂接spi_message，如果上一次的spi_message还没有处理完，接下来的spi_message就挂接在queue上等待处理
u8     busy;            //忙碌标志
u8     use_dma;
u8     flags;
struct spi_master *master;/*一下3个函数都是在函数s3c24xx_spi_probe()中被初始化*/
int     (*setup_transfer)(struct spi_device *spi,struct spi_transfer *t);   //设置传输模式
void    (*chipselect)(struct spi_device *spi, int is_on);                    //片选
#define   BITBANG_CS_ACTIVE   1   /* normally nCS, active low */
#define   BITBANG_CS_INACTIVE 0/*传输函数，由s3c24xx_spi_txrx来实现*/
int    (*txrx_bufs)(struct spi_device *spi, struct spi_transfer *t);
u32    (*txrx_word[4])(struct spi_device *spi,unsigned nsecs,u32 word, u8 bits);
}; 

        为了解决多个不同的SPI设备共享SPI控制器而带来的访问冲突，spi_bitbang使用内核提供的工作队列(workqueue)。workqueue是Linux内核中定义的一种回调处理方式。采用这种方式需要传输数据时，不直接完成数据的传输，而是将要传输的工作分装成相应的消息(spi_message)，发送给对应的workqueue，由与workqueue关联的内核守护线程(daemon)负责具体的执行。由于workqueue会将收到的消息按时间先后顺序排列，这样就是对设备的访问严格串行化，解决了冲突。

6.spi_message

struct spi_message {
struct list_head    transfers;   //此次消息的传输队列，一个消息可以包含多个传输段
struct spi_device *spi;        //传输的目的设备
unsigned      is_dma_mapped:1;  //如果为真，此次调用提供dma和cpu虚拟地址
void          (*complete)(void *context);  //异步调用完成后的回调函数
void         *context;                    //回调函数的参数
unsigned      actual_length;               //此次传输的实际长度
int         status;                      //执行的结果，成功被置0，否则是一个负的错误码
struct list_head   queue;
void          *state;
};     

         在有消息需要传递的时候，会将spi_transfer通过自己的transfer_list字段挂到spi_message的transfers链表头上。spi_message用来原子的执行spi_transfer表示的一串数组传输请求。这个传输队列是原子的，这意味着在这个消息完成之前不会有其他消息占用总线。消息的执行总是按照FIFO的顺序。

7.spi_transfer

struct spi_transfer {   
const void *tx_buf;  //要写入设备的数据(必须是dma_safe)，或者为NULL    
void       *rx_buf;  //要读取的数据缓冲(必须是dma_safe)，或者为NULL    
unsigned   len;      //tx和rx的大小(字节数),这里不是指它的和，而是各自的长度，他们总是相等的    
dma_addr_t    tx_dma;   //如果spi_message.is_dma_mapped是真，这个是tx的dma地址    
dma_addr_t rx_dma;   //如果spi_message.is_dma_mapped是真，这个是rx的dma地址    
unsigned   cs_change:1;    //影响此次传输之后的片选，指示本次tranfer结束之后是否要重新片选并调用setup改变设置，这个标志可以较少系统开销u8        
bits_per_word;  //每个字长的比特数，如果是0，使用默认值    
u16        delay_usecs;    //此次传输结束和片选改变之间的延时，之后就会启动另一个传输或者结束整个消息    
u32       speed_hz;       //通信时钟。如果是0，使用默认值    
struct list_head transfer_list; //用来连接的双向链表节点    
};  

8.spi_master_class,spi_bus_types

truct bus_type spi_bus_type = {   
   .name       = "spi",
   .dev_attrs  = spi_dev_attrs,
   .match    = spi_match_device,
   .uevent   = spi_uevent, 
   .suspend  = spi_suspend,
   .resume   = spi_resume,
}; 
static struct class spi_master_class = {   
    .name             = "spi_master", 
    .owner           = THIS_MODULE,
    .dev_release    = spi_master_release,
}; 

spi_bus_type对应spi中的spi bus总线，spidev的类定义如下：static struct class *spidev_class; 创建这个类的主要目的是使mdev/udev能在/dev下创建设备节点/dev/spiB.C。B代表总线，C代表片外设备的片选号。 

三.主要的API

struct spi_master *spi_alloc_master(struct device *host, unsigned size);
int spi_register_master(struct spi_master *master);
void spi_unregister_master(struct spi_master *master);