1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 9. Serial Peripheral Interface (SPI)</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Linux Device Drivers"><link rel="up" href="index.html" title="Linux Device Drivers"><link rel="prev" href="API-sparse-keymap-report-event.html" title="sparse_keymap_report_event"><link rel="next" href="API-struct-spi-device.html" title="struct spi_device"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 9. Serial Peripheral Interface (SPI)</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-sparse-keymap-report-event.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="API-struct-spi-device.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="spi"></a>Chapter 9. Serial Peripheral Interface (SPI)</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="refentrytitle"><a href="API-struct-spi-device.html"><span class="phrase">struct spi_device</span></a></span><span class="refpurpose"> — 2 Master side proxy for an SPI slave device 3 </span></dt><dt><span class="refentrytitle"><a href="API-struct-spi-driver.html"><span class="phrase">struct spi_driver</span></a></span><span class="refpurpose"> — 4 Host side <span class="quote">“<span class="quote">protocol</span>”</span> driver 5 </span></dt><dt><span class="refentrytitle"><a href="API-spi-unregister-driver.html"><span class="phrase">spi_unregister_driver</span></a></span><span class="refpurpose"> — 6 reverse effect of spi_register_driver 7 </span></dt><dt><span class="refentrytitle"><a href="API-module-spi-driver.html"><span class="phrase">module_spi_driver</span></a></span><span class="refpurpose"> — 8 Helper macro for registering a SPI driver 9 </span></dt><dt><span class="refentrytitle"><a href="API-struct-spi-master.html"><span class="phrase">struct spi_master</span></a></span><span class="refpurpose"> — 10 interface to SPI master controller 11 </span></dt><dt><span class="refentrytitle"><a href="API-struct-spi-transfer.html"><span class="phrase">struct spi_transfer</span></a></span><span class="refpurpose"> — 12 a read/write buffer pair 13 </span></dt><dt><span class="refentrytitle"><a href="API-struct-spi-message.html"><span class="phrase">struct spi_message</span></a></span><span class="refpurpose"> — 14 one multi-segment SPI transaction 15 </span></dt><dt><span class="refentrytitle"><a href="API-spi-message-init-with-transfers.html"><span class="phrase">spi_message_init_with_transfers</span></a></span><span class="refpurpose"> — 16 Initialize spi_message and append transfers 17 </span></dt><dt><span class="refentrytitle"><a href="API-spi-write.html"><span class="phrase">spi_write</span></a></span><span class="refpurpose"> — 18 SPI synchronous write 19 </span></dt><dt><span class="refentrytitle"><a href="API-spi-read.html"><span class="phrase">spi_read</span></a></span><span class="refpurpose"> — 20 SPI synchronous read 21 </span></dt><dt><span class="refentrytitle"><a href="API-spi-sync-transfer.html"><span class="phrase">spi_sync_transfer</span></a></span><span class="refpurpose"> — 22 synchronous SPI data transfer 23 </span></dt><dt><span class="refentrytitle"><a href="API-spi-w8r8.html"><span class="phrase">spi_w8r8</span></a></span><span class="refpurpose"> — 24 SPI synchronous 8 bit write followed by 8 bit read 25 </span></dt><dt><span class="refentrytitle"><a href="API-spi-w8r16.html"><span class="phrase">spi_w8r16</span></a></span><span class="refpurpose"> — 26 SPI synchronous 8 bit write followed by 16 bit read 27 </span></dt><dt><span class="refentrytitle"><a href="API-spi-w8r16be.html"><span class="phrase">spi_w8r16be</span></a></span><span class="refpurpose"> — 28 SPI synchronous 8 bit write followed by 16 bit big-endian read 29 </span></dt><dt><span class="refentrytitle"><a href="API-struct-spi-board-info.html"><span class="phrase">struct spi_board_info</span></a></span><span class="refpurpose"> — 30 board-specific template for a SPI device 31 </span></dt><dt><span class="refentrytitle"><a href="API-spi-register-board-info.html"><span class="phrase">spi_register_board_info</span></a></span><span class="refpurpose"> — 32 register SPI devices for a given board 33 </span></dt><dt><span class="refentrytitle"><a href="API-spi-register-driver.html"><span class="phrase">spi_register_driver</span></a></span><span class="refpurpose"> — 34 register a SPI driver 35 </span></dt><dt><span class="refentrytitle"><a href="API-spi-alloc-device.html"><span class="phrase">spi_alloc_device</span></a></span><span class="refpurpose"> — 36 Allocate a new SPI device 37 </span></dt><dt><span class="refentrytitle"><a href="API-spi-add-device.html"><span class="phrase">spi_add_device</span></a></span><span class="refpurpose"> — 38 Add spi_device allocated with spi_alloc_device 39 </span></dt><dt><span class="refentrytitle"><a href="API-spi-new-device.html"><span class="phrase">spi_new_device</span></a></span><span class="refpurpose"> — 40 instantiate one new SPI device 41 </span></dt><dt><span class="refentrytitle"><a href="API-spi-finalize-current-transfer.html"><span class="phrase">spi_finalize_current_transfer</span></a></span><span class="refpurpose"> — 42 report completion of a transfer 43 </span></dt><dt><span class="refentrytitle"><a href="API-spi-get-next-queued-message.html"><span class="phrase">spi_get_next_queued_message</span></a></span><span class="refpurpose"> — 44 called by driver to check for queued messages 45 </span></dt><dt><span class="refentrytitle"><a href="API-spi-finalize-current-message.html"><span class="phrase">spi_finalize_current_message</span></a></span><span class="refpurpose"> — 46 the current message is complete 47 </span></dt><dt><span class="refentrytitle"><a href="API-spi-alloc-master.html"><span class="phrase">spi_alloc_master</span></a></span><span class="refpurpose"> — 48 allocate SPI master controller 49 </span></dt><dt><span class="refentrytitle"><a href="API-spi-register-master.html"><span class="phrase">spi_register_master</span></a></span><span class="refpurpose"> — 50 register SPI master controller 51 </span></dt><dt><span class="refentrytitle"><a href="API-devm-spi-register-master.html"><span class="phrase">devm_spi_register_master</span></a></span><span class="refpurpose"> — 52 register managed SPI master controller 53 </span></dt><dt><span class="refentrytitle"><a href="API-spi-unregister-master.html"><span class="phrase">spi_unregister_master</span></a></span><span class="refpurpose"> — 54 unregister SPI master controller 55 </span></dt><dt><span class="refentrytitle"><a href="API-spi-busnum-to-master.html"><span class="phrase">spi_busnum_to_master</span></a></span><span class="refpurpose"> — 56 look up master associated with bus_num 57 </span></dt><dt><span class="refentrytitle"><a href="API-spi-setup.html"><span class="phrase">spi_setup</span></a></span><span class="refpurpose"> — 58 setup SPI mode and clock rate 59 </span></dt><dt><span class="refentrytitle"><a href="API-spi-async.html"><span class="phrase">spi_async</span></a></span><span class="refpurpose"> — 60 asynchronous SPI transfer 61 </span></dt><dt><span class="refentrytitle"><a href="API-spi-async-locked.html"><span class="phrase">spi_async_locked</span></a></span><span class="refpurpose"> — 62 version of spi_async with exclusive bus usage 63 </span></dt><dt><span class="refentrytitle"><a href="API-spi-sync.html"><span class="phrase">spi_sync</span></a></span><span class="refpurpose"> — 64 blocking/synchronous SPI data transfers 65 </span></dt><dt><span class="refentrytitle"><a href="API-spi-sync-locked.html"><span class="phrase">spi_sync_locked</span></a></span><span class="refpurpose"> — 66 version of spi_sync with exclusive bus usage 67 </span></dt><dt><span class="refentrytitle"><a href="API-spi-bus-lock.html"><span class="phrase">spi_bus_lock</span></a></span><span class="refpurpose"> — 68 obtain a lock for exclusive SPI bus usage 69 </span></dt><dt><span class="refentrytitle"><a href="API-spi-bus-unlock.html"><span class="phrase">spi_bus_unlock</span></a></span><span class="refpurpose"> — 70 release the lock for exclusive SPI bus usage 71 </span></dt><dt><span class="refentrytitle"><a href="API-spi-write-then-read.html"><span class="phrase">spi_write_then_read</span></a></span><span class="refpurpose"> — 72 SPI synchronous write followed by read 73 </span></dt></dl></div><p> 74 SPI is the "Serial Peripheral Interface", widely used with 75 embedded systems because it is a simple and efficient 76 interface: basically a multiplexed shift register. 77 Its three signal wires hold a clock (SCK, often in the range 78 of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and 79 a "Master In, Slave Out" (MISO) data line. 80 SPI is a full duplex protocol; for each bit shifted out the 81 MOSI line (one per clock) another is shifted in on the MISO line. 82 Those bits are assembled into words of various sizes on the 83 way to and from system memory. 84 An additional chipselect line is usually active-low (nCS); 85 four signals are normally used for each peripheral, plus 86 sometimes an interrupt. 87 </p><p> 88 The SPI bus facilities listed here provide a generalized 89 interface to declare SPI busses and devices, manage them 90 according to the standard Linux driver model, and perform 91 input/output operations. 92 At this time, only "master" side interfaces are supported, 93 where Linux talks to SPI peripherals and does not implement 94 such a peripheral itself. 95 (Interfaces to support implementing SPI slaves would 96 necessarily look different.) 97 </p><p> 98 The programming interface is structured around two kinds of driver, 99 and two kinds of device. 100 A "Controller Driver" abstracts the controller hardware, which may 101 be as simple as a set of GPIO pins or as complex as a pair of FIFOs 102 connected to dual DMA engines on the other side of the SPI shift 103 register (maximizing throughput). Such drivers bridge between 104 whatever bus they sit on (often the platform bus) and SPI, and 105 expose the SPI side of their device as a 106 <span class="structname">struct spi_master</span>. 107 SPI devices are children of that master, represented as a 108 <span class="structname">struct spi_device</span> and manufactured from 109 <span class="structname">struct spi_board_info</span> descriptors which 110 are usually provided by board-specific initialization code. 111 A <span class="structname">struct spi_driver</span> is called a 112 "Protocol Driver", and is bound to a spi_device using normal 113 driver model calls. 114 </p><p> 115 The I/O model is a set of queued messages. Protocol drivers 116 submit one or more <span class="structname">struct spi_message</span> 117 objects, which are processed and completed asynchronously. 118 (There are synchronous wrappers, however.) Messages are 119 built from one or more <span class="structname">struct spi_transfer</span> 120 objects, each of which wraps a full duplex SPI transfer. 121 A variety of protocol tweaking options are needed, because 122 different chips adopt very different policies for how they 123 use the bits transferred with SPI. 124 </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-sparse-keymap-report-event.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="API-struct-spi-device.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">sparse_keymap_report_event</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">struct spi_device</span></td></tr></table></div></body></html> 125