gpio: Add helpers for optional GPIOs

Introduce gpiod_get_optional() and gpiod_get_index_optional() helpers
that make it easier for drivers to handle optional GPIOs.

Currently in order to handle optional GPIOs, a driver needs to special
case error handling for -ENOENT, such as this:

	gpio = gpiod_get(dev, "foo");
	if (IS_ERR(gpio)) {
		if (PTR_ERR(gpio) != -ENOENT)
			return PTR_ERR(gpio);

		gpio = NULL;
	}

	if (gpio) {
		/* set up GPIO */
	}

With these new helpers the above is reduced to:

	gpio = gpiod_get_optional(dev, "foo");
	if (IS_ERR(gpio))
		return PTR_ERR(gpio);

	if (gpio) {
		/* set up GPIO */
	}

While at it, device-managed variants of these functions are also
provided.

Signed-off-by: Thierry Reding <treding@nvidia.com>
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt
index 8ff1167cfedf9562cbb7f5c69588d935e654e034..10b8c5d2c79701e9d33e1f8e31ba1339e056973f 100644 (file)
--- a/Documentation/driver-model/devres.txt
+++ b/Documentation/driver-model/devres.txt
@@ -312,4 +312,6 @@ SPI
 GPIO
   devm_gpiod_get()
   devm_gpiod_get_index()
+  devm_gpiod_get_optional()
+  devm_gpiod_get_index_optional()
   devm_gpiod_put()

diff --git a/drivers/gpio/devres.c b/drivers/gpio/devres.c
index 307464fd015f4ceb6b733095663dd011eb73af3c..65978cf85f791cefbf494b9f2cfc694d9a3929ba 100644 (file)
--- a/drivers/gpio/devres.c
+++ b/drivers/gpio/devres.c
@@ -51,6 +51,22 @@ struct gpio_desc *__must_check devm_gpiod_get(struct device *dev,
 }
 EXPORT_SYMBOL(devm_gpiod_get);
 
