About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / spi / pxa2xx


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1	PXA2xx SPI on SSP driver HOWTO
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
22	found in include/linux/spi/pxa2xx_spi.h:
23	
24	struct pxa2xx_spi_master {
25		u16 num_chipselect;
26		u8 enable_dma;
27	};
28	
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 = {
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
82	"Documentation/spi/spi-summary" for additional information.
83	
84	Each slave device attached to the PXA must provide slave specific configuration
85	information via the structure "pxa2xx_spi_chip" found in
86	"include/linux/spi/pxa2xx_spi.h".  The pxa2xx_spi master controller driver
87	will uses the configuration whenever the driver communicates with the slave
88	device. All fields are optional.
89	
90	struct pxa2xx_spi_chip {
91		u8 tx_threshold;
92		u8 rx_threshold;
93		u8 dma_burst_size;
94		u32 timeout;
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	
104		.tx_threshold = 8,
105		.rx_threshold = 8,
106	
107	The range is 1 to 16 where zero indicates "use default".
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
113	use a value of 8. The driver will determine a reasonable default if
114	dma_burst_size == 0.
115	
116	The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle
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
119	slave device.  Please note that the PXA2xx SSP 1 does not support trailing byte
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
124	connects the SSPTX pin to the SSPRX pin.  This is useful for initial setup
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	
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)
135	to accommodate these chips.
136	
137	
138	NSSP SLAVE SAMPLE
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 = {
163		.tx_threshold = 8, /* SSP hardward FIFO threshold */
164		.rx_threshold = 8, /* SSP hardward FIFO threshold */
165		.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
166		.timeout = 235, /* See Intel documentation */
167		.cs_control = cs8415a_cs_control, /* Use external chip select */
168	};
169	
170	static struct pxa2xx_spi_chip cs8405a_chip_info = {
171		.tx_threshold = 8, /* SSP hardward FIFO threshold */
172		.rx_threshold = 8, /* SSP hardward FIFO threshold */
173		.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
174		.timeout = 235, /* See Intel documentation */
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	-----------------------
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.
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	
215	if !enable_dma then
216		always use PIO transfers
217	
218	if spi_message.len > 8191 then
219		print "rate limited" warning
220		use PIO transfers
221	
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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog