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