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>

1 files changed, 6 insertions, 1 deletions

diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h
index 2cc43fa380cb..a0faa18f7b1b 100644
--- 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