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