SPI Subsystem SPI Driver

1. SPI driver source file directory

Linux common spi driver.

 kernel - 4.14 / drivers / spi / spi.c General interface encapsulation layer driver provided by Linux
 kernel - 4.14 / drivers / spi / spidev.c SPI generic device driver provided by linux
 kernel - 4.14 / include / linux / spi / spi.h contains the main data structures and functions of SPI provided by linux

spi controller driver, provided by IC manufacturers, with different names for different manufacturers.

 kernel - 4.14 / drivers / spi / spi - mt65xx.c MTK SPI controller driver
 kernel - 4.14 / drivers / spi / spi - mt65xx - dev.c
 kernel - 4.14 / include / linux / platform_data / spi - mt65xx.h

dts.

 kernel - 4.14 / arch / arm / boot / dts / …
 kernel - 4.14 / arch / arm64 / boot / dts / …

The above files correspond to the following SPI driver software architecture:

SPI controller driver

The SPI controller does not need to care about the specific functions of the device. It is only responsible for sending the data prepared by the upper-layer protocol driver to the SPI device according to the timing requirements of the SPI bus, and returning the data received from the device to the upper-layer protocol driver. Therefore, the kernel separates the driver program of the SPI controller.

The SPI controller driver is responsible for controlling specific controller hardware, such as DMA and interrupt operations, etc. Because multiple upper-level protocol drivers may request data transfer operations through the controller, the SPI controller driver is also responsible for queue management of these requests to ensure the first-in-first-out principle.

SPI general interface encapsulation layer

In order to simplify the programming of the SPI driver and reduce the coupling between the protocol driver and the controller driver, the kernel encapsulates some common operations of the controller driver and the protocol driver into a standard interface, plus some common logic processing operations, to form the SPI general interface encapsulation layer.

The advantage of this is that for the controller driver, it only needs to implement the standard interface callback API and register it to the general interface layer, without directly interacting with the protocol layer driver. For the protocol layer driver, it only needs to complete the registration of the device and driver through the API provided by the general interface layer, and complete the data transmission through the API of the general interface layer, without paying attention to the implementation details of the SPI controller driver.

SPI protocol driver

The specific functions of the SPI device are completed by the SPI protocol driver, which understands the functions of the device and the protocol format of the communication data. Downward, the protocol driver exchanges data with the controller through the general interface layer, and upward, the protocol driver usually interacts with other subsystems of the kernel according to the specific functions of the device.

For example, we can interact with the MTD layer to implement a storage device with an SPI interface as a file system, interact with the TTY subsystem to implement an SPI device as a TTY device, and interact with the network subsystem to implement an SPI device as a network device. If it is a proprietary SPI device, we can also implement our own proprietary protocol driver according to the protocol requirements of the device.

SPI generic device driver

Considering the variability of devices connected to the SPI controller, there is no corresponding protocol driver in the kernel. For this case, the kernel prepares a general SPI device driver for us. The general device driver provides a control interface for controlling SPI control to the user space. The specific protocol control and data transmission are completed by the user space according to the specific device. In this way, only a synchronous method can be used to communicate with the SPI device, so it is usually used for some simple SPI devices with less data volume.

2. SPI general interface layer

1. The SPI general interface layer connects the protocol driver of the specific SPI device and the SPI controller driver together.
2. Responsible for the initialization of the SPI system and the Linux device model.
3. Provides a series of standard interface APIs and their data structures for protocol drivers and controller drivers.
4. SPI devices, SPI protocol drivers, data abstraction of SPI controllers
5. Data structures defined to assist in data transfer.

kernel-4.14/drivers/spi/spi.c.

 static int __init spi_init ( void )
 {
 int status ;
 buf = kmalloc ( SPI_BUFSIZ , GFP_KERNEL ) ;
 if ( ! buf ) {
 status = -ENOMEM ;
 goto err0 ;
 }
 // Create the / sys / bus / spi node
 status = bus_register ( & spi_bus_type ) ;
 if ( status < 0 )
 goto err1 ;
 // Create / sys / class / spi_master node
 status = class_register ( & spi_master_class ) ;
 if ( status < 0 )
 goto err2 ;
 if ( IS_ENABLED ( CONFIG_SPI_SLAVE ) ) {
 status = class_register ( & spi_slave_class ) ;
 if ( status < 0 )
 goto err3 ;
 }
 ......
 }

The SPI bus is created here, and the /sys/bus/spi node and /sys/class/spi_master node are created.

Important data structures:

 spi_device
 spi_driver
 spi_board_info
 spi_controller / spi_master
 spi_transfer
 spi_message

Important APIs.

 spi_message_init
 spi_message_add_tail
 spi_sync
 spi_async
 spi_write
 spi_read

Next, we will analyze the structure and API in detail, only explaining the key parts. For a complete analysis, please refer to the official documentation:

https://www.kernel.org/doc/html/v4.14//driver-api/spi.html.

Only by being familiar with what is stored in each structure can you truly understand the SPI module.

spi_master/spi_controller: describes a spi master device.

 struct spi_master {
 // Devices in the Linux driver model
 struct device dev ;
 // The node of this spi_master device in the global spi_master linked list
 struct list_head list ;
 // This spi_master number
 s16 bus_num ;
 // The number of chip select signals supported by this spi_master
 u16 num_chipselect ;
 // dma address alignment
 u16 dma_alignment ;
 // This spi_master supports the transmission mode
 u16 mode_bits ;
 u32 bits_per_word_mask ;
 /* limits on transfer speed */
 u32 min_speed_hz ;
 u32 max_speed_hz ;
 /* other constraints relevant to this driver */
 u16 flags ;
 /* lock and mutex for SPI bus locking */
 spinlock_t bus_lock_spinlock ; // bus spin lock
 struct mutex bus_lock_mutex ; // bus mutex lock
 // Is the bus in lock state?
 bool bus_lock_flag ;
 // Prepare for transmission and set transmission parameters
 int ( * setup ) ( struct spi_device * spi ) ;
 // Transfer data
 int ( * transfer ) ( struct spi_device * spi ,
 struct spi_message * mesg ) ;
 // Clearing work when the device is released
 void ( * cleanup ) ( struct spi_device * spi ) ;
 bool ( * can_dma ) ( struct spi_master * master ,
 struct spi_device * spi ,
 struct spi_transfer * xfer ) ;
 bool queued ; // Whether to use the system serialization transmission
 struct kthread_worker kworker ; // thread worker for serialized transmission
 struct task_struct * kworker_task ; // Serialized transmission thread
 struct kthread_work pump_messages ; // Processing function for serialized transmission
 spinlock_t queue_lock ; // queue_lock for serialized transmission
 struct list_head queue ; // msg queue head for serialized transmission
 struct spi_message * cur_msg ; // Current msg during serialization transmission
 bool idling ;
 bool busy ; // Whether the thread is busy during serialization transmission
 bool running ; // Whether the thread is running during serialization transmission
 bool rt ; // Whether to transmit in real time
 ......
 int ( * prepare_transfer_hardware ) ( struct spi_master * master ) ;
 // A msg transmission implementation
 int ( * transfer_one_message ) ( struct spi_master * master ,
 struct spi_message * mesg ) ;
 ......
 /* gpio chip select */
 int * cs_gpios ;
 ......
 } ;

