blob: 7982bcc4d151adfa6f0782182a84a482b8d976a0 [file] [log] [blame]
David Brownell8ae12a02006-01-08 13:34:19 -08001Overview of Linux kernel SPI support
2====================================
3
Linus Walleijffbbdd212012-02-22 10:05:38 +0100402-Feb-2012
David Brownell8ae12a02006-01-08 13:34:19 -08005
6What is SPI?
7------------
David Brownellb8852442006-01-08 13:34:23 -08008The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
9link used to connect microcontrollers to sensors, memory, and peripherals.
David Brownell43d4f962007-05-23 13:57:36 -070010It's a simple "de facto" standard, not complicated enough to acquire a
11standardization body. SPI uses a master/slave configuration.
David Brownell8ae12a02006-01-08 13:34:19 -080012
David Brownell33e34dc2007-05-08 00:32:21 -070013The three signal wires hold a clock (SCK, often on the order of 10 MHz),
David Brownell8ae12a02006-01-08 13:34:19 -080014and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
15Slave Out" (MISO) signals. (Other names are also used.) There are four
16clocking modes through which data is exchanged; mode-0 and mode-3 are most
David Brownellb8852442006-01-08 13:34:23 -080017commonly used. Each clock cycle shifts data out and data in; the clock
David Brownell43d4f962007-05-23 13:57:36 -070018doesn't cycle except when there is a data bit to shift. Not all data bits
19are used though; not every protocol uses those full duplex capabilities.
David Brownell8ae12a02006-01-08 13:34:19 -080020
David Brownell43d4f962007-05-23 13:57:36 -070021SPI masters use a fourth "chip select" line to activate a given SPI slave
David Brownell8ae12a02006-01-08 13:34:19 -080022device, so those three signal wires may be connected to several chips
David Brownell43d4f962007-05-23 13:57:36 -070023in parallel. All SPI slaves support chipselects; they are usually active
24low signals, labeled nCSx for slave 'x' (e.g. nCS0). Some devices have
David Brownell8ae12a02006-01-08 13:34:19 -080025other signals, often including an interrupt to the master.
26
David Brownell43d4f962007-05-23 13:57:36 -070027Unlike serial busses like USB or SMBus, even low level protocols for
David Brownell8ae12a02006-01-08 13:34:19 -080028SPI slave functions are usually not interoperable between vendors
David Brownell33e34dc2007-05-08 00:32:21 -070029(except for commodities like SPI memory chips).
David Brownell8ae12a02006-01-08 13:34:19 -080030
31 - SPI may be used for request/response style device protocols, as with
32 touchscreen sensors and memory chips.
33
34 - It may also be used to stream data in either direction (half duplex),
35 or both of them at the same time (full duplex).
36
John Whitmore0c64bc12013-12-06 13:33:50 +000037 - Some devices may use eight bit words. Others may use different word
David Brownell8ae12a02006-01-08 13:34:19 -080038 lengths, such as streams of 12-bit or 20-bit digital samples.
39
David Brownell43d4f962007-05-23 13:57:36 -070040 - Words are usually sent with their most significant bit (MSB) first,
41 but sometimes the least significant bit (LSB) goes first instead.
42
43 - Sometimes SPI is used to daisy-chain devices, like shift registers.
44
David Brownell8ae12a02006-01-08 13:34:19 -080045In the same way, SPI slaves will only rarely support any kind of automatic
46discovery/enumeration protocol. The tree of slave devices accessible from
47a given SPI master will normally be set up manually, with configuration
48tables.
49
50SPI is only one of the names used by such four-wire protocols, and
51most controllers have no problem handling "MicroWire" (think of it as
52half-duplex SPI, for request/response protocols), SSP ("Synchronous
53Serial Protocol"), PSP ("Programmable Serial Protocol"), and other
54related protocols.
55
David Brownell43d4f962007-05-23 13:57:36 -070056Some chips eliminate a signal line by combining MOSI and MISO, and
57limiting themselves to half-duplex at the hardware level. In fact
58some SPI chips have this signal mode as a strapping option. These
59can be accessed using the same programming interface as SPI, but of
60course they won't handle full duplex transfers. You may find such
61chips described as using "three wire" signaling: SCK, data, nCSx.
62(That data line is sometimes called MOMI or SISO.)
63
David Brownell8ae12a02006-01-08 13:34:19 -080064Microcontrollers often support both master and slave sides of the SPI
65protocol. This document (and Linux) currently only supports the master
66side of SPI interactions.
67
68
69Who uses it? On what kinds of systems?
70---------------------------------------
71Linux developers using SPI are probably writing device drivers for embedded
72systems boards. SPI is used to control external chips, and it is also a
73protocol supported by every MMC or SD memory card. (The older "DataFlash"
74cards, predating MMC cards but using the same connectors and card shape,
75support only SPI.) Some PC hardware uses SPI flash for BIOS code.
76
77SPI slave chips range from digital/analog converters used for analog
78sensors and codecs, to memory, to peripherals like USB controllers
79or Ethernet adapters; and more.
80
81Most systems using SPI will integrate a few devices on a mainboard.
82Some provide SPI links on expansion connectors; in cases where no
83dedicated SPI controller exists, GPIO pins can be used to create a
84low speed "bitbanging" adapter. Very few systems will "hotplug" an SPI
85controller; the reasons to use SPI focus on low cost and simple operation,
86and if dynamic reconfiguration is important, USB will often be a more
87appropriate low-pincount peripheral bus.
88
89Many microcontrollers that can run Linux integrate one or more I/O
90interfaces with SPI modes. Given SPI support, they could use MMC or SD
91cards without needing a special purpose MMC/SD/SDIO controller.
92
93
David Brownell43d4f962007-05-23 13:57:36 -070094I'm confused. What are these four SPI "clock modes"?
95-----------------------------------------------------
96It's easy to be confused here, and the vendor documentation you'll
97find isn't necessarily helpful. The four modes combine two mode bits:
98
99 - CPOL indicates the initial clock polarity. CPOL=0 means the
100 clock starts low, so the first (leading) edge is rising, and
101 the second (trailing) edge is falling. CPOL=1 means the clock
102 starts high, so the first (leading) edge is falling.
103
104 - CPHA indicates the clock phase used to sample data; CPHA=0 says
105 sample on the leading edge, CPHA=1 means the trailing edge.
106
107 Since the signal needs to stablize before it's sampled, CPHA=0
108 implies that its data is written half a clock before the first
109 clock edge. The chipselect may have made it become available.
110
111Chip specs won't always say "uses SPI mode X" in as many words,
112but their timing diagrams will make the CPOL and CPHA modes clear.
113
114In the SPI mode number, CPOL is the high order bit and CPHA is the
115low order bit. So when a chip's timing diagram shows the clock
116starting low (CPOL=0) and data stabilized for sampling during the
117trailing clock edge (CPHA=1), that's SPI mode 1.
118
David Brownell6395bee2008-04-08 17:41:58 -0700119Note that the clock mode is relevant as soon as the chipselect goes
120active. So the master must set the clock to inactive before selecting
121a slave, and the slave can tell the chosen polarity by sampling the
122clock level when its select line goes active. That's why many devices
123support for example both modes 0 and 3: they don't care about polarity,
John Whitmore0c64bc12013-12-06 13:33:50 +0000124and always clock data in/out on rising clock edges.
David Brownell6395bee2008-04-08 17:41:58 -0700125
David Brownell43d4f962007-05-23 13:57:36 -0700126
David Brownell8ae12a02006-01-08 13:34:19 -0800127How do these driver programming interfaces work?
128------------------------------------------------
129The <linux/spi/spi.h> header file includes kerneldoc, as does the
David Brownell33e34dc2007-05-08 00:32:21 -0700130main source code, and you should certainly read that chapter of the
131kernel API document. This is just an overview, so you get the big
132picture before those details.
David Brownell8ae12a02006-01-08 13:34:19 -0800133
David Brownellb8852442006-01-08 13:34:23 -0800134SPI requests always go into I/O queues. Requests for a given SPI device
135are always executed in FIFO order, and complete asynchronously through
136completion callbacks. There are also some simple synchronous wrappers
137for those calls, including ones for common transaction types like writing
138a command and then reading its response.
139
David Brownell8ae12a02006-01-08 13:34:19 -0800140There are two types of SPI driver, here called:
141
John Whitmore0c64bc12013-12-06 13:33:50 +0000142 Controller drivers ... controllers may be built into System-On-Chip
David Brownell8ae12a02006-01-08 13:34:19 -0800143 processors, and often support both Master and Slave roles.
144 These drivers touch hardware registers and may use DMA.
David Brownellb8852442006-01-08 13:34:23 -0800145 Or they can be PIO bitbangers, needing just GPIO pins.
David Brownell8ae12a02006-01-08 13:34:19 -0800146
147 Protocol drivers ... these pass messages through the controller
148 driver to communicate with a Slave or Master device on the
149 other side of an SPI link.
150
151So for example one protocol driver might talk to the MTD layer to export
152data to filesystems stored on SPI flash like DataFlash; and others might
153control audio interfaces, present touchscreen sensors as input interfaces,
154or monitor temperature and voltage levels during industrial processing.
155And those might all be sharing the same controller driver.
156
157A "struct spi_device" encapsulates the master-side interface between
158those two types of driver. At this writing, Linux has no slave side
159programming interface.
160
161There is a minimal core of SPI programming interfaces, focussing on
David Brownell33e34dc2007-05-08 00:32:21 -0700162using the driver model to connect controller and protocol drivers using
David Brownell8ae12a02006-01-08 13:34:19 -0800163device tables provided by board specific initialization code. SPI
164shows up in sysfs in several locations:
165
Tony Jones49dce682007-10-16 01:27:48 -0700166 /sys/devices/.../CTLR ... physical node for a given SPI controller
167
David Brownell33e34dc2007-05-08 00:32:21 -0700168 /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B",
David Brownell8ae12a02006-01-08 13:34:19 -0800169 chipselect C, accessed through CTLR.
170
Tony Jones49dce682007-10-16 01:27:48 -0700171 /sys/bus/spi/devices/spiB.C ... symlink to that physical
172 .../CTLR/spiB.C device
173
David Brownell71117632006-01-08 13:34:29 -0800174 /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
175 that should be used with this device (for hotplug/coldplug)
176
David Brownell8ae12a02006-01-08 13:34:19 -0800177 /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices
178
Tony Jones49dce682007-10-16 01:27:48 -0700179 /sys/class/spi_master/spiB ... symlink (or actual device node) to
180 a logical node which could hold class related state for the
181 controller managing bus "B". All spiB.* devices share one
David Brownell8ae12a02006-01-08 13:34:19 -0800182 physical SPI bus segment, with SCLK, MOSI, and MISO.
183
Tony Jones49dce682007-10-16 01:27:48 -0700184Note that the actual location of the controller's class state depends
185on whether you enabled CONFIG_SYSFS_DEPRECATED or not. At this time,
186the only class-specific state is the bus number ("B" in "spiB"), so
187those /sys/class entries are only useful to quickly identify busses.
188
David Brownell8ae12a02006-01-08 13:34:19 -0800189
190How does board-specific init code declare SPI devices?
191------------------------------------------------------
192Linux needs several kinds of information to properly configure SPI devices.
193That information is normally provided by board-specific code, even for
194chips that do support some of automated discovery/enumeration.
195
196DECLARE CONTROLLERS
197
198The first kind of information is a list of what SPI controllers exist.
199For System-on-Chip (SOC) based boards, these will usually be platform
200devices, and the controller may need some platform_data in order to
201operate properly. The "struct platform_device" will include resources
202like the physical address of the controller's first register and its IRQ.
203
204Platforms will often abstract the "register SPI controller" operation,
205maybe coupling it with code to initialize pin configurations, so that
206the arch/.../mach-*/board-*.c files for several boards can all share the
207same basic controller setup code. This is because most SOCs have several
208SPI-capable controllers, and only the ones actually usable on a given
209board should normally be set up and registered.
210
211So for example arch/.../mach-*/board-*.c files might have code like:
212
Russell Kinga09e64f2008-08-05 16:14:15 +0100213 #include <mach/spi.h> /* for mysoc_spi_data */
David Brownell8ae12a02006-01-08 13:34:19 -0800214
215 /* if your mach-* infrastructure doesn't support kernels that can
216 * run on multiple boards, pdata wouldn't benefit from "__init".
217 */
Sachin Kamat61679ef2013-08-08 10:45:10 +0530218 static struct mysoc_spi_data pdata __initdata = { ... };
David Brownell8ae12a02006-01-08 13:34:19 -0800219
220 static __init board_init(void)
221 {
222 ...
223 /* this board only uses SPI controller #2 */
224 mysoc_register_spi(2, &pdata);
225 ...
226 }
227
228And SOC-specific utility code might look something like:
229
Russell Kinga09e64f2008-08-05 16:14:15 +0100230 #include <mach/spi.h>
David Brownell8ae12a02006-01-08 13:34:19 -0800231
232 static struct platform_device spi2 = { ... };
233
234 void mysoc_register_spi(unsigned n, struct mysoc_spi_data *pdata)
235 {
236 struct mysoc_spi_data *pdata2;
237
238 pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
239 *pdata2 = pdata;
240 ...
241 if (n == 2) {
242 spi2->dev.platform_data = pdata2;
243 register_platform_device(&spi2);
244
245 /* also: set up pin modes so the spi2 signals are
246 * visible on the relevant pins ... bootloaders on
247 * production boards may already have done this, but
248 * developer boards will often need Linux to do it.
249 */
250 }
251 ...
252 }
253
254Notice how the platform_data for boards may be different, even if the
255same SOC controller is used. For example, on one board SPI might use
256an external clock, where another derives the SPI clock from current
257settings of some master clock.
258
259
260DECLARE SLAVE DEVICES
261
262The second kind of information is a list of what SPI slave devices exist
263on the target board, often with some board-specific data needed for the
264driver to work correctly.
265
266Normally your arch/.../mach-*/board-*.c files would provide a small table
267listing the SPI devices on each board. (This would typically be only a
268small handful.) That might look like:
269
270 static struct ads7846_platform_data ads_info = {
271 .vref_delay_usecs = 100,
272 .x_plate_ohms = 580,
273 .y_plate_ohms = 410,
274 };
275
276 static struct spi_board_info spi_board_info[] __initdata = {
277 {
278 .modalias = "ads7846",
279 .platform_data = &ads_info,
280 .mode = SPI_MODE_0,
281 .irq = GPIO_IRQ(31),
282 .max_speed_hz = 120000 /* max sample rate at 3V */ * 16,
283 .bus_num = 1,
284 .chip_select = 0,
285 },
286 };
287
288Again, notice how board-specific information is provided; each chip may need
289several types. This example shows generic constraints like the fastest SPI
290clock to allow (a function of board voltage in this case) or how an IRQ pin
291is wired, plus chip-specific constraints like an important delay that's
292changed by the capacitance at one pin.
293
294(There's also "controller_data", information that may be useful to the
295controller driver. An example would be peripheral-specific DMA tuning
296data or chipselect callbacks. This is stored in spi_device later.)
297
298The board_info should provide enough information to let the system work
299without the chip's driver being loaded. The most troublesome aspect of
300that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since
301sharing a bus with a device that interprets chipselect "backwards" is
David Brownell33e34dc2007-05-08 00:32:21 -0700302not possible until the infrastructure knows how to deselect it.
David Brownell8ae12a02006-01-08 13:34:19 -0800303
304Then your board initialization code would register that table with the SPI
305infrastructure, so that it's available later when the SPI master controller
306driver is registered:
307
308 spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
309
310Like with other static board-specific setup, you won't unregister those.
311
David Brownell71117632006-01-08 13:34:29 -0800312The widely used "card" style computers bundle memory, cpu, and little else
313onto a card that's maybe just thirty square centimeters. On such systems,
314your arch/.../mach-.../board-*.c file would primarily provide information
315about the devices on the mainboard into which such a card is plugged. That
316certainly includes SPI devices hooked up through the card connectors!
317
David Brownell8ae12a02006-01-08 13:34:19 -0800318
319NON-STATIC CONFIGURATIONS
320
321Developer boards often play by different rules than product boards, and one
322example is the potential need to hotplug SPI devices and/or controllers.
323
Paolo Ornati670e9f32006-10-03 22:57:56 +0200324For those cases you might need to use spi_busnum_to_master() to look
David Brownell8ae12a02006-01-08 13:34:19 -0800325up the spi bus master, and will likely need spi_new_device() to provide the
326board info based on the board that was hotplugged. Of course, you'd later
327call at least spi_unregister_device() when that board is removed.
328
David Brownell71117632006-01-08 13:34:29 -0800329When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those
David Brownell33e34dc2007-05-08 00:32:21 -0700330configurations will also be dynamic. Fortunately, such devices all support
331basic device identification probes, so they should hotplug normally.
David Brownell71117632006-01-08 13:34:29 -0800332
David Brownell8ae12a02006-01-08 13:34:19 -0800333
334How do I write an "SPI Protocol Driver"?
335----------------------------------------
David Brownell33e34dc2007-05-08 00:32:21 -0700336Most SPI drivers are currently kernel drivers, but there's also support
337for userspace drivers. Here we talk only about kernel drivers.
David Brownell8ae12a02006-01-08 13:34:19 -0800338
David Brownellb8852442006-01-08 13:34:23 -0800339SPI protocol drivers somewhat resemble platform device drivers:
David Brownell8ae12a02006-01-08 13:34:19 -0800340
David Brownellb8852442006-01-08 13:34:23 -0800341 static struct spi_driver CHIP_driver = {
342 .driver = {
343 .name = "CHIP",
David Brownellb8852442006-01-08 13:34:23 -0800344 .owner = THIS_MODULE,
345 },
346
David Brownell8ae12a02006-01-08 13:34:19 -0800347 .probe = CHIP_probe,
Greg Kroah-Hartman63a29f72012-12-21 15:15:02 -0800348 .remove = CHIP_remove,
David Brownell8ae12a02006-01-08 13:34:19 -0800349 .suspend = CHIP_suspend,
350 .resume = CHIP_resume,
351 };
352
Ben Dooks9ed7ef52009-09-22 16:46:11 -0700353The driver core will automatically attempt to bind this driver to any SPI
David Brownell8ae12a02006-01-08 13:34:19 -0800354device whose board_info gave a modalias of "CHIP". Your probe() code
Tony Jones49dce682007-10-16 01:27:48 -0700355might look like this unless you're creating a device which is managing
356a bus (appearing under /sys/class/spi_master).
David Brownell8ae12a02006-01-08 13:34:19 -0800357
Greg Kroah-Hartman63a29f72012-12-21 15:15:02 -0800358 static int CHIP_probe(struct spi_device *spi)
David Brownell8ae12a02006-01-08 13:34:19 -0800359 {
David Brownell8ae12a02006-01-08 13:34:19 -0800360 struct CHIP *chip;
David Brownellb8852442006-01-08 13:34:23 -0800361 struct CHIP_platform_data *pdata;
362
363 /* assuming the driver requires board-specific data: */
364 pdata = &spi->dev.platform_data;
365 if (!pdata)
366 return -ENODEV;
David Brownell8ae12a02006-01-08 13:34:19 -0800367
368 /* get memory for driver's per-chip state */
369 chip = kzalloc(sizeof *chip, GFP_KERNEL);
370 if (!chip)
371 return -ENOMEM;
Ben Dooks9b40ff42007-02-12 00:52:41 -0800372 spi_set_drvdata(spi, chip);
David Brownell8ae12a02006-01-08 13:34:19 -0800373
374 ... etc
375 return 0;
376 }
377
378As soon as it enters probe(), the driver may issue I/O requests to
379the SPI device using "struct spi_message". When remove() returns,
David Brownell33e34dc2007-05-08 00:32:21 -0700380or after probe() fails, the driver guarantees that it won't submit
381any more such messages.
David Brownell8ae12a02006-01-08 13:34:19 -0800382
Paolo Ornati670e9f32006-10-03 22:57:56 +0200383 - An spi_message is a sequence of protocol operations, executed
David Brownell8ae12a02006-01-08 13:34:19 -0800384 as one atomic sequence. SPI driver controls include:
385
386 + when bidirectional reads and writes start ... by how its
387 sequence of spi_transfer requests is arranged;
388
David Brownell6395bee2008-04-08 17:41:58 -0700389 + which I/O buffers are used ... each spi_transfer wraps a
390 buffer for each transfer direction, supporting full duplex
391 (two pointers, maybe the same one in both cases) and half
392 duplex (one pointer is NULL) transfers;
393
David Brownell8ae12a02006-01-08 13:34:19 -0800394 + optionally defining short delays after transfers ... using
David Brownell6395bee2008-04-08 17:41:58 -0700395 the spi_transfer.delay_usecs setting (this delay can be the
396 only protocol effect, if the buffer length is zero);
David Brownell8ae12a02006-01-08 13:34:19 -0800397
398 + whether the chipselect becomes inactive after a transfer and
399 any delay ... by using the spi_transfer.cs_change flag;
400
401 + hinting whether the next message is likely to go to this same
402 device ... using the spi_transfer.cs_change flag on the last
403 transfer in that atomic group, and potentially saving costs
404 for chip deselect and select operations.
405
406 - Follow standard kernel rules, and provide DMA-safe buffers in
407 your messages. That way controller drivers using DMA aren't forced
408 to make extra copies unless the hardware requires it (e.g. working
409 around hardware errata that force the use of bounce buffering).
410
411 If standard dma_map_single() handling of these buffers is inappropriate,
412 you can use spi_message.is_dma_mapped to tell the controller driver
413 that you've already provided the relevant DMA addresses.
414
415 - The basic I/O primitive is spi_async(). Async requests may be
416 issued in any context (irq handler, task, etc) and completion
417 is reported using a callback provided with the message.
David Brownellb8852442006-01-08 13:34:23 -0800418 After any detected error, the chip is deselected and processing
419 of that spi_message is aborted.
David Brownell8ae12a02006-01-08 13:34:19 -0800420
421 - There are also synchronous wrappers like spi_sync(), and wrappers
422 like spi_read(), spi_write(), and spi_write_then_read(). These
423 may be issued only in contexts that may sleep, and they're all
424 clean (and small, and "optional") layers over spi_async().
425
426 - The spi_write_then_read() call, and convenience wrappers around
427 it, should only be used with small amounts of data where the
428 cost of an extra copy may be ignored. It's designed to support
429 common RPC-style requests, such as writing an eight bit command
430 and reading a sixteen bit response -- spi_w8r16() being one its
431 wrappers, doing exactly that.
432
433Some drivers may need to modify spi_device characteristics like the
434transfer mode, wordsize, or clock rate. This is done with spi_setup(),
435which would normally be called from probe() before the first I/O is
David Brownell33e34dc2007-05-08 00:32:21 -0700436done to the device. However, that can also be called at any time
437that no message is pending for that device.
David Brownell8ae12a02006-01-08 13:34:19 -0800438
439While "spi_device" would be the bottom boundary of the driver, the
440upper boundaries might include sysfs (especially for sensor readings),
441the input layer, ALSA, networking, MTD, the character device framework,
442or other Linux subsystems.
443
David Brownell0c868462006-01-08 13:34:25 -0800444Note that there are two types of memory your driver must manage as part
445of interacting with SPI devices.
446
447 - I/O buffers use the usual Linux rules, and must be DMA-safe.
448 You'd normally allocate them from the heap or free page pool.
449 Don't use the stack, or anything that's declared "static".
450
451 - The spi_message and spi_transfer metadata used to glue those
452 I/O buffers into a group of protocol transactions. These can
453 be allocated anywhere it's convenient, including as part of
454 other allocate-once driver data structures. Zero-init these.
455
456If you like, spi_message_alloc() and spi_message_free() convenience
457routines are available to allocate and zero-initialize an spi_message
458with several transfers.
459
David Brownell8ae12a02006-01-08 13:34:19 -0800460
461How do I write an "SPI Master Controller Driver"?
462-------------------------------------------------
463An SPI controller will probably be registered on the platform_bus; write
464a driver to bind to the device, whichever bus is involved.
465
466The main task of this type of driver is to provide an "spi_master".
Tony Jones49dce682007-10-16 01:27:48 -0700467Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
David Brownell8ae12a02006-01-08 13:34:19 -0800468to get the driver-private data allocated for that device.
469
470 struct spi_master *master;
471 struct CONTROLLER *c;
472
473 master = spi_alloc_master(dev, sizeof *c);
474 if (!master)
475 return -ENODEV;
476
Tony Jones49dce682007-10-16 01:27:48 -0700477 c = spi_master_get_devdata(master);
David Brownell8ae12a02006-01-08 13:34:19 -0800478
479The driver will initialize the fields of that spi_master, including the
480bus number (maybe the same as the platform device ID) and three methods
481used to interact with the SPI core and SPI protocol drivers. It will
David Brownella020ed72006-04-03 15:49:04 -0700482also initialize its own internal state. (See below about bus numbering
483and those methods.)
484
485After you initialize the spi_master, then use spi_register_master() to
Linus Walleijffbbdd212012-02-22 10:05:38 +0100486publish it to the rest of the system. At that time, device nodes for the
487controller and any predeclared spi devices will be made available, and
488the driver model core will take care of binding them to drivers.
David Brownella020ed72006-04-03 15:49:04 -0700489
490If you need to remove your SPI controller driver, spi_unregister_master()
491will reverse the effect of spi_register_master().
492
493
494BUS NUMBERING
495
496Bus numbering is important, since that's how Linux identifies a given
497SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
498SOC systems, the bus numbers should match the numbers defined by the chip
499manufacturer. For example, hardware controller SPI2 would be bus number 2,
500and spi_board_info for devices connected to it would use that number.
501
502If you don't have such hardware-assigned bus number, and for some reason
503you can't just assign them, then provide a negative bus number. That will
504then be replaced by a dynamically assigned number. You'd then need to treat
505this as a non-static configuration (see above).
506
507
508SPI MASTER METHODS
David Brownell8ae12a02006-01-08 13:34:19 -0800509
510 master->setup(struct spi_device *spi)
511 This sets up the device clock rate, SPI mode, and word sizes.
512 Drivers may change the defaults provided by board_info, and then
513 call spi_setup(spi) to invoke this routine. It may sleep.
David Brownell6e538aa2009-04-21 12:24:49 -0700514
David Brownell33e34dc2007-05-08 00:32:21 -0700515 Unless each SPI slave has its own configuration registers, don't
516 change them right away ... otherwise drivers could corrupt I/O
517 that's in progress for other SPI devices.
David Brownell8ae12a02006-01-08 13:34:19 -0800518
David Brownell6e538aa2009-04-21 12:24:49 -0700519 ** BUG ALERT: for some reason the first version of
520 ** many spi_master drivers seems to get this wrong.
521 ** When you code setup(), ASSUME that the controller
522 ** is actively processing transfers for another device.
523
David Brownell8ae12a02006-01-08 13:34:19 -0800524 master->cleanup(struct spi_device *spi)
525 Your controller driver may use spi_device.controller_state to hold
526 state it dynamically associates with that device. If you do that,
527 be sure to provide the cleanup() method to free that state.
528
Linus Walleijffbbdd212012-02-22 10:05:38 +0100529 master->prepare_transfer_hardware(struct spi_master *master)
530 This will be called by the queue mechanism to signal to the driver
531 that a message is coming in soon, so the subsystem requests the
532 driver to prepare the transfer hardware by issuing this call.
533 This may sleep.
534
535 master->unprepare_transfer_hardware(struct spi_master *master)
536 This will be called by the queue mechanism to signal to the driver
537 that there are no more messages pending in the queue and it may
538 relax the hardware (e.g. by power management calls). This may sleep.
539
540 master->transfer_one_message(struct spi_master *master,
541 struct spi_message *mesg)
542 The subsystem calls the driver to transfer a single message while
543 queuing transfers that arrive in the meantime. When the driver is
544 finished with this message, it must call
545 spi_finalize_current_message() so the subsystem can issue the next
Baruch Siache9305332014-01-25 22:36:15 +0200546 message. This may sleep.
Linus Walleijffbbdd212012-02-22 10:05:38 +0100547
Baruch Siach18cc0ad2014-01-25 22:36:14 +0200548 master->transfer_one(struct spi_master *master, struct spi_device *spi,
549 struct spi_transfer *transfer)
550 The subsystem calls the driver to transfer a single transfer while
551 queuing transfers that arrive in the meantime. When the driver is
552 finished with this transfer, it must call
553 spi_finalize_current_transfer() so the subsystem can issue the next
554 transfer. This may sleep. Note: transfer_one and transfer_one_message
555 are mutually exclusive; when both are set, the generic subsystem does
556 not call your transfer_one callback.
557
558 Return values:
559 negative errno: error
560 0: transfer is finished
561 1: transfer is still in progress
562
Linus Walleijffbbdd212012-02-22 10:05:38 +0100563 DEPRECATED METHODS
564
565 master->transfer(struct spi_device *spi, struct spi_message *message)
John Whitmore0c64bc12013-12-06 13:33:50 +0000566 This must not sleep. Its responsibility is to arrange that the
Linus Walleijffbbdd212012-02-22 10:05:38 +0100567 transfer happens and its complete() callback is issued. The two
568 will normally happen later, after other transfers complete, and
569 if the controller is idle it will need to be kickstarted. This
570 method is not used on queued controllers and must be NULL if
571 transfer_one_message() and (un)prepare_transfer_hardware() are
572 implemented.
573
David Brownella020ed72006-04-03 15:49:04 -0700574
575SPI MESSAGE QUEUE
576
Linus Walleijffbbdd212012-02-22 10:05:38 +0100577If you are happy with the standard queueing mechanism provided by the
578SPI subsystem, just implement the queued methods specified above. Using
579the message queue has the upside of centralizing a lot of code and
580providing pure process-context execution of methods. The message queue
581can also be elevated to realtime priority on high-priority SPI traffic.
582
583Unless the queueing mechanism in the SPI subsystem is selected, the bulk
584of the driver will be managing the I/O queue fed by the now deprecated
585function transfer().
David Brownell8ae12a02006-01-08 13:34:19 -0800586
587That queue could be purely conceptual. For example, a driver used only
André Goddard Rosaaf901ca2009-11-14 13:09:05 -0200588for low-frequency sensor access might be fine using synchronous PIO.
David Brownell8ae12a02006-01-08 13:34:19 -0800589
590But the queue will probably be very real, using message->queue, PIO,
591often DMA (especially if the root filesystem is in SPI flash), and
592execution contexts like IRQ handlers, tasklets, or workqueues (such
593as keventd). Your driver can be as fancy, or as simple, as you need.
David Brownella020ed72006-04-03 15:49:04 -0700594Such a transfer() method would normally just add the message to a
595queue, and then start some asynchronous transfer engine (unless it's
596already running).
David Brownell8ae12a02006-01-08 13:34:19 -0800597
598
599THANKS TO
600---------
601Contributors to Linux-SPI discussions include (in alphabetical order,
602by last name):
603
604David Brownell
605Russell King
606Dmitry Pervushin
607Stephen Street
608Mark Underwood
609Andrew Victor
610Vitaly Wool
Linus Walleijffbbdd212012-02-22 10:05:38 +0100611Grant Likely
612Mark Brown
613Linus Walleij