基于S3C2440的嵌入式Linux驱动——SPI子系统解读（一）

本文将介绍SPI子系统。内核版本为2.6.30。如有错误欢迎指正。

预备知识要求：1.SPI总线

                       2. platfrom平台

                       3. sysfs子系统

                       4. 阅读过LDD3第3，5，6，7，9，10，11章的内容。

NOTE：如果没有看过LDD3的相关内容，直接看内核源码将非常吃力！！！

PC主机：Ubuntu 和 redhat 9.0

目标板：TQ2440开发板 cpu:s3c2440 linux内核:2.6.30

0.引言

    本系列文章对Linux设备模型中的SPI子系统进行讲解。SPI子系统的讲解将分为4个部分。

   第一部分，即本篇文章，将对SPI子系统整体进行描述，同时给出SPI的相关数据结构，最后描述SPI总线的注册。

   第二部分，该文将对SPI的主控制器(master)驱动进行描述。             基于S3C2440的嵌入式Linux驱动——SPI子系统解读（二）

   第三部分，该文将对SPI设备驱动，也称protocol 驱动，进行讲解。基于S3C2440的嵌入式Linux驱动——SPI子系统解读（三）

   第四部分，通过SPI设备驱动留给用户层的API，我们将从上到下描述数据是如何通过SPI的protocol 驱动，由bitbang中转，最后由master驱动将数据传输出去。

                    基于S3C2440的嵌入式Linux驱动——SPI子系统解读（四）

1.SPI子系统综述

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

  platform_device结构中描述了SPI控制器的相关资源，同时在板级信息中将会添加spi设备的相关信息。master驱动将以platform_driver形式体现出来，也就是说

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

信息转换成spi_device，然后注册spi_device到spi总线上。spi_driver结构用于描述spi设备驱动，也将挂载到spi总线上。连同spi_driver一起注册的是字符设备，该

字符设备将提供5个API给用户空间。通过API，用户空间可以执行半双工读、半双工写和全双工读写。

2. SPI的相关数据结构

  这里将介绍内核所用到的关键数据结构，还有些结构将在用到时加以说明。

2.1 spi_master

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

[cpp] view plaincopyprint?

1. /** 
2.  * struct spi_master - interface to SPI master controller 
3.  * @dev: device interface to this driver 
4.  * @bus_num: board-specific (and often SOC-specific) identifier for a 
5.  *  given SPI controller. 
6.  * @num_chipselect: chipselects are used to distinguish individual 
7.  *  SPI slaves, and are numbered from zero to num_chipselects. 
8.  *  each slave has a chipselect signal, but it's common that not 
9.  *  every chipselect is connected to a slave. 
10.  * @dma_alignment: SPI controller constraint on DMA buffers alignment. 
11.  * @setup: updates the device mode and clocking records used by a 
12.  *  device's SPI controller; protocol code may call this.  This 
13.  *  must fail if an unrecognized or unsupported mode is requested. 
14.  *  It's always safe to call this unless transfers are pending on 
15.  *  the device whose settings are being modified. 
16.  * @transfer: adds a message to the controller's transfer queue. 
17.  * @cleanup: frees controller-specific state 
18.  * 
19.  * Each SPI master controller can communicate with one or more @spi_device 
20.  * children.  These make a small bus, sharing MOSI, MISO and SCK signals 
21.  * but not chip select signals.  Each device may be configured to use a 
22.  * different clock rate, since those shared signals are ignored unless 
23.  * the chip is selected. 
24.  * 
25.  * The driver for an SPI controller manages access to those devices through 
26.  * a queue of spi_message transactions, copying data between CPU memory and 
27.  * an SPI slave device.  For each such message it queues, it calls the 
28.  * message's completion function when the transaction completes. 
29.  */  
30. struct spi_master {  
31.     struct device   dev;  
32.   
33.     /* other than negative (== assign one dynamically), bus_num is fully 
34.      * board-specific.  usually that simplifies to being SOC-specific. 
35.      * example:  one SOC has three SPI controllers, numbered 0..2, 
36.      * and one board's schematics might show it using SPI-2.  software 
37.      * would normally use bus_num=2 for that controller. 
38.      */  
39.     s16         bus_num;  
40.   
41.     /* chipselects will be integral to many controllers; some others 
42.      * might use board-specific GPIOs. 
43.      */  
44.     u16         num_chipselect; //该值不能为0，否则会注册失败  
45.   
46.     /* some SPI controllers pose alignment requirements on DMAable 
47.      * buffers; let protocol drivers know about these requirements. 
48.      */  
49.     u16         dma_alignment;  
50.   
51.     /* Setup mode and clock, etc (spi driver may call many times). 
52.      * 
53.      * IMPORTANT:  this may be called when transfers to another 
54.      * device are active.  DO NOT UPDATE SHARED REGISTERS in ways 
55.      * which could break those transfers. 
56.      */  
57.     int         (*setup)(struct spi_device *spi);  
58.   
59.     /* bidirectional bulk transfers 
60.      * 
61.      * + The transfer() method may not sleep; its main role is 
62.      *   just to add the message to the queue. 
63.      * + For now there's no remove-from-queue operation, or 
64.      *   any other request management 
65.      * + To a given spi_device, message queueing is pure fifo 
66.      * 
67.      * + The master's main job is to process its message queue, 
68.      *   selecting a chip then transferring data 
69.      * + If there are multiple spi_device children, the i/o queue 
70.      *   arbitration algorithm is unspecified (round robin, fifo, 
71.      *   priority, reservations, preemption, etc) 
72.      * 
73.      * + Chipselect stays active during the entire message 
74.      *   (unless modified by spi_transfer.cs_change != 0). 
75.      * + The message transfers use clock and SPI mode parameters 
76.      *   previously established by setup() for this device 
77.      */  
78.     int         (*transfer)(struct spi_device *spi,  
79.                         struct spi_message *mesg);  
80.   
81.     /* called on release() to free memory provided by spi_master */  
82.     void            (*cleanup)(struct spi_device *spi);  
83. };  

