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

spi doc updates 



Update two points in the SPI interface documentation:

- Update description of the "chip stays selected after message ends"
  mode.  In some cases it's required for correctness; it isn't just a
  performance tweak.  (Yes: to use this mode on mult-device busses, another
  programming interface will be needed.  One draft has been circulated
  already.)

- Clarify spi_setup(), highlighting that callers must ensure that no
  requests are queued (can't change configuration except between I/Os), and
  that the device must be deselected when this returns (which is a key part
  of why it's called during device init).

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 ed456662

include/linux/spi/spi.h

+13 −7
Original line number Diff line number Diff line
@@ -341,9 +341,14 @@ extern struct spi_master *spi_busnum_to_master(u16 busnum); 
 * chip transactions together.

 *

 * (ii) When the transfer is the last one in the message, the chip may

 * stay selected until the next transfer.  This is purely a performance

 * hint; the controller driver may need to select a different device

 * for the next message.

 * stay selected until the next transfer.  On multi-device SPI busses

 * with nothing blocking messages going to other devices, this is just

 * a performance hint; starting a message to another device deselects

 * this one.  But in other cases, this can be used to ensure correctness.

 * Some devices need protocol transactions to be built from a series of

 * spi_message submissions, where the content of one message is determined

 * by the results of previous messages and where the whole transaction

 * ends when the chipselect goes intactive.

 *

 * The code that submits an spi_message (and its spi_transfers)

 * to the lower layers is responsible for managing its memory.
@@ -480,14 +485,15 @@ static inline void spi_message_free(struct spi_message *m) 
/**

 * spi_setup - setup SPI mode and clock rate

 * @spi: the device whose settings are being modified

 * Context: can sleep

 * Context: can sleep, and no requests are queued to the device

 *

 * SPI protocol drivers may need to update the transfer mode if the

 * device doesn't work with the mode 0 default.  They may likewise need

 * device doesn't work with its default.  They may likewise need

 * to update clock rates or word sizes from initial values.  This function

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

 * Except for SPI_CS_HIGH, which takes effect immediately, the changes take

 * effect the next time the device is selected and data is transferred to

 * or from it.  When this function returns, the spi device is deselected.

 *

 * Note that this call will fail if the protocol driver specifies an option

 * that the underlying controller or its driver does not support.  For

CRA Git | Maintained and supported by SUSTech CRA and CCSE