diff options
Diffstat (limited to 'include/linux/spi/spi.h')
| -rw-r--r-- | include/linux/spi/spi.h | 82 |
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 | */ |
| 60 | struct spi_device { | 65 | struct 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 | ||
| 89 | static inline struct spi_device *to_spi_device(struct device *dev) | 96 | static 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 | ||
| 147 | extern int spi_register_driver(struct spi_driver *sdrv); | 154 | extern 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 | */ | ||
| 149 | static inline void spi_unregister_driver(struct spi_driver *sdrv) | 161 | static 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 | */ |
| 182 | struct spi_master { | 196 | struct 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 | */ |
| 565 | static inline int | 583 | static 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 |