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 targets will only rarely support any kind of automatic
47 discovery/enumeration protocol. The tree of target 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 host and target 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 target handler to this file
191 	Reading from this file shows the name of the target device ("(null)"
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 ------------------------------------------------------
205 Linux needs several kinds of information to properly configure SPI devices.
206 That information is normally provided by board-specific code, even for
207 chips that do support some of automated discovery/enumeration.
212 The first kind of information is a list of what SPI controllers exist.
213 For System-on-Chip (SOC) based boards, these will usually be platform
216 like the physical address of the controller's first register and its IRQ.
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;
271 settings of some master clock.
276 The second kind of information is a list of what SPI target devices exist
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
304 clock to allow (a function of board voltage in this case) or how an IRQ pin
305 is wired, plus chip-specific constraints like an important delay that's
309 controller driver.  An example would be peripheral-specific DMA tuning
313 without the chip's driver being loaded.  The most troublesome aspect of
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 ----------------------------------------
359 device whose board_info gave a modalias of "CHIP".  Your probe() code
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
394         sequence of spi_transfer requests is arranged;
416   - Follow standard kernel rules, and provide DMA-safe buffers in
419     around hardware errata that force the use of bounce buffering).
421   - The basic I/O primitive is spi_async().  Async requests may be
425     of that spi_message is aborted.
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
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
445 While "spi_device" would be the bottom boundary of the driver, the
450 Note that there are two types of memory your driver must manage as part
451 of interacting with SPI devices.
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
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.
463 routines are available to allocate and zero-initialize an spi_message
468 -------------------------------------------------
472 The main task of this type of driver is to provide an "spi_controller".
474 spi_controller_get_devdata() to get the driver-private data allocated for that
484 		return -ENODEV;
488 The driver will initialize the fields of that spi_controller, including the bus
489 number (maybe the same as the platform device ID) and three methods used to
494 publish it to the rest of the system. At that time, device nodes for the
496 the driver model core will take care of binding them to drivers.
499 will reverse the effect of spi_register_controller().
508 manufacturer.  For example, hardware controller SPI2 would be bus number 2,
509 and spi_board_info for devices connected to it would use that number.
511 If you don't have such hardware-assigned bus number, and for some reason
512 you can't just assign them, then provide a negative bus number.  That will
513 then be replaced by a dynamically assigned number. You'd then need to treat
514 this as a non-static configuration (see above).
520 ``ctlr->setup(struct spi_device *spi)``
531 		BUG ALERT:  for some reason the first version of
536 ``ctlr->cleanup(struct spi_device *spi)``
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_…
582 ``ctrl->transfer(struct spi_device *spi, struct spi_message *message)``
597 the message queue has the upside of centralizing a lot of code and
598 providing pure process-context execution of methods. The message queue
599 can also be elevated to realtime priority on high-priority SPI traffic.
602 of the driver will be managing the I/O queue fed by the now deprecated
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 ------------------------------
644   • marks the start/end of transmission;
683   • marks the start/end of transmission;
693 ``SPI_MOSI_IDLE_HIGH`` bit into the mode attribute of their ``struct
696 of their ``struct spi_controller``. The configuration to idle MOSI low is
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