diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/DocBook/kernel-api.tmpl | 63 | ||||
-rw-r--r-- | Documentation/spi/spi-summary | 43 |
2 files changed, 87 insertions, 19 deletions
diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index b61dfc79e1b8..a2b2b4d187c5 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl | |||
@@ -576,4 +576,67 @@ X!Idrivers/video/console/fonts.c | |||
576 | !Edrivers/input/ff-core.c | 576 | !Edrivers/input/ff-core.c |
577 | !Edrivers/input/ff-memless.c | 577 | !Edrivers/input/ff-memless.c |
578 | </chapter> | 578 | </chapter> |
579 | |||
580 | <chapter id="spi"> | ||
581 | <title>Serial Peripheral Interface (SPI)</title> | ||
582 | <para> | ||
583 | SPI is the "Serial Peripheral Interface", widely used with | ||
584 | embedded systems because it is a simple and efficient | ||
585 | interface: basically a multiplexed shift register. | ||
586 | Its three signal wires hold a clock (SCK, often in the range | ||
587 | of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and | ||
588 | a "Master In, Slave Out" (MISO) data line. | ||
589 | SPI is a full duplex protocol; for each bit shifted out the | ||
590 | MOSI line (one per clock) another is shifted in on the MISO line. | ||
591 | Those bits are assembled into words of various sizes on the | ||
592 | way to and from system memory. | ||
593 | An additional chipselect line is usually active-low (nCS); | ||
594 | four signals are normally used for each peripheral, plus | ||
595 | sometimes an interrupt. | ||
596 | </para> | ||
597 | <para> | ||
598 | The SPI bus facilities listed here provide a generalized | ||
599 | interface to declare SPI busses and devices, manage them | ||
600 | according to the standard Linux driver model, and perform | ||
601 | input/output operations. | ||
602 | At this time, only "master" side interfaces are supported, | ||
603 | where Linux talks to SPI peripherals and does not implement | ||
604 | such a peripheral itself. | ||
605 | (Interfaces to support implementing SPI slaves would | ||
606 | necessarily look different.) | ||
607 | </para> | ||
608 | <para> | ||
609 | The programming interface is structured around two kinds of driver, | ||
610 | and two kinds of device. | ||
611 | A "Controller Driver" abstracts the controller hardware, which may | ||
612 | be as simple as a set of GPIO pins or as complex as a pair of FIFOs | ||
613 | connected to dual DMA engines on the other side of the SPI shift | ||
614 | register (maximizing throughput). Such drivers bridge between | ||
615 | whatever bus they sit on (often the platform bus) and SPI, and | ||
616 | expose the SPI side of their device as a | ||
617 | <structname>struct spi_master</structname>. | ||
618 | SPI devices are children of that master, represented as a | ||
619 | <structname>struct spi_device</structname> and manufactured from | ||
620 | <structname>struct spi_board_info</structname> descriptors which | ||
621 | are usually provided by board-specific initialization code. | ||
622 | A <structname>struct spi_driver</structname> is called a | ||
623 | "Protocol Driver", and is bound to a spi_device using normal | ||
624 | driver model calls. | ||
625 | </para> | ||
626 | <para> | ||
627 | The I/O model is a set of queued messages. Protocol drivers | ||
628 | submit one or more <structname>struct spi_message</structname> | ||
629 | objects, which are processed and completed asynchronously. | ||
630 | (There are synchronous wrappers, however.) Messages are | ||
631 | built from one or more <structname>struct spi_transfer</structname> | ||
632 | objects, each of which wraps a full duplex SPI transfer. | ||
633 | A variety of protocol tweaking options are needed, because | ||
634 | different chips adopt very different policies for how they | ||
635 | use the bits transferred with SPI. | ||
636 | </para> | ||
637 | !Iinclude/linux/spi/spi.h | ||
638 | !Fdrivers/spi/spi.c spi_register_board_info | ||
639 | !Edrivers/spi/spi.c | ||
640 | </chapter> | ||
641 | |||
579 | </book> | 642 | </book> |
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? | |||
8 | The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial | 8 | The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial |
9 | link used to connect microcontrollers to sensors, memory, and peripherals. | 9 | link used to connect microcontrollers to sensors, memory, and peripherals. |
10 | 10 | ||
11 | The three signal wires hold a clock (SCLK, often on the order of 10 MHz), | 11 | The three signal wires hold a clock (SCK, often on the order of 10 MHz), |
12 | and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In, | 12 | and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In, |
13 | Slave Out" (MISO) signals. (Other names are also used.) There are four | 13 | Slave Out" (MISO) signals. (Other names are also used.) There are four |
14 | clocking modes through which data is exchanged; mode-0 and mode-3 are most | 14 | 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 | 22 | ||
23 | Unlike serial busses like USB or SMBUS, even low level protocols for | 23 | Unlike serial busses like USB or SMBUS, even low level protocols for |
24 | SPI slave functions are usually not interoperable between vendors | 24 | SPI 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. | |||
77 | How do these driver programming interfaces work? | 77 | How do these driver programming interfaces work? |
78 | ------------------------------------------------ | 78 | ------------------------------------------------ |
79 | The <linux/spi/spi.h> header file includes kerneldoc, as does the | 79 | The <linux/spi/spi.h> header file includes kerneldoc, as does the |
80 | main source code, and you should certainly read that. This is just | 80 | main source code, and you should certainly read that chapter of the |
81 | an overview, so you get the big picture before the details. | 81 | kernel API document. This is just an overview, so you get the big |
82 | picture before those details. | ||
82 | 83 | ||
83 | SPI requests always go into I/O queues. Requests for a given SPI device | 84 | SPI requests always go into I/O queues. Requests for a given SPI device |
84 | are always executed in FIFO order, and complete asynchronously through | 85 | are always executed in FIFO order, and complete asynchronously through |
@@ -88,7 +89,7 @@ a command and then reading its response. | |||
88 | 89 | ||
89 | There are two types of SPI driver, here called: | 90 | There 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 | |||
108 | programming interface. | 109 | programming interface. |
109 | 110 | ||
110 | There is a minimal core of SPI programming interfaces, focussing on | 111 | There is a minimal core of SPI programming interfaces, focussing on |
111 | using driver model to connect controller and protocol drivers using | 112 | using the driver model to connect controller and protocol drivers using |
112 | device tables provided by board specific initialization code. SPI | 113 | device tables provided by board specific initialization code. SPI |
113 | shows up in sysfs in several locations: | 114 | shows 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 | |||
240 | without the chip's driver being loaded. The most troublesome aspect of | 241 | without the chip's driver being loaded. The most troublesome aspect of |
241 | that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since | 242 | that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since |
242 | sharing a bus with a device that interprets chipselect "backwards" is | 243 | sharing a bus with a device that interprets chipselect "backwards" is |
243 | not possible. | 244 | not possible until the infrastructure knows how to deselect it. |
244 | 245 | ||
245 | Then your board initialization code would register that table with the SPI | 246 | Then your board initialization code would register that table with the SPI |
246 | infrastructure, so that it's available later when the SPI master controller | 247 | 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 | call at least spi_unregister_device() when that board is removed. | 269 | call at least spi_unregister_device() when that board is removed. |
269 | 270 | ||
270 | When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those | 271 | When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those |
271 | configurations will also be dynamic. Fortunately, those devices all support | 272 | configurations will also be dynamic. Fortunately, such devices all support |
272 | basic device identification probes, so that support should hotplug normally. | 273 | basic device identification probes, so they should hotplug normally. |
273 | 274 | ||
274 | 275 | ||
275 | How do I write an "SPI Protocol Driver"? | 276 | How do I write an "SPI Protocol Driver"? |
276 | ---------------------------------------- | 277 | ---------------------------------------- |
277 | All SPI drivers are currently kernel drivers. A userspace driver API | 278 | Most SPI drivers are currently kernel drivers, but there's also support |
278 | would just be another kernel driver, probably offering some lowlevel | 279 | for userspace drivers. Here we talk only about kernel drivers. |
279 | access through aio_read(), aio_write(), and ioctl() calls and using the | ||
280 | standard userspace sysfs mechanisms to bind to a given SPI device. | ||
281 | 280 | ||
282 | SPI protocol drivers somewhat resemble platform device drivers: | 281 | SPI 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 | ||
320 | As soon as it enters probe(), the driver may issue I/O requests to | 319 | As soon as it enters probe(), the driver may issue I/O requests to |
321 | the SPI device using "struct spi_message". When remove() returns, | 320 | the SPI device using "struct spi_message". When remove() returns, |
322 | the driver guarantees that it won't submit any more such messages. | 321 | or after probe() fails, the driver guarantees that it won't submit |
322 | any 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. | |||
368 | Some drivers may need to modify spi_device characteristics like the | 368 | Some drivers may need to modify spi_device characteristics like the |
369 | transfer mode, wordsize, or clock rate. This is done with spi_setup(), | 369 | transfer mode, wordsize, or clock rate. This is done with spi_setup(), |
370 | which would normally be called from probe() before the first I/O is | 370 | which would normally be called from probe() before the first I/O is |
371 | done to the device. | 371 | done to the device. However, that can also be called at any time |
372 | that no message is pending for that device. | ||
372 | 373 | ||
373 | While "spi_device" would be the bottom boundary of the driver, the | 374 | While "spi_device" would be the bottom boundary of the driver, the |
374 | upper boundaries might include sysfs (especially for sensor readings), | 375 | upper 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 |