Understanding of linux SPI driver Model

The kernel SPI subsystem is divided into Controller Driver and Protocol Drivers.

Controller Driver
A controller driver is represented by the structure spi_master. The driver for an SPI controller manages access to spi slave 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.

Protocol Driver
A Protocol driver is represented by the structure spi_driver, they pass messages through the controller driver to communicate with a Slave or Master device on the other side of an SPI link. 

Initializing and probing of SPI Controller Driver

For embedded System-on-Chip (SOC) based boards, SPI master controllers connect to their drivers using some non SPI bus, such as the platform bus. Initializing and probing SPI controller driver is performed using the platform bus. During the initial stage of platform driver registration stage of probe() in that code includes calling spi_alloc_master which allocated the structure spi_master in the kernel and during final stage calling spi_register_master() to hook up to this SPI bus glue.

SPI controller’s will usually be platform devices, and the controller may need some platform_data in order to operate properly. The “struct platform_device” will include resources like the physical address of the controller’s first register and its IRQ.

Platforms will often abstract the “register SPI controller” operation,maybe coupling it with code to initialize pin configurations in the board initialization files. This is because most SOCs have several SPI-capable controllers, and only the ones actually usable on a given board should normally be set up and registered.

1 /* spi bus : spi0 */
2 static struct platform_device mysoc_spi_dev0 = {
3 .name = “mysoc_spi”,
4 .id = 0,
5 . resource = &mysoc_spi_resources [0] ,
6 . num_resources = 2,
7 . dev = {
8 . platform_data = &mysoc_spi_dev0_data ,
9 },
10 };
11
21 static int __init mysoc_spi_init ( void )
22 {
23 …
24 platform_device_register (&mysoc_spi_dev0 );
25 …
28 }
29

 Listing 1: Registration of the SPI platform device with the platform bus.

On the driver’s side, the registration with the platform bus is achieved by populating a structure platform_driver and passing it to the macro module_platform_driver() as argument (Listing-2). The platform bus simply compares the driver.name member against the name of each device, as defined in the platform_device data structure (Listing 1); if they are the same the device matches the platform driver.

1 # define DRIVER_NAME “mysoc_spi”
2
3 static struct platform_driver mysoc_spi_driver = {
4 .probe = mysoc_spi_probe ,
5 .remove = mysoc_spi_remove,
6 .driver = {
7 .name = DRIVER_NAME ,
8 .owner = THIS_MODULE ,
9 .pm = &mysoc_spi_pm_ops ,
10 },
11 };
12 module_platform_driver ( mysoc_spi_driver );

Listing 2: Registration of the SPI platform driver with the platform bus.

 

As usual, binding a device to a driver involves calling the driver’s probe() function passing a pointer to the device as a parameter. The SPI controller driver registers with the SPI subsystem by using a structure spi_master that is instantiated and initialized by the SPI platform driver’s probe() function, as shown in Listing 3.

The sequence of operations performed on probing are the following:

1. Get the device resource definitions.
2. Allocate the appropriate memory and remap it to a virtual address for being accessed by the kernel.
3. Load the device settings.
4. Configure the device hardware.
5. Register with the power management system.
6. Create the per-device sysfs nodes.
7. Request the interrupt and register the IRQ.
8. Set up the struct spi_master and register the master controller driver with the SPI core.

On successful completion of above steps the driver is bounded to the devices representing the mysoc SPI controllers.

1 /* Probe function */
2 static int mysoc_spi_probe ( struct platform_device * pdev )
3 {
4 …
5 struct spi_master *master;
6 …
7 /* Allocate master */
8 master = spi_alloc_master(&pdev->dev, sizeof(struct spi_master));
9 …
10 /* Register with the SPI framework */
11 status = spi_register_master(master);
12 …
14 }

Listing 3: Registration of the SPI Controller Driver.

Analysis of SPI sub system

The SPI subsystem in Linux initialization is starting from the spi_init function in the drivers/spi/spi.c file, have a look the definition:

