spi: documentation tweaks

Update SPI documentation to clarify some areas of recent confusion: clock polarity takes effect when chipselect goes active; and zero length buffers are OK in certain cases. 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>

spi: documentation tweaks
Update SPI documentation to clarify some areas of recent confusion: clock polarity takes effect when chipselect goes active; and zero length buffers are OK in certain cases. 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>
David Brownell · Linus Torvalds
1 parent f9e522caec
Showing 1 changed file with 14 additions and 1 deletions Side-by-side Diff
Documentation/spi/spi-summary
@@ -116,7 +116,14 @@
 starting low (CPOL=0) and data stabilized for sampling during the
 trailing clock edge (CPHA=1), that's SPI mode 1.
  
+Note that the clock mode is relevant as soon as the chipselect goes
+active.  So the master must set the clock to inactive before selecting
+a slave, and the slave can tell the chosen polarity by sampling the
+clock level when its select line goes active.  That's why many devices
+support for example both modes 0 and 3:  they don't care about polarity,
+and alway clock data in/out on rising clock edges.
  
+
 How do these driver programming interfaces work?
 ------------------------------------------------
 The <linux/spi/spi.h> header file includes kerneldoc, as does the
  
@@ -379,8 +386,14 @@
       + when bidirectional reads and writes start ... by how its
         sequence of spi_transfer requests is arranged;
  
+      + which I/O buffers are used ... each spi_transfer wraps a
+        buffer for each transfer direction, supporting full duplex
+        (two pointers, maybe the same one in both cases) and half
+        duplex (one pointer is NULL) transfers;
+
       + optionally defining short delays after transfers ... using
-        the spi_transfer.delay_usecs setting;
+        the spi_transfer.delay_usecs setting (this delay can be the
+        only protocol effect, if the buffer length is zero);
  
       + whether the chipselect becomes inactive after a transfer and
         any delay ... by using the spi_transfer.cs_change flag;
...	...	@@ -116,7 +116,14 @@
116	116	starting low (CPOL=0) and data stabilized for sampling during the
117	117	trailing clock edge (CPHA=1), that's SPI mode 1.
118	118
	119	+Note that the clock mode is relevant as soon as the chipselect goes
	120	+active. So the master must set the clock to inactive before selecting
	121	+a slave, and the slave can tell the chosen polarity by sampling the
	122	+clock level when its select line goes active. That's why many devices
	123	+support for example both modes 0 and 3: they don't care about polarity,
	124	+and alway clock data in/out on rising clock edges.
119	125
	126	+
120	127	How do these driver programming interfaces work?
121	128	------------------------------------------------
122	129	The <linux/spi/spi.h> header file includes kerneldoc, as does the
123	130
...	...	@@ -379,8 +386,14 @@
379	386	+ when bidirectional reads and writes start ... by how its
380	387	sequence of spi_transfer requests is arranged;
381	388
	389	+ + which I/O buffers are used ... each spi_transfer wraps a
	390	+ buffer for each transfer direction, supporting full duplex
	391	+ (two pointers, maybe the same one in both cases) and half
	392	+ duplex (one pointer is NULL) transfers;
	393	+
382	394	+ optionally defining short delays after transfers ... using
383		- the spi_transfer.delay_usecs setting;
	395	+ the spi_transfer.delay_usecs setting (this delay can be the
	396	+ only protocol effect, if the buffer length is zero);
384	397
385	398	+ whether the chipselect becomes inactive after a transfer and
386	399	any delay ... by using the spi_transfer.cs_change flag;