blob: 04f2a3856c406f17a8dcd180b8a66b7baeab6b41 [file] [log] [blame]
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -03001==============================
Jan Engelhardt96de0e22007-10-19 23:21:04 +02002PXA2xx SPI on SSP driver HOWTO
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -03003==============================
4
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +03005This a mini HOWTO on the pxa2xx_spi driver. The driver turns a PXA2xx
6synchronous serial port into an SPI master controller
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -03007(see Documentation/spi/spi-summary.rst). The driver has the following features
Stephen Streete0c99052006-03-07 23:53:24 -08008
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +03009- Support for any PXA2xx and compatible SSP.
Stephen Streete0c99052006-03-07 23:53:24 -080010- 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 Shevchenkof96e6c0e2021-05-17 17:03:50 +030015The driver is built around a &struct spi_message FIFO serviced by kernel
16thread. The kernel thread, spi_pump_messages(), drives message FIFO and
17is responsible for queuing SPI transactions and setting up and launching
18the DMA or interrupt driven transfers.
Stephen Streete0c99052006-03-07 23:53:24 -080019
20Declaring PXA2xx Master Controllers
21-----------------------------------
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +030022Typically, for a legacy platform, an SPI master is defined in the
23arch/.../mach-*/board-*.c as a "platform device". The master configuration
24is passed to the driver via a table found in include/linux/spi/pxa2xx_spi.h::
Stephen Streete0c99052006-03-07 23:53:24 -080025
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -030026 struct pxa2xx_spi_controller {
Stephen Streete0c99052006-03-07 23:53:24 -080027 u16 num_chipselect;
28 u8 enable_dma;
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +030029 ...
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -030030 };
Stephen Streete0c99052006-03-07 23:53:24 -080031
Lubomir Rintel51eea522019-01-16 16:13:31 +010032The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
Stephen Streete0c99052006-03-07 23:53:24 -080033slave device (chips) attached to this SPI master.
34
Lubomir Rintel51eea522019-01-16 16:13:31 +010035The "pxa2xx_spi_controller.enable_dma" field informs the driver that SSP DMA should
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +030036be used. This caused the driver to acquire two DMA channels: Rx channel and
37Tx channel. The Rx channel has a higher DMA service priority than the Tx channel.
Stephen Streete0c99052006-03-07 23:53:24 -080038See the "PXA2xx Developer Manual" section "DMA Controller".
39
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +030040For the new platforms the description of the controller and peripheral devices
41comes from Device Tree or ACPI.
42
Stephen Streete0c99052006-03-07 23:53:24 -080043NSSP MASTER SAMPLE
44------------------
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +030045Below is a sample configuration using the PXA255 NSSP for a legacy platform::
Stephen Streete0c99052006-03-07 23:53:24 -080046
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -030047 static struct resource pxa_spi_nssp_resources[] = {
Stephen Streete0c99052006-03-07 23:53:24 -080048 [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 Chehab9cdd2732019-07-31 17:08:50 -030058 };
Stephen Streete0c99052006-03-07 23:53:24 -080059
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -030060 static struct pxa2xx_spi_controller pxa_nssp_master_info = {
Stephen Streete0c99052006-03-07 23:53:24 -080061 .num_chipselect = 1, /* Matches the number of chips attached to NSSP */
62 .enable_dma = 1, /* Enables NSSP DMA */
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -030063 };
Stephen Streete0c99052006-03-07 23:53:24 -080064
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -030065 static struct platform_device pxa_spi_nssp = {
Stephen Streete0c99052006-03-07 23:53:24 -080066 .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 Chehab9cdd2732019-07-31 17:08:50 -030073 };
Stephen Streete0c99052006-03-07 23:53:24 -080074
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -030075 static struct platform_device *devices[] __initdata = {
Stephen Streete0c99052006-03-07 23:53:24 -080076 &pxa_spi_nssp,
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -030077 };
Stephen Streete0c99052006-03-07 23:53:24 -080078
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -030079 static void __init board_init(void)
80 {
Stephen Streete0c99052006-03-07 23:53:24 -080081 (void)platform_add_device(devices, ARRAY_SIZE(devices));
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -030082 }
Stephen Streete0c99052006-03-07 23:53:24 -080083
84Declaring Slave Devices
85-----------------------
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +030086Typically, for a legacy platform, each SPI slave (chip) is defined in the
87arch/.../mach-*/board-*.c using the "spi_board_info" structure found in
88"linux/spi/spi.h". See "Documentation/spi/spi-summary.rst" for additional
89information.
Stephen Streete0c99052006-03-07 23:53:24 -080090
91Each slave device attached to the PXA must provide slave specific configuration
92information via the structure "pxa2xx_spi_chip" found in
Sebastian Andrzej Siewior8348c252010-11-22 17:12:15 -080093"include/linux/spi/pxa2xx_spi.h". The pxa2xx_spi master controller driver
Stephen Streete0c99052006-03-07 23:53:24 -080094will uses the configuration whenever the driver communicates with the slave
Vernon Sauderf1f640a2008-10-15 22:02:43 -070095device. All fields are optional.
Stephen Streete0c99052006-03-07 23:53:24 -080096
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -030097::
98
99 struct pxa2xx_spi_chip {
Stephen Streete0c99052006-03-07 23:53:24 -0800100 u8 tx_threshold;
101 u8 rx_threshold;
102 u8 dma_burst_size;
Stephen Street8d94cc52006-12-10 02:18:54 -0800103 u32 timeout;
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300104 };
Stephen Streete0c99052006-03-07 23:53:24 -0800105
106The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +0300107used to configure the SSP hardware FIFO. These fields are critical to the
Stephen Streete0c99052006-03-07 23:53:24 -0800108performance of pxa2xx_spi driver and misconfiguration will result in rx
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +0300109FIFO overruns (especially in PIO mode transfers). Good default values are::
Stephen Streete0c99052006-03-07 23:53:24 -0800110
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700111 .tx_threshold = 8,
112 .rx_threshold = 8,
113
114The range is 1 to 16 where zero indicates "use default".
Stephen Streete0c99052006-03-07 23:53:24 -0800115
116The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA
117engine and is related the "spi_device.bits_per_word" field. Read and understand
118the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers
119to determine the correct value. An SSP configured for byte-wide transfers would
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700120use a value of 8. The driver will determine a reasonable default if
121dma_burst_size == 0.
Stephen Streete0c99052006-03-07 23:53:24 -0800122
Stephen Street8d94cc52006-12-10 02:18:54 -0800123The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +0300124trailing bytes in the SSP receiver FIFO. The correct value for this field is
Stephen Streete0c99052006-03-07 23:53:24 -0800125dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific
Paolo Ornati670e9f32006-10-03 22:57:56 +0200126slave device. Please note that the PXA2xx SSP 1 does not support trailing byte
Stephen Streete0c99052006-03-07 23:53:24 -0800127timeouts and must busy-wait any trailing bytes.
128
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700129NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the
130chipselect is dropped after each spi_transfer. Most devices need chip select
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +0300131asserted around the complete message. Use SSPFRM as a GPIO (through a descriptor)
Lucas De Marchi25985ed2011-03-30 22:57:33 -0300132to accommodate these chips.
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700133
134
135NSSP SLAVE SAMPLE
Stephen Streete0c99052006-03-07 23:53:24 -0800136-----------------
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +0300137For a legacy platform or in some other cases, the pxa2xx_spi_chip structure
138is passed to the pxa2xx_spi driver in the "spi_board_info.controller_data"
139field. Below is a sample configuration using the PXA255 NSSP.
Stephen Streete0c99052006-03-07 23:53:24 -0800140
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300141::
142
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300143 static struct pxa2xx_spi_chip cs8415a_chip_info = {
Randy Dunlap0f6d2ce2023-01-26 22:39:57 -0800144 .tx_threshold = 8, /* SSP hardware FIFO threshold */
145 .rx_threshold = 8, /* SSP hardware FIFO threshold */
Stephen Streete0c99052006-03-07 23:53:24 -0800146 .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
Stephen Street8d94cc52006-12-10 02:18:54 -0800147 .timeout = 235, /* See Intel documentation */
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300148 };
Stephen Streete0c99052006-03-07 23:53:24 -0800149
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300150 static struct pxa2xx_spi_chip cs8405a_chip_info = {
Randy Dunlap0f6d2ce2023-01-26 22:39:57 -0800151 .tx_threshold = 8, /* SSP hardware FIFO threshold */
152 .rx_threshold = 8, /* SSP hardware FIFO threshold */
Stephen Streete0c99052006-03-07 23:53:24 -0800153 .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
Stephen Street8d94cc52006-12-10 02:18:54 -0800154 .timeout = 235, /* See Intel documentation */
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300155 };
Stephen Streete0c99052006-03-07 23:53:24 -0800156
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300157 static struct spi_board_info streetracer_spi_board_info[] __initdata = {
Stephen Streete0c99052006-03-07 23:53:24 -0800158 {
159 .modalias = "cs8415a", /* Name of spi_driver for this device */
Randy Dunlap0f6d2ce2023-01-26 22:39:57 -0800160 .max_speed_hz = 3686400, /* Run SSP as fast a possible */
Stephen Streete0c99052006-03-07 23:53:24 -0800161 .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 Dunlap0f6d2ce2023-01-26 22:39:57 -0800169 .max_speed_hz = 3686400, /* Run SSP as fast a possible */
Stephen Streete0c99052006-03-07 23:53:24 -0800170 .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 Chehab9cdd2732019-07-31 17:08:50 -0300175 };
Stephen Streete0c99052006-03-07 23:53:24 -0800176
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300177 static void __init streetracer_init(void)
178 {
Stephen Streete0c99052006-03-07 23:53:24 -0800179 spi_register_board_info(streetracer_spi_board_info,
180 ARRAY_SIZE(streetracer_spi_board_info));
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300181 }
Stephen Streete0c99052006-03-07 23:53:24 -0800182
183
184DMA and PIO I/O Support
185-----------------------
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700186The pxa2xx_spi driver supports both DMA and interrupt driven PIO message
187transfers. The driver defaults to PIO mode and DMA transfers must be enabled
Andy Shevchenkof96e6c0e2021-05-17 17:03:50 +0300188by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure.
189For the newer platforms, that are known to support DMA, the driver will enable
190it automatically and try it first with a possible fallback to PIO. The DMA
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700191mode supports both coherent and stream based DMA mappings.
Stephen Streete0c99052006-03-07 23:53:24 -0800192
193The following logic is used to determine the type of I/O to be used on
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300194a per "spi_transfer" basis::
Stephen Streete0c99052006-03-07 23:53:24 -0800195
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300196 if !enable_dma then
Stephen Streete0c99052006-03-07 23:53:24 -0800197 always use PIO transfers
198
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300199 if spi_message.len > 8191 then
Vernon Sauderf1f640a2008-10-15 22:02:43 -0700200 print "rate limited" warning
201 use PIO transfers
202
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300203 if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
Stephen Streete0c99052006-03-07 23:53:24 -0800204 use coherent DMA mode
205
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300206 if rx_buf and tx_buf are aligned on 8 byte boundary then
Stephen Streete0c99052006-03-07 23:53:24 -0800207 use streaming DMA mode
208
Mauro Carvalho Chehab9cdd2732019-07-31 17:08:50 -0300209 otherwise
Stephen Streete0c99052006-03-07 23:53:24 -0800210 use PIO transfer
211
212THANKS TO
213---------
Stephen Streete0c99052006-03-07 23:53:24 -0800214David Brownell and others for mentoring the development of this driver.