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