- 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"
used for several very different kinds of GPIO controller.
That said, if the convention is supported on their platform, drivers should
-use it when possible:
+use it when possible. Platforms should declare GENERIC_GPIO support in
+Kconfig (boolean true), which multi-platform drivers can depend on when
+using the include file:
#include <asm/gpio.h>
If you stick to this convention then it'll be easier for other developers to
see what your code is doing, and help maintain it.
+Note that these operations include I/O barriers on platforms which need to
+use them; drivers don't need to add them explicitly.
+
Identifying GPIOs
-----------------
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.)
+misconfiguration is possible. You should normally issue these calls from
+a task context. However, for spinlock-safe GPIOs it's OK to use them
+before tasking is enabled, as part of early board setup.
For output GPIOs, the value provided becomes the initial output value.
This helps avoid signal glitching during system startup.
issues including wire-OR and output latencies.
The get/set calls have no error returns because "invalid GPIO" should have
-been reported earlier in gpio_set_direction(). However, note that not all
+been reported earlier from gpio_direction_*(). However, note that not all
platforms can read the value of output pins; those that can't should always
return zero. Also, using these calls for GPIOs that can't safely be accessed
without sleeping (see below) is an error.
Passing invalid GPIO numbers to gpio_request() will fail, as will requesting
GPIOs that have already been claimed with that call. The return value of
-gpio_request() must be checked. (These calls could sleep.)
+gpio_request() must be checked. You should normally issue these calls from
+a task context. However, for spinlock-safe GPIOs it's OK to request GPIOs
+before tasking is enabled, as part of early board setup.
These calls serve two basic purposes. One is marking the signals which
are actually in use as GPIOs, for better diagnostics; systems may have
Those return either the corresponding number in the other namespace, or
else a negative errno code if the mapping can't be done. (For example,
some GPIOs can't used as IRQs.) It is an unchecked error to use a GPIO
-number that hasn't been marked as an input using gpio_set_direction(), or
+number that wasn't set up as an input using gpio_direction_input(), or
to use an IRQ number that didn't originally come from gpio_to_irq().
These two mapping calls are expected to cost on the order of a single
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?
===============================
git.openpandora.org / pandora-kernel.git / blobdiff