aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/spi
diff options
context:
space:
mode:
authorDavid Brownell <david-b@pacbell.net>2006-01-08 16:34:23 -0500
committerGreg Kroah-Hartman <gregkh@suse.de>2006-01-13 19:29:54 -0500
commitb885244eb2628e0b8206e7edaaa6a314da78e9a4 (patch)
treee548fb3a94603c4a5406920c97246a78fe16b64a /Documentation/spi
parent1d6432fe10c3e724e307dd7137cd293a0edcae80 (diff)
[PATCH] spi: add spi_driver to SPI framework
This is a refresh of the "Simple SPI Framework" found in 2.6.15-rc3-mm1 which makes the following changes: * There's now a "struct spi_driver". This increase the footprint of the core a bit, since it now includes code to do what the driver core was previously handling directly. Documentation and comments were updated to match. * spi_alloc_master() now does class_device_initialize(), so it can at least be refcounted before spi_register_master(). To match, spi_register_master() switched over to class_device_add(). * States explicitly that after transfer errors, spi_devices will be deselected. We want fault recovery procedures to work the same for all controller drivers. * Minor tweaks: controller_data no longer points to readonly data; prevent some potential cast-from-null bugs with container_of calls; clarifies some existing kerneldoc, And a few small cleanups. Signed-off-by: David Brownell <dbrownell@users.sourceforge.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Diffstat (limited to 'Documentation/spi')
-rw-r--r--Documentation/spi/spi-summary52
1 files changed, 32 insertions, 20 deletions
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary
index 00497f95ca4b..c6152d1ff2b0 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary
@@ -1,18 +1,19 @@
1Overview of Linux kernel SPI support 1Overview of Linux kernel SPI support
2==================================== 2====================================
3 3
422-Nov-2005 402-Dec-2005
5 5
6What is SPI? 6What is SPI?
7------------ 7------------
8The "Serial Peripheral Interface" (SPI) is a four-wire point-to-point 8The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
9serial link used to connect microcontrollers to sensors and memory. 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 (SCLK, 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
15commonly used. 15commonly used. Each clock cycle shifts data out and data in; the clock
16doesn't cycle except when there is data to shift.
16 17
17SPI masters may use a "chip select" line to activate a given SPI slave 18SPI masters may use a "chip select" line to activate a given SPI slave
18device, so those three signal wires may be connected to several chips 19device, so those three signal wires may be connected to several chips
@@ -79,11 +80,18 @@ The <linux/spi/spi.h> header file includes kerneldoc, as does the
79main source code, and you should certainly read that. This is just 80main source code, and you should certainly read that. This is just
80an overview, so you get the big picture before the details. 81an overview, so you get the big picture before the details.
81 82
83SPI requests always go into I/O queues. Requests for a given SPI device
84are always executed in FIFO order, and complete asynchronously through
85completion callbacks. There are also some simple synchronous wrappers
86for those calls, including ones for common transaction types like writing
87a command and then reading its response.
88
82There are two types of SPI driver, here called: 89There are two types of SPI driver, here called:
83 90
84 Controller drivers ... these are often built in to System-On-Chip 91 Controller drivers ... these are often built in to System-On-Chip
85 processors, and often support both Master and Slave roles. 92 processors, and often support both Master and Slave roles.
86 These drivers touch hardware registers and may use DMA. 93 These drivers touch hardware registers and may use DMA.
94 Or they can be PIO bitbangers, needing just GPIO pins.
87 95
88 Protocol drivers ... these pass messages through the controller 96 Protocol drivers ... these pass messages through the controller
89 driver to communicate with a Slave or Master device on the 97 driver to communicate with a Slave or Master device on the
@@ -116,11 +124,6 @@ shows up in sysfs in several locations:
116 managing bus "B". All the spiB.* devices share the same 124 managing bus "B". All the spiB.* devices share the same
117 physical SPI bus segment, with SCLK, MOSI, and MISO. 125 physical SPI bus segment, with SCLK, MOSI, and MISO.
118 126
119The basic I/O primitive submits an asynchronous message to an I/O queue
120maintained by the controller driver. A completion callback is issued
121asynchronously when the data transfer(s) in that message completes.
122There are also some simple synchronous wrappers for those calls.
123
124 127
125How does board-specific init code declare SPI devices? 128How does board-specific init code declare SPI devices?
126------------------------------------------------------ 129------------------------------------------------------
@@ -263,33 +266,40 @@ would just be another kernel driver, probably offering some lowlevel
263access through aio_read(), aio_write(), and ioctl() calls and using the 266access through aio_read(), aio_write(), and ioctl() calls and using the
264standard userspace sysfs mechanisms to bind to a given SPI device. 267standard userspace sysfs mechanisms to bind to a given SPI device.
265 268
266SPI protocol drivers are normal device drivers, with no more wrapper 269SPI protocol drivers somewhat resemble platform device drivers:
267than needed by platform devices: 270
271 static struct spi_driver CHIP_driver = {
272 .driver = {
273 .name = "CHIP",
274 .bus = &spi_bus_type,
275 .owner = THIS_MODULE,
276 },
268 277
269 static struct device_driver CHIP_driver = {
270 .name = "CHIP",
271 .bus = &spi_bus_type,
272 .probe = CHIP_probe, 278 .probe = CHIP_probe,
273 .remove = __exit_p(CHIP_remove), 279 .remove = __devexit_p(CHIP_remove),
274 .suspend = CHIP_suspend, 280 .suspend = CHIP_suspend,
275 .resume = CHIP_resume, 281 .resume = CHIP_resume,
276 }; 282 };
277 283
278The SPI core will autmatically attempt to bind this driver to any SPI 284The driver core will autmatically attempt to bind this driver to any SPI
279device whose board_info gave a modalias of "CHIP". Your probe() code 285device whose board_info gave a modalias of "CHIP". Your probe() code
280might look like this unless you're creating a class_device: 286might look like this unless you're creating a class_device:
281 287
282 static int __init CHIP_probe(struct device *dev) 288 static int __devinit CHIP_probe(struct spi_device *spi)
283 { 289 {
284 struct spi_device *spi = to_spi_device(dev);
285 struct CHIP *chip; 290 struct CHIP *chip;
286 struct CHIP_platform_data *pdata = dev->platform_data; 291 struct CHIP_platform_data *pdata;
292
293 /* assuming the driver requires board-specific data: */
294 pdata = &spi->dev.platform_data;
295 if (!pdata)
296 return -ENODEV;
287 297
288 /* get memory for driver's per-chip state */ 298 /* get memory for driver's per-chip state */
289 chip = kzalloc(sizeof *chip, GFP_KERNEL); 299 chip = kzalloc(sizeof *chip, GFP_KERNEL);
290 if (!chip) 300 if (!chip)
291 return -ENOMEM; 301 return -ENOMEM;
292 dev_set_drvdata(dev, chip); 302 dev_set_drvdata(&spi->dev, chip);
293 303
294 ... etc 304 ... etc
295 return 0; 305 return 0;
@@ -328,6 +338,8 @@ the driver guarantees that it won't submit any more such messages.
328 - The basic I/O primitive is spi_async(). Async requests may be 338 - The basic I/O primitive is spi_async(). Async requests may be
329 issued in any context (irq handler, task, etc) and completion 339 issued in any context (irq handler, task, etc) and completion
330 is reported using a callback provided with the message. 340 is reported using a callback provided with the message.
341 After any detected error, the chip is deselected and processing
342 of that spi_message is aborted.
331 343
332 - There are also synchronous wrappers like spi_sync(), and wrappers 344 - There are also synchronous wrappers like spi_sync(), and wrappers
333 like spi_read(), spi_write(), and spi_write_then_read(). These 345 like spi_read(), spi_write(), and spi_write_then_read(). These