Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 1 | ============================== |
Jan Engelhardt | 96de0e2 | 2007-10-19 23:21:04 +0200 | [diff] [blame] | 2 | PXA2xx SPI on SSP driver HOWTO |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 3 | ============================== |
| 4 | |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 5 | This a mini HOWTO on the pxa2xx_spi driver. The driver turns a PXA2xx |
| 6 | synchronous serial port into an SPI master controller |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 7 | (see Documentation/spi/spi-summary.rst). The driver has the following features |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 8 | |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 9 | - Support for any PXA2xx and compatible SSP. |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 10 | - SSP PIO and SSP DMA data transfers. |
| 11 | - External and Internal (SSPFRM) chip selects. |
| 12 | - Per slave device (chip) configuration. |
| 13 | - Full suspend, freeze, resume support. |
| 14 | |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 15 | The driver is built around a &struct spi_message FIFO serviced by kernel |
| 16 | thread. The kernel thread, spi_pump_messages(), drives message FIFO and |
| 17 | is responsible for queuing SPI transactions and setting up and launching |
| 18 | the DMA or interrupt driven transfers. |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 19 | |
| 20 | Declaring PXA2xx Master Controllers |
| 21 | ----------------------------------- |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 22 | Typically, for a legacy platform, an SPI master is defined in the |
| 23 | arch/.../mach-*/board-*.c as a "platform device". The master configuration |
| 24 | is passed to the driver via a table found in include/linux/spi/pxa2xx_spi.h:: |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 25 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 26 | struct pxa2xx_spi_controller { |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 27 | u16 num_chipselect; |
| 28 | u8 enable_dma; |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 29 | ... |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 30 | }; |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 31 | |
Lubomir Rintel | 51eea52 | 2019-01-16 16:13:31 +0100 | [diff] [blame] | 32 | The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 33 | slave device (chips) attached to this SPI master. |
| 34 | |
Lubomir Rintel | 51eea52 | 2019-01-16 16:13:31 +0100 | [diff] [blame] | 35 | The "pxa2xx_spi_controller.enable_dma" field informs the driver that SSP DMA should |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 36 | be used. This caused the driver to acquire two DMA channels: Rx channel and |
| 37 | Tx channel. The Rx channel has a higher DMA service priority than the Tx channel. |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 38 | See the "PXA2xx Developer Manual" section "DMA Controller". |
| 39 | |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 40 | For the new platforms the description of the controller and peripheral devices |
| 41 | comes from Device Tree or ACPI. |
| 42 | |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 43 | NSSP MASTER SAMPLE |
| 44 | ------------------ |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 45 | Below is a sample configuration using the PXA255 NSSP for a legacy platform:: |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 46 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 47 | static struct resource pxa_spi_nssp_resources[] = { |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 48 | [0] = { |
| 49 | .start = __PREG(SSCR0_P(2)), /* Start address of NSSP */ |
| 50 | .end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */ |
| 51 | .flags = IORESOURCE_MEM, |
| 52 | }, |
| 53 | [1] = { |
| 54 | .start = IRQ_NSSP, /* NSSP IRQ */ |
| 55 | .end = IRQ_NSSP, |
| 56 | .flags = IORESOURCE_IRQ, |
| 57 | }, |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 58 | }; |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 59 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 60 | static struct pxa2xx_spi_controller pxa_nssp_master_info = { |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 61 | .num_chipselect = 1, /* Matches the number of chips attached to NSSP */ |
| 62 | .enable_dma = 1, /* Enables NSSP DMA */ |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 63 | }; |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 64 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 65 | static struct platform_device pxa_spi_nssp = { |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 66 | .name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */ |
| 67 | .id = 2, /* Bus number, MUST MATCH SSP number 1..n */ |
| 68 | .resource = pxa_spi_nssp_resources, |
| 69 | .num_resources = ARRAY_SIZE(pxa_spi_nssp_resources), |
| 70 | .dev = { |
| 71 | .platform_data = &pxa_nssp_master_info, /* Passed to driver */ |
| 72 | }, |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 73 | }; |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 74 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 75 | static struct platform_device *devices[] __initdata = { |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 76 | &pxa_spi_nssp, |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 77 | }; |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 78 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 79 | static void __init board_init(void) |
| 80 | { |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 81 | (void)platform_add_device(devices, ARRAY_SIZE(devices)); |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 82 | } |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 83 | |
| 84 | Declaring Slave Devices |
| 85 | ----------------------- |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 86 | Typically, for a legacy platform, each SPI slave (chip) is defined in the |
| 87 | arch/.../mach-*/board-*.c using the "spi_board_info" structure found in |
| 88 | "linux/spi/spi.h". See "Documentation/spi/spi-summary.rst" for additional |
| 89 | information. |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 90 | |
| 91 | Each slave device attached to the PXA must provide slave specific configuration |
| 92 | information via the structure "pxa2xx_spi_chip" found in |
Sebastian Andrzej Siewior | 8348c25 | 2010-11-22 17:12:15 -0800 | [diff] [blame] | 93 | "include/linux/spi/pxa2xx_spi.h". The pxa2xx_spi master controller driver |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 94 | will uses the configuration whenever the driver communicates with the slave |
Vernon Sauder | f1f640a | 2008-10-15 22:02:43 -0700 | [diff] [blame] | 95 | device. All fields are optional. |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 96 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 97 | :: |
| 98 | |
| 99 | struct pxa2xx_spi_chip { |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 100 | u8 tx_threshold; |
| 101 | u8 rx_threshold; |
| 102 | u8 dma_burst_size; |
Stephen Street | 8d94cc5 | 2006-12-10 02:18:54 -0800 | [diff] [blame] | 103 | u32 timeout; |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 104 | }; |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 105 | |
| 106 | The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 107 | used to configure the SSP hardware FIFO. These fields are critical to the |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 108 | performance of pxa2xx_spi driver and misconfiguration will result in rx |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 109 | FIFO overruns (especially in PIO mode transfers). Good default values are:: |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 110 | |
Vernon Sauder | f1f640a | 2008-10-15 22:02:43 -0700 | [diff] [blame] | 111 | .tx_threshold = 8, |
| 112 | .rx_threshold = 8, |
| 113 | |
| 114 | The range is 1 to 16 where zero indicates "use default". |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 115 | |
| 116 | The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA |
| 117 | engine and is related the "spi_device.bits_per_word" field. Read and understand |
| 118 | the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers |
| 119 | to determine the correct value. An SSP configured for byte-wide transfers would |
Vernon Sauder | f1f640a | 2008-10-15 22:02:43 -0700 | [diff] [blame] | 120 | use a value of 8. The driver will determine a reasonable default if |
| 121 | dma_burst_size == 0. |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 122 | |
Stephen Street | 8d94cc5 | 2006-12-10 02:18:54 -0800 | [diff] [blame] | 123 | The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 124 | trailing bytes in the SSP receiver FIFO. The correct value for this field is |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 125 | dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific |
Paolo Ornati | 670e9f3 | 2006-10-03 22:57:56 +0200 | [diff] [blame] | 126 | slave device. Please note that the PXA2xx SSP 1 does not support trailing byte |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 127 | timeouts and must busy-wait any trailing bytes. |
| 128 | |
Vernon Sauder | f1f640a | 2008-10-15 22:02:43 -0700 | [diff] [blame] | 129 | NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the |
| 130 | chipselect is dropped after each spi_transfer. Most devices need chip select |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 131 | asserted around the complete message. Use SSPFRM as a GPIO (through a descriptor) |
Lucas De Marchi | 25985ed | 2011-03-30 22:57:33 -0300 | [diff] [blame] | 132 | to accommodate these chips. |
Vernon Sauder | f1f640a | 2008-10-15 22:02:43 -0700 | [diff] [blame] | 133 | |
| 134 | |
| 135 | NSSP SLAVE SAMPLE |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 136 | ----------------- |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 137 | For a legacy platform or in some other cases, the pxa2xx_spi_chip structure |
| 138 | is passed to the pxa2xx_spi driver in the "spi_board_info.controller_data" |
| 139 | field. Below is a sample configuration using the PXA255 NSSP. |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 140 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 141 | :: |
| 142 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 143 | static struct pxa2xx_spi_chip cs8415a_chip_info = { |
Randy Dunlap | 0f6d2ce | 2023-01-26 22:39:57 -0800 | [diff] [blame] | 144 | .tx_threshold = 8, /* SSP hardware FIFO threshold */ |
| 145 | .rx_threshold = 8, /* SSP hardware FIFO threshold */ |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 146 | .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ |
Stephen Street | 8d94cc5 | 2006-12-10 02:18:54 -0800 | [diff] [blame] | 147 | .timeout = 235, /* See Intel documentation */ |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 148 | }; |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 149 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 150 | static struct pxa2xx_spi_chip cs8405a_chip_info = { |
Randy Dunlap | 0f6d2ce | 2023-01-26 22:39:57 -0800 | [diff] [blame] | 151 | .tx_threshold = 8, /* SSP hardware FIFO threshold */ |
| 152 | .rx_threshold = 8, /* SSP hardware FIFO threshold */ |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 153 | .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ |
Stephen Street | 8d94cc5 | 2006-12-10 02:18:54 -0800 | [diff] [blame] | 154 | .timeout = 235, /* See Intel documentation */ |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 155 | }; |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 156 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 157 | static struct spi_board_info streetracer_spi_board_info[] __initdata = { |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 158 | { |
| 159 | .modalias = "cs8415a", /* Name of spi_driver for this device */ |
Randy Dunlap | 0f6d2ce | 2023-01-26 22:39:57 -0800 | [diff] [blame] | 160 | .max_speed_hz = 3686400, /* Run SSP as fast a possible */ |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 161 | .bus_num = 2, /* Framework bus number */ |
| 162 | .chip_select = 0, /* Framework chip select */ |
| 163 | .platform_data = NULL; /* No spi_driver specific config */ |
| 164 | .controller_data = &cs8415a_chip_info, /* Master chip config */ |
| 165 | .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */ |
| 166 | }, |
| 167 | { |
| 168 | .modalias = "cs8405a", /* Name of spi_driver for this device */ |
Randy Dunlap | 0f6d2ce | 2023-01-26 22:39:57 -0800 | [diff] [blame] | 169 | .max_speed_hz = 3686400, /* Run SSP as fast a possible */ |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 170 | .bus_num = 2, /* Framework bus number */ |
| 171 | .chip_select = 1, /* Framework chip select */ |
| 172 | .controller_data = &cs8405a_chip_info, /* Master chip config */ |
| 173 | .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */ |
| 174 | }, |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 175 | }; |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 176 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 177 | static void __init streetracer_init(void) |
| 178 | { |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 179 | spi_register_board_info(streetracer_spi_board_info, |
| 180 | ARRAY_SIZE(streetracer_spi_board_info)); |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 181 | } |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 182 | |
| 183 | |
| 184 | DMA and PIO I/O Support |
| 185 | ----------------------- |
Vernon Sauder | f1f640a | 2008-10-15 22:02:43 -0700 | [diff] [blame] | 186 | The pxa2xx_spi driver supports both DMA and interrupt driven PIO message |
| 187 | transfers. The driver defaults to PIO mode and DMA transfers must be enabled |
Andy Shevchenko | f96e6c0e | 2021-05-17 17:03:50 +0300 | [diff] [blame] | 188 | by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. |
| 189 | For the newer platforms, that are known to support DMA, the driver will enable |
| 190 | it automatically and try it first with a possible fallback to PIO. The DMA |
Vernon Sauder | f1f640a | 2008-10-15 22:02:43 -0700 | [diff] [blame] | 191 | mode supports both coherent and stream based DMA mappings. |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 192 | |
| 193 | The following logic is used to determine the type of I/O to be used on |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 194 | a per "spi_transfer" basis:: |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 195 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 196 | if !enable_dma then |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 197 | always use PIO transfers |
| 198 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 199 | if spi_message.len > 8191 then |
Vernon Sauder | f1f640a | 2008-10-15 22:02:43 -0700 | [diff] [blame] | 200 | print "rate limited" warning |
| 201 | use PIO transfers |
| 202 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 203 | if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 204 | use coherent DMA mode |
| 205 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 206 | if rx_buf and tx_buf are aligned on 8 byte boundary then |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 207 | use streaming DMA mode |
| 208 | |
Mauro Carvalho Chehab | 9cdd273 | 2019-07-31 17:08:50 -0300 | [diff] [blame] | 209 | otherwise |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 210 | use PIO transfer |
| 211 | |
| 212 | THANKS TO |
| 213 | --------- |
Stephen Street | e0c9905 | 2006-03-07 23:53:24 -0800 | [diff] [blame] | 214 | David Brownell and others for mentoring the development of this driver. |