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