15e995786SJonathan CorbetSerial Peripheral Interface (SPI) 25e995786SJonathan Corbet================================= 35e995786SJonathan Corbet 45e995786SJonathan CorbetSPI is the "Serial Peripheral Interface", widely used with embedded 55e995786SJonathan Corbetsystems because it is a simple and efficient interface: basically a 65e995786SJonathan Corbetmultiplexed shift register. Its three signal wires hold a clock (SCK, 75e995786SJonathan Corbetoften in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data 85e995786SJonathan Corbetline, and a "Master In, Slave Out" (MISO) data line. SPI is a full 95e995786SJonathan Corbetduplex protocol; for each bit shifted out the MOSI line (one per clock) 105e995786SJonathan Corbetanother is shifted in on the MISO line. Those bits are assembled into 115e995786SJonathan Corbetwords of various sizes on the way to and from system memory. An 125e995786SJonathan Corbetadditional chipselect line is usually active-low (nCS); four signals are 135e995786SJonathan Corbetnormally used for each peripheral, plus sometimes an interrupt. 145e995786SJonathan Corbet 155e995786SJonathan CorbetThe SPI bus facilities listed here provide a generalized interface to 165e995786SJonathan Corbetdeclare SPI busses and devices, manage them according to the standard 175e995786SJonathan CorbetLinux driver model, and perform input/output operations. At this time, 185e995786SJonathan Corbetonly "master" side interfaces are supported, where Linux talks to SPI 195e995786SJonathan Corbetperipherals and does not implement such a peripheral itself. (Interfaces 205e995786SJonathan Corbetto support implementing SPI slaves would necessarily look different.) 215e995786SJonathan Corbet 225e995786SJonathan CorbetThe programming interface is structured around two kinds of driver, and 235e995786SJonathan Corbettwo kinds of device. A "Controller Driver" abstracts the controller 245e995786SJonathan Corbethardware, which may be as simple as a set of GPIO pins or as complex as 255e995786SJonathan Corbeta pair of FIFOs connected to dual DMA engines on the other side of the 265e995786SJonathan CorbetSPI shift register (maximizing throughput). Such drivers bridge between 275e995786SJonathan Corbetwhatever bus they sit on (often the platform bus) and SPI, and expose 28*bf585cceSJonathan Neuschäferthe SPI side of their device as a :c:type:`struct spi_controller 29*bf585cceSJonathan Neuschäfer<spi_controller>`. SPI devices are children of that master, 305e995786SJonathan Corbetrepresented as a :c:type:`struct spi_device <spi_device>` and 315e995786SJonathan Corbetmanufactured from :c:type:`struct spi_board_info 325e995786SJonathan Corbet<spi_board_info>` descriptors which are usually provided by 335e995786SJonathan Corbetboard-specific initialization code. A :c:type:`struct spi_driver 345e995786SJonathan Corbet<spi_driver>` is called a "Protocol Driver", and is bound to a 355e995786SJonathan Corbetspi_device using normal driver model calls. 365e995786SJonathan Corbet 375e995786SJonathan CorbetThe I/O model is a set of queued messages. Protocol drivers submit one 385e995786SJonathan Corbetor more :c:type:`struct spi_message <spi_message>` objects, 395e995786SJonathan Corbetwhich are processed and completed asynchronously. (There are synchronous 405e995786SJonathan Corbetwrappers, however.) Messages are built from one or more 415e995786SJonathan Corbet:c:type:`struct spi_transfer <spi_transfer>` objects, each of 425e995786SJonathan Corbetwhich wraps a full duplex SPI transfer. A variety of protocol tweaking 435e995786SJonathan Corbetoptions are needed, because different chips adopt very different 445e995786SJonathan Corbetpolicies for how they use the bits transferred with SPI. 455e995786SJonathan Corbet 465e995786SJonathan Corbet.. kernel-doc:: include/linux/spi/spi.h 475e995786SJonathan Corbet :internal: 485e995786SJonathan Corbet 495e995786SJonathan Corbet.. kernel-doc:: drivers/spi/spi.c 505e995786SJonathan Corbet :functions: spi_register_board_info 515e995786SJonathan Corbet 525e995786SJonathan Corbet.. kernel-doc:: drivers/spi/spi.c 535e995786SJonathan Corbet :export: 54