Documentation/spi/spi-summary.rst

5 02-Feb-2012
8 ------------
17 clocking modes through which data is exchanged; mode-0 and mode-3 are most
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.
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
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
129 ------------------------------------------------
143   Controller drivers ...
144         controllers may be built into System-On-Chip
150         these pass messages through the controller
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
165 device tables provided by board specific initialization code.  SPI
168    /sys/devices/.../CTLR ... physical node for a given SPI controller
183 	master controller managing bus "B".  All spiB.* devices share one
187 	slave device for an SPI slave controller.
196 	slave controller on bus "B".  When registered, a single spiB.*
200 Note that the actual location of the controller's class state depends
202 the only class-specific state is the bus number ("B" in "spiB"), so
206 How does board-specific init code declare SPI devices?
207 ------------------------------------------------------
209 That information is normally provided by board-specific code, even for
216 For System-on-Chip (SOC) based boards, these will usually be platform
217 devices, and the controller may need some platform_data in order to
219 like the physical address of the controller's first register and its IRQ.
221 Platforms will often abstract the "register SPI controller" operation,
223 the arch/.../mach-*/board-*.c files for several boards can all share the
224 same basic controller setup code.  This is because most SOCs have several
225 SPI-capable controllers, and only the ones actually usable on a given
228 So for example arch/.../mach-*/board-*.c files might have code like::
232 	/* if your mach-* infrastructure doesn't support kernels that can
240 		/* this board only uses SPI controller #2 */
245 And SOC-specific utility code might look something like::
259 			spi2->dev.platform_data = pdata2;
272 same SOC controller is used.  For example, on one board SPI might use
280 on the target board, often with some board-specific data needed for the
283 Normally your arch/.../mach-*/board-*.c files would provide a small table
305 Again, notice how board-specific information is provided; each chip may need
308 is wired, plus chip-specific constraints like an important delay that's
312 controller driver.  An example would be peripheral-specific DMA tuning
322 infrastructure, so that it's available later when the SPI master controller
327 Like with other static board-specific setup, you won't unregister those.
331 your ``arch/.../mach-.../board-*.c`` file would primarily provide information
336 Non-static Configurations
353 ----------------------------------------
382 		/* assuming the driver requires board-specific data: */
383 		pdata = &spi->dev.platform_data;
385 			return -ENODEV;
387 		/* get memory for driver's per-chip state */
390 			return -ENOMEM;
402   - An spi_message is a sequence of protocol operations, executed
425   - Follow standard kernel rules, and provide DMA-safe buffers in
426     your messages.  That way controller drivers using DMA aren't forced
431     you can use spi_message.is_dma_mapped to tell the controller driver
434   - The basic I/O primitive is spi_async().  Async requests may be
440   - There are also synchronous wrappers like spi_sync(), and wrappers
445   - The spi_write_then_read() call, and convenience wrappers around
448     common RPC-style requests, such as writing an eight bit command
449     and reading a sixteen bit response -- spi_w8r16() being one its
466   - I/O buffers use the usual Linux rules, and must be DMA-safe.
470   - The spi_message and spi_transfer metadata used to glue those
473     other allocate-once driver data structures.  Zero-init these.
476 routines are available to allocate and zero-initialize an spi_message
480 How do I write an "SPI Master Controller Driver"?
481 -------------------------------------------------
482 An SPI controller will probably be registered on the platform_bus; write
487 to get the driver-private data allocated for that device.
492 	struct CONTROLLER	*c;
496 		return -ENODEV;
508 controller and any predeclared spi devices will be made available, and
511 If you need to remove your SPI controller driver, spi_unregister_master()
521 manufacturer.  For example, hardware controller SPI2 would be bus number 2,
524 If you don't have such hardware-assigned bus number, and for some reason
527 this as a non-static configuration (see above).
533 ``master->setup(struct spi_device *spi)``
546 		When you code setup(), ASSUME that the controller
549 ``master->cleanup(struct spi_device *spi)``
550 	Your controller driver may use spi_device.controller_state to hold
554 ``master->prepare_transfer_hardware(struct spi_master *master)``
560 ``master->unprepare_transfer_hardware(struct spi_master *master)``
565 ``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
572 ``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *tran…
587 ``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactiv…
588 	This method allows SPI client drivers to request SPI master controller
589 	for configuring device specific CS setup, hold and inactive timing
595 ``master->transfer(struct spi_device *spi, struct spi_message *message)``
599 	if the controller is idle it will need to be kickstarted. This
611 providing pure process-context execution of methods. The message queue
612 can also be elevated to realtime priority on high-priority SPI traffic.
619 for low-frequency sensor access might be fine using synchronous PIO.
621 But the queue will probably be very real, using message->queue, PIO,
631 ---------
632 Contributors to Linux-SPI discussions include (in alphabetical order,
635 - Mark Brown
636 - David Brownell
637 - Russell King
638 - Grant Likely
639 - Dmitry Pervushin
640 - Stephen Street
641 - Mark Underwood
642 - Andrew Victor
643 - Linus Walleij
644 - Vitaly Wool