aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/spi
diff options
context:
space:
mode:
authorDavid Brownell <david-b@pacbell.net>2007-05-08 03:32:21 -0400
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-05-08 14:15:16 -0400
commit33e34dc6ee2cb2cf2d50e65c5b825d9ebb8b9e66 (patch)
tree965e5feaaa7c7802129205bff03ec5e0982a75ba /Documentation/spi
parent814a8d50eb1d88cedcef97567be53ee0d4512631 (diff)
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: David Brownell <dbrownell@users.sourceforge.net> Cc: "Randy.Dunlap" <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation/spi')
-rw-r--r--Documentation/spi/spi-summary43
1 files changed, 24 insertions, 19 deletions
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary
index ecc7c9eb9f29..795fbb48ffa7 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary
@@ -8,7 +8,7 @@ What is SPI?
8The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial 8The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
9link used to connect microcontrollers to sensors, memory, and peripherals. 9link used to connect microcontrollers to sensors, memory, and peripherals.
10 10
11The three signal wires hold a clock (SCLK, often on the order of 10 MHz), 11The three signal wires hold a clock (SCK, often on the order of 10 MHz),
12and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In, 12and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
13Slave Out" (MISO) signals. (Other names are also used.) There are four 13Slave Out" (MISO) signals. (Other names are also used.) There are four
14clocking modes through which data is exchanged; mode-0 and mode-3 are most 14clocking 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 22
23Unlike serial busses like USB or SMBUS, even low level protocols for 23Unlike serial busses like USB or SMBUS, even low level protocols for
24SPI slave functions are usually not interoperable between vendors 24SPI slave functions are usually not interoperable between vendors
25(except for cases like SPI memory chips). 25(except for commodities like SPI memory chips).
26 26
27 - SPI may be used for request/response style device protocols, as with 27 - SPI may be used for request/response style device protocols, as with
28 touchscreen sensors and memory chips. 28 touchscreen sensors and memory chips.
@@ -77,8 +77,9 @@ cards without needing a special purpose MMC/SD/SDIO controller.
77How do these driver programming interfaces work? 77How do these driver programming interfaces work?
78------------------------------------------------ 78------------------------------------------------
79The <linux/spi/spi.h> header file includes kerneldoc, as does the 79The <linux/spi/spi.h> header file includes kerneldoc, as does the
80main source code, and you should certainly read that. This is just 80main source code, and you should certainly read that chapter of the
81an overview, so you get the big picture before the details. 81kernel API document. This is just an overview, so you get the big
82picture before those details.
82 83
83SPI requests always go into I/O queues. Requests for a given SPI device 84SPI requests always go into I/O queues. Requests for a given SPI device
84are always executed in FIFO order, and complete asynchronously through 85are always executed in FIFO order, and complete asynchronously through
@@ -88,7 +89,7 @@ a command and then reading its response.
88 89
89There are two types of SPI driver, here called: 90There are two types of SPI driver, here called:
90 91
91 Controller drivers ... these are often built in to System-On-Chip 92 Controller drivers ... controllers may be built in to System-On-Chip
92 processors, and often support both Master and Slave roles. 93 processors, and often support both Master and Slave roles.
93 These drivers touch hardware registers and may use DMA. 94 These drivers touch hardware registers and may use DMA.
94 Or they can be PIO bitbangers, needing just GPIO pins. 95 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
108programming interface. 109programming interface.
109 110
110There is a minimal core of SPI programming interfaces, focussing on 111There is a minimal core of SPI programming interfaces, focussing on
111using driver model to connect controller and protocol drivers using 112using the driver model to connect controller and protocol drivers using
112device tables provided by board specific initialization code. SPI 113device tables provided by board specific initialization code. SPI
113shows up in sysfs in several locations: 114shows up in sysfs in several locations:
114 115
115 /sys/devices/.../CTLR/spiB.C ... spi_device for on bus "B", 116 /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B",
116 chipselect C, accessed through CTLR. 117 chipselect C, accessed through CTLR.
117 118
118 /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver 119 /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
119 that should be used with this device (for hotplug/coldplug) 120 that should be used with this device (for hotplug/coldplug)
120 121
121 /sys/bus/spi/devices/spiB.C ... symlink to the physical 122 /sys/bus/spi/devices/spiB.C ... symlink to the physical
122 spiB-C device 123 spiB.C device
123 124
124 /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices 125 /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices
125 126
@@ -240,7 +241,7 @@ The board_info should provide enough information to let the system work
240without the chip's driver being loaded. The most troublesome aspect of 241without the chip's driver being loaded. The most troublesome aspect of
241that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since 242that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since
242sharing a bus with a device that interprets chipselect "backwards" is 243sharing a bus with a device that interprets chipselect "backwards" is
243not possible. 244not possible until the infrastructure knows how to deselect it.
244 245
245Then your board initialization code would register that table with the SPI 246Then your board initialization code would register that table with the SPI
246infrastructure, so that it's available later when the SPI master controller 247infrastructure, 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
268call at least spi_unregister_device() when that board is removed. 269call at least spi_unregister_device() when that board is removed.
269 270
270When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those 271When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those
271configurations will also be dynamic. Fortunately, those devices all support 272configurations will also be dynamic. Fortunately, such devices all support
272basic device identification probes, so that support should hotplug normally. 273basic device identification probes, so they should hotplug normally.
273 274
274 275
275How do I write an "SPI Protocol Driver"? 276How do I write an "SPI Protocol Driver"?
276---------------------------------------- 277----------------------------------------
277All SPI drivers are currently kernel drivers. A userspace driver API 278Most SPI drivers are currently kernel drivers, but there's also support
278would just be another kernel driver, probably offering some lowlevel 279for userspace drivers. Here we talk only about kernel drivers.
279access through aio_read(), aio_write(), and ioctl() calls and using the
280standard userspace sysfs mechanisms to bind to a given SPI device.
281 280
282SPI protocol drivers somewhat resemble platform device drivers: 281SPI protocol drivers somewhat resemble platform device drivers:
283 282
@@ -319,7 +318,8 @@ might look like this unless you're creating a class_device:
319 318
320As soon as it enters probe(), the driver may issue I/O requests to 319As soon as it enters probe(), the driver may issue I/O requests to
321the SPI device using "struct spi_message". When remove() returns, 320the SPI device using "struct spi_message". When remove() returns,
322the driver guarantees that it won't submit any more such messages. 321or after probe() fails, the driver guarantees that it won't submit
322any more such messages.
323 323
324 - An spi_message is a sequence of protocol operations, executed 324 - An spi_message is a sequence of protocol operations, executed
325 as one atomic sequence. SPI driver controls include: 325 as one atomic sequence. SPI driver controls include:
@@ -368,7 +368,8 @@ the driver guarantees that it won't submit any more such messages.
368Some drivers may need to modify spi_device characteristics like the 368Some drivers may need to modify spi_device characteristics like the
369transfer mode, wordsize, or clock rate. This is done with spi_setup(), 369transfer mode, wordsize, or clock rate. This is done with spi_setup(),
370which would normally be called from probe() before the first I/O is 370which would normally be called from probe() before the first I/O is
371done to the device. 371done to the device. However, that can also be called at any time
372that no message is pending for that device.
372 373
373While "spi_device" would be the bottom boundary of the driver, the 374While "spi_device" would be the bottom boundary of the driver, the
374upper boundaries might include sysfs (especially for sensor readings), 375upper boundaries might include sysfs (especially for sensor readings),
@@ -445,11 +446,15 @@ SPI MASTER METHODS
445 This sets up the device clock rate, SPI mode, and word sizes. 446 This sets up the device clock rate, SPI mode, and word sizes.
446 Drivers may change the defaults provided by board_info, and then 447 Drivers may change the defaults provided by board_info, and then
447 call spi_setup(spi) to invoke this routine. It may sleep. 448 call spi_setup(spi) to invoke this routine. It may sleep.
449 Unless each SPI slave has its own configuration registers, don't
450 change them right away ... otherwise drivers could corrupt I/O
451 that's in progress for other SPI devices.
448 452
449 master->transfer(struct spi_device *spi, struct spi_message *message) 453 master->transfer(struct spi_device *spi, struct spi_message *message)
450 This must not sleep. Its responsibility is arrange that the 454 This must not sleep. Its responsibility is arrange that the
451 transfer happens and its complete() callback is issued; the two 455 transfer happens and its complete() callback is issued. The two
452 will normally happen later, after other transfers complete. 456 will normally happen later, after other transfers complete, and
457 if the controller is idle it will need to be kickstarted.
453 458
454 master->cleanup(struct spi_device *spi) 459 master->cleanup(struct spi_device *spi)
455 Your controller driver may use spi_device.controller_state to hold 460 Your controller driver may use spi_device.controller_state to hold