xref: /linux/Documentation/spi/spi-summary.rst (revision 3ea5eb68b9d624935108b5e696859304edfac202)
1====================================
2Overview of Linux kernel SPI support
3====================================
4
502-Feb-2012
6
7What is SPI?
8------------
9The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
10link used to connect microcontrollers to sensors, memory, and peripherals.
11It's a simple "de facto" standard, not complicated enough to acquire a
12standardization body.  SPI uses a host/target configuration.
13
14The three signal wires hold a clock (SCK, often on the order of 10 MHz),
15and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
16Slave Out" (MISO) signals.  (Other names are also used.)  There are four
17clocking modes through which data is exchanged; mode-0 and mode-3 are most
18commonly used.  Each clock cycle shifts data out and data in; the clock
19doesn't cycle except when there is a data bit to shift.  Not all data bits
20are used though; not every protocol uses those full duplex capabilities.
21
22SPI hosts use a fourth "chip select" line to activate a given SPI target
23device, so those three signal wires may be connected to several chips
24in parallel.  All SPI targets support chipselects; they are usually active
25low signals, labeled nCSx for target 'x' (e.g. nCS0).  Some devices have
26other signals, often including an interrupt to the host.
27
28Unlike serial busses like USB or SMBus, even low level protocols for
29SPI target functions are usually not interoperable between vendors
30(except for commodities like SPI memory chips).
31
32  - SPI may be used for request/response style device protocols, as with
33    touchscreen sensors and memory chips.
34
35  - It may also be used to stream data in either direction (half duplex),
36    or both of them at the same time (full duplex).
37
38  - Some devices may use eight bit words.  Others may use different word
39    lengths, such as streams of 12-bit or 20-bit digital samples.
40
41  - Words are usually sent with their most significant bit (MSB) first,
42    but sometimes the least significant bit (LSB) goes first instead.
43
44  - Sometimes SPI is used to daisy-chain devices, like shift registers.
45
46In the same way, SPI targets will only rarely support any kind of automatic
47discovery/enumeration protocol. The tree of target devices accessible from
48a given SPI host controller will normally be set up manually, with
49configuration tables.
50
51SPI is only one of the names used by such four-wire protocols, and
52most controllers have no problem handling "MicroWire" (think of it as
53half-duplex SPI, for request/response protocols), SSP ("Synchronous
54Serial Protocol"), PSP ("Programmable Serial Protocol"), and other
55related protocols.
56
57Some chips eliminate a signal line by combining MOSI and MISO, and
58limiting themselves to half-duplex at the hardware level.  In fact
59some SPI chips have this signal mode as a strapping option.  These
60can be accessed using the same programming interface as SPI, but of
61course they won't handle full duplex transfers.  You may find such
62chips described as using "three wire" signaling: SCK, data, nCSx.
63(That data line is sometimes called MOMI or SISO.)
64
65Microcontrollers often support both host and target sides of the SPI
66protocol.  This document (and Linux) supports both the host and target
67sides of SPI interactions.
68
69
70Who uses it?  On what kinds of systems?
71---------------------------------------
72Linux developers using SPI are probably writing device drivers for embedded
73systems boards.  SPI is used to control external chips, and it is also a
74protocol supported by every MMC or SD memory card.  (The older "DataFlash"
75cards, predating MMC cards but using the same connectors and card shape,
76support only SPI.)  Some PC hardware uses SPI flash for BIOS code.
77
78SPI target chips range from digital/analog converters used for analog
79sensors and codecs, to memory, to peripherals like USB controllers
80or Ethernet adapters; and more.
81
82Most systems using SPI will integrate a few devices on a mainboard.
83Some provide SPI links on expansion connectors; in cases where no
84dedicated SPI controller exists, GPIO pins can be used to create a
85low speed "bitbanging" adapter.  Very few systems will "hotplug" an SPI
86controller; the reasons to use SPI focus on low cost and simple operation,
87and if dynamic reconfiguration is important, USB will often be a more
88appropriate low-pincount peripheral bus.
89
90Many microcontrollers that can run Linux integrate one or more I/O
91interfaces with SPI modes.  Given SPI support, they could use MMC or SD
92cards without needing a special purpose MMC/SD/SDIO controller.
93
94
95I'm confused.  What are these four SPI "clock modes"?
96-----------------------------------------------------
97It's easy to be confused here, and the vendor documentation you'll
98find isn't necessarily helpful.  The four modes combine two mode bits:
99
100 - CPOL indicates the initial clock polarity.  CPOL=0 means the
101   clock starts low, so the first (leading) edge is rising, and
102   the second (trailing) edge is falling.  CPOL=1 means the clock
103   starts high, so the first (leading) edge is falling.
104
105 - CPHA indicates the clock phase used to sample data; CPHA=0 says
106   sample on the leading edge, CPHA=1 means the trailing edge.
107
108   Since the signal needs to stabilize before it's sampled, CPHA=0
109   implies that its data is written half a clock before the first
110   clock edge.  The chipselect may have made it become available.
111
112Chip specs won't always say "uses SPI mode X" in as many words,
113but their timing diagrams will make the CPOL and CPHA modes clear.
114
115In the SPI mode number, CPOL is the high order bit and CPHA is the
116low order bit.  So when a chip's timing diagram shows the clock
117starting low (CPOL=0) and data stabilized for sampling during the
118trailing clock edge (CPHA=1), that's SPI mode 1.
119
120Note that the clock mode is relevant as soon as the chipselect goes
121active.  So the host must set the clock to inactive before selecting
122a target, and the target can tell the chosen polarity by sampling the
123clock level when its select line goes active.  That's why many devices
124support for example both modes 0 and 3:  they don't care about polarity,
125and always clock data in/out on rising clock edges.
126
127
128How do these driver programming interfaces work?
129------------------------------------------------
130The <linux/spi/spi.h> header file includes kerneldoc, as does the
131main source code, and you should certainly read that chapter of the
132kernel API document.  This is just an overview, so you get the big
133picture before those details.
134
135SPI requests always go into I/O queues.  Requests for a given SPI device
136are always executed in FIFO order, and complete asynchronously through
137completion callbacks.  There are also some simple synchronous wrappers
138for those calls, including ones for common transaction types like writing
139a command and then reading its response.
140
141There are two types of SPI driver, here called:
142
143  Controller drivers ...
144        controllers may be built into System-On-Chip
145	processors, and often support both Controller and target roles.
146	These drivers touch hardware registers and may use DMA.
147	Or they can be PIO bitbangers, needing just GPIO pins.
148
149  Protocol drivers ...
150        these pass messages through the controller
151	driver to communicate with a target or Controller device on the
152	other side of an SPI link.
153
154So for example one protocol driver might talk to the MTD layer to export
155data to filesystems stored on SPI flash like DataFlash; and others might
156control audio interfaces, present touchscreen sensors as input interfaces,
157or monitor temperature and voltage levels during industrial processing.
158And those might all be sharing the same controller driver.
159
160A "struct spi_device" encapsulates the controller-side interface between
161those two types of drivers.
162
163There is a minimal core of SPI programming interfaces, focussing on
164using the driver model to connect controller and protocol drivers using
165device tables provided by board specific initialization code.  SPI
166shows up in sysfs in several locations::
167
168   /sys/devices/.../CTLR ... physical node for a given SPI controller
169
170   /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B",
171	chipselect C, accessed through CTLR.
172
173   /sys/bus/spi/devices/spiB.C ... symlink to that physical
174	.../CTLR/spiB.C device
175
176   /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
177	that should be used with this device (for hotplug/coldplug)
178
179   /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices
180
181   /sys/class/spi_master/spiB ... symlink to a logical node which could hold
182	class related state for the SPI host controller managing bus "B".
183	All spiB.* devices share one physical SPI bus segment, with SCLK,
184	MOSI, and MISO.
185
186   /sys/devices/.../CTLR/slave ... virtual file for (un)registering the
187	target device for an SPI target controller.
188	Writing the driver name of an SPI target handler to this file
189	registers the target device; writing "(null)" unregisters the target
190	device.
191	Reading from this file shows the name of the target device ("(null)"
192	if not registered).
193
194   /sys/class/spi_slave/spiB ... symlink to a logical node which could hold
195	class related state for the SPI target controller on bus "B".  When
196	registered, a single spiB.* device is present here, possible sharing
197	the physical SPI bus segment with other SPI target devices.
198
199At this time, the only class-specific state is the bus number ("B" in "spiB"),
200so those /sys/class entries are only useful to quickly identify busses.
201
202
203How does board-specific init code declare SPI devices?
204------------------------------------------------------
205Linux needs several kinds of information to properly configure SPI devices.
206That information is normally provided by board-specific code, even for
207chips that do support some of automated discovery/enumeration.
208
209Declare Controllers
210^^^^^^^^^^^^^^^^^^^
211
212The first kind of information is a list of what SPI controllers exist.
213For System-on-Chip (SOC) based boards, these will usually be platform
214devices, and the controller may need some platform_data in order to
215operate properly.  The "struct platform_device" will include resources
216like the physical address of the controller's first register and its IRQ.
217
218Platforms will often abstract the "register SPI controller" operation,
219maybe coupling it with code to initialize pin configurations, so that
220the arch/.../mach-*/board-*.c files for several boards can all share the
221same basic controller setup code.  This is because most SOCs have several
222SPI-capable controllers, and only the ones actually usable on a given
223board should normally be set up and registered.
224
225So for example arch/.../mach-*/board-*.c files might have code like::
226
227	#include <mach/spi.h>	/* for mysoc_spi_data */
228
229	/* if your mach-* infrastructure doesn't support kernels that can
230	 * run on multiple boards, pdata wouldn't benefit from "__init".
231	 */
232	static struct mysoc_spi_data pdata __initdata = { ... };
233
234	static __init board_init(void)
235	{
236		...
237		/* this board only uses SPI controller #2 */
238		mysoc_register_spi(2, &pdata);
239		...
240	}
241
242And SOC-specific utility code might look something like::
243
244	#include <mach/spi.h>
245
246	static struct platform_device spi2 = { ... };
247
248	void mysoc_register_spi(unsigned n, struct mysoc_spi_data *pdata)
249	{
250		struct mysoc_spi_data *pdata2;
251
252		pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
253		*pdata2 = pdata;
254		...
255		if (n == 2) {
256			spi2->dev.platform_data = pdata2;
257			register_platform_device(&spi2);
258
259			/* also: set up pin modes so the spi2 signals are
260			 * visible on the relevant pins ... bootloaders on
261			 * production boards may already have done this, but
262			 * developer boards will often need Linux to do it.
263			 */
264		}
265		...
266	}
267
268Notice how the platform_data for boards may be different, even if the
269same SOC controller is used.  For example, on one board SPI might use
270an external clock, where another derives the SPI clock from current
271settings of some master clock.
272
273Declare target Devices
274^^^^^^^^^^^^^^^^^^^^^^
275
276The second kind of information is a list of what SPI target devices exist
277on the target board, often with some board-specific data needed for the
278driver to work correctly.
279
280Normally your arch/.../mach-*/board-*.c files would provide a small table
281listing the SPI devices on each board.  (This would typically be only a
282small handful.)  That might look like::
283
284	static struct ads7846_platform_data ads_info = {
285		.vref_delay_usecs	= 100,
286		.x_plate_ohms		= 580,
287		.y_plate_ohms		= 410,
288	};
289
290	static struct spi_board_info spi_board_info[] __initdata = {
291	{
292		.modalias	= "ads7846",
293		.platform_data	= &ads_info,
294		.mode		= SPI_MODE_0,
295		.irq		= GPIO_IRQ(31),
296		.max_speed_hz	= 120000 /* max sample rate at 3V */ * 16,
297		.bus_num	= 1,
298		.chip_select	= 0,
299	},
300	};
301
302Again, notice how board-specific information is provided; each chip may need
303several types.  This example shows generic constraints like the fastest SPI
304clock to allow (a function of board voltage in this case) or how an IRQ pin
305is wired, plus chip-specific constraints like an important delay that's
306changed by the capacitance at one pin.
307
308(There's also "controller_data", information that may be useful to the
309controller driver.  An example would be peripheral-specific DMA tuning
310data or chipselect callbacks.  This is stored in spi_device later.)
311
312The board_info should provide enough information to let the system work
313without the chip's driver being loaded.  The most troublesome aspect of
314that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since
315sharing a bus with a device that interprets chipselect "backwards" is
316not possible until the infrastructure knows how to deselect it.
317
318Then your board initialization code would register that table with the SPI
319infrastructure, so that it's available later when the SPI host controller
320driver is registered::
321
322	spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
323
324Like with other static board-specific setup, you won't unregister those.
325
326The widely used "card" style computers bundle memory, cpu, and little else
327onto a card that's maybe just thirty square centimeters.  On such systems,
328your ``arch/.../mach-.../board-*.c`` file would primarily provide information
329about the devices on the mainboard into which such a card is plugged.  That
330certainly includes SPI devices hooked up through the card connectors!
331
332
333Non-static Configurations
334^^^^^^^^^^^^^^^^^^^^^^^^^
335
336When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those
337configurations will also be dynamic.  Fortunately, such devices all support
338basic device identification probes, so they should hotplug normally.
339
340
341How do I write an "SPI Protocol Driver"?
342----------------------------------------
343Most SPI drivers are currently kernel drivers, but there's also support
344for userspace drivers.  Here we talk only about kernel drivers.
345
346SPI protocol drivers somewhat resemble platform device drivers::
347
348	static struct spi_driver CHIP_driver = {
349		.driver = {
350			.name		= "CHIP",
351			.pm		= &CHIP_pm_ops,
352		},
353
354		.probe		= CHIP_probe,
355		.remove		= CHIP_remove,
356	};
357
358The driver core will automatically attempt to bind this driver to any SPI
359device whose board_info gave a modalias of "CHIP".  Your probe() code
360might look like this unless you're creating a device which is managing
361a bus (appearing under /sys/class/spi_master).
362
363::
364
365	static int CHIP_probe(struct spi_device *spi)
366	{
367		struct CHIP			*chip;
368		struct CHIP_platform_data	*pdata;
369
370		/* assuming the driver requires board-specific data: */
371		pdata = &spi->dev.platform_data;
372		if (!pdata)
373			return -ENODEV;
374
375		/* get memory for driver's per-chip state */
376		chip = kzalloc(sizeof *chip, GFP_KERNEL);
377		if (!chip)
378			return -ENOMEM;
379		spi_set_drvdata(spi, chip);
380
381		... etc
382		return 0;
383	}
384
385As soon as it enters probe(), the driver may issue I/O requests to
386the SPI device using "struct spi_message".  When remove() returns,
387or after probe() fails, the driver guarantees that it won't submit
388any more such messages.
389
390  - An spi_message is a sequence of protocol operations, executed
391    as one atomic sequence.  SPI driver controls include:
392
393      + when bidirectional reads and writes start ... by how its
394        sequence of spi_transfer requests is arranged;
395
396      + which I/O buffers are used ... each spi_transfer wraps a
397        buffer for each transfer direction, supporting full duplex
398        (two pointers, maybe the same one in both cases) and half
399        duplex (one pointer is NULL) transfers;
400
401      + optionally defining short delays after transfers ... using
402        the spi_transfer.delay.value setting (this delay can be the
403        only protocol effect, if the buffer length is zero) ...
404        when specifying this delay the default spi_transfer.delay.unit
405        is microseconds, however this can be adjusted to clock cycles
406        or nanoseconds if needed;
407
408      + whether the chipselect becomes inactive after a transfer and
409        any delay ... by using the spi_transfer.cs_change flag;
410
411      + hinting whether the next message is likely to go to this same
412        device ... using the spi_transfer.cs_change flag on the last
413	transfer in that atomic group, and potentially saving costs
414	for chip deselect and select operations.
415
416  - Follow standard kernel rules, and provide DMA-safe buffers in
417    your messages.  That way controller drivers using DMA aren't forced
418    to make extra copies unless the hardware requires it (e.g. working
419    around hardware errata that force the use of bounce buffering).
420
421  - The basic I/O primitive is spi_async().  Async requests may be
422    issued in any context (irq handler, task, etc) and completion
423    is reported using a callback provided with the message.
424    After any detected error, the chip is deselected and processing
425    of that spi_message is aborted.
426
427  - There are also synchronous wrappers like spi_sync(), and wrappers
428    like spi_read(), spi_write(), and spi_write_then_read().  These
429    may be issued only in contexts that may sleep, and they're all
430    clean (and small, and "optional") layers over spi_async().
431
432  - The spi_write_then_read() call, and convenience wrappers around
433    it, should only be used with small amounts of data where the
434    cost of an extra copy may be ignored.  It's designed to support
435    common RPC-style requests, such as writing an eight bit command
436    and reading a sixteen bit response -- spi_w8r16() being one its
437    wrappers, doing exactly that.
438
439Some drivers may need to modify spi_device characteristics like the
440transfer mode, wordsize, or clock rate.  This is done with spi_setup(),
441which would normally be called from probe() before the first I/O is
442done to the device.  However, that can also be called at any time
443that no message is pending for that device.
444
445While "spi_device" would be the bottom boundary of the driver, the
446upper boundaries might include sysfs (especially for sensor readings),
447the input layer, ALSA, networking, MTD, the character device framework,
448or other Linux subsystems.
449
450Note that there are two types of memory your driver must manage as part
451of interacting with SPI devices.
452
453  - I/O buffers use the usual Linux rules, and must be DMA-safe.
454    You'd normally allocate them from the heap or free page pool.
455    Don't use the stack, or anything that's declared "static".
456
457  - The spi_message and spi_transfer metadata used to glue those
458    I/O buffers into a group of protocol transactions.  These can
459    be allocated anywhere it's convenient, including as part of
460    other allocate-once driver data structures.  Zero-init these.
461
462If you like, spi_message_alloc() and spi_message_free() convenience
463routines are available to allocate and zero-initialize an spi_message
464with several transfers.
465
466
467How do I write an "SPI Controller Driver"?
468-------------------------------------------------
469An SPI controller will probably be registered on the platform_bus; write
470a driver to bind to the device, whichever bus is involved.
471
472The main task of this type of driver is to provide an "spi_controller".
473Use spi_alloc_host() to allocate the host controller, and
474spi_controller_get_devdata() to get the driver-private data allocated for that
475device.
476
477::
478
479	struct spi_controller	*ctlr;
480	struct CONTROLLER	*c;
481
482	ctlr = spi_alloc_host(dev, sizeof *c);
483	if (!ctlr)
484		return -ENODEV;
485
486	c = spi_controller_get_devdata(ctlr);
487
488The driver will initialize the fields of that spi_controller, including the bus
489number (maybe the same as the platform device ID) and three methods used to
490interact with the SPI core and SPI protocol drivers.  It will also initialize
491its own internal state.  (See below about bus numbering and those methods.)
492
493After you initialize the spi_controller, then use spi_register_controller() to
494publish it to the rest of the system. At that time, device nodes for the
495controller and any predeclared spi devices will be made available, and
496the driver model core will take care of binding them to drivers.
497
498If you need to remove your SPI controller driver, spi_unregister_controller()
499will reverse the effect of spi_register_controller().
500
501
502Bus Numbering
503^^^^^^^^^^^^^
504
505Bus numbering is important, since that's how Linux identifies a given
506SPI bus (shared SCK, MOSI, MISO).  Valid bus numbers start at zero.  On
507SOC systems, the bus numbers should match the numbers defined by the chip
508manufacturer.  For example, hardware controller SPI2 would be bus number 2,
509and spi_board_info for devices connected to it would use that number.
510
511If you don't have such hardware-assigned bus number, and for some reason
512you can't just assign them, then provide a negative bus number.  That will
513then be replaced by a dynamically assigned number. You'd then need to treat
514this as a non-static configuration (see above).
515
516
517SPI Host Controller Methods
518^^^^^^^^^^^^^^^^^^^^^^^^^^^
519
520``ctlr->setup(struct spi_device *spi)``
521	This sets up the device clock rate, SPI mode, and word sizes.
522	Drivers may change the defaults provided by board_info, and then
523	call spi_setup(spi) to invoke this routine.  It may sleep.
524
525	Unless each SPI target has its own configuration registers, don't
526	change them right away ... otherwise drivers could corrupt I/O
527	that's in progress for other SPI devices.
528
529	.. note::
530
531		BUG ALERT:  for some reason the first version of
532		many spi_controller drivers seems to get this wrong.
533		When you code setup(), ASSUME that the controller
534		is actively processing transfers for another device.
535
536``ctlr->cleanup(struct spi_device *spi)``
537	Your controller driver may use spi_device.controller_state to hold
538	state it dynamically associates with that device.  If you do that,
539	be sure to provide the cleanup() method to free that state.
540
541``ctlr->prepare_transfer_hardware(struct spi_controller *ctlr)``
542	This will be called by the queue mechanism to signal to the driver
543	that a message is coming in soon, so the subsystem requests the
544	driver to prepare the transfer hardware by issuing this call.
545	This may sleep.
546
547``ctlr->unprepare_transfer_hardware(struct spi_controller *ctlr)``
548	This will be called by the queue mechanism to signal to the driver
549	that there are no more messages pending in the queue and it may
550	relax the hardware (e.g. by power management calls). This may sleep.
551
552``ctlr->transfer_one_message(struct spi_controller *ctlr, struct spi_message *mesg)``
553	The subsystem calls the driver to transfer a single message while
554	queuing transfers that arrive in the meantime. When the driver is
555	finished with this message, it must call
556	spi_finalize_current_message() so the subsystem can issue the next
557	message. This may sleep.
558
559``ctrl->transfer_one(struct spi_controller *ctlr, struct spi_device *spi, struct spi_transfer *transfer)``
560	The subsystem calls the driver to transfer a single transfer while
561	queuing transfers that arrive in the meantime. When the driver is
562	finished with this transfer, it must call
563	spi_finalize_current_transfer() so the subsystem can issue the next
564	transfer. This may sleep. Note: transfer_one and transfer_one_message
565	are mutually exclusive; when both are set, the generic subsystem does
566	not call your transfer_one callback.
567
568	Return values:
569
570	* negative errno: error
571	* 0: transfer is finished
572	* 1: transfer is still in progress
573
574``ctrl->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
575	This method allows SPI client drivers to request SPI host controller
576	for configuring device specific CS setup, hold and inactive timing
577	requirements.
578
579Deprecated Methods
580^^^^^^^^^^^^^^^^^^
581
582``ctrl->transfer(struct spi_device *spi, struct spi_message *message)``
583	This must not sleep. Its responsibility is to arrange that the
584	transfer happens and its complete() callback is issued. The two
585	will normally happen later, after other transfers complete, and
586	if the controller is idle it will need to be kickstarted. This
587	method is not used on queued controllers and must be NULL if
588	transfer_one_message() and (un)prepare_transfer_hardware() are
589	implemented.
590
591
592SPI Message Queue
593^^^^^^^^^^^^^^^^^
594
595If you are happy with the standard queueing mechanism provided by the
596SPI subsystem, just implement the queued methods specified above. Using
597the message queue has the upside of centralizing a lot of code and
598providing pure process-context execution of methods. The message queue
599can also be elevated to realtime priority on high-priority SPI traffic.
600
601Unless the queueing mechanism in the SPI subsystem is selected, the bulk
602of the driver will be managing the I/O queue fed by the now deprecated
603function transfer().
604
605That queue could be purely conceptual.  For example, a driver used only
606for low-frequency sensor access might be fine using synchronous PIO.
607
608But the queue will probably be very real, using message->queue, PIO,
609often DMA (especially if the root filesystem is in SPI flash), and
610execution contexts like IRQ handlers, tasklets, or workqueues (such
611as keventd).  Your driver can be as fancy, or as simple, as you need.
612Such a transfer() method would normally just add the message to a
613queue, and then start some asynchronous transfer engine (unless it's
614already running).
615
616
617Extensions to the SPI protocol
618------------------------------
619The fact that SPI doesn't have a formal specification or standard permits chip
620manufacturers to implement the SPI protocol in slightly different ways. In most
621cases, SPI protocol implementations from different vendors are compatible among
622each other. For example, in SPI mode 0 (CPOL=0, CPHA=0) the bus lines may behave
623like the following:
624
625::
626
627  nCSx ___                                                                   ___
628          \_________________________________________________________________/
629          •                                                                 •
630          •                                                                 •
631  SCLK         ___     ___     ___     ___     ___     ___     ___     ___
632       _______/   \___/   \___/   \___/   \___/   \___/   \___/   \___/   \_____
633          •   :   ;   :   ;   :   ;   :   ;   :   ;   :   ;   :   ;   :   ; •
634          •   :   ;   :   ;   :   ;   :   ;   :   ;   :   ;   :   ;   :   ; •
635  MOSI XXX__________         _______                 _______         ________XXX
636  0xA5 XXX__/ 1     \_0_____/ 1     \_0_______0_____/ 1     \_0_____/ 1    \_XXX
637          •       ;       ;       ;       ;       ;       ;       ;       ; •
638          •       ;       ;       ;       ;       ;       ;       ;       ; •
639  MISO XXX__________         _______________________          _______        XXX
640  0xBA XXX__/     1 \_____0_/     1       1       1 \_____0__/    1  \____0__XXX
641
642Legend::
643
644  • marks the start/end of transmission;
645  : marks when data is clocked into the peripheral;
646  ; marks when data is clocked into the controller;
647  X marks when line states are not specified.
648
649In some few cases, chips extend the SPI protocol by specifying line behaviors
650that other SPI protocols don't (e.g. data line state for when CS is not
651asserted). Those distinct SPI protocols, modes, and configurations are supported
652by different SPI mode flags.
653
654MOSI idle state configuration
655^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
656
657Common SPI protocol implementations don't specify any state or behavior for the
658MOSI line when the controller is not clocking out data. However, there do exist
659peripherals that require specific MOSI line state when data is not being clocked
660out. For example, if the peripheral expects the MOSI line to be high when the
661controller is not clocking out data (``SPI_MOSI_IDLE_HIGH``), then a transfer in
662SPI mode 0 would look like the following:
663
664::
665
666  nCSx ___                                                                   ___
667          \_________________________________________________________________/
668          •                                                                 •
669          •                                                                 •
670  SCLK         ___     ___     ___     ___     ___     ___     ___     ___
671       _______/   \___/   \___/   \___/   \___/   \___/   \___/   \___/   \_____
672          •   :   ;   :   ;   :   ;   :   ;   :   ;   :   ;   :   ;   :   ; •
673          •   :   ;   :   ;   :   ;   :   ;   :   ;   :   ;   :   ;   :   ; •
674  MOSI _____         _______         _______         _______________         ___
675  0x56      \_0_____/ 1     \_0_____/ 1     \_0_____/ 1       1     \_0_____/
676          •       ;       ;       ;       ;       ;       ;       ;       ; •
677          •       ;       ;       ;       ;       ;       ;       ;       ; •
678  MISO XXX__________         _______________________          _______        XXX
679  0xBA XXX__/     1 \_____0_/     1       1       1 \_____0__/    1  \____0__XXX
680
681Legend::
682
683  • marks the start/end of transmission;
684  : marks when data is clocked into the peripheral;
685  ; marks when data is clocked into the controller;
686  X marks when line states are not specified.
687
688In this extension to the usual SPI protocol, the MOSI line state is specified to
689be kept high when CS is asserted but the controller is not clocking out data to
690the peripheral and also when CS is not asserted.
691
692Peripherals that require this extension must request it by setting the
693``SPI_MOSI_IDLE_HIGH`` bit into the mode attribute of their ``struct
694spi_device`` and call spi_setup(). Controllers that support this extension
695should indicate it by setting ``SPI_MOSI_IDLE_HIGH`` in the mode_bits attribute
696of their ``struct spi_controller``. The configuration to idle MOSI low is
697analogous but uses the ``SPI_MOSI_IDLE_LOW`` mode bit.
698
699
700THANKS TO
701---------
702Contributors to Linux-SPI discussions include (in alphabetical order,
703by last name):
704
705- Mark Brown
706- David Brownell
707- Russell King
708- Grant Likely
709- Dmitry Pervushin
710- Stephen Street
711- Mark Underwood
712- Andrew Victor
713- Linus Walleij
714- Vitaly Wool
715