Overview of Linux kernel SPI support
====================================
-22-Nov-2005
+02-Dec-2005
What is SPI?
------------
-The "Serial Peripheral Interface" (SPI) is a four-wire point-to-point
-serial link used to connect microcontrollers to sensors and memory.
+The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
+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),
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.
+commonly used. Each clock cycle shifts data out and data in; the clock
+doesn't cycle except when there is data to shift.
SPI masters may use a "chip select" line to activate a given SPI slave
device, so those three signal wires may be connected to several chips
main source code, and you should certainly read that. This is just
an overview, so you get the big picture before the 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 ... these are often 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
/sys/devices/.../CTLR/spiB.C ... spi_device for on bus "B",
chipselect C, accessed through CTLR.
+ /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
+ that should be used with this device (for hotplug/coldplug)
+
/sys/bus/spi/devices/spiB.C ... symlink to the physical
spiB-C device
managing bus "B". All the spiB.* devices share the same
physical SPI bus segment, with SCLK, MOSI, and MISO.
-The basic I/O primitive submits an asynchronous message to an I/O queue
-maintained by the controller driver. A completion callback is issued
-asynchronously when the data transfer(s) in that message completes.
-There are also some simple synchronous wrappers for those calls.
-
How does board-specific init code declare SPI devices?
------------------------------------------------------
Like with other static board-specific setup, you won't unregister those.
+The widely used "card" style computers bundle memory, cpu, and little else
+onto a card that's maybe just thirty square centimeters. On such systems,
+your arch/.../mach-.../board-*.c file would primarily provide information
+about the devices on the mainboard into which such a card is plugged. That
+certainly includes SPI devices hooked up through the card connectors!
+
NON-STATIC CONFIGURATIONS
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.
+When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those
+configurations will also be dynamic. Fortunately, those devices all support
+basic device identification probes, so that support should hotplug normally.
+
How do I write an "SPI Protocol Driver"?
----------------------------------------
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 are normal device drivers, with no more wrapper
-than needed by platform devices:
+SPI protocol drivers somewhat resemble platform device drivers:
+
+ static struct spi_driver CHIP_driver = {
+ .driver = {
+ .name = "CHIP",
+ .bus = &spi_bus_type,
+ .owner = THIS_MODULE,
+ },
- static struct device_driver CHIP_driver = {
- .name = "CHIP",
- .bus = &spi_bus_type,
.probe = CHIP_probe,
- .remove = __exit_p(CHIP_remove),
+ .remove = __devexit_p(CHIP_remove),
.suspend = CHIP_suspend,
.resume = CHIP_resume,
};
-The SPI core will autmatically attempt to bind this driver to any SPI
+The driver core will autmatically attempt to bind this driver to any SPI
device whose board_info gave a modalias of "CHIP". Your probe() code
might look like this unless you're creating a class_device:
- static int __init CHIP_probe(struct device *dev)
+ static int __devinit CHIP_probe(struct spi_device *spi)
{
- struct spi_device *spi = to_spi_device(dev);
struct CHIP *chip;
- struct CHIP_platform_data *pdata = dev->platform_data;
+ struct CHIP_platform_data *pdata;
+
+ /* assuming the driver requires board-specific data: */
+ pdata = &spi->dev.platform_data;
+ if (!pdata)
+ return -ENODEV;
/* get memory for driver's per-chip state */
chip = kzalloc(sizeof *chip, GFP_KERNEL);
if (!chip)
return -ENOMEM;
- dev_set_drvdata(dev, chip);
+ dev_set_drvdata(&spi->dev, chip);
... etc
return 0;
- The basic I/O primitive is spi_async(). Async requests may be
issued in any context (irq handler, task, etc) and completion
is reported using a callback provided with the message.
+ After any detected error, the chip is deselected and processing
+ of that spi_message is aborted.
- There are also synchronous wrappers like spi_sync(), and wrappers
like spi_read(), spi_write(), and spi_write_then_read(). These
the input layer, ALSA, networking, MTD, the character device framework,
or other Linux subsystems.
+Note that there are two types of memory your driver must manage as part
+of interacting with SPI devices.
+
+ - I/O buffers use the usual Linux rules, and must be DMA-safe.
+ You'd normally allocate them from the heap or free page pool.
+ Don't use the stack, or anything that's declared "static".
+
+ - The spi_message and spi_transfer metadata used to glue those
+ I/O buffers into a group of protocol transactions. These can
+ be allocated anywhere it's convenient, including as part of
+ other allocate-once driver data structures. Zero-init these.
+
+If you like, spi_message_alloc() and spi_message_free() convenience
+routines are available to allocate and zero-initialize an spi_message
+with several transfers.
+
How do I write an "SPI Master Controller Driver"?
-------------------------------------------------
git://ftp.safe.ca / safe / jmp / linux-2.6 / blobdiff