/** * struct spi_master - interface to SPI master controller * @dev: device interface to this driver * @bus_num: board-specific (and often SOC-specific) identifier for a *given SPI controller. * @num_chipselect: chipselects are used to distinguish individual *SPI slaves, and are numbered from zero to num_chipselects. *each slave has a chipselect signal, but it's common that not *every chipselect is connected to a slave. * @dma_alignment: SPI controller constraint on DMA buffers alignment. * @setup: updates the device mode and clocking records used by a *device's SPI controller; protocol code may call this.  This *must fail if an unrecognized or unsupported mode is requested. *It's always safe to call this unless transfers are pending on *the device whose settings are being modified. * @transfer: adds a message to the controller's transfer queue. * @cleanup: frees controller-specific state * * Each SPI master controller can communicate with one or more @spi_device * children.  These make a small bus, sharing MOSI, MISO and SCK signals * but not chip select signals.  Each device may be configured to use a * different clock rate, since those shared signals are ignored unless * the chip is selected. * * The driver for an SPI controller manages access to those devices through * a queue of spi_message transactions, copying data between CPU memory and * an SPI slave device.  For each such message it queues, it calls the * message's completion function when the transaction completes. */struct spi_master {struct devicedev;/* other than negative (== assign one dynamically), bus_num is fully * board-specific.  usually that simplifies to being SOC-specific. * example:  one SOC has three SPI controllers, numbered 0..2, * and one board's schematics might show it using SPI-2.  software * would normally use bus_num=2 for that controller. */s16bus_num;/* chipselects will be integral to many controllers; some others * might use board-specific GPIOs. */u16num_chipselect;//该值不能为0，否则会注册失败/* some SPI controllers pose alignment requirements on DMAable * buffers; let protocol drivers know about these requirements. */u16dma_alignment;/* Setup mode and clock, etc (spi driver may call many times). * * IMPORTANT:  this may be called when transfers to another * device are active.  DO NOT UPDATE SHARED REGISTERS in ways * which could break those transfers. */int(*setup)(struct spi_device *spi);/* bidirectional bulk transfers * * + The transfer() method may not sleep; its main role is *   just to add the message to the queue. * + For now there's no remove-from-queue operation, or *   any other request management * + To a given spi_device, message queueing is pure fifo * * + The master's main job is to process its message queue, *   selecting a chip then transferring data * + If there are multiple spi_device children, the i/o queue *   arbitration algorithm is unspecified (round robin, fifo, *   priority, reservations, preemption, etc) * * + Chipselect stays active during the entire message *   (unless modified by spi_transfer.cs_change != 0). * + The message transfers use clock and SPI mode parameters *   previously established by setup() for this device */int (*transfer)(struct spi_device *spi,struct spi_message *mesg);/* called on release() to free memory provided by spi_master */void(*cleanup)(struct spi_device *spi);};

2.2 spi_device

该结构用于描述SPI设备，也就是从设备的相关信息。

NOTE：SPI子系统只支持主模式，也就是说S3C2440的SPI只能工作在master模式，外围设备只能为slave模式。

[cpp] view plaincopyprint?

1. /** 
2.  * struct spi_device - Master side proxy for an SPI slave device 
3.  * @dev: Driver model representation of the device. 
4.  * @master: SPI controller used with the device. 
5.  * @max_speed_hz: Maximum clock rate to be used with this chip 
6.  *  (on this board); may be changed by the device's driver. 
7.  *  The spi_transfer.speed_hz can override this for each transfer. 
8.  * @chip_select: Chipselect, distinguishing chips handled by @master. 
9.  * @mode: The spi mode defines how data is clocked out and in. 
10.  *  This may be changed by the device's driver. 
11.  *  The "active low" default for chipselect mode can be overridden 
12.  *  (by specifying SPI_CS_HIGH) as can the "MSB first" default for 
13.  *  each word in a transfer (by specifying SPI_LSB_FIRST). 
14.  * @bits_per_word: Data transfers involve one or more words; word sizes 
15.  *  like eight or 12 bits are common.  In-memory wordsizes are 
16.  *  powers of two bytes (e.g. 20 bit samples use 32 bits). 
17.  *  This may be changed by the device's driver, or left at the 
18.  *  default (0) indicating protocol words are eight bit bytes. 
19.  *  The spi_transfer.bits_per_word can override this for each transfer. 
20.  * @irq: Negative, or the number passed to request_irq() to receive 
21.  *  interrupts from this device. 
22.  * @controller_state: Controller's runtime state 
23.  * @controller_data: Board-specific definitions for controller, such as 
24.  *  FIFO initialization parameters; from board_info.controller_data 
25.  * @modalias: Name of the driver to use with this device, or an alias 
26.  *  for that name.  This appears in the sysfs "modalias" attribute 
27.  *  for driver coldplugging, and in uevents used for hotplugging 
28.  * 
29.  * A @spi_device is used to interchange data between an SPI slave 
30.  * (usually a discrete chip) and CPU memory. 
31.  * 
32.  * In @dev, the platform_data is used to hold information about this 
33.  * device that's meaningful to the device's protocol driver, but not 
34.  * to its controller.  One example might be an identifier for a chip 
35.  * variant with slightly different functionality; another might be 
36.  * information about how this particular board wires the chip's pins. 
37.  */  
38. struct spi_device {  
39.     struct device       dev;  
40.     struct spi_master   *master;  
41.     u32         max_speed_hz;  
42.     u8          chip_select;  
43.     u8          mode;  
44. #define SPI_CPHA    0x01            /* clock phase */  
45. #define SPI_CPOL    0x02            /* clock polarity */  
46. #define SPI_MODE_0  (0|0)           /* (original MicroWire) */  
47. #define SPI_MODE_1  (0|SPI_CPHA)  
48. #define SPI_MODE_2  (SPI_CPOL|0)   
49. #define SPI_MODE_3  (SPI_CPOL|SPI_CPHA)  
50. #define SPI_CS_HIGH 0x04            /* chipselect active high? */  
51. #define SPI_LSB_FIRST   0x08            /* per-word bits-on-wire */  
52. #define SPI_3WIRE   0x10            /* SI/SO signals shared */  
53. #define SPI_LOOP    0x20            /* loopback mode */  
54.     u8          bits_per_word;  
55.     int         irq;  
56.     void            *controller_state;  
57.     void            *controller_data;  
58.     char            modalias[32];  
59.   
60.     /* 
61.      * likely need more hooks for more protocol options affecting how 
62.      * the controller talks to each chip, like: 
63.      *  - memory packing (12 bit samples into low bits, others zeroed) 
64.      *  - priority 
65.      *  - drop chipselect after each word 
66.      *  - chipselect delays 
67.      *  - ... 
68.      */  
69. };  

/** * struct spi_device - Master side proxy for an SPI slave device * @dev: Driver model representation of the device. * @master: SPI controller used with the device. * @max_speed_hz: Maximum clock rate to be used with this chip *(on this board); may be changed by the device's driver. *The spi_transfer.speed_hz can override this for each transfer. * @chip_select: Chipselect, distinguishing chips handled by @master. * @mode: The spi mode defines how data is clocked out and in. *This may be changed by the device's driver. *The "active low" default for chipselect mode can be overridden *(by specifying SPI_CS_HIGH) as can the "MSB first" default for *each word in a transfer (by specifying SPI_LSB_FIRST). * @bits_per_word: Data transfers involve one or more words; word sizes *like eight or 12 bits are common.  In-memory wordsizes are *powers of two bytes (e.g. 20 bit samples use 32 bits). *This may be changed by the device's driver, or left at the *default (0) indicating protocol words are eight bit bytes. *The spi_transfer.bits_per_word can override this for each transfer. * @irq: Negative, or the number passed to request_irq() to receive *interrupts from this device. * @controller_state: Controller's runtime state * @controller_data: Board-specific definitions for controller, such as *FIFO initialization parameters; from board_info.controller_data * @modalias: Name of the driver to use with this device, or an alias *for that name.  This appears in the sysfs "modalias" attribute *for driver coldplugging, and in uevents used for hotplugging * * A @spi_device is used to interchange data between an SPI slave * (usually a discrete chip) and CPU memory. * * In @dev, the platform_data is used to hold information about this * device that's meaningful to the device's protocol driver, but not * to its controller.  One example might be an identifier for a chip * variant with slightly different functionality; another might be * information about how this particular board wires the chip's pins. */struct spi_device {struct devicedev;struct spi_master*master;u32max_speed_hz;u8chip_select;u8mode;#defineSPI_CPHA0x01/* clock phase */#defineSPI_CPOL0x02/* clock polarity */#defineSPI_MODE_0(0|0)/* (original MicroWire) */#defineSPI_MODE_1(0|SPI_CPHA)#defineSPI_MODE_2(SPI_CPOL|0)#defineSPI_MODE_3(SPI_CPOL|SPI_CPHA)#defineSPI_CS_HIGH0x04/* chipselect active high? */#defineSPI_LSB_FIRST0x08/* per-word bits-on-wire */#defineSPI_3WIRE0x10/* SI/SO signals shared */#defineSPI_LOOP0x20/* loopback mode */u8bits_per_word;intirq;void*controller_state;void*controller_data;charmodalias[32];/* * likely need more hooks for more protocol options affecting how * the controller talks to each chip, like: *  - memory packing (12 bit samples into low bits, others zeroed) *  - priority *  - drop chipselect after each word *  - chipselect delays *  - ... */};

2.3 spi_board_info

   该结构也是对从设备的描述，只不过它是板级信息，最终该结构的所有信息将复制给spi_device。

[cpp] view plaincopyprint?

1.  * INTERFACE between board init code and SPI infrastructure.  
2.  *  
3.  * No SPI driver ever sees these SPI device table segments, but  
4.  * it's how the SPI core (or adapters that get hotplugged) grows  
5.  * the driver model tree.  
6.  *  
7.  * As a rule, SPI devices can't be probed.  Instead, board init code  
8.  * provides a table listing the devices which are present, with enough  
9.  * information to bind and set up the device's driver.  There's basic  
10.  * support for nonstatic configurations too; enough to handle adding  
11.  * parport adapters, or microcontrollers acting as USB-to-SPI bridges.  
12.  */  
13.   
14. /** 
15.  * struct spi_board_info - board-specific template for a SPI device 
16.  * @modalias: Initializes spi_device.modalias; identifies the driver. 
17.  * @platform_data: Initializes spi_device.platform_data; the particular 
18.  *  data stored there is driver-specific. 
19.  * @controller_data: Initializes spi_device.controller_data; some 
20.  *  controllers need hints about hardware setup, e.g. for DMA. 
21.  * @irq: Initializes spi_device.irq; depends on how the board is wired. 
22.  * @max_speed_hz: Initializes spi_device.max_speed_hz; based on limits 
23.  *  from the chip datasheet and board-specific signal quality issues. 
24.  * @bus_num: Identifies which spi_master parents the spi_device; unused 
25.  *  by spi_new_device(), and otherwise depends on board wiring. 
26.  * @chip_select: Initializes spi_device.chip_select; depends on how 
27.  *  the board is wired. 
28.  * @mode: Initializes spi_device.mode; based on the chip datasheet, board 
29.  *  wiring (some devices support both 3WIRE and standard modes), and 
30.  *  possibly presence of an inverter in the chipselect path. 
31.  * 
32.  * When adding new SPI devices to the device tree, these structures serve 
33.  * as a partial device template.  They hold information which can't always 
34.  * be determined by drivers.  Information that probe() can establish (such 
35.  * as the default transfer wordsize) is not included here. 
36.  * 
37.  * These structures are used in two places.  Their primary role is to 
38.  * be stored in tables of board-specific device descriptors, which are 
39.  * declared early in board initialization and then used (much later) to 
40.  * populate a controller's device tree after the that controller's driver 
41.  * initializes.  A secondary (and atypical) role is as a parameter to 
42.  * spi_new_device() call, which happens after those controller drivers 
43.  * are active in some dynamic board configuration models. 
44.  */  
45. struct spi_board_info {  
46.     /* the device name and module name are coupled, like platform_bus; 
47.      * "modalias" is normally the driver name. 
48.      * 
49.      * platform_data goes to spi_device.dev.platform_data, 
50.      * controller_data goes to spi_device.controller_data, 
51.      * irq is copied too 
52.      */  
53.     char        modalias[32];  
54.     const void  *platform_data;  
55.     void        *controller_data;  
56.     int     irq;  
57.   
58.     /* slower signaling on noisy or low voltage boards */  
59.     u32     max_speed_hz;  
60.   
61.   
62.     /* bus_num is board specific and matches the bus_num of some 
63.      * spi_master that will probably be registered later. 
64.      * 
65.      * chip_select reflects how this chip is wired to that master; 
66.      * it's less than num_chipselect. 
67.      */  
68.     u16     bus_num;  
69.     u16     chip_select;  
70.   
71.     /* mode becomes spi_device.mode, and is essential for chips 
72.      * where the default of SPI_CS_HIGH = 0 is wrong. 
73.      */  
74.     u8      mode;  
75.   
76.     /* ... may need additional spi_device chip config data here. 
77.      * avoid stuff protocol drivers can set; but include stuff 
78.      * needed to behave without being bound to a driver: 
79.      *  - quirks like clock rate mattering when not selected 
80.      */  
81. };  

 * INTERFACE between board init code and SPI infrastructure. * * No SPI driver ever sees these SPI device table segments, but * it's how the SPI core (or adapters that get hotplugged) grows * the driver model tree. * * As a rule, SPI devices can't be probed.  Instead, board init code * provides a table listing the devices which are present, with enough * information to bind and set up the device's driver.  There's basic * support for nonstatic configurations too; enough to handle adding * parport adapters, or microcontrollers acting as USB-to-SPI bridges. *//** * struct spi_board_info - board-specific template for a SPI device * @modalias: Initializes spi_device.modalias; identifies the driver. * @platform_data: Initializes spi_device.platform_data; the particular *data stored there is driver-specific. * @controller_data: Initializes spi_device.controller_data; some *controllers need hints about hardware setup, e.g. for DMA. * @irq: Initializes spi_device.irq; depends on how the board is wired. * @max_speed_hz: Initializes spi_device.max_speed_hz; based on limits *from the chip datasheet and board-specific signal quality issues. * @bus_num: Identifies which spi_master parents the spi_device; unused *by spi_new_device(), and otherwise depends on board wiring. * @chip_select: Initializes spi_device.chip_select; depends on how *the board is wired. * @mode: Initializes spi_device.mode; based on the chip datasheet, board *wiring (some devices support both 3WIRE and standard modes), and *possibly presence of an inverter in the chipselect path. * * When adding new SPI devices to the device tree, these structures serve * as a partial device template.  They hold information which can't always * be determined by drivers.  Information that probe() can establish (such * as the default transfer wordsize) is not included here. * * These structures are used in two places.  Their primary role is to * be stored in tables of board-specific device descriptors, which are * declared early in board initialization and then used (much later) to * populate a controller's device tree after the that controller's driver * initializes.  A secondary (and atypical) role is as a parameter to * spi_new_device() call, which happens after those controller drivers * are active in some dynamic board configuration models. */struct spi_board_info {/* the device name and module name are coupled, like platform_bus; * "modalias" is normally the driver name. * * platform_data goes to spi_device.dev.platform_data, * controller_data goes to spi_device.controller_data, * irq is copied too */charmodalias[32];const void*platform_data;void*controller_data;intirq;/* slower signaling on noisy or low voltage boards */u32max_speed_hz;/* bus_num is board specific and matches the bus_num of some * spi_master that will probably be registered later. * * chip_select reflects how this chip is wired to that master; * it's less than num_chipselect. */u16bus_num;u16chip_select;/* mode becomes spi_device.mode, and is essential for chips * where the default of SPI_CS_HIGH = 0 is wrong. */u8mode;/* ... may need additional spi_device chip config data here. * avoid stuff protocol drivers can set; but include stuff * needed to behave without being bound to a driver: *  - quirks like clock rate mattering when not selected */};

2.4 spi_driver

    该结构用于描述SPI设备驱动。

[cpp] view plaincopyprint?

1. 驱动核心将根据driver.name和spi_board_info 的modalias进行匹配，如过modalia和name相等，则绑定驱动程序和SPI设备。  
2. /** 
3.  * struct spi_driver - Host side "protocol" driver 
4.  * @probe: Binds this driver to the spi device.  Drivers can verify 
5.  *  that the device is actually present, and may need to configure 
6.  *  characteristics (such as bits_per_word) which weren't needed for 
7.  *  the initial configuration done during system setup. 
8.  * @remove: Unbinds this driver from the spi device 
9.  * @shutdown: Standard shutdown callback used during system state 
10.  *  transitions such as powerdown/halt and kexec 
11.  * @suspend: Standard suspend callback used during system state transitions 
12.  * @resume: Standard resume callback used during system state transitions 
13.  * @driver: SPI device drivers should initialize the name and owner 
14.  *  field of this structure. 
15.  * 
16.  * This represents the kind of device driver that uses SPI messages to 
17.  * interact with the hardware at the other end of a SPI link.  It's called 
18.  * a "protocol" driver because it works through messages rather than talking 
19.  * directly to SPI hardware (which is what the underlying SPI controller 
20.  * driver does to pass those messages).  These protocols are defined in the 
21.  * specification for the device(s) supported by the driver. 
22.  * 
23.  * As a rule, those device protocols represent the lowest level interface 
24.  * supported by a driver, and it will support upper level interfaces too. 
25.  * Examples of such upper levels include frameworks like MTD, networking, 
26.  * MMC, RTC, filesystem character device nodes, and hardware monitoring. 
27.  */  
28. struct spi_driver {  
29.     int         (*probe)(struct spi_device *spi);  
30.     int         (*remove)(struct spi_device *spi);  
31.     void            (*shutdown)(struct spi_device *spi);  
32.     int         (*suspend)(struct spi_device *spi, pm_message_t mesg);  
33.     int         (*resume)(struct spi_device *spi);  
34.     struct device_driver     driver;  
35. };  

驱动核心将根据driver.name和spi_board_info 的modalias进行匹配，如过modalia和name相等，则绑定驱动程序和SPI设备。/** * struct spi_driver - Host side "protocol" driver * @probe: Binds this driver to the spi device.  Drivers can verify *that the device is actually present, and may need to configure *characteristics (such as bits_per_word) which weren't needed for *the initial configuration done during system setup. * @remove: Unbinds this driver from the spi device * @shutdown: Standard shutdown callback used during system state *transitions such as powerdown/halt and kexec * @suspend: Standard suspend callback used during system state transitions * @resume: Standard resume callback used during system state transitions * @driver: SPI device drivers should initialize the name and owner *field of this structure. * * This represents the kind of device driver that uses SPI messages to * interact with the hardware at the other end of a SPI link.  It's called * a "protocol" driver because it works through messages rather than talking * directly to SPI hardware (which is what the underlying SPI controller * driver does to pass those messages).  These protocols are defined in the * specification for the device(s) supported by the driver. * * As a rule, those device protocols represent the lowest level interface * supported by a driver, and it will support upper level interfaces too. * Examples of such upper levels include frameworks like MTD, networking, * MMC, RTC, filesystem character device nodes, and hardware monitoring. */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;};

2.5 spi_transfer

  该数据结构是对一次完整的数据传输的描述。

[cpp] view plaincopyprint?

1. <SPAN style="FONT-SIZE: 12px">/* 
2.  * I/O INTERFACE between SPI controller and protocol drivers 
3.  * 
4.  * Protocol drivers use a queue of spi_messages, each transferring data 
5.  * between the controller and memory buffers. 
6.  * 
7.  * The spi_messages themselves consist of a series of read+write transfer 
8.  * segments.  Those segments always read the same number of bits as they 
9.  * write; but one or the other is easily ignored by passing a null buffer 
10.  * pointer.  (This is unlike most types of I/O API, because SPI hardware 
11.  * is full duplex.) 
12.  * 
13.  * NOTE:  Allocation of spi_transfer and spi_message memory is entirely 
14.  * up to the protocol driver, which guarantees the integrity of both (as 
15.  * well as the data buffers) for as long as the message is queued. 
16.  */  
17.   
18. /** 
19.  * struct spi_transfer - a read/write buffer pair 
20.  * @tx_buf: data to be written (dma-safe memory), or NULL 
21.  * @rx_buf: data to be read (dma-safe memory), or NULL 
22.  * @tx_dma: DMA address of tx_buf, if @spi_message.is_dma_mapped 
23.  * @rx_dma: DMA address of rx_buf, if @spi_message.is_dma_mapped 
24.  * @len: size of rx and tx buffers (in bytes) 
25.  * @speed_hz: Select a speed other than the device default for this 
26.  *      transfer. If 0 the default (from @spi_device) is used. 
27.  * @bits_per_word: select a bits_per_word other than the device default 
28.  *      for this transfer. If 0 the default (from @spi_device) is used. 
29.  * @cs_change: affects chipselect after this transfer completes 
30.  * @delay_usecs: microseconds to delay after this transfer before 
31.  *  (optionally) changing the chipselect status, then starting 
32.  *  the next transfer or completing this @spi_message. 
33.  * @transfer_list: transfers are sequenced through @spi_message.transfers 
34.  * 
35.  * SPI transfers always write the same number of bytes as they read. 
36.  * Protocol drivers should always provide @rx_buf and/or @tx_buf. 
37.  * In some cases, they may also want to provide DMA addresses for 
38.  * the data being transferred; that may reduce overhead, when the 
39.  * underlying driver uses dma. 
40.  * 
41.  * If the transmit buffer is null, zeroes will be shifted out 
42.  * while filling @rx_buf.  If the receive buffer is null, the data 
43.  * shifted in will be discarded.  Only "len" bytes shift out (or in). 
44.  * It's an error to try to shift out a partial word.  (For example, by 
45.  * shifting out three bytes with word size of sixteen or twenty bits; 
46.  * the former uses two bytes per word, the latter uses four bytes.) 
47.  * 
48.  * In-memory data values are always in native CPU byte order, translated 
49.  * from the wire byte order (big-endian except with SPI_LSB_FIRST).  So 
50.  * for example when bits_per_word is sixteen, buffers are 2N bytes long 
51.  * (@len = 2N) and hold N sixteen bit words in CPU byte order. 
52.  * 
53.  * When the word size of the SPI transfer is not a power-of-two multiple 
54.  * of eight bits, those in-memory words include extra bits.  In-memory 
55.  * words are always seen by protocol drivers as right-justified, so the 
56.  * undefined (rx) or unused (tx) bits are always the most significant bits. 
57.  * 
58.  * All SPI transfers start with the relevant chipselect active.  Normally 
59.  * it stays selected until after the last transfer in a message.  Drivers 
60.  * can affect the chipselect signal using cs_change. 
61.  * 
62.  * (i) If the transfer isn't the last one in the message, this flag is 
63.  * used to make the chipselect briefly go inactive in the middle of the 
64.  * message.  Toggling chipselect in this way may be needed to terminate 
65.  * a chip command, letting a single spi_message perform all of group of 
66.  * chip transactions together. 
67.  * 
68.  * (ii) When the transfer is the last one in the message, the chip may 
69.  * stay selected until the next transfer.  On multi-device SPI busses 
70.  * with nothing blocking messages going to other devices, this is just 
71.  * a performance hint; starting a message to another device deselects 
72.  * this one.  But in other cases, this can be used to ensure correctness. 
73.  * Some devices need protocol transactions to be built from a series of 
74.  * spi_message submissions, where the content of one message is determined 
75.  * by the results of previous messages and where the whole transaction 
76.  * ends when the chipselect goes intactive. 
77.  * 
78.  * The code that submits an spi_message (and its spi_transfers) 
79.  * to the lower layers is responsible for managing its memory. 
80.  * Zero-initialize every field you don't set up explicitly, to 
81.  * insulate against future API updates.  After you submit a message 
82.  * and its transfers, ignore them until its completion callback. 
83.  */  
84. struct spi_transfer {  
85.     /* it's ok if tx_buf == rx_buf (right?) 
86.      * for MicroWire, one buffer must be null 
87.      * buffers must work with dma_*map_single() calls, unless 
88.      *   spi_message.is_dma_mapped reports a pre-existing mapping 
89.      */  
90.     const void  *tx_buf;  
91.     void        *rx_buf;  
92.     unsigned    len;  
93.   
94.     dma_addr_t  tx_dma;  
95.     dma_addr_t  rx_dma;  
96.   
97.     unsigned    cs_change:1;  
98.     u8      bits_per_word;  
99.     u16     delay_usecs;  
100.     u32     speed_hz;  
101.   
102.     struct list_head transfer_list;  
103. };</SPAN>  

/* * I/O INTERFACE between SPI controller and protocol drivers * * Protocol drivers use a queue of spi_messages, each transferring data * between the controller and memory buffers. * * The spi_messages themselves consist of a series of read+write transfer * segments.  Those segments always read the same number of bits as they * write; but one or the other is easily ignored by passing a null buffer * pointer.  (This is unlike most types of I/O API, because SPI hardware * is full duplex.) * * NOTE:  Allocation of spi_transfer and spi_message memory is entirely * up to the protocol driver, which guarantees the integrity of both (as * well as the data buffers) for as long as the message is queued. *//** * struct spi_transfer - a read/write buffer pair * @tx_buf: data to be written (dma-safe memory), or NULL * @rx_buf: data to be read (dma-safe memory), or NULL * @tx_dma: DMA address of tx_buf, if @spi_message.is_dma_mapped * @rx_dma: DMA address of rx_buf, if @spi_message.is_dma_mapped * @len: size of rx and tx buffers (in bytes) * @speed_hz: Select a speed other than the device default for this *      transfer. If 0 the default (from @spi_device) is used. * @bits_per_word: select a bits_per_word other than the device default *      for this transfer. If 0 the default (from @spi_device) is used. * @cs_change: affects chipselect after this transfer completes * @delay_usecs: microseconds to delay after this transfer before *(optionally) changing the chipselect status, then starting *the next transfer or completing this @spi_message. * @transfer_list: transfers are sequenced through @spi_message.transfers * * SPI transfers always write the same number of bytes as they read. * Protocol drivers should always provide @rx_buf and/or @tx_buf. * In some cases, they may also want to provide DMA addresses for * the data being transferred; that may reduce overhead, when the * underlying driver uses dma. * * If the transmit buffer is null, zeroes will be shifted out * while filling @rx_buf.  If the receive buffer is null, the data * shifted in will be discarded.  Only "len" bytes shift out (or in). * It's an error to try to shift out a partial word.  (For example, by * shifting out three bytes with word size of sixteen or twenty bits; * the former uses two bytes per word, the latter uses four bytes.) * * In-memory data values are always in native CPU byte order, translated * from the wire byte order (big-endian except with SPI_LSB_FIRST).  So * for example when bits_per_word is sixteen, buffers are 2N bytes long * (@len = 2N) and hold N sixteen bit words in CPU byte order. * * When the word size of the SPI transfer is not a power-of-two multiple * of eight bits, those in-memory words include extra bits.  In-memory * words are always seen by protocol drivers as right-justified, so the * undefined (rx) or unused (tx) bits are always the most significant bits. * * All SPI transfers start with the relevant chipselect active.  Normally * it stays selected until after the last transfer in a message.  Drivers * can affect the chipselect signal using cs_change. * * (i) If the transfer isn't the last one in the message, this flag is * used to make the chipselect briefly go inactive in the middle of the * message.  Toggling chipselect in this way may be needed to terminate * a chip command, letting a single spi_message perform all of group of * chip transactions together. * * (ii) When the transfer is the last one in the message, the chip may * stay selected until the next transfer.  On multi-device SPI busses * with nothing blocking messages going to other devices, this is just * a performance hint; starting a message to another device deselects * this one.  But in other cases, this can be used to ensure correctness. * Some devices need protocol transactions to be built from a series of * spi_message submissions, where the content of one message is determined * by the results of previous messages and where the whole transaction * ends when the chipselect goes intactive. * * The code that submits an spi_message (and its spi_transfers) * to the lower layers is responsible for managing its memory. * Zero-initialize every field you don't set up explicitly, to * insulate against future API updates.  After you submit a message * and its transfers, ignore them until its completion callback. */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;void*rx_buf;unsignedlen;dma_addr_ttx_dma;dma_addr_trx_dma;unsignedcs_change:1;u8bits_per_word;u16delay_usecs;u32speed_hz;struct list_head transfer_list;};

2.6 spi_message

   该结构就是对多个spi_transfer的封装。

[cpp] view plaincopyprint?

1. <SPAN style="FONT-SIZE: 12px">/** 
2.  * struct spi_message - one multi-segment SPI transaction 
3.  * @transfers: list of transfer segments in this transaction 
4.  * @spi: SPI device to which the transaction is queued 
5.  * @is_dma_mapped: if true, the caller provided both dma and cpu virtual 
6.  *  addresses for each transfer buffer 
7.  * @complete: called to report transaction completions 
8.  * @context: the argument to complete() when it's called 
9.  * @actual_length: the total number of bytes that were transferred in all 
10.  *  successful segments 
11.  * @status: zero for success, else negative errno 
12.  * @queue: for use by whichever driver currently owns the message 
13.  * @state: for use by whichever driver currently owns the message 
14.  * 
15.  * A @spi_message is used to execute an atomic sequence of data transfers, 
16.  * each represented by a struct spi_transfer.  The sequence is "atomic" 
17.  * in the sense that no other spi_message may use that SPI bus until that 
18.  * sequence completes.  On some systems, many such sequences can execute as 
19.  * as single programmed DMA transfer.  On all systems, these messages are 
20.  * queued, and might complete after transactions to other devices.  Messages 
21.  * sent to a given spi_device are alway executed in FIFO order. 
22.  * 
23.  * The code that submits an spi_message (and its spi_transfers) 
24.  * to the lower layers is responsible for managing its memory. 
25.  * Zero-initialize every field you don't set up explicitly, to 
26.  * insulate against future API updates.  After you submit a message 
27.  * and its transfers, ignore them until its completion callback. 
28.  */  
29. struct spi_message {  
30.     struct list_head    transfers;  
31.   
32.     struct spi_device   *spi;  
33.   
34.     unsigned        is_dma_mapped:1;  
35.   
36.     /* REVISIT:  we might want a flag affecting the behavior of the 
37.      * last transfer ... allowing things like "read 16 bit length L" 
38.      * immediately followed by "read L bytes".  Basically imposing 
39.      * a specific message scheduling algorithm. 
40.      * 
41.      * Some controller drivers (message-at-a-time queue processing) 
42.      * could provide that as their default scheduling algorithm.  But 
43.      * others (with multi-message pipelines) could need a flag to 
44.      * tell them about such special cases. 
45.      */  
46.   
47.     /* completion is reported through a callback */  
48.     void            (*complete)(void *context);  
49.     void            *context;  
50.     unsigned        actual_length;  
51.     int         status;  
52.   
53.     /* for optional use by whatever driver currently owns the 
54.      * spi_message ...  between calls to spi_async and then later 
55.      * complete(), that's the spi_master controller driver. 
56.      */  
57.     struct list_head    queue;  
58.     void            *state;  
59. };</SPAN>  

/** * struct spi_message - one multi-segment SPI transaction * @transfers: list of transfer segments in this transaction * @spi: SPI device to which the transaction is queued * @is_dma_mapped: if true, the caller provided both dma and cpu virtual *addresses for each transfer buffer * @complete: called to report transaction completions * @context: the argument to complete() when it's called * @actual_length: the total number of bytes that were transferred in all *successful segments * @status: zero for success, else negative errno * @queue: for use by whichever driver currently owns the message * @state: for use by whichever driver currently owns the message * * A @spi_message is used to execute an atomic sequence of data transfers, * each represented by a struct spi_transfer.  The sequence is "atomic" * in the sense that no other spi_message may use that SPI bus until that * sequence completes.  On some systems, many such sequences can execute as * as single programmed DMA transfer.  On all systems, these messages are * queued, and might complete after transactions to other devices.  Messages * sent to a given spi_device are alway executed in FIFO order. * * The code that submits an spi_message (and its spi_transfers) * to the lower layers is responsible for managing its memory. * Zero-initialize every field you don't set up explicitly, to * insulate against future API updates.  After you submit a message * and its transfers, ignore them until its completion callback. */struct spi_message {struct list_headtransfers;struct spi_device*spi;unsignedis_dma_mapped:1;/* 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;unsignedactual_length;intstatus;/* 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_headqueue;void*state;};

2.7 spi_bitbang

[cpp] view plaincopyprint?

1. <SPAN style="FONT-SIZE: 12px">struct spi_bitbang {  
2.     struct workqueue_struct *workqueue;  
3.     struct work_struct  work;  
4.   
5.     spinlock_t      lock;  
6.     struct list_head    queue;  
7.     u8          busy;  
8.     u8          use_dma;  
9.     u8          flags;      /* extra spi->mode support */  
10.   
11.     struct spi_master   *master;  
12.   
13.     /* setup_transfer() changes clock and/or wordsize to match settings 
14.      * for this transfer; zeroes restore defaults from spi_device. 
15.      */  
16.     int (*setup_transfer)(struct spi_device *spi,  
17.             struct spi_transfer *t);  
18.   
19.     void    (*chipselect)(struct spi_device *spi, int is_on);  
20. #define BITBANG_CS_ACTIVE   1   /* normally nCS, active low */  
21. #define BITBANG_CS_INACTIVE 0  
22.   
23.     /* txrx_bufs() may handle dma mapping for transfers that don't 
24.      * already have one (transfer.{tx,rx}_dma is zero), or use PIO 
25.      */  
26.     int (*txrx_bufs)(struct spi_device *spi, struct spi_transfer *t);  
27.   
28.     /* txrx_word[SPI_MODE_*]() just looks like a shift register */  
29.     u32 (*txrx_word[4])(struct spi_device *spi,  
30.             unsigned nsecs,  
31.             u32 word, u8 bits);  
32. };</SPAN>  