+/**
+ * devm_gpiod_get_optional - Resource-managed gpiod_get_optional()
+ * @dev: GPIO consumer
+ * @con_id: function within the GPIO consumer
+ *
+ * Managed gpiod_get_optional(). GPIO descriptors returned from this function
+ * are automatically disposed on driver detach. See gpiod_get_optional() for
+ * detailed information about behavior and return values.
+ */
+struct gpio_desc *__must_check devm_gpiod_get_optional(struct device *dev,
+                                                      const char *con_id)
+{
+       return devm_gpiod_get_index_optional(dev, con_id, 0);
+}
+EXPORT_SYMBOL(devm_gpiod_get_optional);
+
 /**
  * devm_gpiod_get_index - Resource-managed gpiod_get_index()
  * @dev:       GPIO consumer
@@ -86,6 +102,33 @@ struct gpio_desc *__must_check devm_gpiod_get_index(struct device *dev,
 }
 EXPORT_SYMBOL(devm_gpiod_get_index);
 
+/**
+ * devm_gpiod_get_index_optional - Resource-managed gpiod_get_index_optional()
+ * @dev: GPIO consumer
+ * @con_id: function within the GPIO consumer
+ * @index: index of the GPIO to obtain in the consumer
+ *
+ * Managed gpiod_get_index_optional(). GPIO descriptors returned from this
+ * function are automatically disposed on driver detach. See
+ * gpiod_get_index_optional() for detailed information about behavior and
+ * return values.
+ */
+struct gpio_desc *__must_check devm_gpiod_get_index_optional(struct device *dev,
+                                                            const char *con_id,
+                                                            unsigned int index)
+{
+       struct gpio_desc *desc;
+
+       desc = devm_gpiod_get_index(dev, con_id, index);
+       if (IS_ERR(desc)) {
+               if (PTR_ERR(desc) == -ENOENT)
+                       return NULL;
+       }
+
+       return desc;
+}
+EXPORT_SYMBOL(devm_gpiod_get_index_optional);
+
 /**
  * devm_gpiod_put - Resource-managed gpiod_put()
  * @desc:      GPIO descriptor to dispose of

diff --git a/drivers/gpio/gpiolib.c b/drivers/gpio/gpiolib.c
index 4ad110e793c5153e6c63775c96e3f632f99ace94..d9c9cb4665dbf8899d3fe5b7ce9269b3fdee5961 100644 (file)
--- a/drivers/gpio/gpiolib.c
+++ b/drivers/gpio/gpiolib.c
@@ -2737,6 +2737,22 @@ struct gpio_desc *__must_check gpiod_get(struct device *dev, const char *con_id)
 }
 EXPORT_SYMBOL_GPL(gpiod_get);
 
+/**
+ * gpiod_get_optional - obtain an optional GPIO for a given GPIO function
+ * @dev: GPIO consumer, can be NULL for system-global GPIOs
+ * @con_id: function within the GPIO consumer
+ *
+ * This is equivalent to gpiod_get(), except that when no GPIO was assigned to
+ * the requested function it will return NULL. This is convenient for drivers
+ * that need to handle optional GPIOs.
+ */
+struct gpio_desc *__must_check gpiod_get_optional(struct device *dev,
+                                                 const char *con_id)
+{
+       return gpiod_get_index_optional(dev, con_id, 0);
+}
+EXPORT_SYMBOL_GPL(gpiod_get_optional);
+
 /**
  * gpiod_get_index - obtain a GPIO from a multi-index GPIO function
  * @dev:       GPIO consumer, can be NULL for system-global GPIOs
@@ -2799,6 +2815,33 @@ struct gpio_desc *__must_check gpiod_get_index(struct device *dev,
 }
 EXPORT_SYMBOL_GPL(gpiod_get_index);
 
+/**
+ * gpiod_get_index_optional - obtain an optional GPIO from a multi-index GPIO
+ *                            function
+ * @dev: GPIO consumer, can be NULL for system-global GPIOs
+ * @con_id: function within the GPIO consumer
+ * @index: index of the GPIO to obtain in the consumer
+ *
+ * This is equivalent to gpiod_get_index(), except that when no GPIO with the
+ * specified index was assigned to the requested function it will return NULL.
+ * This is convenient for drivers that need to handle optional GPIOs.
+ */
+struct gpio_desc *__must_check gpiod_get_index_optional(struct device *dev,
+                                                       const char *con_id,
+                                                       unsigned int index)
+{
+       struct gpio_desc *desc;
+
+       desc = gpiod_get_index(dev, con_id, index);
+       if (IS_ERR(desc)) {
+               if (PTR_ERR(desc) == -ENOENT)
+                       return NULL;
+       }
+
+       return desc;
+}
+EXPORT_SYMBOL_GPL(gpiod_get_index_optional);
+
 /**
  * gpiod_put - dispose of a GPIO descriptor
  * @desc:      GPIO descriptor to dispose of

diff --git a/include/linux/gpio/consumer.h b/include/linux/gpio/consumer.h
index bed128e8f4b10c318ff6439933b04dc0845660f9..6a37ef0dc59cb1da029621a216de795b98963556 100644 (file)
--- a/include/linux/gpio/consumer.h
+++ b/include/linux/gpio/consumer.h
@@ -23,6 +23,12 @@ struct gpio_desc *__must_check gpiod_get(struct device *dev,
 struct gpio_desc *__must_check gpiod_get_index(struct device *dev,
                                               const char *con_id,
                                               unsigned int idx);
+struct gpio_desc *__must_check gpiod_get_optional(struct device *dev,
+                                                 const char *con_id);
+struct gpio_desc *__must_check gpiod_get_index_optional(struct device *dev,
+                                                       const char *con_id,
+                                                       unsigned int index);
+
 void gpiod_put(struct gpio_desc *desc);
 
 struct gpio_desc *__must_check devm_gpiod_get(struct device *dev,
@@ -30,6 +36,12 @@ struct gpio_desc *__must_check devm_gpiod_get(struct device *dev,
 struct gpio_desc *__must_check devm_gpiod_get_index(struct device *dev,
                                                    const char *con_id,
                                                    unsigned int idx);
+struct gpio_desc *__must_check devm_gpiod_get_optional(struct device *dev,
+                                                      const char *con_id);
+struct gpio_desc *__must_check
+devm_gpiod_get_index_optional(struct device *dev, const char *con_id,
+                             unsigned int index);
+
 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc);
 
 int gpiod_get_direction(const struct gpio_desc *desc);
@@ -73,6 +85,20 @@ static inline struct gpio_desc *__must_check gpiod_get_index(struct device *dev,
 {
        return ERR_PTR(-ENOSYS);
 }
+
+static inline struct gpio_desc *__must_check
+gpiod_get_optional(struct device *dev, const char *con_id)
+{
+       return ERR_PTR(-ENOSYS);
+}
+
+static inline struct gpio_desc *__must_check
+gpiod_get_index_optional(struct device *dev, const char *con_id,
+                        unsigned int index)
+{
+       return ERR_PTR(-ENOSYS);
+}
+
 static inline void gpiod_put(struct gpio_desc *desc)
 {
        might_sleep();
@@ -93,6 +119,20 @@ struct gpio_desc *__must_check devm_gpiod_get_index(struct device *dev,
 {
        return ERR_PTR(-ENOSYS);
 }
+
+static inline struct gpio_desc *__must_check
+devm_gpiod_get_optional(struct device *dev, const char *con_id)
+{
+       return ERR_PTR(-ENOSYS);
+}
+
+static inline struct gpio_desc *__must_check
+devm_gpiod_get_index_optional(struct device *dev, const char *con_id,
+                             unsigned int index)
+{
+       return ERR_PTR(-ENOSYS);
+}
+
 static inline void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
 {
        might_sleep();