[PATCH] doc: gpio.txt describes open-drain emulation

Update the GPIO docs to describe the idiom whereby open drain signals are emulated by toggling the GPIO direction. 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>

[PATCH] doc: gpio.txt describes open-drain emulation
Update the GPIO docs to describe the idiom whereby open drain signals are emulated by toggling the GPIO direction. 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 fe20e581a7
Showing 1 changed file with 30 additions and 1 deletions Side-by-side Diff
Documentation/gpio.txt
@@ -27,7 +27,7 @@
   - Output values are writable (high=1, low=0).  Some chips also have
     options about how that value is driven, so that for example only one
     value might be driven ... supporting "wire-OR" and similar schemes
-    for the other value.
+    for the other value (notably, "open drain" signaling).
  
   - Input values are likewise readable (1, 0).  Some chips support readback
     of pins configured as "output", which is very useful in such "wire-OR"
@@ -246,6 +246,35 @@
 with gpio_get_value(), for example to initialize or update driver state
 when the IRQ is edge-triggered.
  
+
+Emulating Open Drain Signals
+----------------------------
+Sometimes shared signals need to use "open drain" signaling, where only the
+low signal level is actually driven.  (That term applies to CMOS transistors;
+"open collector" is used for TTL.)  A pullup resistor causes the high signal
+level.  This is sometimes called a "wire-AND"; or more practically, from the
+negative logic (low=true) perspective this is a "wire-OR".
+
+One common example of an open drain signal is a shared active-low IRQ line.
+Also, bidirectional data bus signals sometimes use open drain signals.
+
+Some GPIO controllers directly support open drain outputs; many don't.  When
+you need open drain signaling but your hardware doesn't directly support it,
+there's a common idiom you can use to emulate it with any GPIO pin that can
+be used as either an input or an output:
+
+ LOW:	gpio_direction_output(gpio, 0) ... this drives the signal
+	and overrides the pullup.
+
+ HIGH:	gpio_direction_input(gpio) ... this turns off the output,
+	so the pullup (or some other device) controls the signal.
+
+If you are "driving" the signal high but gpio_get_value(gpio) reports a low
+value (after the appropriate rise time passes), you know some other component
+is driving the shared signal low.  That's not necessarily an error.  As one
+common example, that's how I2C clocks are stretched:  a slave that needs a
+slower clock delays the rising edge of SCK, and the I2C master adjusts its
+signaling rate accordingly.
  
  
 What do these conventions omit?
...	...	@@ -27,7 +27,7 @@
27	27	- Output values are writable (high=1, low=0). Some chips also have
28	28	options about how that value is driven, so that for example only one
29	29	value might be driven ... supporting "wire-OR" and similar schemes
30		- for the other value.
	30	+ for the other value (notably, "open drain" signaling).
31	31
32	32	- Input values are likewise readable (1, 0). Some chips support readback
33	33	of pins configured as "output", which is very useful in such "wire-OR"
...	...	@@ -246,6 +246,35 @@
246	246	with gpio_get_value(), for example to initialize or update driver state
247	247	when the IRQ is edge-triggered.
248	248
	249	+
	250	+Emulating Open Drain Signals
	251	+----------------------------
	252	+Sometimes shared signals need to use "open drain" signaling, where only the
	253	+low signal level is actually driven. (That term applies to CMOS transistors;
	254	+"open collector" is used for TTL.) A pullup resistor causes the high signal
	255	+level. This is sometimes called a "wire-AND"; or more practically, from the
	256	+negative logic (low=true) perspective this is a "wire-OR".
	257	+
	258	+One common example of an open drain signal is a shared active-low IRQ line.
	259	+Also, bidirectional data bus signals sometimes use open drain signals.
	260	+
	261	+Some GPIO controllers directly support open drain outputs; many don't. When
	262	+you need open drain signaling but your hardware doesn't directly support it,
	263	+there's a common idiom you can use to emulate it with any GPIO pin that can
	264	+be used as either an input or an output:
	265	+
	266	+ LOW: gpio_direction_output(gpio, 0) ... this drives the signal
	267	+ and overrides the pullup.
	268	+
	269	+ HIGH: gpio_direction_input(gpio) ... this turns off the output,
	270	+ so the pullup (or some other device) controls the signal.
	271	+
	272	+If you are "driving" the signal high but gpio_get_value(gpio) reports a low
	273	+value (after the appropriate rise time passes), you know some other component
	274	+is driving the shared signal low. That's not necessarily an error. As one
	275	+common example, that's how I2C clocks are stretched: a slave that needs a
	276	+slower clock delays the rising edge of SCK, and the I2C master adjusts its
	277	+signaling rate accordingly.
249	278
250	279
251	280	What do these conventions omit?