0001 Serial Peripheral Interface (SPI)
0002 =================================
0003
0004 SPI is the "Serial Peripheral Interface", widely used with embedded
0005 systems because it is a simple and efficient interface: basically a
0006 multiplexed shift register. Its three signal wires hold a clock (SCK,
0007 often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data
0008 line, and a "Master In, Slave Out" (MISO) data line. SPI is a full
0009 duplex protocol; for each bit shifted out the MOSI line (one per clock)
0010 another is shifted in on the MISO line. Those bits are assembled into
0011 words of various sizes on the way to and from system memory. An
0012 additional chipselect line is usually active-low (nCS); four signals are
0013 normally used for each peripheral, plus sometimes an interrupt.
0014
0015 The SPI bus facilities listed here provide a generalized interface to
0016 declare SPI busses and devices, manage them according to the standard
0017 Linux driver model, and perform input/output operations. At this time,
0018 only "master" side interfaces are supported, where Linux talks to SPI
0019 peripherals and does not implement such a peripheral itself. (Interfaces
0020 to support implementing SPI slaves would necessarily look different.)
0021
0022 The programming interface is structured around two kinds of driver, and
0023 two kinds of device. A "Controller Driver" abstracts the controller
0024 hardware, which may be as simple as a set of GPIO pins or as complex as
0025 a pair of FIFOs connected to dual DMA engines on the other side of the
0026 SPI shift register (maximizing throughput). Such drivers bridge between
0027 whatever bus they sit on (often the platform bus) and SPI, and expose
0028 the SPI side of their device as a :c:type:`struct spi_master
0029 <spi_master>`. SPI devices are children of that master,
0030 represented as a :c:type:`struct spi_device <spi_device>` and
0031 manufactured from :c:type:`struct spi_board_info
0032 <spi_board_info>` descriptors which are usually provided by
0033 board-specific initialization code. A :c:type:`struct spi_driver
0034 <spi_driver>` is called a "Protocol Driver", and is bound to a
0035 spi_device using normal driver model calls.
0036
0037 The I/O model is a set of queued messages. Protocol drivers submit one
0038 or more :c:type:`struct spi_message <spi_message>` objects,
0039 which are processed and completed asynchronously. (There are synchronous
0040 wrappers, however.) Messages are built from one or more
0041 :c:type:`struct spi_transfer <spi_transfer>` objects, each of
0042 which wraps a full duplex SPI transfer. A variety of protocol tweaking
0043 options are needed, because different chips adopt very different
0044 policies for how they use the bits transferred with SPI.
0045
0046 .. kernel-doc:: include/linux/spi/spi.h
0047 :internal:
0048
0049 .. kernel-doc:: drivers/spi/spi.c
0050 :functions: spi_register_board_info
0051
0052 .. kernel-doc:: drivers/spi/spi.c
0053 :export:
