aboutsummaryrefslogtreecommitdiffstats
path: root/include
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 /include
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 'include')
-rw-r--r--include/linux/spi/spi.h82
1 files changed, 51 insertions, 31 deletions
diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h
index 4f0f8c2e58a5..b6bedc3ee95c 100644
--- a/include/linux/spi/spi.h
+++ b/include/linux/spi/spi.h
@@ -32,11 +32,12 @@ extern struct bus_type spi_bus_type;
32 * @max_speed_hz: Maximum clock rate to be used with this chip 32 * @max_speed_hz: Maximum clock rate to be used with this chip
33 * (on this board); may be changed by the device's driver. 33 * (on this board); may be changed by the device's driver.
34 * The spi_transfer.speed_hz can override this for each transfer. 34 * The spi_transfer.speed_hz can override this for each transfer.
35 * @chip-select: Chipselect, distinguishing chips handled by "master". 35 * @chip_select: Chipselect, distinguishing chips handled by @master.
36 * @mode: The spi mode defines how data is clocked out and in. 36 * @mode: The spi mode defines how data is clocked out and in.
37 * This may be changed by the device's driver. 37 * This may be changed by the device's driver.
38 * The "active low" default for chipselect mode can be overridden, 38 * The "active low" default for chipselect mode can be overridden
39 * as can the "MSB first" default for each word in a transfer. 39 * (by specifying SPI_CS_HIGH) as can the "MSB first" default for
40 * each word in a transfer (by specifying SPI_LSB_FIRST).
40 * @bits_per_word: Data transfers involve one or more words; word sizes 41 * @bits_per_word: Data transfers involve one or more words; word sizes
41 * like eight or 12 bits are common. In-memory wordsizes are 42 * like eight or 12 bits are common. In-memory wordsizes are
42 * powers of two bytes (e.g. 20 bit samples use 32 bits). 43 * powers of two bytes (e.g. 20 bit samples use 32 bits).
@@ -48,14 +49,18 @@ extern struct bus_type spi_bus_type;
48 * @controller_state: Controller's runtime state 49 * @controller_state: Controller's runtime state
49 * @controller_data: Board-specific definitions for controller, such as 50 * @controller_data: Board-specific definitions for controller, such as
50 * FIFO initialization parameters; from board_info.controller_data 51 * FIFO initialization parameters; from board_info.controller_data
52 * @modalias: Name of the driver to use with this device, or an alias
53 * for that name. This appears in the sysfs "modalias" attribute
54 * for driver coldplugging, and in uevents used for hotplugging
51 * 55 *
52 * An spi_device is used to interchange data between an SPI slave 56 * A @spi_device is used to interchange data between an SPI slave
53 * (usually a discrete chip) and CPU memory. 57 * (usually a discrete chip) and CPU memory.
54 * 58 *
55 * In "dev", the platform_data is used to hold information about this 59 * In @dev, the platform_data is used to hold information about this
56 * device that's meaningful to the device's protocol driver, but not 60 * device that's meaningful to the device's protocol driver, but not
57 * to its controller. One example might be an identifier for a chip 61 * to its controller. One example might be an identifier for a chip
58 * variant with slightly different functionality. 62 * variant with slightly different functionality; another might be
63 * information about how this particular board wires the chip's pins.
59 */ 64 */
60struct spi_device { 65struct spi_device {
61 struct device dev; 66 struct device dev;
@@ -77,13 +82,15 @@ struct spi_device {
77 void *controller_data; 82 void *controller_data;
78 const char *modalias; 83 const char *modalias;
79 84
80 // likely need more hooks for more protocol options affecting how 85 /*
81 // the controller talks to each chip, like: 86 * likely need more hooks for more protocol options affecting how
82 // - memory packing (12 bit samples into low bits, others zeroed) 87 * the controller talks to each chip, like:
83 // - priority 88 * - memory packing (12 bit samples into low bits, others zeroed)
84 // - drop chipselect after each word 89 * - priority
85 // - chipselect delays 90 * - drop chipselect after each word
86 // - ... 91 * - chipselect delays
92 * - ...
93 */
87}; 94};
88 95
89static inline struct spi_device *to_spi_device(struct device *dev) 96static inline struct spi_device *to_spi_device(struct device *dev)
@@ -146,6 +153,11 @@ static inline struct spi_driver *to_spi_driver(struct device_driver *drv)
146 153
147extern int spi_register_driver(struct spi_driver *sdrv); 154extern int spi_register_driver(struct spi_driver *sdrv);
148 155
156/**
157 * spi_unregister_driver - reverse effect of spi_register_driver
158 * @sdrv: the driver to unregister
159 * Context: can sleep
160 */
149static inline void spi_unregister_driver(struct spi_driver *sdrv) 161static inline void spi_unregister_driver(struct spi_driver *sdrv)
150{ 162{
151 if (sdrv) 163 if (sdrv)
@@ -165,18 +177,20 @@ static inline void spi_unregister_driver(struct spi_driver *sdrv)
165 * @setup: updates the device mode and clocking records used by a 177 * @setup: updates the device mode and clocking records used by a
166 * device's SPI controller; protocol code may call this. This 178 * device's SPI controller; protocol code may call this. This
167 * must fail if an unrecognized or unsupported mode is requested. 179 * must fail if an unrecognized or unsupported mode is requested.
180 * It's always safe to call this unless transfers are pending on
181 * the device whose settings are being modified.
168 * @transfer: adds a message to the controller's transfer queue. 182 * @transfer: adds a message to the controller's transfer queue.
169 * @cleanup: frees controller-specific state 183 * @cleanup: frees controller-specific state
170 * 184 *
171 * Each SPI master controller can communicate with one or more spi_device 185 * Each SPI master controller can communicate with one or more @spi_device
172 * children. These make a small bus, sharing MOSI, MISO and SCK signals 186 * children. These make a small bus, sharing MOSI, MISO and SCK signals
173 * but not chip select signals. Each device may be configured to use a 187 * but not chip select signals. Each device may be configured to use a
174 * different clock rate, since those shared signals are ignored unless 188 * different clock rate, since those shared signals are ignored unless
175 * the chip is selected. 189 * the chip is selected.
176 * 190 *
177 * The driver for an SPI controller manages access to those devices through 191 * The driver for an SPI controller manages access to those devices through
178 * a queue of spi_message transactions, copyin data between CPU memory and 192 * a queue of spi_message transactions, copying data between CPU memory and
179 * an SPI slave device). For each such message it queues, it calls the 193 * an SPI slave device. For each such message it queues, it calls the
180 * message's completion function when the transaction completes. 194 * message's completion function when the transaction completes.
181 */ 195 */
182struct spi_master { 196struct spi_master {
@@ -280,27 +294,27 @@ extern struct spi_master *spi_busnum_to_master(u16 busnum);
280 * struct spi_transfer - a read/write buffer pair 294 * struct spi_transfer - a read/write buffer pair
281 * @tx_buf: data to be written (dma-safe memory), or NULL 295 * @tx_buf: data to be written (dma-safe memory), or NULL
282 * @rx_buf: data to be read (dma-safe memory), or NULL 296 * @rx_buf: data to be read (dma-safe memory), or NULL
283 * @tx_dma: DMA address of tx_buf, if spi_message.is_dma_mapped 297 * @tx_dma: DMA address of tx_buf, if @spi_message.is_dma_mapped
284 * @rx_dma: DMA address of rx_buf, if spi_message.is_dma_mapped 298 * @rx_dma: DMA address of rx_buf, if @spi_message.is_dma_mapped
285 * @len: size of rx and tx buffers (in bytes) 299 * @len: size of rx and tx buffers (in bytes)
286 * @speed_hz: Select a speed other then the device default for this 300 * @speed_hz: Select a speed other then the device default for this
287 * transfer. If 0 the default (from spi_device) is used. 301 * transfer. If 0 the default (from @spi_device) is used.
288 * @bits_per_word: select a bits_per_word other then the device default 302 * @bits_per_word: select a bits_per_word other then the device default
289 * for this transfer. If 0 the default (from spi_device) is used. 303 * for this transfer. If 0 the default (from @spi_device) is used.
290 * @cs_change: affects chipselect after this transfer completes 304 * @cs_change: affects chipselect after this transfer completes
291 * @delay_usecs: microseconds to delay after this transfer before 305 * @delay_usecs: microseconds to delay after this transfer before
292 * (optionally) changing the chipselect status, then starting 306 * (optionally) changing the chipselect status, then starting
293 * the next transfer or completing this spi_message. 307 * the next transfer or completing this @spi_message.
294 * @transfer_list: transfers are sequenced through spi_message.transfers 308 * @transfer_list: transfers are sequenced through @spi_message.transfers
295 * 309 *
296 * SPI transfers always write the same number of bytes as they read. 310 * SPI transfers always write the same number of bytes as they read.
297 * Protocol drivers should always provide rx_buf and/or tx_buf. 311 * Protocol drivers should always provide @rx_buf and/or @tx_buf.
298 * In some cases, they may also want to provide DMA addresses for 312 * In some cases, they may also want to provide DMA addresses for
299 * the data being transferred; that may reduce overhead, when the 313 * the data being transferred; that may reduce overhead, when the
300 * underlying driver uses dma. 314 * underlying driver uses dma.
301 * 315 *
302 * If the transmit buffer is null, zeroes will be shifted out 316 * If the transmit buffer is null, zeroes will be shifted out
303 * while filling rx_buf. If the receive buffer is null, the data 317 * while filling @rx_buf. If the receive buffer is null, the data
304 * shifted in will be discarded. Only "len" bytes shift out (or in). 318 * shifted in will be discarded. Only "len" bytes shift out (or in).
305 * It's an error to try to shift out a partial word. (For example, by 319 * It's an error to try to shift out a partial word. (For example, by
306 * shifting out three bytes with word size of sixteen or twenty bits; 320 * shifting out three bytes with word size of sixteen or twenty bits;
@@ -309,7 +323,7 @@ extern struct spi_master *spi_busnum_to_master(u16 busnum);
309 * In-memory data values are always in native CPU byte order, translated 323 * In-memory data values are always in native CPU byte order, translated
310 * from the wire byte order (big-endian except with SPI_LSB_FIRST). So 324 * from the wire byte order (big-endian except with SPI_LSB_FIRST). So
311 * for example when bits_per_word is sixteen, buffers are 2N bytes long 325 * for example when bits_per_word is sixteen, buffers are 2N bytes long
312 * and hold N sixteen bit words in CPU byte order. 326 * (@len = 2N) and hold N sixteen bit words in CPU byte order.
313 * 327 *
314 * When the word size of the SPI transfer is not a power-of-two multiple 328 * When the word size of the SPI transfer is not a power-of-two multiple
315 * of eight bits, those in-memory words include extra bits. In-memory 329 * of eight bits, those in-memory words include extra bits. In-memory
@@ -318,7 +332,7 @@ extern struct spi_master *spi_busnum_to_master(u16 busnum);
318 * 332 *
319 * All SPI transfers start with the relevant chipselect active. Normally 333 * All SPI transfers start with the relevant chipselect active. Normally
320 * it stays selected until after the last transfer in a message. Drivers 334 * it stays selected until after the last transfer in a message. Drivers
321 * can affect the chipselect signal using cs_change: 335 * can affect the chipselect signal using cs_change.
322 * 336 *
323 * (i) If the transfer isn't the last one in the message, this flag is 337 * (i) If the transfer isn't the last one in the message, this flag is
324 * used to make the chipselect briefly go inactive in the middle of the 338 * used to make the chipselect briefly go inactive in the middle of the
@@ -372,7 +386,7 @@ struct spi_transfer {
372 * @queue: for use by whichever driver currently owns the message 386 * @queue: for use by whichever driver currently owns the message
373 * @state: for use by whichever driver currently owns the message 387 * @state: for use by whichever driver currently owns the message
374 * 388 *
375 * An spi_message is used to execute an atomic sequence of data transfers, 389 * A @spi_message is used to execute an atomic sequence of data transfers,
376 * each represented by a struct spi_transfer. The sequence is "atomic" 390 * each represented by a struct spi_transfer. The sequence is "atomic"
377 * in the sense that no other spi_message may use that SPI bus until that 391 * in the sense that no other spi_message may use that SPI bus until that
378 * sequence completes. On some systems, many such sequences can execute as 392 * sequence completes. On some systems, many such sequences can execute as
@@ -464,8 +478,9 @@ static inline void spi_message_free(struct spi_message *m)
464} 478}
465 479
466/** 480/**
467 * spi_setup -- setup SPI mode and clock rate 481 * spi_setup - setup SPI mode and clock rate
468 * @spi: the device whose settings are being modified 482 * @spi: the device whose settings are being modified
483 * Context: can sleep
469 * 484 *
470 * SPI protocol drivers may need to update the transfer mode if the 485 * SPI protocol drivers may need to update the transfer mode if the
471 * device doesn't work with the mode 0 default. They may likewise need 486 * device doesn't work with the mode 0 default. They may likewise need
@@ -474,7 +489,7 @@ static inline void spi_message_free(struct spi_message *m)
474 * The changes take effect the next time the device is selected and data 489 * The changes take effect the next time the device is selected and data
475 * is transferred to or from it. 490 * is transferred to or from it.
476 * 491 *
477 * Note that this call wil fail if the protocol driver specifies an option 492 * Note that this call will fail if the protocol driver specifies an option
478 * that the underlying controller or its driver does not support. For 493 * that the underlying controller or its driver does not support. For
479 * example, not all hardware supports wire transfers using nine bit words, 494 * example, not all hardware supports wire transfers using nine bit words,
480 * LSB-first wire encoding, or active-high chipselects. 495 * LSB-first wire encoding, or active-high chipselects.
@@ -487,9 +502,10 @@ spi_setup(struct spi_device *spi)
487 502
488 503
489/** 504/**
490 * spi_async -- asynchronous SPI transfer 505 * spi_async - asynchronous SPI transfer
491 * @spi: device with which data will be exchanged 506 * @spi: device with which data will be exchanged
492 * @message: describes the data transfers, including completion callback 507 * @message: describes the data transfers, including completion callback
508 * Context: any (irqs may be blocked, etc)
493 * 509 *
494 * This call may be used in_irq and other contexts which can't sleep, 510 * This call may be used in_irq and other contexts which can't sleep,
495 * as well as from task contexts which can sleep. 511 * as well as from task contexts which can sleep.
@@ -535,6 +551,7 @@ extern int spi_sync(struct spi_device *spi, struct spi_message *message);
535 * @spi: device to which data will be written 551 * @spi: device to which data will be written
536 * @buf: data buffer 552 * @buf: data buffer
537 * @len: data buffer size 553 * @len: data buffer size
554 * Context: can sleep
538 * 555 *
539 * This writes the buffer and returns zero or a negative error code. 556 * This writes the buffer and returns zero or a negative error code.
540 * Callable only from contexts that can sleep. 557 * Callable only from contexts that can sleep.
@@ -558,8 +575,9 @@ spi_write(struct spi_device *spi, const u8 *buf, size_t len)
558 * @spi: device from which data will be read 575 * @spi: device from which data will be read
559 * @buf: data buffer 576 * @buf: data buffer
560 * @len: data buffer size 577 * @len: data buffer size
578 * Context: can sleep
561 * 579 *
562 * This writes the buffer and returns zero or a negative error code. 580 * This reads the buffer and returns zero or a negative error code.
563 * Callable only from contexts that can sleep. 581 * Callable only from contexts that can sleep.
564 */ 582 */
565static inline int 583static inline int
@@ -585,6 +603,7 @@ extern int spi_write_then_read(struct spi_device *spi,
585 * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read 603 * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read
586 * @spi: device with which data will be exchanged 604 * @spi: device with which data will be exchanged
587 * @cmd: command to be written before data is read back 605 * @cmd: command to be written before data is read back
606 * Context: can sleep
588 * 607 *
589 * This returns the (unsigned) eight bit number returned by the 608 * This returns the (unsigned) eight bit number returned by the
590 * device, or else a negative error code. Callable only from 609 * device, or else a negative error code. Callable only from
@@ -605,6 +624,7 @@ static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd)
605 * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read 624 * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read
606 * @spi: device with which data will be exchanged 625 * @spi: device with which data will be exchanged
607 * @cmd: command to be written before data is read back 626 * @cmd: command to be written before data is read back
627 * Context: can sleep
608 * 628 *
609 * This returns the (unsigned) sixteen bit number returned by the 629 * This returns the (unsigned) sixteen bit number returned by the
610 * device, or else a negative error code. Callable only from 630 * device, or else a negative error code. Callable only from