struct spi_bitbang {struct workqueue_struct*workqueue;struct work_structwork;spinlock_tlock;struct list_headqueue;u8busy;u8use_dma;u8flags;/* extra spi->mode support */struct spi_master*master;/* setup_transfer() changes clock and/or wordsize to match settings * for this transfer; zeroes restore defaults from spi_device. */int(*setup_transfer)(struct spi_device *spi,struct spi_transfer *t);void(*chipselect)(struct spi_device *spi, int is_on);#defineBITBANG_CS_ACTIVE1/* normally nCS, active low */#defineBITBANG_CS_INACTIVE0/* txrx_bufs() may handle dma mapping for transfers that don't * already have one (transfer.{tx,rx}_dma is zero), or use PIO */int(*txrx_bufs)(struct spi_device *spi, struct spi_transfer *t);/* txrx_word[SPI_MODE_*]() just looks like a shift register */u32(*txrx_word[4])(struct spi_device *spi,unsigned nsecs,u32 word, u8 bits);};

3. 注册SPI总线

    下列函数位于drivers/spi/spi.c中。

[cpp] view plaincopyprint?

1. struct bus_type spi_bus_type = {  
2.     .name        = "spi",  
3.     .dev_attrs    = spi_dev_attrs,  
4.     .match        = spi_match_device,  
5.     .uevent        = spi_uevent,  
6.     .suspend    = spi_suspend,  
7.     .resume        = spi_resume,  
8. };  
9. EXPORT_SYMBOL_GPL(spi_bus_type);  
10.   
11. static struct class spi_master_class = {  
12.     .name        = "spi_master",  
13.     .owner        = THIS_MODULE,  
14.     .dev_release    = spi_master_release,  
15. };  
16.   
17. /* portable code must never pass more than 32 bytes */  
18. #define    SPI_BUFSIZ    max(32,SMP_CACHE_BYTES)  
19.   
20. static u8    *buf;  
21.   
22. static int __init spi_init(void)  
23. {  
24.     int status;  
25.   
26.     buf = kmalloc(SPI_BUFSIZ, GFP_KERNEL);  
27.     if (!buf) {  
28.         status = -ENOMEM;  
29.         goto err0;  
30.     }  
31.   
32.     status = bus_register(&spi_bus_type);       /*注册SPI总线*/  
33.     if (status < 0)  
34.         goto err1;  
35.   
36.     status = class_register(&spi_master_class);/*注册SPI类*/  
37.     if (status < 0)  
38.         goto err2;  
39.     return 0;  
40.   
41. err2:  
42.     bus_unregister(&spi_bus_type);  
43. err1:  
44.     kfree(buf);  
45.     buf = NULL;  
46. err0:  
47.     return status;  
48. }  
49.   
50. /* board_info is normally registered in arch_initcall(), 
51.  * but even essential drivers wait till later 
52.  * 
53.  * REVISIT only boardinfo really needs static linking. the rest (device and 
54.  * driver registration) _could_ be dynamically linked (modular) ... costs 
55.  * include needing to have boardinfo data structures be much more public. 
56.  */  
57. postcore_initcall(spi_init);  

struct 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,};EXPORT_SYMBOL_GPL(spi_bus_type);static struct class spi_master_class = {    .name        = "spi_master",    .owner        = THIS_MODULE,    .dev_release    = spi_master_release,};/* portable code must never pass more than 32 bytes */#define    SPI_BUFSIZ    max(32,SMP_CACHE_BYTES)static u8    *buf;static int __init spi_init(void){intstatus;buf = kmalloc(SPI_BUFSIZ, GFP_KERNEL);if (!buf) {status = -ENOMEM;goto err0;}status = bus_register(&spi_bus_type);/*注册SPI总线*/if (status < 0)goto err1;status = class_register(&spi_master_class);/*注册SPI类*/if (status < 0)goto err2;return 0;err2:bus_unregister(&spi_bus_type);err1:kfree(buf);buf = NULL;err0:return status;}/* board_info is normally registered in arch_initcall(), * but even essential drivers wait till later * * REVISIT only boardinfo really needs static linking. the rest (device and * driver registration) _could_ be dynamically linked (modular) ... costs * include needing to have boardinfo data structures be much more public. */postcore_initcall(spi_init);

    spi_init函数注册SPI总线以及SPI类到内核中。该函数在内核初始化的postcore_initcall阶段被调用。

    顺便看看下总线的匹配函数。

     下列函数位于drivers/spi/spi.c中。

[cpp] view plaincopyprint?

1. /* modalias support makes "modprobe $MODALIAS" new-style hotplug work, 
2.  * and the sysfs version makes coldplug work too. 
3.  */  
4.   
5. static int spi_match_device(struct device *dev, struct device_driver *drv)  
6. {  
7.     const struct spi_device *spi = to_spi_device(dev);  
8.   
9.     return strcmp(spi->modalias, drv->name) == 0;  
10. }  

/* modalias support makes "modprobe $MODALIAS" new-style hotplug work, * and the sysfs version makes coldplug work too. */static int spi_match_device(struct device *dev, struct device_driver *drv){const struct spi_device*spi = to_spi_device(dev);return strcmp(spi->modalias, drv->name) == 0;}

   从这里我们可以看出，SPI设备和驱动的匹配是通过device的modalias字段和driver的name字段，这两个字段相等则绑定设备和驱动。