Commit 33e34dc6 authored by David Brownell's avatar David Brownell Committed by Linus Torvalds

SPI kerneldoc

Various documentation updates for the SPI infrastructure, to clarify things
that may not have been clear, to cope with lack of editing, and fix
omissions.

Also, plug SPI into the kernel-api DocBook template, and fix all the
resulting glitches in document generation.
Signed-off-by: default avatarDavid Brownell <dbrownell@users.sourceforge.net>
Cc: "Randy.Dunlap" <rdunlap@xenotime.net>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 814a8d50
...@@ -576,4 +576,67 @@ X!Idrivers/video/console/fonts.c ...@@ -576,4 +576,67 @@ X!Idrivers/video/console/fonts.c
!Edrivers/input/ff-core.c !Edrivers/input/ff-core.c
!Edrivers/input/ff-memless.c !Edrivers/input/ff-memless.c
</chapter> </chapter>
<chapter id="spi">
<title>Serial Peripheral Interface (SPI)</title>
<para>
SPI is the "Serial Peripheral Interface", widely used with
embedded systems because it is a simple and efficient
interface: basically a multiplexed shift register.
Its three signal wires hold a clock (SCK, often in the range
of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and
a "Master In, Slave Out" (MISO) data line.
SPI is a full duplex protocol; for each bit shifted out the
MOSI line (one per clock) another is shifted in on the MISO line.
Those bits are assembled into words of various sizes on the
way to and from system memory.
An additional chipselect line is usually active-low (nCS);
four signals are normally used for each peripheral, plus
sometimes an interrupt.
</para>
<para>
The SPI bus facilities listed here provide a generalized
interface to declare SPI busses and devices, manage them
according to the standard Linux driver model, and perform
input/output operations.
At this time, only "master" side interfaces are supported,
where Linux talks to SPI peripherals and does not implement
such a peripheral itself.
(Interfaces to support implementing SPI slaves would
necessarily look different.)
</para>
<para>
The programming interface is structured around two kinds of driver,
and two kinds of device.
A "Controller Driver" abstracts the controller hardware, which may
be as simple as a set of GPIO pins or as complex as a pair of FIFOs
connected to dual DMA engines on the other side of the SPI shift
register (maximizing throughput). Such drivers bridge between
whatever bus they sit on (often the platform bus) and SPI, and
expose the SPI side of their device as a
<structname>struct spi_master</structname>.
SPI devices are children of that master, represented as a
<structname>struct spi_device</structname> and manufactured from
<structname>struct spi_board_info</structname> descriptors which
are usually provided by board-specific initialization code.
A <structname>struct spi_driver</structname> is called a
"Protocol Driver", and is bound to a spi_device using normal
driver model calls.
</para>
<para>
The I/O model is a set of queued messages. Protocol drivers
submit one or more <structname>struct spi_message</structname>
objects, which are processed and completed asynchronously.
(There are synchronous wrappers, however.) Messages are
built from one or more <structname>struct spi_transfer</structname>
objects, each of which wraps a full duplex SPI transfer.
A variety of protocol tweaking options are needed, because
different chips adopt very different policies for how they
use the bits transferred with SPI.
</para>
!Iinclude/linux/spi/spi.h
!Fdrivers/spi/spi.c spi_register_board_info
!Edrivers/spi/spi.c
</chapter>
</book> </book>
...@@ -8,7 +8,7 @@ What is SPI? ...@@ -8,7 +8,7 @@ What is SPI?
The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
link used to connect microcontrollers to sensors, memory, and peripherals. link used to connect microcontrollers to sensors, memory, and peripherals.
The three signal wires hold a clock (SCLK, often on the order of 10 MHz), 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, 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 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 clocking modes through which data is exchanged; mode-0 and mode-3 are most
...@@ -22,7 +22,7 @@ other signals, often including an interrupt to the master. ...@@ -22,7 +22,7 @@ other signals, often including an interrupt to the master.
Unlike serial busses like USB or SMBUS, even low level protocols for Unlike serial busses like USB or SMBUS, even low level protocols for
SPI slave functions are usually not interoperable between vendors SPI slave functions are usually not interoperable between vendors
(except for cases like SPI memory chips). (except for commodities like SPI memory chips).
- SPI may be used for request/response style device protocols, as with - SPI may be used for request/response style device protocols, as with
touchscreen sensors and memory chips. touchscreen sensors and memory chips.
...@@ -77,8 +77,9 @@ cards without needing a special purpose MMC/SD/SDIO controller. ...@@ -77,8 +77,9 @@ cards without needing a special purpose MMC/SD/SDIO controller.
How do these driver programming interfaces work? How do these driver programming interfaces work?
------------------------------------------------ ------------------------------------------------
The <linux/spi/spi.h> header file includes kerneldoc, as does the The <linux/spi/spi.h> header file includes kerneldoc, as does the
main source code, and you should certainly read that. This is just main source code, and you should certainly read that chapter of the
an overview, so you get the big picture before the details. 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 SPI requests always go into I/O queues. Requests for a given SPI device
are always executed in FIFO order, and complete asynchronously through are always executed in FIFO order, and complete asynchronously through
...@@ -88,7 +89,7 @@ a command and then reading its response. ...@@ -88,7 +89,7 @@ a command and then reading its response.
There are two types of SPI driver, here called: There are two types of SPI driver, here called:
Controller drivers ... these are often built in to System-On-Chip Controller drivers ... controllers may be built in to System-On-Chip
processors, and often support both Master and Slave roles. processors, and often support both Master and Slave roles.
These drivers touch hardware registers and may use DMA. These drivers touch hardware registers and may use DMA.
Or they can be PIO bitbangers, needing just GPIO pins. Or they can be PIO bitbangers, needing just GPIO pins.
...@@ -108,18 +109,18 @@ those two types of driver. At this writing, Linux has no slave side ...@@ -108,18 +109,18 @@ those two types of driver. At this writing, Linux has no slave side
programming interface. programming interface.
There is a minimal core of SPI programming interfaces, focussing on There is a minimal core of SPI programming interfaces, focussing on
using driver model to connect controller and protocol drivers using using the driver model to connect controller and protocol drivers using
device tables provided by board specific initialization code. SPI device tables provided by board specific initialization code. SPI
shows up in sysfs in several locations: shows up in sysfs in several locations:
/sys/devices/.../CTLR/spiB.C ... spi_device for on bus "B", /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B",
chipselect C, accessed through CTLR. chipselect C, accessed through CTLR.
/sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
that should be used with this device (for hotplug/coldplug) that should be used with this device (for hotplug/coldplug)
/sys/bus/spi/devices/spiB.C ... symlink to the physical /sys/bus/spi/devices/spiB.C ... symlink to the physical
spiB-C device spiB.C device
/sys/bus/spi/drivers/D ... driver for one or more spi*.* devices /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices
...@@ -240,7 +241,7 @@ The board_info should provide enough information to let the system work ...@@ -240,7 +241,7 @@ The board_info should provide enough information to let the system work
without the chip's driver being loaded. The most troublesome aspect of without the chip's driver being loaded. The most troublesome aspect of
that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since
sharing a bus with a device that interprets chipselect "backwards" is sharing a bus with a device that interprets chipselect "backwards" is
not possible. not possible until the infrastructure knows how to deselect it.
Then your board initialization code would register that table with the SPI Then your board initialization code would register that table with the SPI
infrastructure, so that it's available later when the SPI master controller infrastructure, so that it's available later when the SPI master controller
...@@ -268,16 +269,14 @@ board info based on the board that was hotplugged. Of course, you'd later ...@@ -268,16 +269,14 @@ board info based on the board that was hotplugged. Of course, you'd later
call at least spi_unregister_device() when that board is removed. call at least spi_unregister_device() when that board is removed.
When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those
configurations will also be dynamic. Fortunately, those devices all support configurations will also be dynamic. Fortunately, such devices all support
basic device identification probes, so that support should hotplug normally. basic device identification probes, so they should hotplug normally.
How do I write an "SPI Protocol Driver"? How do I write an "SPI Protocol Driver"?
---------------------------------------- ----------------------------------------
All SPI drivers are currently kernel drivers. A userspace driver API Most SPI drivers are currently kernel drivers, but there's also support
would just be another kernel driver, probably offering some lowlevel for userspace drivers. Here we talk only about kernel drivers.
access through aio_read(), aio_write(), and ioctl() calls and using the
standard userspace sysfs mechanisms to bind to a given SPI device.
SPI protocol drivers somewhat resemble platform device drivers: SPI protocol drivers somewhat resemble platform device drivers:
...@@ -319,7 +318,8 @@ might look like this unless you're creating a class_device: ...@@ -319,7 +318,8 @@ might look like this unless you're creating a class_device:
As soon as it enters probe(), the driver may issue I/O requests to As soon as it enters probe(), the driver may issue I/O requests to
the SPI device using "struct spi_message". When remove() returns, the SPI device using "struct spi_message". When remove() returns,
the driver guarantees that it won't submit any more such messages. or after probe() fails, the driver guarantees that it won't submit
any more such messages.
- An spi_message is a sequence of protocol operations, executed - An spi_message is a sequence of protocol operations, executed
as one atomic sequence. SPI driver controls include: as one atomic sequence. SPI driver controls include:
...@@ -368,7 +368,8 @@ the driver guarantees that it won't submit any more such messages. ...@@ -368,7 +368,8 @@ the driver guarantees that it won't submit any more such messages.
Some drivers may need to modify spi_device characteristics like the Some drivers may need to modify spi_device characteristics like the
transfer mode, wordsize, or clock rate. This is done with spi_setup(), transfer mode, wordsize, or clock rate. This is done with spi_setup(),
which would normally be called from probe() before the first I/O is which would normally be called from probe() before the first I/O is
done to the device. done to the device. However, that can also be called at any time
that no message is pending for that device.
While "spi_device" would be the bottom boundary of the driver, the While "spi_device" would be the bottom boundary of the driver, the
upper boundaries might include sysfs (especially for sensor readings), upper boundaries might include sysfs (especially for sensor readings),
...@@ -445,11 +446,15 @@ SPI MASTER METHODS ...@@ -445,11 +446,15 @@ SPI MASTER METHODS
This sets up the device clock rate, SPI mode, and word sizes. This sets up the device clock rate, SPI mode, and word sizes.
Drivers may change the defaults provided by board_info, and then Drivers may change the defaults provided by board_info, and then
call spi_setup(spi) to invoke this routine. It may sleep. call spi_setup(spi) to invoke this routine. It may sleep.
Unless each SPI slave has its own configuration registers, don't
change them right away ... otherwise drivers could corrupt I/O
that's in progress for other SPI devices.
master->transfer(struct spi_device *spi, struct spi_message *message) master->transfer(struct spi_device *spi, struct spi_message *message)
This must not sleep. Its responsibility is arrange that the This must not sleep. Its responsibility is arrange that the
transfer happens and its complete() callback is issued; the two transfer happens and its complete() callback is issued. The two
will normally happen later, after other transfers complete. will normally happen later, after other transfers complete, and
if the controller is idle it will need to be kickstarted.
master->cleanup(struct spi_device *spi) master->cleanup(struct spi_device *spi)
Your controller driver may use spi_device.controller_state to hold Your controller driver may use spi_device.controller_state to hold
......
...@@ -152,6 +152,11 @@ static void spi_drv_shutdown(struct device *dev) ...@@ -152,6 +152,11 @@ static void spi_drv_shutdown(struct device *dev)
sdrv->shutdown(to_spi_device(dev)); sdrv->shutdown(to_spi_device(dev));
} }
/**
* spi_register_driver - register a SPI driver
* @sdrv: the driver to register
* Context: can sleep
*/
int spi_register_driver(struct spi_driver *sdrv) int spi_register_driver(struct spi_driver *sdrv)
{ {
sdrv->driver.bus = &spi_bus_type; sdrv->driver.bus = &spi_bus_type;
...@@ -183,7 +188,13 @@ static LIST_HEAD(board_list); ...@@ -183,7 +188,13 @@ static LIST_HEAD(board_list);
static DECLARE_MUTEX(board_lock); static DECLARE_MUTEX(board_lock);
/* On typical mainboards, this is purely internal; and it's not needed /**
* spi_new_device - instantiate one new SPI device
* @master: Controller to which device is connected
* @chip: Describes the SPI device
* Context: can sleep
*
* On typical mainboards, this is purely internal; and it's not needed
* after board init creates the hard-wired devices. Some development * after board init creates the hard-wired devices. Some development
* platforms may not be able to use spi_register_board_info though, and * platforms may not be able to use spi_register_board_info though, and
* this is exported so that for example a USB or parport based adapter * this is exported so that for example a USB or parport based adapter
...@@ -251,7 +262,12 @@ struct spi_device *spi_new_device(struct spi_master *master, ...@@ -251,7 +262,12 @@ struct spi_device *spi_new_device(struct spi_master *master,
} }
EXPORT_SYMBOL_GPL(spi_new_device); EXPORT_SYMBOL_GPL(spi_new_device);
/* /**
* spi_register_board_info - register SPI devices for a given board
* @info: array of chip descriptors
* @n: how many descriptors are provided
* Context: can sleep
*
* Board-specific early init code calls this (probably during arch_initcall) * Board-specific early init code calls this (probably during arch_initcall)
* with segments of the SPI device table. Any device nodes are created later, * with segments of the SPI device table. Any device nodes are created later,
* after the relevant parent SPI controller (bus_num) is defined. We keep * after the relevant parent SPI controller (bus_num) is defined. We keep
...@@ -337,9 +353,10 @@ static struct class spi_master_class = { ...@@ -337,9 +353,10 @@ static struct class spi_master_class = {
/** /**
* spi_alloc_master - allocate SPI master controller * spi_alloc_master - allocate SPI master controller
* @dev: the controller, possibly using the platform_bus * @dev: the controller, possibly using the platform_bus
* @size: how much driver-private data to preallocate; the pointer to this * @size: how much zeroed driver-private data to allocate; the pointer to this
* memory is in the class_data field of the returned class_device, * memory is in the class_data field of the returned class_device,
* accessible with spi_master_get_devdata(). * accessible with spi_master_get_devdata().
* Context: can sleep
* *
* This call is used only by SPI master controller drivers, which are the * This call is used only by SPI master controller drivers, which are the
* only ones directly touching chip registers. It's how they allocate * only ones directly touching chip registers. It's how they allocate
...@@ -375,6 +392,7 @@ EXPORT_SYMBOL_GPL(spi_alloc_master); ...@@ -375,6 +392,7 @@ EXPORT_SYMBOL_GPL(spi_alloc_master);
/** /**
* spi_register_master - register SPI master controller * spi_register_master - register SPI master controller
* @master: initialized master, originally from spi_alloc_master() * @master: initialized master, originally from spi_alloc_master()
* Context: can sleep
* *
* SPI master controllers connect to their drivers using some non-SPI bus, * SPI master controllers connect to their drivers using some non-SPI bus,
* such as the platform bus. The final stage of probe() in that code * such as the platform bus. The final stage of probe() in that code
...@@ -437,6 +455,7 @@ static int __unregister(struct device *dev, void *unused) ...@@ -437,6 +455,7 @@ static int __unregister(struct device *dev, void *unused)
/** /**
* spi_unregister_master - unregister SPI master controller * spi_unregister_master - unregister SPI master controller
* @master: the master being unregistered * @master: the master being unregistered
* Context: can sleep
* *
* This call is used only by SPI master controller drivers, which are the * This call is used only by SPI master controller drivers, which are the
* only ones directly touching chip registers. * only ones directly touching chip registers.
...@@ -455,6 +474,7 @@ EXPORT_SYMBOL_GPL(spi_unregister_master); ...@@ -455,6 +474,7 @@ EXPORT_SYMBOL_GPL(spi_unregister_master);
/** /**
* spi_busnum_to_master - look up master associated with bus_num * spi_busnum_to_master - look up master associated with bus_num
* @bus_num: the master's bus number * @bus_num: the master's bus number
* Context: can sleep
* *
* This call may be used with devices that are registered after * This call may be used with devices that are registered after
* arch init time. It returns a refcounted pointer to the relevant * arch init time. It returns a refcounted pointer to the relevant
...@@ -492,6 +512,7 @@ static void spi_complete(void *arg) ...@@ -492,6 +512,7 @@ static void spi_complete(void *arg)
* spi_sync - blocking/synchronous SPI data transfers * spi_sync - blocking/synchronous SPI data transfers
* @spi: device with which data will be exchanged * @spi: device with which data will be exchanged
* @message: describes the data transfers * @message: describes the data transfers
* Context: can sleep
* *
* This call may only be used from a context that may sleep. The sleep * This call may only be used from a context that may sleep. The sleep
* is non-interruptible, and has no timeout. Low-overhead controller * is non-interruptible, and has no timeout. Low-overhead controller
...@@ -508,7 +529,7 @@ static void spi_complete(void *arg) ...@@ -508,7 +529,7 @@ static void spi_complete(void *arg)
* *
* The return value is a negative error code if the message could not be * The return value is a negative error code if the message could not be
* submitted, else zero. When the value is zero, then message->status is * submitted, else zero. When the value is zero, then message->status is
* also defined: it's the completion code for the transfer, either zero * also defined; it's the completion code for the transfer, either zero
* or a negative error code from the controller driver. * or a negative error code from the controller driver.
*/ */
int spi_sync(struct spi_device *spi, struct spi_message *message) int spi_sync(struct spi_device *spi, struct spi_message *message)
...@@ -538,6 +559,7 @@ static u8 *buf; ...@@ -538,6 +559,7 @@ static u8 *buf;
* @n_tx: size of txbuf, in bytes * @n_tx: size of txbuf, in bytes
* @rxbuf: buffer into which data will be read * @rxbuf: buffer into which data will be read
* @n_rx: size of rxbuf, in bytes (need not be dma-safe) * @n_rx: size of rxbuf, in bytes (need not be dma-safe)
* Context: can sleep
* *
* This performs a half duplex MicroWire style transaction with the * This performs a half duplex MicroWire style transaction with the
* device, sending txbuf and then reading rxbuf. The return value * device, sending txbuf and then reading rxbuf. The return value
...@@ -545,7 +567,8 @@ static u8 *buf; ...@@ -545,7 +567,8 @@ static u8 *buf;
* This call may only be used from a context that may sleep. * This call may only be used from a context that may sleep.
* *
* Parameters to this routine are always copied using a small buffer; * Parameters to this routine are always copied using a small buffer;
* performance-sensitive or bulk transfer code should instead use * portable code should never use this for more than 32 bytes.
* Performance-sensitive or bulk transfer code should instead use
* spi_{async,sync}() calls with dma-safe buffers. * spi_{async,sync}() calls with dma-safe buffers.
*/ */
int spi_write_then_read(struct spi_device *spi, int spi_write_then_read(struct spi_device *spi,
......
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment