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

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

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

Documentation/spi/spi-summary

+6 −0
Original line number Diff line number Diff line
@@ -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

include/linux/spi/spi.h

+6 −1
Original line number Diff line number Diff line
@@ -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