Documentation/spi/spi-summary.rst

2 Overview of Linux kernel SPI support
5 02-Feb-2012
8 ------------
14 The three signal wires hold a clock (SCK, often on the order of 10 MHz),
17 clocking modes through which data is exchanged; mode-0 and mode-3 are most
23 device, so those three signal wires may be connected to several chips
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),
36     or both of them at the same time (full 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.
46 In the same way, SPI slaves will only rarely support any kind of automatic
47 discovery/enumeration protocol.  The tree of slave devices accessible from
51 SPI is only one of the names used by such four-wire protocols, and
52 most controllers have no problem handling "MicroWire" (think of it as
53 half-duplex SPI, for request/response protocols), SSP ("Synchronous
58 limiting themselves to half-duplex at the hardware level.  In fact
60 can be accessed using the same programming interface as SPI, but of
65 Microcontrollers often support both master and slave sides of the SPI
67 sides of SPI interactions.
70 Who uses it?  On what kinds of systems?
71 ---------------------------------------
88 appropriate low-pincount peripheral bus.
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
115 In the SPI mode number, CPOL is the high order bit and CPHA is the
129 ------------------------------------------------
131 main source code, and you should certainly read that chapter of the
141 There are two types of SPI driver, here called:
144         controllers may be built into System-On-Chip
152 	other side of an SPI link.
160 A "struct spi_device" encapsulates the controller-side interface between
161 those two types of drivers.
163 There is a minimal core of SPI programming interfaces, focussing on
188 	Writing the driver name of an SPI slave handler to this file
191 	Reading from this file shows the name of the slave device ("(null)"
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 ------------------------------------------------------
208 Linux needs several kinds of information to properly configure SPI devices.
209 That information is normally provided by board-specific code, even for
210 chips that do support some of automated discovery/enumeration.
215 The first kind of information is a list of what SPI controllers exist.
216 For System-on-Chip (SOC) based boards, these will usually be platform
219 like the physical address of the controller's first register and its IRQ.
223 the arch/.../mach-*/board-*.c files for several boards can all share the
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
245 And SOC-specific utility code might look something like::
259 			spi2->dev.platform_data = pdata2;
274 settings of some master clock.
279 The second kind of information is a list of what SPI slave devices exist
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
307 clock to allow (a function of board voltage in this case) or how an IRQ pin
308 is wired, plus chip-specific constraints like an important delay that's
312 controller driver.  An example would be peripheral-specific DMA tuning
316 without the chip's driver being loaded.  The most troublesome aspect of
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
344 board info based on the board that was hotplugged.  Of course, you'd later
353 ----------------------------------------
371 device whose board_info gave a modalias of "CHIP".  Your probe() code
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
406         sequence of spi_transfer requests is arranged;
425   - Follow standard kernel rules, and provide DMA-safe buffers in
428     around hardware errata that force the use of bounce buffering).
430     If standard dma_map_single() handling of these buffers is inappropriate,
434   - The basic I/O primitive is spi_async().  Async requests may be
438     of that spi_message is aborted.
440   - There are also synchronous wrappers like spi_sync(), and wrappers
445   - The spi_write_then_read() call, and convenience wrappers around
446     it, should only be used with small amounts of data where the
447     cost of an extra copy may be ignored.  It's designed to support
448     common RPC-style requests, such as writing an eight bit command
449     and reading a sixteen bit response -- spi_w8r16() being one its
458 While "spi_device" would be the bottom boundary of the driver, the
463 Note that there are two types of memory your driver must manage as part
464 of interacting with SPI devices.
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
471     I/O buffers into a group of protocol transactions.  These can
472     be allocated anywhere it's convenient, including as part of
473     other allocate-once driver data structures.  Zero-init these.
476 routines are available to allocate and zero-initialize an spi_message
481 -------------------------------------------------
485 The main task of this type of driver is to provide an "spi_master".
487 to get the driver-private data allocated for that device.
496 		return -ENODEV;
500 The driver will initialize the fields of that spi_master, including the
501 bus number (maybe the same as the platform device ID) and three methods
507 publish it to the rest of the system. At that time, device nodes for the
509 the driver model core will take care of binding them to drivers.
512 will reverse the effect of spi_register_master().
521 manufacturer.  For example, hardware controller SPI2 would be bus number 2,
522 and spi_board_info for devices connected to it would use that number.
524 If you don't have such hardware-assigned bus number, and for some reason
525 you can't just assign them, then provide a negative bus number.  That will
526 then be replaced by a dynamically assigned number. You'd then need to treat
527 this as a non-static configuration (see above).
533 ``master->setup(struct spi_device *spi)``
544 		BUG ALERT:  for some reason the first version of
549 ``master->cleanup(struct spi_device *spi)``
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…
595 ``master->transfer(struct spi_device *spi, struct spi_message *message)``
610 the message queue has the upside of centralizing a lot of code and
611 providing pure process-context execution of methods. The message queue
612 can also be elevated to realtime priority on high-priority SPI traffic.
615 of the driver will be managing the I/O queue fed by the now deprecated
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