Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

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

[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

include/linux/spi/spi.h

+17 −1
Original line number Diff line number Diff line
@@ -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

 *	every chipselect is connected to a slave.

 * @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.

 * @cleanup: frees controller-specific state

 *
@@ -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;

 * 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

 * it stays selected until after the last transfer in a message.  Drivers

 * can affect the chipselect signal using cs_change:
@@ -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.

 * The changes take effect the next time the device is selected and data

 * 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

spi_setup(struct spi_device *spi)