Commit 80224561 authored by David Brownell's avatar David Brownell Committed by Linus Torvalds

[PATCH] SPI doc clarifications

This clarifies some aspects of the SPI programming interface, based on
feedback from Hans-Peter Nilsson.  The in-memory representation of words is
right-aligned, so for example a twelve bit word is stored using sixteen bits
with four undefined bits in the MSB.  And controller drivers must reject
protocol tweaking modes they do not support.
Signed-off-by: default avatarDavid Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 0ffa0285
...@@ -163,7 +163,8 @@ static inline void spi_unregister_driver(struct spi_driver *sdrv) ...@@ -163,7 +163,8 @@ static inline void spi_unregister_driver(struct spi_driver *sdrv)
* each slave has a chipselect signal, but it's common that not * each slave has a chipselect signal, but it's common that not
* every chipselect is connected to a slave. * every chipselect is connected to a slave.
* @setup: updates the device mode and clocking records used by a * @setup: updates the device mode and clocking records used by a
* device's SPI controller; protocol code may call this. * device's SPI controller; protocol code may call this. This
* must fail if an unrecognized or unsupported mode is requested.
* @transfer: adds a message to the controller's transfer queue. * @transfer: adds a message to the controller's transfer queue.
* @cleanup: frees controller-specific state * @cleanup: frees controller-specific state
* *
...@@ -305,6 +306,16 @@ extern struct spi_master *spi_busnum_to_master(u16 busnum); ...@@ -305,6 +306,16 @@ extern struct spi_master *spi_busnum_to_master(u16 busnum);
* shifting out three bytes with word size of sixteen or twenty bits; * shifting out three bytes with word size of sixteen or twenty bits;
* the former uses two bytes per word, the latter uses four bytes.) * the former uses two bytes per word, the latter uses four bytes.)
* *
* In-memory data values are always in native CPU byte order, translated
* from the wire byte order (big-endian except with SPI_LSB_FIRST). So
* for example when bits_per_word is sixteen, buffers are 2N bytes long
* and hold N sixteen bit words in CPU byte order.
*
* When the word size of the SPI transfer is not a power-of-two multiple
* of eight bits, those in-memory words include extra bits. In-memory
* words are always seen by protocol drivers as right-justified, so the
* undefined (rx) or unused (tx) bits are always the most significant bits.
*
* All SPI transfers start with the relevant chipselect active. Normally * All SPI transfers start with the relevant chipselect active. Normally
* it stays selected until after the last transfer in a message. Drivers * it stays selected until after the last transfer in a message. Drivers
* can affect the chipselect signal using cs_change: * can affect the chipselect signal using cs_change:
...@@ -462,6 +473,11 @@ static inline void spi_message_free(struct spi_message *m) ...@@ -462,6 +473,11 @@ static inline void spi_message_free(struct spi_message *m)
* changes those settings, and must be called from a context that can sleep. * changes those settings, and must be called from a context that can sleep.
* The changes take effect the next time the device is selected and data * The changes take effect the next time the device is selected and data
* is transferred to or from it. * is transferred to or from it.
*
* Note that this call wil fail if the protocol driver specifies an option
* that the underlying controller or its driver does not support. For
* example, not all hardware supports wire transfers using nine bit words,
* LSB-first wire encoding, or active-high chipselects.
*/ */
static inline int static inline int
spi_setup(struct spi_device *spi) spi_setup(struct spi_device *spi)
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment