1 files changed, 34 insertions, 2 deletions

diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt
index 576ce463cf44..f8528db967fa 100644
--- a/Documentation/gpio.txt
+++ b/Documentation/gpio.txt
@@ -27,7 +27,7 @@ The exact capabilities of GPIOs vary between systems.  Common options:
   - 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"
@@ -105,12 +105,15 @@ setting up a platform_device using the GPIO, is mark its direction:
 
         /* set as input or output, returning 0 or negative errno */
         int gpio_direction_input(unsigned gpio);
-        int gpio_direction_output(unsigned gpio);
+        int gpio_direction_output(unsigned gpio, int value);
 
 The return value is zero for success, else a negative errno.  It should
 be checked, since the get/set calls don't have error returns and since
 misconfiguration is possible.  (These calls could sleep.)
 
+For output GPIOs, the value provided becomes the initial output value.
+This helps avoid signal glitching during system startup.
+
 Setting the direction can fail if the GPIO number is invalid, or when
 that particular GPIO can't be used in that mode.  It's generally a bad
 idea to rely on boot firmware to have set the direction correctly, since
@@ -244,6 +247,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?
 ===============================