Commit 6e538aaf authored by David Brownell's avatar David Brownell Committed by Linus Torvalds

spi: documentation: emphasise spi_master.setup() semantics

This is a doc-only patch which I hope will reduce the number of
spi_master controller driver patches starting out with a common
implementation bug.

(As in: almost every spi_master driver I see starts out with its
version of this bug.  Sigh.)

It just re-emphasizes that the setup() method may be called for one
device while a transfer is active on another ...  which means that most
driver implementations shouldn't touch any registers.
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 14fadca7
...@@ -511,10 +511,16 @@ SPI MASTER METHODS ...@@ -511,10 +511,16 @@ SPI MASTER METHODS
This sets up the device clock rate, SPI mode, and word sizes. This sets up the device clock rate, SPI mode, and word sizes.
Drivers may change the defaults provided by board_info, and then Drivers may change the defaults provided by board_info, and then
call spi_setup(spi) to invoke this routine. It may sleep. call spi_setup(spi) to invoke this routine. It may sleep.
Unless each SPI slave has its own configuration registers, don't Unless each SPI slave has its own configuration registers, don't
change them right away ... otherwise drivers could corrupt I/O change them right away ... otherwise drivers could corrupt I/O
that's in progress for other SPI devices. that's in progress for other SPI devices.
** BUG ALERT: for some reason the first version of
** many spi_master drivers seems to get this wrong.
** When you code setup(), ASSUME that the controller
** is actively processing transfers for another device.
master->transfer(struct spi_device *spi, struct spi_message *message) master->transfer(struct spi_device *spi, struct spi_message *message)
This must not sleep. Its responsibility is arrange that the This must not sleep. Its responsibility is arrange that the
transfer happens and its complete() callback is issued. The two transfer happens and its complete() callback is issued. The two
......
...@@ -245,7 +245,12 @@ struct spi_master { ...@@ -245,7 +245,12 @@ struct spi_master {
*/ */
u16 dma_alignment; u16 dma_alignment;
/* setup mode and clock, etc (spi driver may call many times) */ /* Setup mode and clock, etc (spi driver may call many times).
*
* IMPORTANT: this may be called when transfers to another
* device are active. DO NOT UPDATE SHARED REGISTERS in ways
* which could break those transfers.
*/
int (*setup)(struct spi_device *spi); int (*setup)(struct spi_device *spi);
/* bidirectional bulk transfers /* bidirectional bulk transfers
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment