Documentation/spi/spi-summary.rst

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),
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 ---------------------------------------
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
129 ------------------------------------------------
141 There are two types of SPI driver, here called:
144         controllers may be built into System-On-Chip
160 A "struct spi_device" encapsulates the controller-side interface between
161 those two types of drivers.
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
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
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
398         (two pointers, maybe the same one in both cases) and half
416   - Follow standard kernel rules, and provide DMA-safe buffers in
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
435     common RPC-style requests, such as writing an eight bit command
436     and reading a sixteen bit response -- spi_w8r16() being one its
450 Note that there are two types of memory your driver must manage as part
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
468 -------------------------------------------------
474 spi_controller_get_devdata() to get the driver-private data allocated for that
484 		return -ENODEV;
511 If you don't have such hardware-assigned bus number, and for some reason
514 this as a non-static configuration (see above).
520 ``ctlr->setup(struct spi_device *spi)``
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)``
584 	transfer happens and its complete() callback is issued. The two
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 ------------------------------
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