gpio: introduce gpio_request_one() and friends

gpio_request() without initial configuration of the GPIO is normally
useless, introduce gpio_request_one() together with GPIOF_ flags for
input/output direction and initial output level.

gpio_{request,free}_array() for multiple GPIOs.

Signed-off-by: Eric Miao <eric.y.miao@gmail.com>
Cc: David Brownell <dbrownell@users.sourceforge.net>
Cc: Ben Nizette <bn@niasdigital.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

1 files changed, 64 insertions, 0 deletions

diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt
index 1866c27eec69..c2c6e9b39bbe 100644
--- 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
 --------------------