| 1 | Serial Peripheral Interface (SPI)
|
| 2 | =================================
|
| 3 |
|
| 4 | SPI is the "Serial Peripheral Interface", widely used with embedded
|
| 5 | systems because it is a simple and efficient interface: basically a
|
| 6 | multiplexed shift register. Its three signal wires hold a clock (SCK,
|
| 7 | often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data
|
| 8 | line, and a "Master In, Slave Out" (MISO) data line. SPI is a full
|
| 9 | duplex protocol; for each bit shifted out the MOSI line (one per clock)
|
| 10 | another is shifted in on the MISO line. Those bits are assembled into
|
| 11 | words of various sizes on the way to and from system memory. An
|
| 12 | additional chipselect line is usually active-low (nCS); four signals are
|
| 13 | normally used for each peripheral, plus sometimes an interrupt.
|
| 14 |
|
| 15 | The SPI bus facilities listed here provide a generalized interface to
|
| 16 | declare SPI buses and devices, manage them according to the standard
|
| 17 | Linux driver model, and perform input/output operations. At this time,
|
| 18 | only "master" side interfaces are supported, where Linux talks to SPI
|
| 19 | peripherals and does not implement such a peripheral itself. (Interfaces
|
| 20 | to support implementing SPI slaves would necessarily look different.)
|
| 21 |
|
| 22 | The programming interface is structured around two kinds of driver, and
|
| 23 | two kinds of device. A "Controller Driver" abstracts the controller
|
| 24 | hardware, which may be as simple as a set of GPIO pins or as complex as
|
| 25 | a pair of FIFOs connected to dual DMA engines on the other side of the
|
| 26 | SPI shift register (maximizing throughput). Such drivers bridge between
|
| 27 | whatever bus they sit on (often the platform bus) and SPI, and expose
|
| 28 | the SPI side of their device as a :c:type:`struct spi_controller
|
| 29 | <spi_controller>`. SPI devices are children of that master,
|
| 30 | represented as a :c:type:`struct spi_device <spi_device>` and
|
| 31 | manufactured from :c:type:`struct spi_board_info
|
| 32 | <spi_board_info>` descriptors which are usually provided by
|
| 33 | board-specific initialization code. A :c:type:`struct spi_driver
|
| 34 | <spi_driver>` is called a "Protocol Driver", and is bound to a
|
| 35 | spi_device using normal driver model calls.
|
| 36 |
|
| 37 | The I/O model is a set of queued messages. Protocol drivers submit one
|
| 38 | or more :c:type:`struct spi_message <spi_message>` objects,
|
| 39 | which are processed and completed asynchronously. (There are synchronous
|
| 40 | wrappers, however.) Messages are built from one or more
|
| 41 | :c:type:`struct spi_transfer <spi_transfer>` objects, each of
|
| 42 | which wraps a full duplex SPI transfer. A variety of protocol tweaking
|
| 43 | options are needed, because different chips adopt very different
|
| 44 | policies for how they use the bits transferred with SPI.
|
| 45 |
|
| 46 | .. kernel-doc:: include/linux/spi/spi.h
|
| 47 | :internal:
|
| 48 |
|
| 49 | .. kernel-doc:: drivers/spi/spi.c
|
| 50 | :functions: spi_register_board_info
|
| 51 |
|
| 52 | .. kernel-doc:: drivers/spi/spi.c
|
| 53 | :export:
|