Commit:     802245611adea5e5877d8c5d9a20f94d8131bfdd
Parent:     0ffa0285052607513a29f529ddb5061c907fd8a6
Author:     David Brownell <[EMAIL PROTECTED]>
AuthorDate: Mon Feb 12 00:52:46 2007 -0800
Committer:  Linus Torvalds <[EMAIL PROTECTED]>
CommitDate: Mon Feb 12 09:48:31 2007 -0800

    [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: David Brownell <[EMAIL PROTECTED]>
    Signed-off-by: Andrew Morton <[EMAIL PROTECTED]>
    Signed-off-by: Linus Torvalds <[EMAIL PROTECTED]>
 include/linux/spi/spi.h |   18 +++++++++++++++++-
 1 files changed, 17 insertions(+), 1 deletions(-)

diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h
index 9d8d631..4f0f8c2 100644
--- a/include/linux/spi/spi.h
+++ b/include/linux/spi/spi.h
@@ -163,7 +163,8 @@ static inline void spi_unregister_driver(struct spi_driver 
  *     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)
To unsubscribe from this list: send the line "unsubscribe git-commits-head" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at

Reply via email to