Merge git://git.kernel.org/pub/scm/linux/kernel/git/sfrench/cifs-2.6

[pandora-kernel.git] / Documentation / gpio.txt

diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt
index e4e7dae..c2c6e9b 100644 (file)
--- a/Documentation/gpio.txt
+++ b/Documentation/gpio.txt
@@ -253,6 +253,70 @@ pin setup (e.g. controlling which pin the GPIO uses, pullup/pulldown).
 Also note that it's your responsibility to have stopped using a GPIO
 before you free it.
 
+Considering in most cases GPIOs are actually configured right after they
+are claimed, three additional calls are defined:
+
+       /* request a single GPIO, with initial configuration specified by
+        * 'flags', identical to gpio_request() wrt other arguments and
+        * return value
+        */
+       int gpio_request_one(unsigned gpio, unsigned long flags, const char *label);
+
+       /* request multiple GPIOs in a single call
+        */
+       int gpio_request_array(struct gpio *array, size_t num);
+
+       /* release multiple GPIOs in a single call
+        */
+       void gpio_free_array(struct gpio *array, size_t num);
+
+where 'flags' is currently defined to specify the following properties:
+
+       * GPIOF_DIR_IN          - to configure direction as input
+       * GPIOF_DIR_OUT         - to configure direction as output
+
+       * GPIOF_INIT_LOW        - as output, set initial level to LOW
+       * GPIOF_INIT_HIGH       - as output, set initial level to HIGH
+
+since GPIOF_INIT_* are only valid when configured as output, so group valid
+combinations as:
+
+       * GPIOF_IN              - configure as input
+       * GPIOF_OUT_INIT_LOW    - configured as output, initial level LOW
+       * GPIOF_OUT_INIT_HIGH   - configured as output, initial level HIGH
+
+In the future, these flags can be extended to support more properties such
+as open-drain status.
+
+Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is
+introduced to encapsulate all three fields as:
+
+       struct gpio {
+               unsigned        gpio;
+               unsigned long   flags;
+               const char      *label;
+       };
+
+A typical example of usage:
+
+       static struct gpio leds_gpios[] = {
+               { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */
+               { 33, GPIOF_OUT_INIT_LOW,  "Green LED" }, /* default to OFF */
+               { 34, GPIOF_OUT_INIT_LOW,  "Red LED"   }, /* default to OFF */
+               { 35, GPIOF_OUT_INIT_LOW,  "Blue LED"  }, /* default to OFF */
+               { ... },
+       };
+
+       err = gpio_request_one(31, GPIOF_IN, "Reset Button");
+       if (err)
+               ...
+
+       err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios));
+       if (err)
+               ...
+
+       gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios));
+
 
 GPIOs mapped to IRQs
 --------------------
@@ -531,6 +595,13 @@ and have the following read/write attributes:
                This file exists only if the pin can be configured as an
                interrupt generating input pin.
 
+       "active_low" ... reads as either 0 (false) or 1 (true).  Write
+               any nonzero value to invert the value attribute both
+               for reading and writing.  Existing and subsequent
+               poll(2) support configuration via the edge attribute
+               for "rising" and "falling" edges will follow this
+               setting.
+
 GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the
 controller implementing GPIOs starting at #42) and have the following
 read-only attributes:
@@ -566,6 +637,8 @@ requested using gpio_request():
        int gpio_export_link(struct device *dev, const char *name,
                unsigned gpio)
 
+       /* change the polarity of a GPIO node in sysfs */
+       int gpio_sysfs_set_active_low(unsigned gpio, int value);
 
 After a kernel driver requests a GPIO, it may only be made available in
 the sysfs interface by gpio_export().  The driver can control whether the
@@ -580,3 +653,9 @@ After the GPIO has been exported, gpio_export_link() allows creating
 symlinks from elsewhere in sysfs to the GPIO sysfs node.  Drivers can
 use this to provide the interface under their own device in sysfs with
 a descriptive name.
+
+Drivers can use gpio_sysfs_set_active_low() to hide GPIO line polarity
+differences between boards from user space.  This only affects the
+sysfs interface.  Polarity change can be done both before and after
+gpio_export(), and previously enabled poll(2) support for either
+rising or falling edge will be reconfigured to follow this setting.