spi_device: describes a spi slave device.

 struct spi_device {
 // Devices in the Linux driver model
 struct device dev ;
 struct spi_master * master ; // The spi host device to which the device is connected
 u32 max_speed_hz ; // The maximum transmission rate of the device
 u8 chip_select ; // CS chip select signal number
 u8 bits_per_word ; // length of each transmission
 u16 mode ; // Transmission mode
 ......
 int irq ; // Software interrupt number
 void * controller_state ; // controller state
 void * controller_data ; // control parameters
 char modalias [ SPI_NAME_SIZE ] ; // Device name
 // GPIO number corresponding to the CS chip select signal
 int cs_gpio ; /* chip select gpio */

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

spi_driver: describes a spi device driver.

 struct spi_driver {
 // List of spi devices supported by this driver
 const struct spi_device_id * id_table ;
 int ( * probe ) ( struct spi_device * spi ) ;
 int ( * remove ) ( struct spi_device * spi ) ;
 // Callback function when the system is shut down
 void ( * shutdown ) ( struct spi_device * spi ) ;
 struct device_driver driver ;
 } ;

spi_board_info: describes the board-level information of a spi slave device, used when there is no device tree.

 struct spi_board_info {
 // Device name
 char modalias [ SPI_NAME_SIZE ] ;
 const void * platform_data ; // Device platform data
 void * controller_data ; // device controller data
 int irq ; // Device interrupt number
 u32 max_speed_hz ; // The maximum speed supported by the device
 u16 bus_num ; // The spi bus number to which the device is connected
 u16 chip_select ; // CS signal number of the device connection
 u16 mode ; // Transmission mode used by the device
 } ;

spi_transfer: describes the specific data transmitted by spi.

 struct spi_transfer {
 const void * tx_buf ; // spi_transfer send buf
 void * rx_buf ; // spi_transfer receiving buf
 unsigned len ; // spi_transfer send and receive length
 dma_addr_t tx_dma ; // dma address corresponding to tx_buf
 dma_addr_t rx_dma ; // dma address corresponding to rx_buf
 struct sg_table tx_sg ;
 struct sg_table rx_sg ;
 // After spi_transfer is completed, whether to change the CS chip select signal
 unsigned cs_change : 1 ;
 unsigned tx_nbits : 3 ;
 unsigned rx_nbits : 3 ;
 ......
 u8 bits_per_word ; // bits occupied by a word in spi_transfer
 u16 delay_usecs ; // two spi_transfer direct waiting delay
 u32 speed_hz ; // spi_transfer transmission rate

 struct list_head transfer_list ; // message node where spi_transfer is mounted
 } ;

spi_message: Information describing a spi transmission.

 struct spi_message {
 // Mount the transfer link header on this msg
 struct list_head transfers ;
 // This msg needs to communicate with the spi slave device
 struct spi_device * spi ;
 // Whether the address used is a DMA address
 unsigned is_dma_mapped : 1 ;

 // Processing function after msg is sent
 void ( * complete ) ( void * context ) ;
 void * context ; // parameters of the complete function
 unsigned frame_length ;
 unsigned actual_length ; // The number of bytes actually sent successfully by this msg
 int status ; // Sending status of this msg, 0: success, negative number: failure

 struct list_head queue ; // This msg is the linked list node in all msgs
 void * state ; // Private data of this msg
 } ;

Queuing

SPI data transmission can be done in two ways: synchronous and asynchronous.

Synchronous mode: The initiator of data transmission must wait for the end of this transmission and cannot do other things during this period. To explain it in code, after calling the transmission function, the function will not return until the data transmission is completed.

Asynchronous mode: The initiator of data transmission does not need to wait for the end of the transmission, and can do other things during the data transmission. To explain it in code, after calling the transmission function, the function will return immediately without waiting for the data transmission to be completed. We only need to set a callback function. After the transmission is completed, the callback function will be called to notify the initiator that the data transmission has been completed.

The synchronous method is simple and easy to use, and is very suitable for processing single transmission of small amounts of data. However, for transmission of large amounts of data and frequent transmissions, the asynchronous method is more suitable.

For the SPI controller, the following two conditions must be considered to support asynchronous mode:

1. For the initiator of the same data transmission, since the asynchronous method can return without waiting for the completion of data transmission, after returning, the initiator can immediately initiate another message, and the previous message has not been processed yet.
2. It is also possible for another different initiator to initiate a message transmission request at the same time.

Queuing is to solve the above problems. Queuing means putting the messages waiting to be transmitted into a waiting queue. Initiating a transmission operation actually means putting the corresponding messages into a waiting queue in order. The system will continuously detect whether there are messages waiting to be transmitted in the queue. If there are, the data transmission kernel thread will be continuously scheduled to take out the messages in the queue one by one for processing until the queue becomes empty. The SPI general interface layer implements the basic framework of queuing for us.

spi_message is an atomic operation of SPI data exchange and cannot be interrupted.

3. SPI controller driver layer

The SPI controller driver layer is responsible for the lowest level of data transmission and reception, and has the following main functions:

1. Apply for necessary hardware resources, such as interrupts, DMA channels, DMA memory buffers, etc.
2. Configure the working mode and parameters of the SPI controller so that it can correctly exchange data with the corresponding device.
3. Provide an interface to the general interface layer so that the upper layer protocol driver can access the controller driver through the general interface layer.
4. Cooperate with the general interface layer to complete the queuing and processing of the data message queue until the message queue becomes empty.

SPI master driver is the SPI controller driver of SOC. Linux kernel uses spi_master/spi_controller to represent SPI master driver. spi_master is a structure defined in include/linux/spi/spi.h file.

The core of the SPI master driver is to apply for spi_master, then initialize spi_master, and finally register spi_master with the Linux kernel.

The API is as follows:

 spi_alloc_master function: apply for spi_master.
 spi_master_put function: releases spi_master.
 spi_register_master function: registers spi_master.
 spi_unregister_master function: Unregister spi_master.
 spi_bitbang_start function: register spi_master.
 spi_bitbang_stop function: unregister spi_master.

SPI master driver loading

Take MTK as an example, the source code comes from Xiaomi open source project:

https://github.com/MiCode/Xiaomi_Kernel_OpenSource.

Every time Xiaomi starts a project, it will open source the kernel part because it needs to comply with the Linux GPL open source agreement.

【Device】Declared in the device tree

 kernel - 4.14 / arch / arm64 / boot / dts / mediatek / mt6885.dts 

【drive】

kernel-4.14/drivers/spi/spi-mt65xx.c.

After matching, the probe function is executed, spi_master is applied for, spi_master is initialized, and finally spi_master is registered with the Linux kernel.

4. Software Process

If you understand this diagram, you will have a complete understanding of the SPI driver framework.

1, 2, 3 are executed in sequence. First, the SPI bus is registered, then the SPI controller driver is loaded, and then the device driver is loaded.

The difference is that when the spi controller driver is loaded, it relies on the platform bus to match the device (controller) and the driver. When the spi device driver is loaded, it relies on the spi bus to match the device (peripheral IC) and the driver.

init flow

Call sequence diagram of spi_register_master

Queuing working mechanism and process

When the protocol driver initiates a message request through spi_async, the queue and worker threads are activated, triggering a series of operations and finally completing the message transmission operation.

spi_sync is similar to spi_async, except that there is a wait process.

5. SPI device driver

【Device】Declared in the device tree.

Note: In the device declaration, the slave device node should be included under the &spi node you want to mount, and bind the device to the master. Then specify the GPIO through the pinctrl method and operate the pinctrl handle in the driver.

【Driver】demo

The Linux kernel uses the spi_driver structure to represent the spi device driver. We need to implement spi_driver when writing SPI device drivers. The spi_driver structure is defined in the include/linux/spi/spi.h file.

 spi_register_driver: Register spi_driver
 spi_unregister_driver: destroy spi_driver 

 /* probe function */
 static int xxx_probe ( struct spi_device * spi )
 {

 /* Specific function content */
 return 0 ;
 }

 /* remove function */
 static int xxx_remove ( struct spi_device * spi )
 {

 /* Specific function content */
 return 0 ;
 }

 /* Traditional matching method ID list*/
 static const struct spi_device_id xxx_id [ ] = {

 { "xxx" , 0 } ,
 { }
 } ;

 /* Device tree matching list */
 static const struct of_device_id xxx_of_match [ ] = {

 { .compatible = "xxx" } ,
 { /* Sentinel */ }
 } ;

 /* SPI driver structure*/
 static struct spi_driver xxx_driver = {

 .probe = xxx_probe ,
 .remove = xxx_remove ,
 .driver = {
 .owner = THIS_MODULE ,
 .name = "xxx" ,
 .of_match_table = xxx_of_match ,
 } ,
 .id_table = xxx_id ,
 } ;
 /* Driver entry function */
 static int __init xxx_init ( void )
 {
 return spi_register_driver ( & xxx_driver ) ;
 }
 /* Driver export function */
 static void __exit xxx_exit ( void )
 {
 spi_unregister_driver ( & xxx_driver ) ;
 }
 module_init ( xxx_init ) ;
 module_exit ( xxx_exit ) ;

Call spi_register_driver in the driver entry function to register spi_driver.

Call spi_unregister_driver in the driver exit function to unregister spi_driver.

spi read and write data demo.

 /* SPI multi-byte transmission */
 static int spi_send ( struct spi_device * spi , u8 * buf , int len ​​)
 {
 int ret ;
 struct spi_message m ;

 struct spi_transfer t = {
 .tx_buf = buf ,
 .len = len ,
 } ;
 spi_message_init ( & m ) ; /* Initialize spi_message */
 spi_message_add_tail ( t , & m ) ; /* Add spi_transfer to spi_message queue */
 ret = spi_sync ( spi , & m ) ; /* Synchronous transmission */
 return ret ;
 }
 /* SPI multi-byte reception */
 static int spi_receive ( struct spi_device * spi , u8 * buf , int len ​​)
 {
 int ret ;
 struct spi_message m ;
 struct spi_transfer t = {
 .rx_buf = buf ,
 .len = len ,
 } ;
 spi_message_init ( & m ) ; /* Initialize spi_message */
 spi_message_add_tail ( t , & m ) ; /* Add spi_transfer to spi_message queue */
 ret = spi_sync ( spi , & m ) ; /* Synchronous transmission */
 return ret ;
 }

In addition to init, exit, probe, remove, read, and write functions, other functions are implemented according to requirements. These are the most basic.

6. Summary

Linux is a framework of buses, devices, and drivers. If you understand this framework, you can understand all module driver frameworks.

SPI driver is much simpler than I2C driver.