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: David Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary
index 0f5122e..4a02d25 100644 (file)
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary
@@ -511,10 +511,16 @@ SPI MASTER METHODS
        This sets up the device clock rate, SPI mode, and word sizes.
        Drivers may change the defaults provided by board_info, and then
        call spi_setup(spi) to invoke this routine.  It may sleep.
+
        Unless each SPI slave has its own configuration registers, don't
        change them right away ... otherwise drivers could corrupt I/O
        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)
        This must not sleep.  Its responsibility is arrange that the
        transfer happens and its complete() callback is issued.  The two

diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h
index 2cc43fa..a0faa18 100644 (file)
--- a/include/linux/spi/spi.h
+++ b/include/linux/spi/spi.h
@@ -245,7 +245,12 @@ struct spi_master {
         */
        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);
 
        /* bidirectional bulk transfers