Documentation/spi/spi-summary.rst

5 02-Feb-2012
8 ------------
15 and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
17 clocking modes through which data is exchanged; mode-0 and mode-3 are most
18 commonly used.  Each clock cycle shifts data out and data in; the clock
19 doesn't cycle except when there is a data bit to shift.  Not all data bits
32   - SPI may be used for request/response style device protocols, as with
35   - It may also be used to stream data in either direction (half duplex),
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.
41   - Words are usually sent with their most significant bit (MSB) first,
44   - Sometimes SPI is used to daisy-chain devices, like shift registers.
48 a given SPI host controller will normally be set up manually, with
51 SPI is only one of the names used by such four-wire protocols, and
53 half-duplex SPI, for request/response protocols), SSP ("Synchronous
58 limiting themselves to half-duplex at the hardware level.  In fact
62 chips described as using "three wire" signaling: SCK, data, nCSx.
63 (That data line is sometimes called MOMI or SISO.)
71 ---------------------------------------
84 dedicated SPI controller exists, GPIO pins can be used to create a
86 controller; the reasons to use SPI focus on low cost and simple operation,
88 appropriate low-pincount peripheral bus.
92 cards without needing a special purpose MMC/SD/SDIO controller.
96 -----------------------------------------------------
100  - CPOL indicates the initial clock polarity.  CPOL=0 means the
105  - CPHA indicates the clock phase used to sample data; CPHA=0 says
109    implies that its data is written half a clock before the first
117 starting low (CPOL=0) and data stabilized for sampling during the
125 and always clock data in/out on rising clock edges.
129 ------------------------------------------------
143   Controller drivers ...
144         controllers may be built into System-On-Chip
145 	processors, and often support both Controller and target roles.
150         these pass messages through the controller
151 	driver to communicate with a target or Controller device on the
155 data to filesystems stored on SPI flash like DataFlash; and others might
158 And those might all be sharing the same controller driver.
160 A "struct spi_device" encapsulates the controller-side interface between
164 using the driver model to connect controller and protocol drivers using
168    /sys/devices/.../CTLR ... physical node for a given SPI controller
182 	class related state for the SPI host controller managing bus "B".
187 	target device for an SPI target controller.
195 	class related state for the SPI target controller on bus "B".  When
199 At this time, the only class-specific state is the bus number ("B" in "spiB"),
203 How does board-specific init code declare SPI devices?
204 ------------------------------------------------------
206 That information is normally provided by board-specific code, even for
213 For System-on-Chip (SOC) based boards, these will usually be platform
214 devices, and the controller may need some platform_data in order to
216 like the physical address of the controller's first register and its IRQ.
218 Platforms will often abstract the "register SPI controller" operation,
220 the arch/.../mach-*/board-*.c files for several boards can all share the
221 same basic controller setup code.  This is because most SOCs have several
222 SPI-capable controllers, and only the ones actually usable on a given
225 So for example arch/.../mach-*/board-*.c files might have code like::
229 	/* if your mach-* infrastructure doesn't support kernels that can
237 		/* this board only uses SPI controller #2 */
242 And SOC-specific utility code might look something like::
256 			spi2->dev.platform_data = pdata2;
269 same SOC controller is used.  For example, on one board SPI might use
277 on the target board, often with some board-specific data needed for the
280 Normally your arch/.../mach-*/board-*.c files would provide a small table
302 Again, notice how board-specific information is provided; each chip may need
305 is wired, plus chip-specific constraints like an important delay that's
309 controller driver.  An example would be peripheral-specific DMA tuning
310 data or chipselect callbacks.  This is stored in spi_device later.)
319 infrastructure, so that it's available later when the SPI host controller
324 Like with other static board-specific setup, you won't unregister those.
328 your ``arch/.../mach-.../board-*.c`` file would primarily provide information
333 Non-static Configurations
342 ----------------------------------------
370 		/* assuming the driver requires board-specific data: */
371 		pdata = &spi->dev.platform_data;
373 			return -ENODEV;
375 		/* get memory for driver's per-chip state */
378 			return -ENOMEM;
390   - An spi_message is a sequence of protocol operations, executed
416   - Follow standard kernel rules, and provide DMA-safe buffers in
417     your messages.  That way controller drivers using DMA aren't forced
421   - The basic I/O primitive is spi_async().  Async requests may be
427   - There are also synchronous wrappers like spi_sync(), and wrappers
432   - The spi_write_then_read() call, and convenience wrappers around
433     it, should only be used with small amounts of data where the
435     common RPC-style requests, such as writing an eight bit command
436     and reading a sixteen bit response -- spi_w8r16() being one its
453   - I/O buffers use the usual Linux rules, and must be DMA-safe.
457   - The spi_message and spi_transfer metadata used to glue those
460     other allocate-once driver data structures.  Zero-init these.
463 routines are available to allocate and zero-initialize an spi_message
467 How do I write an "SPI Controller Driver"?
468 -------------------------------------------------
469 An SPI controller will probably be registered on the platform_bus; write
473 Use spi_alloc_host() to allocate the host controller, and
474 spi_controller_get_devdata() to get the driver-private data allocated for that
480 	struct CONTROLLER	*c;
484 		return -ENODEV;
495 controller and any predeclared spi devices will be made available, and
498 If you need to remove your SPI controller driver, spi_unregister_controller()
508 manufacturer.  For example, hardware controller SPI2 would be bus number 2,
511 If you don't have such hardware-assigned bus number, and for some reason
514 this as a non-static configuration (see above).
517 SPI Host Controller Methods
520 ``ctlr->setup(struct spi_device *spi)``
533 		When you code setup(), ASSUME that the controller
536 ``ctlr->cleanup(struct spi_device *spi)``
537 	Your controller driver may use spi_device.controller_state to hold
541 ``ctlr->prepare_transfer_hardware(struct spi_controller *ctlr)``
547 ``ctlr->unprepare_transfer_hardware(struct spi_controller *ctlr)``
552 ``ctlr->transfer_one_message(struct spi_controller *ctlr, struct spi_message *mesg)``
559 ``ctrl->transfer_one(struct spi_controller *ctlr, struct spi_device *spi, struct spi_transfer *tran…
574 ``ctrl->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_…
575 	This method allows SPI client drivers to request SPI host controller
582 ``ctrl->transfer(struct spi_device *spi, struct spi_message *message)``
586 	if the controller is idle it will need to be kickstarted. This
598 providing pure process-context execution of methods. The message queue
599 can also be elevated to realtime priority on high-priority SPI traffic.
606 for low-frequency sensor access might be fine using synchronous PIO.
608 But the queue will probably be very real, using message->queue, PIO,
618 ------------------------------
645   : marks when data is clocked into the peripheral;
646   ; marks when data is clocked into the controller;
650 that other SPI protocols don't (e.g. data line state for when CS is not
658 MOSI line when the controller is not clocking out data. However, there do exist
659 peripherals that require specific MOSI line state when data is not being clocked
661 controller is not clocking out data (``SPI_MOSI_IDLE_HIGH``), then a transfer in
684   : marks when data is clocked into the peripheral;
685   ; marks when data is clocked into the controller;
689 be kept high when CS is asserted but the controller is not clocking out data to
701 ---------
702 Contributors to Linux-SPI discussions include (in alphabetical order,
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