Documentation/spi/spi-summary.rst

5 02-Feb-2012
8 ------------
9 The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
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
59 some SPI chips have this signal mode as a strapping option.  These
62 chips described as using "three wire" signaling: SCK, data, nCSx.
71 ---------------------------------------
88 appropriate low-pincount peripheral bus.
96 -----------------------------------------------------
98 find isn't necessarily helpful.  The four modes combine two mode bits:
100  - CPOL indicates the initial clock polarity.  CPOL=0 means the
105  - CPHA indicates the clock phase used to sample data; CPHA=0 says
112 Chip specs won't always say "uses SPI mode X" in as many words,
115 In the SPI mode number, CPOL is the high order bit and CPHA is the
118 trailing clock edge (CPHA=1), that's SPI mode 1.
120 Note that the clock mode is relevant as soon as the chipselect goes
129 ------------------------------------------------
144         controllers may be built into System-On-Chip
160 A "struct spi_device" encapsulates the controller-side interface between
186    /sys/devices/.../CTLR/slave ... virtual file for (un)registering the
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
220 the arch/.../mach-*/board-*.c files for several boards can all share the
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
242 And SOC-specific utility code might look something like::
256 			spi2->dev.platform_data = pdata2;
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
294 		.mode		= SPI_MODE_0,
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
314 that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since
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 ----------------------------------------
371 		/* assuming the driver requires board-specific data: */
372 		pdata = &spi->dev.platform_data;
374 			return -ENODEV;
376 		/* get memory for driver's per-chip state */
379 			return -ENOMEM;
391   - An spi_message is a sequence of protocol operations, executed
417   - Follow standard kernel rules, and provide DMA-safe buffers in
426   - The basic I/O primitive is spi_async().  Async requests may be
432   - There are also synchronous wrappers like spi_sync(), and wrappers
437   - The spi_write_then_read() call, and convenience wrappers around
440     common RPC-style requests, such as writing an eight bit command
441     and reading a sixteen bit response -- spi_w8r16() being one its
445 transfer mode, wordsize, or clock rate.  This is done with spi_setup(),
458   - I/O buffers use the usual Linux rules, and must be DMA-safe.
462   - The spi_message and spi_transfer metadata used to glue those
465     other allocate-once driver data structures.  Zero-init these.
468 routines are available to allocate and zero-initialize an spi_message
473 -------------------------------------------------
479 to get the driver-private data allocated for that device.
488 		return -ENODEV;
516 If you don't have such hardware-assigned bus number, and for some reason
519 this as a non-static configuration (see above).
525 ``master->setup(struct spi_device *spi)``
526 	This sets up the device clock rate, SPI mode, and word sizes.
541 ``master->cleanup(struct spi_device *spi)``
546 ``master->prepare_transfer_hardware(struct spi_master *master)``
552 ``master->unprepare_transfer_hardware(struct spi_master *master)``
557 ``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
564 ``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *tran…
579 ``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactiv…
587 ``master->transfer(struct spi_device *spi, struct spi_message *message)``
603 providing pure process-context execution of methods. The message queue
604 can also be elevated to realtime priority on high-priority SPI traffic.
611 for low-frequency sensor access might be fine using synchronous PIO.
613 But the queue will probably be very real, using message->queue, PIO,
623 ---------
624 Contributors to Linux-SPI discussions include (in alphabetical order,
627 - Mark Brown
628 - David Brownell
629 - Russell King
630 - Grant Likely
631 - Dmitry Pervushin
632 - Stephen Street
633 - Mark Underwood
634 - Andrew Victor
635 - Linus Walleij
636 - Vitaly Wool