spi-summary

linux 内核源代码

Overview of Linux kernel SPI support
====================================

21-May-2007

What is SPI?
------------
The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
link used to connect microcontrollers to sensors, memory, and peripherals.
It's a simple "de facto" standard, not complicated enough to acquire a
standardization body.  SPI uses a master/slave configuration.

The three signal wires hold a clock (SCK, often on the order of 10 MHz),
and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
Slave Out" (MISO) signals.  (Other names are also used.)  There are four
clocking modes through which data is exchanged; mode-0 and mode-3 are most
commonly used.  Each clock cycle shifts data out and data in; the clock
doesn't cycle except when there is a data bit to shift.  Not all data bits
are used though; not every protocol uses those full duplex capabilities.

SPI masters use a fourth "chip select" line to activate a given SPI slave
device, so those three signal wires may be connected to several chips
in parallel.  All SPI slaves support chipselects; they are usually active
low signals, labeled nCSx for slave 'x' (e.g. nCS0).  Some devices have
other signals, often including an interrupt to the master.

Unlike serial busses like USB or SMBus, even low level protocols for
SPI slave functions are usually not interoperable between vendors
(except for commodities like SPI memory chips).

  - SPI may be used for request/response style device protocols, as with
    touchscreen sensors and memory chips.

  - It may also be used to stream data in either direction (half duplex),
    or both of them at the same time (full duplex).

  - Some devices may use eight bit words.  Others may different word
    lengths, such as streams of 12-bit or 20-bit digital samples.

  - Words are usually sent with their most significant bit (MSB) first,
    but sometimes the least significant bit (LSB) goes first instead.

  - Sometimes SPI is used to daisy-chain devices, like shift registers.

In the same way, SPI slaves will only rarely support any kind of automatic
discovery/enumeration protocol.  The tree of slave devices accessible from
a given SPI master will normally be set up manually, with configuration
tables.

