gpiolib: add gpiod_get_array and gpiod_put_array functions

Introduce new functions for conveniently obtaining and disposing of
an entire array of GPIOs with one function call.

ACPI parts tested by Mika Westerberg, DT parts tested by Rojhalat
Ibrahim.

Change log:
v5: move the ACPI functions to gpiolib-acpi.c
v4: - use shorter names for members of struct gpio_descs
    - rename lut_gpio_count to platform_gpio_count for clarity
    - add check for successful memory allocation
    - use ERR_CAST()
v3: - rebase on current linux-gpio devel branch
    - fix ACPI GPIO counting
    - allow for zero-sized arrays
    - make the flags argument mandatory for the new functions
    - clarify documentation
v2: change interface

Suggested-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Rojhalat Ibrahim <imr@rtschenk.de>
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Reviewed-by: Mika Westerberg <mika.westerberg@linux.intel.com>
Tested-by: Mika Westerberg <mika.westerberg@linux.intel.com>
Tested-by: Rojhalat Ibrahim <imr@rtschenk.de>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

1 files changed, 30 insertions, 3 deletions

diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt
index d85fbae451ea..2924f2ffcd91 100644
--- a/Documentation/gpio/consumer.txt
+++ b/Documentation/gpio/consumer.txt
@@ -58,7 +58,6 @@ pattern where a GPIO is optional, the gpiod_get_optional() and
 gpiod_get_index_optional() functions can be used. These functions return NULL
 instead of -ENOENT if no GPIO has been assigned to the requested function:
 
-
         struct gpio_desc *gpiod_get_optional(struct device *dev,
                                              const char *con_id,
                                              enum gpiod_flags flags)
@@ -68,6 +67,27 @@ instead of -ENOENT if no GPIO has been assigned to the requested function:
                                                    unsigned int index,
                                                    enum gpiod_flags flags)
 
+For a function using multiple GPIOs all of those can be obtained with one call:
+
+        struct gpio_descs *gpiod_get_array(struct device *dev,
+                                           const char *con_id,
+                                           enum gpiod_flags flags)
+
+This function returns a struct gpio_descs which contains an array of
+descriptors:
+
+        struct gpio_descs {
+                unsigned int ndescs;
+                struct gpio_desc *desc[];
+        }
+
+The following function returns NULL instead of -ENOENT if no GPIOs have been
+assigned to the requested function:
+
+        struct gpio_descs *gpiod_get_array_optional(struct device *dev,
+                                                    const char *con_id,
+                                                    enum gpiod_flags flags)
+
 Device-managed variants of these functions are also defined:
 
         struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id,
@@ -91,8 +111,15 @@ A GPIO descriptor can be disposed of using the gpiod_put() function:
 
         void gpiod_put(struct gpio_desc *desc)
 
-It is strictly forbidden to use a descriptor after calling this function. The
-device-managed variant is, unsurprisingly:
+For an array of GPIOs this function can be used:
+
+        void gpiod_put_array(struct gpio_descs *descs)
+
+It is strictly forbidden to use a descriptor after calling these functions.
+It is also not allowed to individually release descriptors (using gpiod_put())
+from an array acquired with gpiod_get_array().
+
+The device-managed variant is, unsurprisingly:
 
         void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)