From 802245611adea5e5877d8c5d9a20f94d8131bfdd Mon Sep 17 00:00:00 2001 From: David Brownell Date: Mon, 12 Feb 2007 00:52:46 -0800 Subject: [PATCH] [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 Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- include/linux/spi/spi.h | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h index 9d8d63109a8f..4f0f8c2e58a5 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 *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) -- 2.30.2