SPI is only one of the names used by such four-wire protocols, and
most controllers have no problem handling "MicroWire" (think of it as
half-duplex SPI, for request/response protocols), SSP ("Synchronous
Serial Protocol"), PSP ("Programmable Serial Protocol"), and other
related protocols.

Some chips eliminate a signal line by combining MOSI and MISO, and
limiting themselves to half-duplex at the hardware level.  In fact
some SPI chips have this signal mode as a strapping option.  These
can be accessed using the same programming interface as SPI, but of
course they won't handle full duplex transfers.  You may find such
chips described as using "three wire" signaling: SCK, data, nCSx.
(That data line is sometimes called MOMI or SISO.)

Microcontrollers often support both master and slave sides of the SPI
protocol.  This document (and Linux) currently only supports the master
side of SPI interactions.


Who uses it?  On what kinds of systems?
---------------------------------------
Linux developers using SPI are probably writing device drivers for embedded
systems boards.  SPI is used to control external chips, and it is also a
protocol supported by every MMC or SD memory card.  (The older "DataFlash"
cards, predating MMC cards but using the same connectors and card shape,
support only SPI.)  Some PC hardware uses SPI flash for BIOS code.

SPI slave chips range from digital/analog converters used for analog
sensors and codecs, to memory, to peripherals like USB controllers
or Ethernet adapters; and more.

Most systems using SPI will integrate a few devices on a mainboard.
Some provide SPI links on expansion connectors; in cases where no
dedicated SPI controller exists, GPIO pins can be used to create a
low speed "bitbanging" adapter.  Very few systems will "hotplug" an SPI
controller; the reasons to use SPI focus on low cost and simple operation,
and if dynamic reconfiguration is important, USB will often be a more
appropriate low-pincount peripheral bus.

Many microcontrollers that can run Linux integrate one or more I/O
interfaces with SPI modes.  Given SPI support, they could use MMC or SD
cards without needing a special purpose MMC/SD/SDIO controller.


I'm confused.  What are these four SPI "clock modes"?
-----------------------------------------------------
It's easy to be confused here, and the vendor documentation you'll
find isn't necessarily helpful.  The four modes combine two mode bits:

 - CPOL indicates the initial clock polarity.  CPOL=0 means the
   clock starts low, so the first (leading) edge is rising, and
   the second (trailing) edge is falling.  CPOL=1 means the clock
   starts high, so the first (leading) edge is falling.

 - CPHA indicates the clock phase used to sample data; CPHA=0 says
   sample on the leading edge, CPHA=1 means the trailing edge.

   Since the signal needs to stablize before it's sampled, CPHA=0
   implies that its data is written half a clock before the first
   clock edge.  The chipselect may have made it become available.

Chip specs won't always say "uses SPI mode X" in as many words,
but their timing diagrams will make the CPOL and CPHA modes clear.

In the SPI mode number, CPOL is the high order bit and CPHA is the
low order bit.  So when a chip's timing diagram shows the clock
starting low (CPOL=0) and data stabilized for sampling during the
trailing clock edge (CPHA=1), that's SPI mode 1.


How do these driver programming interfaces work?
------------------------------------------------
The <linux/spi/spi.h> header file includes kerneldoc, as does the
main source code, and you should certainly read that chapter of the
kernel API document.  This is just an overview, so you get the big
picture before those details.

SPI requests always go into I/O queues.  Requests for a given SPI device
are always executed in FIFO order, and complete asynchronously through
completion callbacks.  There are also some simple synchronous wrappers
for those calls, including ones for common transaction types like writing
a command and then reading its response.

There are two types of SPI driver, here called:

  Controller drivers ... controllers may be built in to System-On-Chip
	processors, and often support both Master and Slave roles.
	These drivers touch hardware registers and may use DMA.
	Or they can be PIO bitbangers, needing just GPIO pins.

  Protocol drivers ... these pass messages through the controller
	driver to communicate with a Slave or Master device on the
	other side of an SPI link.

So for example one protocol driver might talk to the MTD layer to export
data to filesystems stored on SPI flash like DataFlash; and others might
control audio interfaces, present touchscreen sensors as input interfaces,
or monitor temperature and voltage levels during industrial processing.
And those might all be sharing the same controller driver.

A "struct spi_device" encapsulates the master-side interface between
those two types of driver.  At this writing, Linux has no slave side
programming interface.

There is a minimal core of SPI programming interfaces, focussing on
using the driver model to connect controller and protocol drivers using
device tables provided by board specific initialization code.  SPI
shows up in sysfs in several locations:

   /sys/devices/.../CTLR ... physical node for a given SPI controller

   /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B",
	chipselect C, accessed through CTLR.

   /sys/bus/spi/devices/spiB.C ... symlink to that physical
   	.../CTLR/spiB.C device

   /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
	that should be used with this device (for hotplug/coldplug)

   /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices

   /sys/class/spi_master/spiB ... symlink (or actual device node) to
	a logical node which could hold class related state for the
	controller managing bus "B".  All spiB.* devices share one
	physical SPI bus segment, with SCLK, MOSI, and MISO.

Note that the actual location of the controller's class state depends
on whether you enabled CONFIG_SYSFS_DEPRECATED or not.  At this time,
the only class-specific state is the bus number ("B" in "spiB"), so
those /sys/class entries are only useful to quickly identify busses.


How does board-specific init code declare SPI devices?
------------------------------------------------------
Linux needs several kinds of information to properly configure SPI devices.
That information is normally provided by board-specific code, even for
chips that do support some of automated discovery/enumeration.

DECLARE CONTROLLERS

The first kind of information is a list of what SPI controllers exist.
For System-on-Chip (SOC) based boards, these will usually be platform
devices, and the controller may need some platform_data in order to
operate properly.  The "struct platform_device" will include resources
like the physical address of the controller's first register and its IRQ.

Platforms will often abstract the "register SPI controller" operation,
maybe coupling it with code to initialize pin configurations, so that
the arch/.../mach-*/board-*.c files for several boards can all share the
same basic controller setup code.  This is because most SOCs have several
SPI-capable controllers, and only the ones actually usable on a given
board should normally be set up and registered.

So for example arch/.../mach-*/board-*.c files might have code like:

	#include <asm/arch/spi.h>	/* for mysoc_spi_data */

	/* if your mach-* infrastructure doesn't support kernels that can
	 * run on multiple boards, pdata wouldn't benefit from "__init".
	 */
	static struct mysoc_spi_data __init pdata = { ... };

	static __init board_init(void)
	{
		...
		/* this board only uses SPI controller #2 */
		mysoc_register_spi(2, &pdata);
		...
	}

And SOC-specific utility code might look something like:

	#include <asm/arch/spi.h>

	static struct platform_device spi2 = { ... };

	void mysoc_register_spi(unsigned n, struct mysoc_spi_data *pdata)
	{
		struct mysoc_spi_data *pdata2;

		pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
		*pdata2 = pdata;
		...
		if (n == 2) {
			spi2->dev.platform_data = pdata2;
			register_platform_device(&spi2);

			/* also: set up pin modes so the spi2 signals are
			 * visible on the relevant pins ... bootloaders on
			 * production boards may already have done this, but
			 * developer boards will often need Linux to do it.
			 */
		}
		...
	}

Notice how the platform_data for boards may be different, even if the
same SOC controller is used.  For example, on one board SPI might use
an external clock, where another derives the SPI clock from current
settings of some master clock.


DECLARE SLAVE DEVICES

The second kind of information is a list of what SPI slave devices exist
on the target board, often with some board-specific data needed for the
driver to work correctly.

Normally your arch/.../mach-*/board-*.c files would provide a small table
listing the SPI devices on each board.  (This would typically be only a
small handful.)  That might look like:

	static struct ads7846_platform_data ads_info = {
		.vref_delay_usecs	= 100,
		.x_plate_ohms		= 580,
		.y_plate_ohms		= 410,
	};

	static struct spi_board_info spi_board_info[] __initdata = {
	{
		.modalias	= "ads7846",
		.platform_data	= &ads_info,
		.mode		= SPI_MODE_0,