blob: 13a0b7fb192f080fd8ad300973483eb2f3b37894 [file] [log] [blame]
Jan Engelhardt96de0e22007-10-19 23:21:04 +02001PXA2xx SPI on SSP driver HOWTO
Stephen Streete0c99052006-03-07 23:53:24 -08002===================================================
3This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx
4synchronous serial port into a SPI master controller
Paul Bolle395cf962011-08-15 02:02:26 +02005(see Documentation/spi/spi-summary). The driver has the following features
Stephen Streete0c99052006-03-07 23:53:24 -08006
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
13The driver is built around a "spi_message" fifo serviced by workqueue and a
14tasklet. The workqueue, "pump_messages", drives message fifo and the tasklet
15(pump_transfer) is responsible for queuing SPI transactions and setting up and
16launching the dma/interrupt driven transfers.
17
18Declaring PXA2xx Master Controllers
19-----------------------------------
20Typically 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 Siewior8348c252010-11-22 17:12:15 -080022found in include/linux/spi/pxa2xx_spi.h:
Stephen Streete0c99052006-03-07 23:53:24 -080023
24struct pxa2xx_spi_master {
Stephen Streete0c99052006-03-07 23:53:24 -080025 u16 num_chipselect;
26 u8 enable_dma;
27};
28
Stephen Streete0c99052006-03-07 23:53:24 -080029The "pxa2xx_spi_master.num_chipselect" field is used to determine the number of
30slave device (chips) attached to this SPI master.
31
32The "pxa2xx_spi_master.enable_dma" field informs the driver that SSP DMA should
33be used. This caused the driver to acquire two DMA channels: rx_channel and
34tx_channel. The rx_channel has a higher DMA service priority the tx_channel.
35See the "PXA2xx Developer Manual" section "DMA Controller".
36
37NSSP MASTER SAMPLE
38------------------
39Below is a sample configuration using the PXA255 NSSP.
40
41static 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
54static struct pxa2xx_spi_master pxa_nssp_master_info = {
Stephen Streete0c99052006-03-07 23:53:24 -080055 .num_chipselect = 1, /* Matches the number of chips attached to NSSP */
56 .enable_dma = 1, /* Enables NSSP DMA */
57};
58
59static 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
69static struct platform_device *devices[] __initdata = {
70 &pxa_spi_nssp,
71};
72
73static void __init board_init(void)
74{
75 (void)platform_add_device(devices, ARRAY_SIZE(devices));
76}
77
78Declaring Slave Devices
79-----------------------
80Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
81using the "spi_board_info" structure found in "linux/spi/spi.h". See
Paul Bolle395cf962011-08-15 02:02:26 +020082"Documentation/spi/spi-summary" for additional information.
Stephen Streete0c99052006-03-07 23:53:24 -080083
84Each slave device attached to the PXA must provide slave specific configuration
85information via the structure "pxa2xx_spi_chip" found in
Sebastian Andrzej Siewior8348c252010-11-22 17:12:15 -080086"include/linux/spi/pxa2xx_spi.h". The pxa2xx_spi master controller driver
Stephen Streete0c99052006-03-07 23:53:24 -080087will uses the configuration whenever the driver communicates with the slave
Vernon Sauderf1f640a2008-10-15 22:02:43 -070088device. All fields are optional.
Stephen Streete0c99052006-03-07 23:53:24 -080089
90struct pxa2xx_spi_chip {
91 u8 tx_threshold;
92 u8 rx_threshold;
93 u8 dma_burst_size;
Stephen Street8d94cc52006-12-10 02:18:54 -080094 u32 timeout;
Stephen Streete0c99052006-03-07 23:53:24 -080095 u8 enable_loopback;
96 void (*cs_control)(u32 command);
97};
98
99The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
100used to configure the SSP hardware fifo. These fields are critical to the
101performance of pxa2xx_spi driver and misconfiguration will result in rx
102fifo overruns (especially in PIO mode transfers). Good default values are
103
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700104 .tx_threshold = 8,
105 .rx_threshold = 8,
106
107The range is 1 to 16 where zero indicates "use default".
Stephen Streete0c99052006-03-07 23:53:24 -0800108
109The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA
110engine and is related the "spi_device.bits_per_word" field. Read and understand
111the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers
112to determine the correct value. An SSP configured for byte-wide transfers would
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700113use a value of 8. The driver will determine a reasonable default if
114dma_burst_size == 0.
Stephen Streete0c99052006-03-07 23:53:24 -0800115
Stephen Street8d94cc52006-12-10 02:18:54 -0800116The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle
Stephen Streete0c99052006-03-07 23:53:24 -0800117trailing bytes in the SSP receiver fifo. The correct value for this field is
118dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific
Paolo Ornati670e9f32006-10-03 22:57:56 +0200119slave device. Please note that the PXA2xx SSP 1 does not support trailing byte
Stephen Streete0c99052006-03-07 23:53:24 -0800120timeouts and must busy-wait any trailing bytes.
121
122The "pxa2xx_spi_chip.enable_loopback" field is used to place the SSP porting
123into internal loopback mode. In this mode the SSP controller internally
Paolo Ornati670e9f32006-10-03 22:57:56 +0200124connects the SSPTX pin to the SSPRX pin. This is useful for initial setup
Stephen Streete0c99052006-03-07 23:53:24 -0800125testing.
126
127The "pxa2xx_spi_chip.cs_control" field is used to point to a board specific
128function for asserting/deasserting a slave device chip select. If the field is
129NULL, the pxa2xx_spi master controller driver assumes that the SSP port is
130configured to use SSPFRM instead.
131
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700132NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the
133chipselect is dropped after each spi_transfer. Most devices need chip select
134asserted around the complete message. Use SSPFRM as a GPIO (through cs_control)
Lucas De Marchi25985ed2011-03-30 22:57:33 -0300135to accommodate these chips.
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700136
137
138NSSP SLAVE SAMPLE
Stephen Streete0c99052006-03-07 23:53:24 -0800139-----------------
140The 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
142the PXA255 NSSP.
143
144/* Chip Select control for the CS8415A SPI slave device */
145static 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 */
154static 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
162static struct pxa2xx_spi_chip cs8415a_chip_info = {
Stephen Street8d94cc52006-12-10 02:18:54 -0800163 .tx_threshold = 8, /* SSP hardward FIFO threshold */
164 .rx_threshold = 8, /* SSP hardward FIFO threshold */
Stephen Streete0c99052006-03-07 23:53:24 -0800165 .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
Stephen Street8d94cc52006-12-10 02:18:54 -0800166 .timeout = 235, /* See Intel documentation */
Stephen Streete0c99052006-03-07 23:53:24 -0800167 .cs_control = cs8415a_cs_control, /* Use external chip select */
168};
169
170static struct pxa2xx_spi_chip cs8405a_chip_info = {
Stephen Street8d94cc52006-12-10 02:18:54 -0800171 .tx_threshold = 8, /* SSP hardward FIFO threshold */
172 .rx_threshold = 8, /* SSP hardward FIFO threshold */
Stephen Streete0c99052006-03-07 23:53:24 -0800173 .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
Stephen Street8d94cc52006-12-10 02:18:54 -0800174 .timeout = 235, /* See Intel documentation */
Stephen Streete0c99052006-03-07 23:53:24 -0800175 .cs_control = cs8405a_cs_control, /* Use external chip select */
176};
177
178static 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
198static 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
205DMA and PIO I/O Support
206-----------------------
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700207The pxa2xx_spi driver supports both DMA and interrupt driven PIO message
208transfers. The driver defaults to PIO mode and DMA transfers must be enabled
209by setting the "enable_dma" flag in the "pxa2xx_spi_master" structure. The DMA
210mode supports both coherent and stream based DMA mappings.
Stephen Streete0c99052006-03-07 23:53:24 -0800211
212The following logic is used to determine the type of I/O to be used on
213a per "spi_transfer" basis:
214
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700215if !enable_dma then
Stephen Streete0c99052006-03-07 23:53:24 -0800216 always use PIO transfers
217
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700218if spi_message.len > 8191 then
219 print "rate limited" warning
220 use PIO transfers
221
Stephen Streete0c99052006-03-07 23:53:24 -0800222if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
223 use coherent DMA mode
224
225if rx_buf and tx_buf are aligned on 8 byte boundary then
226 use streaming DMA mode
227
228otherwise
229 use PIO transfer
230
231THANKS TO
232---------
233
234David Brownell and others for mentoring the development of this driver.
235