00001025 static int __init spi_init(void)
00001026 {
00001027     int    status;
00001028 
00001029     buf = kmalloc(SPI_BUFSIZ, GFP_KERNEL);
00001030     if (!buf) {
00001031         status = -ENOMEM;
00001032         goto err0;
00001033     }
00001034 
00001035     status = bus_register(&spi_bus_type);
00001036     if (status <0)
00001037         goto err1;
00001038 
00001039     status = class_register(&spi_master_class);
00001040     if (status <0)
00001041         goto err2;
00001042     return 0;
00001043 
00001044 err2:
00001045     bus_unregister(&spi_bus_type);
00001046 err1:
00001047     kfree(buf);
00001048     buf = NULL;
00001049 err0:
00001050     return status;
00001051 }

The 1029 line, distribution of SPI buf memory, where buf and SPI_BUFSIZ are defined in the spi.c file:

00000945 #define    SPI_BUFSIZ    max(32,SMP_CACHE_BYTES)
00000946 
00000947 static u8    *buf;

The 1035 line, register the SPI bus, is also in the spi.c file:

00000145 struct bus_type spi_bus_type = {
00000146     .name        = "spi",
00000147     .dev_attrs    = spi_dev_attrs,
00000148     .match        = spi_match_device,
00000149     .uevent        = spi_uevent,
00000150     .suspend        = spi_suspend,
00000151     .resume        = spi_resume,
00000152 };

The 146 line, bus name is SPI.

The 148 line, the more important, spi_match_device is the function driver on SPI bus equipment and equipment matching, is also in the spi.c file:

00000085 static int spi_match_device(struct device *dev, struct device_driver *drv)
00000086 {
00000087     const struct spi_device    *spi = to_spi_device(dev);
00000088     const struct spi_driver    *sdrv = to_spi_driver(drv);
00000089 
00000090     /* Attempt an OF style match */
00000091     if (of_driver_match_device(dev, drv))
00000092         return 1;
00000093 
00000094     if (sdrv->id_table)
00000095         return !!spi_match_id(sdrv->id_table, spi);
00000096 
00000097     return strcmp(spi->modalias, drv->name) == 0;
00000098 }

Write driver should know platform bus with struct platform_device and struct platform_driver, to SPI bus, of course, also have the corresponding struct spi_device and struct spi_driver, as indicated by the 87,88 row. 87, the definition of struct spi_device is in the include/linux/spi/spi.h:

00000069 struct spi_device {
00000070     struct device        dev;
00000071     struct spi_master    *master;
00000072     u32            max_speed_hz;
00000073     u8            chip_select;
00000074     u8            mode;
00000075 #define    SPI_CPHA    0x01            /* clock phase */
00000076 #define    SPI_CPOL    0x02            /* clock polarity */
00000077 #define    SPI_MODE_0    (0|0)            /* (original MicroWire) */
00000078 #define    SPI_MODE_1    (0|SPI_CPHA)
00000079 #define    SPI_MODE_2    (SPI_CPOL|0)
00000080 #define    SPI_MODE_3    (SPI_CPOL|SPI_CPHA)
00000081 #define    SPI_CS_HIGH    0x04            /* chipselect active high? */
00000082 #define    SPI_LSB_FIRST    0x08            /* per-word bits-on-wire */
00000083 #define    SPI_3WIRE    0x10            /* SI/SO signals shared */
00000084 #define    SPI_LOOP    0x20            /* loopback mode */
00000085 #define    SPI_NO_CS    0x40            /* 1 dev/bus, no chipselect */
00000086 #define    SPI_READY    0x80            /* slave pulls low to pause */
00000087     u8            bits_per_word;
00000088     int            irq;
00000089     void            *controller_state;
00000090     void            *controller_data;
00000091     char            modalias[SPI_NAME_SIZE];
00000092 
00000093     /*
00000094      * likely need more hooks for more protocol options affecting how
00000095      * the controller talks to each chip, like:
00000096      *  - memory packing (12 bit samples into low bits, others zeroed)
00000097      *  - priority
00000098      *  - drop chipselect after each word
00000099      *  - chipselect delays
00000100      *  - ...
00000101      */
00000102 };

The 70 line, dev, embedded into the device model used in the.

The 71 line, master, a high-level description of SPI equipment, each SPI controller corresponds to a master, a SPI device must correspond to a master, master can have multiple SPI devices.

72, 73 For I have nothing to say, from the name of the variable can understand.

SPI Operating Modes

The 74 line, mode, against the clock phase CPHA (0 or 1) and a clock polarity CPOL (0 or 1) of different combinations, SPI can be divided into four modes, is 77 to 80 for the four. CPOL said when they are free (no data transmission) clock signal, CPOL=0 said the low level, CPOL=1 expressed high level. Each clock cycle has two level jump, rising and falling, CPHA said in each clock cycle is the first edge and second edge sampled data sampling data, the first edge and second edge is rising or falling edge is determined by CPOL. Look at the picture below will understand. The blue arrows indicate the sampling of the data.

87, if the transmission is in bytes if it is set to 8, accordingly, if it is 2 byte units is set to 16.

The 88 line, interrupt. 89, do not use, as you'll see later this value will be set to NULL. The 90 line, later specific controller. The 91 line, is very important, in general equipment and driving can match up to see it, note, here is just that, because there are two other matching methods, but most of the equipment and the driver can match up is based on the name are equal, of course, like the USB driver is not based on name matching, but according to the and ID table. The definition of struct spi_driver is in the include/linux/spi/spi.h:

00000175 struct spi_driver {
00000176     const struct spi_device_id *id_table;
00000177     int            (*probe)(struct spi_device *spi);
00000178     int            (*remove)(struct spi_device *spi);
00000179     void            (*shutdown)(struct spi_device *spi);
00000180     int            (*suspend)(struct spi_device *spi, pm_message_t mesg);
00000181     int            (*resume)(struct spi_device *spi);
00000182     struct device_driver    driver;
00000183 };

The 182 line, the device_driver driver is used in the equipment in the model, the other is to define some of function pointers, very familiar, not much said.

      Return to the spi_match_device function, the 91 and 95 rows is the equipment and drive matching two other methods, because the SPI driver to use to talk about is the third kind of method, so here is not to discuss the two methods. The 97 line, matching is carried out according to the device name and drive name is equal, equal to 1 is returned, that match, the probe function will drive is called, this is also what we hope most to see, return 0 said the failure of matching.

      We know that, for a specific platform, NAND, IIC, frame, buffer etc. These are platform equipment, SPI also is the same as the platform, to platform device, in most cases is the first registered equipment registration drive. So here with tiny6410 as the platform, according to this order to tell.

S3c6410 has two SPI controllers, in the case of SPI0 on it. First look at the description about SPI0 controller in S3C6410, in the arch/arm/mach-s3c64xx/dev-spi.c file:

00000101 struct platform_device s3c64xx_device_spi0 = {
00000102     .name          = "s3c64xx-spi",
00000103     .id          = 0,
00000104     .num_resources      = ARRAY_SIZE(s3c64xx_spi0_resource),
00000105     .resource      = s3c64xx_spi0_resource,
00000106     .dev = {
00000107         .dma_mask        = &spi_dmamask,
00000108         .coherent_dma_mask    = DMA_BIT_MASK(32),
00000109         .platform_data = &s3c64xx_spi0_pdata,
00000110     },
00000111 };

The 102 line, driving can match with this equipment, you see the name, so the corresponding driver name must be the same. The 103 line, SPI ID controller, SPI0 controller for SPI1 0, the controller 1.

104 and 105 line is about IO port resources, DMA resources and interrupt resources. The 107108 line is about DMA, do not say. The 109 line, to drive, the drive there. In the initialization function in mini6410_machine_init to call the platform_add_devices function can be SPI0 device is registered to the platform bus.

The SPI controller S3c6410 drive in the drivers/spi/spi_s3c64xx.c file. The initialization function:

00001183 static int __init s3c64xx_spi_init(void)
00001184 {
00001185     return platform_driver_probe(&s3c64xx_spi_driver, s3c64xx_spi_probe);
00001186 }

The 1185 line, s3c64xx_spi_driver is an instance of struct platform_driver, is defined in the spi_s3c64xx.c file:

00001172 static struct platform_driver s3c64xx_spi_driver = {
00001173     .driver = {
00001174         .name    = "s3c64xx-spi",
00001175         .owner = THIS_MODULE,
00001176     },
00001177     .remove = s3c64xx_spi_remove,
00001178     .suspend = s3c64xx_spi_suspend,
00001179     .resume = s3c64xx_spi_resume,
00001180 };

