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

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