The 1174 line, see? And before the definition in the s3c64xx_device_spi0 name is the same, so they can match up, 1185 s3c64xx_spi_probe driver line detection function is called, the definition of its:

00000911 static int __init s3c64xx_spi_probe(struct platform_device *pdev)
00000912 {
00000913     struct resource    *mem_res, *dmatx_res, *dmarx_res;
00000914     struct s3c64xx_spi_driver_data *sdd;
00000915     struct s3c64xx_spi_info *sci;
00000916     struct spi_master *master;
00000917     int ret;
00000918 
00000919     if (pdev->id <0) {
00000920         dev_err(&pdev->dev,
00000921                 "Invalid platform device id-%d\n", pdev->id);
00000922         return -ENODEV;
00000923     }
00000924 
00000925     if (pdev->dev.platform_data == NULL) {
00000926         dev_err(&pdev->dev, "platform_data missing!\n");
00000927         return -ENODEV;
00000928     }
00000929 
00000930     sci = pdev->dev.platform_data;
00000931     if (!sci->src_clk_name) {
00000932         dev_err(&pdev->dev,
00000933             "Board init must call s3c64xx_spi_set_info()\n");
00000934         return -EINVAL;
00000935     }
00000936 
00000937     /* Check for availability of necessary resource */
00000938 
00000939     dmatx_res = platform_get_resource(pdev, IORESOURCE_DMA, 0);
00000940     if (dmatx_res == NULL) {
00000941         dev_err(&pdev->dev, "Unable to get SPI-Tx dma resource\n");
00000942         return -ENXIO;
00000943     }
00000944 
00000945     dmarx_res = platform_get_resource(pdev, IORESOURCE_DMA, 1);
00000946     if (dmarx_res == NULL) {
00000947         dev_err(&pdev->dev, "Unable to get SPI-Rx dma resource\n");
00000948         return -ENXIO;
00000949     }
00000950 
00000951     mem_res = platform_get_resource(pdev, IORESOURCE_MEM, 0);
00000952     if (mem_res == NULL) {
00000953         dev_err(&pdev->dev, "Unable to get SPI MEM resource\n");
00000954         return -ENXIO;
00000955     }
00000956 
00000957     master = spi_alloc_master(&pdev->dev,
00000958                 sizeof(struct s3c64xx_spi_driver_data));
00000959     if (master == NULL) {
00000960         dev_err(&pdev->dev, "Unable to allocate SPI Master\n");
00000961         return -ENOMEM;
00000962     }
00000963 
00000964     platform_set_drvdata(pdev, master);
00000965 
00000966     sdd = spi_master_get_devdata(master);
00000967     sdd->master = master;
00000968     sdd->cntrlr_info = sci;
00000969     sdd->pdev = pdev;
00000970     sdd->sfr_start = mem_res->start;
00000971     sdd->tx_dmach = dmatx_res->start;
00000972     sdd->rx_dmach = dmarx_res->start;
00000973 
00000974     sdd->cur_bpw = 8;
00000975 
00000976     master->bus_num = pdev->id;
00000977     master->setup = s3c64xx_spi_setup;
00000978     master->transfer = s3c64xx_spi_transfer;
00000979     master->num_chipselect = sci->num_cs;
00000980     master->dma_alignment = 8;
00000981     /* the spi->mode bits understood by this driver: */
00000982     
00000983     master->mode_bits = SPI_CPOL | SPI_CPHA | SPI_CS_HIGH;
00000984 
00000985     if (request_mem_region(mem_res->start,
00000986             resource_size(mem_res), pdev->name) == NULL) {
00000987         dev_err(&pdev->dev, "Req mem region failed\n");
00000988         ret = -ENXIO;
00000989         goto err0;
00000990     }
00000991 
00000992     sdd->regs = ioremap(mem_res->start, resource_size(mem_res));
00000993     if (sdd->regs == NULL) {
00000994         dev_err(&pdev->dev, "Unable to remap IO\n");
00000995         ret = -ENXIO;
00000996         goto err1;
00000997     }
00000998 
00000999     if (sci->cfg_gpio == NULL || sci->cfg_gpio(pdev)) {
00001000         dev_err(&pdev->dev, "Unable to config gpio\n");
00001001         ret = -EBUSY;
00001002         goto err2;
00001003     }
00001004 
00001005     /* Setup clocks */
00001006     sdd->clk = clk_get(&pdev->dev, "spi");
00001007     if (IS_ERR(sdd->clk)) {
00001008         dev_err(&pdev->dev, "Unable to acquire clock 'spi'\n");
00001009         ret = PTR_ERR(sdd->clk);
00001010         goto err3;
00001011     }
00001012 
00001013     if (clk_enable(sdd->clk)) {
00001014         dev_err(&pdev->dev, "Couldn't enable clock 'spi'\n");
00001015         ret = -EBUSY;
00001016         goto err4;
00001017     }
00001018 
00001019     sdd->src_clk = clk_get(&pdev->dev, sci->src_clk_name);
00001020     if (IS_ERR(sdd->src_clk)) {
00001021         dev_err(&pdev->dev,
00001022             "Unable to acquire clock '%s'\n", sci->src_clk_name);
00001023         ret = PTR_ERR(sdd->src_clk);
00001024         goto err5;
00001025     }
00001026 
00001027     if (clk_enable(sdd->src_clk)) {
00001028         dev_err(&pdev->dev, "Couldn't enable clock '%s'\n",
00001029                             sci->src_clk_name);
00001030         ret = -EBUSY;
00001031         goto err6;
00001032     }
00001033 
00001034     sdd->workqueue = create_singlethread_workqueue(
00001035                         dev_name(master->dev.parent));
00001036     if (sdd->workqueue == NULL) {
00001037         dev_err(&pdev->dev, "Unable to create workqueue\n");
00001038         ret = -ENOMEM;
00001039         goto err7;
00001040     }
00001041 
00001042     /* Setup Deufult Mode */
00001043     s3c64xx_spi_hwinit(sdd, pdev->id);
00001044 
00001045     spin_lock_init(&sdd->lock);
00001046     init_completion(&sdd->xfer_completion);
00001047     INIT_WORK(&sdd->work, s3c64xx_spi_work);
00001048     INIT_LIST_HEAD(&sdd->queue);
00001049 
00001050     if (spi_register_master(master)) {
00001051         dev_err(&pdev->dev, "cannot register SPI master\n");
00001052         ret = -EBUSY;
00001053         goto err8;
00001054     }
00001055 
00001056     dev_dbg(&pdev->dev, "Samsung SoC SPI Driver loaded for Bus SPI-%d "
00001057                     "with %d Slaves attached\n",
00001058                     pdev->id, master->num_chipselect);
00001059     dev_dbg(&pdev->dev, "\tIOmem=[0x%x-0x%x]\tDMA=[Rx-%d, Tx-%d]\n",
00001060                     mem_res->end, mem_res->start,
00001061                     sdd->rx_dmach, sdd->tx_dmach);
00001062 
00001063     return 0;
00001064 
00001065 err8:
00001066     destroy_workqueue(sdd->workqueue);
00001067 err7:
00001068     clk_disable(sdd->src_clk);
00001069 err6:
00001070     clk_put(sdd->src_clk);
00001071 err5:
00001072     clk_disable(sdd->clk);
00001073 err4:
00001074     clk_put(sdd->clk);
00001075 err3:
00001076 err2:
00001077     iounmap((void *) sdd->regs);
00001078 err1:
00001079     release_mem_region(mem_res->start, resource_size(mem_res));
00001080 err0:
00001081     platform_set_drvdata(pdev, NULL);
00001082     spi_master_put(master);
00001083 
00001084     return ret;
00001085 }

Function is very long, but doing things is very simple. 919 to 923 lines, the SPI controller ID is from the beginning of 0, less than 0 words, no way, error.

925 to 928 rows, must be platform_data, otherwise an error. 930, if platform_data exists it out.

931 to 935, if src_clk_name is 0, indicating that it is not to call the s3c64xx_spi_set_info function in the initialization function.

939 to 955 line, get defined in IO and DMA resources.