drivers/gpio/devres.c

   1 /*
   2  * drivers/gpio/devres.c - managed gpio resources
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License version 2
   6  * as published by the Free Software Foundation.
   7  *
   8  * You should have received a copy of the GNU General Public License
   9  * along with this program; if not, write to the Free Software
  10  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  11  *
  12  * This file is based on kernel/irq/devres.c
  13  *
  14  * Copyright (c) 2011 John Crispin <john@phrozen.org>
  15  */
  16
  17 #include <linux/module.h>
  18 #include <linux/err.h>
  19 #include <linux/gpio.h>
  20 #include <linux/gpio/consumer.h>
  21 #include <linux/device.h>
  22 #include <linux/gfp.h>
  23
  24 #include "gpiolib.h"
  25
  26 static void devm_gpiod_release(struct device *dev, void *res)
  27 {
  28         struct gpio_desc **desc = res;
  29
  30         gpiod_put(*desc);
  31 }
  32
  33 static int devm_gpiod_match(struct device *dev, void *res, void *data)
  34 {
  35         struct gpio_desc **this = res, **gpio = data;
  36
  37         return *this == *gpio;
  38 }
  39
  40 static void devm_gpiod_release_array(struct device *dev, void *res)
  41 {
  42         struct gpio_descs **descs = res;
  43
  44         gpiod_put_array(*descs);
  45 }
  46
  47 static int devm_gpiod_match_array(struct device *dev, void *res, void *data)
  48 {
  49         struct gpio_descs **this = res, **gpios = data;
  50
  51         return *this == *gpios;
  52 }
  53
  54 /**
  55  * devm_gpiod_get - Resource-managed gpiod_get()
  56  * @dev:        GPIO consumer
  57  * @con_id:     function within the GPIO consumer
  58  * @flags:      optional GPIO initialization flags
  59  *
  60  * Managed gpiod_get(). GPIO descriptors returned from this function are
  61  * automatically disposed on driver detach. See gpiod_get() for detailed
  62  * information about behavior and return values.
  63  */
  64 struct gpio_desc *__must_check devm_gpiod_get(struct device *dev,
  65                                               const char *con_id,
  66                                               enum gpiod_flags flags)
  67 {
  68         return devm_gpiod_get_index(dev, con_id, 0, flags);
  69 }
  70 EXPORT_SYMBOL(devm_gpiod_get);
  71
  72 /**
  73  * devm_gpiod_get_optional - Resource-managed gpiod_get_optional()
  74  * @dev: GPIO consumer
  75  * @con_id: function within the GPIO consumer
  76  * @flags: optional GPIO initialization flags
  77  *
  78  * Managed gpiod_get_optional(). GPIO descriptors returned from this function
  79  * are automatically disposed on driver detach. See gpiod_get_optional() for
  80  * detailed information about behavior and return values.
  81  */
  82 struct gpio_desc *__must_check devm_gpiod_get_optional(struct device *dev,
  83                                                        const char *con_id,
  84                                                        enum gpiod_flags flags)
  85 {
  86         return devm_gpiod_get_index_optional(dev, con_id, 0, flags);
  87 }
  88 EXPORT_SYMBOL(devm_gpiod_get_optional);
  89
  90 /**
  91  * devm_gpiod_get_index - Resource-managed gpiod_get_index()
  92  * @dev:        GPIO consumer
  93  * @con_id:     function within the GPIO consumer
  94  * @idx:        index of the GPIO to obtain in the consumer
  95  * @flags:      optional GPIO initialization flags
  96  *
  97  * Managed gpiod_get_index(). GPIO descriptors returned from this function are
  98  * automatically disposed on driver detach. See gpiod_get_index() for detailed
  99  * information about behavior and return values.
 100  */
 101 struct gpio_desc *__must_check devm_gpiod_get_index(struct device *dev,
 102                                                     const char *con_id,
 103                                                     unsigned int idx,
 104                                                     enum gpiod_flags flags)
 105 {
 106         struct gpio_desc **dr;
 107         struct gpio_desc *desc;
 108
 109         dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *),
 110                           GFP_KERNEL);
 111         if (!dr)
 112                 return ERR_PTR(-ENOMEM);
 113
 114         desc = gpiod_get_index(dev, con_id, idx, flags);
 115         if (IS_ERR(desc)) {
 116                 devres_free(dr);
 117                 return desc;
 118         }
 119
 120         *dr = desc;
 121         devres_add(dev, dr);
 122
 123         return desc;
 124 }
 125 EXPORT_SYMBOL(devm_gpiod_get_index);
 126
 127 /**
 128  * devm_gpiod_get_from_of_node() - obtain a GPIO from an OF node
 129  * @dev:        device for lifecycle management
 130  * @node:       handle of the OF node
 131  * @propname:   name of the DT property representing the GPIO
 132  * @index:      index of the GPIO to obtain for the consumer
 133  * @dflags:     GPIO initialization flags
 134  * @label:      label to attach to the requested GPIO
 135  *
 136  * Returns:
 137  * On successful request the GPIO pin is configured in accordance with
 138  * provided @dflags.
 139  *
 140  * In case of error an ERR_PTR() is returned.
 141  */
 142 struct gpio_desc *devm_gpiod_get_from_of_node(struct device *dev,
 143                                               struct device_node *node,
 144                                               const char *propname, int index,
 145                                               enum gpiod_flags dflags,
 146                                               const char *label)
 147 {
 148         struct gpio_desc **dr;
 149         struct gpio_desc *desc;
 150
 151         dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *),
 152                           GFP_KERNEL);
 153         if (!dr)
 154                 return ERR_PTR(-ENOMEM);
 155
 156         desc = gpiod_get_from_of_node(node, propname, index, dflags, label);
 157         if (IS_ERR(desc)) {
 158                 devres_free(dr);
 159                 return desc;
 160         }
 161
 162         *dr = desc;
 163         devres_add(dev, dr);
 164
 165         return desc;
 166 }
 167 EXPORT_SYMBOL(devm_gpiod_get_from_of_node);
 168
 169 /**
 170  * devm_fwnode_get_index_gpiod_from_child - get a GPIO descriptor from a
 171  *                                          device's child node
 172  * @dev:        GPIO consumer
 173  * @con_id:     function within the GPIO consumer
 174  * @index:      index of the GPIO to obtain in the consumer
 175  * @child:      firmware node (child of @dev)
 176  * @flags:      GPIO initialization flags
 177  * @label:      label to attach to the requested GPIO
 178  *
 179  * GPIO descriptors returned from this function are automatically disposed on
 180  * driver detach.
 181  *
 182  * On successful request the GPIO pin is configured in accordance with
 183  * provided @flags.
 184  */
 185 struct gpio_desc *devm_fwnode_get_index_gpiod_from_child(struct device *dev,
 186                                                 const char *con_id, int index,
 187                                                 struct fwnode_handle *child,
 188                                                 enum gpiod_flags flags,
 189                                                 const char *label)
 190 {
 191         char prop_name[32]; /* 32 is max size of property name */
 192         struct gpio_desc **dr;
 193         struct gpio_desc *desc;
 194         unsigned int i;
 195
 196         dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *),
 197                           GFP_KERNEL);
 198         if (!dr)
 199                 return ERR_PTR(-ENOMEM);
 200
 201         for (i = 0; i < ARRAY_SIZE(gpio_suffixes); i++) {
 202                 if (con_id)
 203                         snprintf(prop_name, sizeof(prop_name), "%s-%s",
 204                                             con_id, gpio_suffixes[i]);
 205                 else
 206                         snprintf(prop_name, sizeof(prop_name), "%s",
 207                                             gpio_suffixes[i]);
 208
 209                 desc = fwnode_get_named_gpiod(child, prop_name, index, flags,
 210                                               label);
 211                 if (!IS_ERR(desc) || (PTR_ERR(desc) != -ENOENT))
 212                         break;
 213         }
 214         if (IS_ERR(desc)) {
 215                 devres_free(dr);
 216                 return desc;
 217         }
 218
 219         *dr = desc;
 220         devres_add(dev, dr);
 221
 222         return desc;
 223 }
 224 EXPORT_SYMBOL(devm_fwnode_get_index_gpiod_from_child);
 225
 226 /**
 227  * devm_gpiod_get_index_optional - Resource-managed gpiod_get_index_optional()
 228  * @dev: GPIO consumer
 229  * @con_id: function within the GPIO consumer
 230  * @index: index of the GPIO to obtain in the consumer
 231  * @flags: optional GPIO initialization flags
 232  *
 233  * Managed gpiod_get_index_optional(). GPIO descriptors returned from this
 234  * function are automatically disposed on driver detach. See
 235  * gpiod_get_index_optional() for detailed information about behavior and
 236  * return values.
 237  */
 238 struct gpio_desc *__must_check devm_gpiod_get_index_optional(struct device *dev,
 239                                                              const char *con_id,
 240                                                              unsigned int index,
 241                                                              enum gpiod_flags flags)
 242 {
 243         struct gpio_desc *desc;
 244
 245         desc = devm_gpiod_get_index(dev, con_id, index, flags);
 246         if (IS_ERR(desc)) {
 247                 if (PTR_ERR(desc) == -ENOENT)
 248                         return NULL;
 249         }
 250
 251         return desc;
 252 }
 253 EXPORT_SYMBOL(devm_gpiod_get_index_optional);
 254
 255 /**
 256  * devm_gpiod_get_array - Resource-managed gpiod_get_array()
 257  * @dev:        GPIO consumer
 258  * @con_id:     function within the GPIO consumer
 259  * @flags:      optional GPIO initialization flags
 260  *
 261  * Managed gpiod_get_array(). GPIO descriptors returned from this function are
 262  * automatically disposed on driver detach. See gpiod_get_array() for detailed
 263  * information about behavior and return values.
 264  */
 265 struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev,
 266                                                      const char *con_id,
 267                                                      enum gpiod_flags flags)
 268 {
 269         struct gpio_descs **dr;
 270         struct gpio_descs *descs;
 271
 272         dr = devres_alloc(devm_gpiod_release_array,
 273                           sizeof(struct gpio_descs *), GFP_KERNEL);
 274         if (!dr)
 275                 return ERR_PTR(-ENOMEM);
 276
 277         descs = gpiod_get_array(dev, con_id, flags);
 278         if (IS_ERR(descs)) {
 279                 devres_free(dr);
 280                 return descs;
 281         }
 282
 283         *dr = descs;
 284         devres_add(dev, dr);
 285
 286         return descs;
 287 }
 288 EXPORT_SYMBOL(devm_gpiod_get_array);
 289
 290 /**
 291  * devm_gpiod_get_array_optional - Resource-managed gpiod_get_array_optional()
 292  * @dev:        GPIO consumer
 293  * @con_id:     function within the GPIO consumer
 294  * @flags:      optional GPIO initialization flags
 295  *
 296  * Managed gpiod_get_array_optional(). GPIO descriptors returned from this
 297  * function are automatically disposed on driver detach.
 298  * See gpiod_get_array_optional() for detailed information about behavior and
 299  * return values.
 300  */
 301 struct gpio_descs *__must_check
 302 devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
 303                               enum gpiod_flags flags)
 304 {
 305         struct gpio_descs *descs;
 306
 307         descs = devm_gpiod_get_array(dev, con_id, flags);
 308         if (IS_ERR(descs) && (PTR_ERR(descs) == -ENOENT))
 309                 return NULL;
 310
 311         return descs;
 312 }
 313 EXPORT_SYMBOL(devm_gpiod_get_array_optional);
 314
 315 /**
 316  * devm_gpiod_put - Resource-managed gpiod_put()
 317  * @dev:        GPIO consumer
 318  * @desc:       GPIO descriptor to dispose of
 319  *
 320  * Dispose of a GPIO descriptor obtained with devm_gpiod_get() or
 321  * devm_gpiod_get_index(). Normally this function will not be called as the GPIO
 322  * will be disposed of by the resource management code.
 323  */
 324 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
 325 {
 326         WARN_ON(devres_release(dev, devm_gpiod_release, devm_gpiod_match,
 327                 &desc));
 328 }
 329 EXPORT_SYMBOL(devm_gpiod_put);
 330
 331 /**
 332  * devm_gpiod_put_array - Resource-managed gpiod_put_array()
 333  * @dev:        GPIO consumer
 334  * @descs:      GPIO descriptor array to dispose of
 335  *
 336  * Dispose of an array of GPIO descriptors obtained with devm_gpiod_get_array().
 337  * Normally this function will not be called as the GPIOs will be disposed of
 338  * by the resource management code.
 339  */
 340 void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs)
 341 {
 342         WARN_ON(devres_release(dev, devm_gpiod_release_array,
 343                                devm_gpiod_match_array, &descs));
 344 }
 345 EXPORT_SYMBOL(devm_gpiod_put_array);
 346
 347
 348
 349
 350 static void devm_gpio_release(struct device *dev, void *res)
 351 {
 352         unsigned *gpio = res;
 353
 354         gpio_free(*gpio);
 355 }
 356
 357 static int devm_gpio_match(struct device *dev, void *res, void *data)
 358 {
 359         unsigned *this = res, *gpio = data;
 360
 361         return *this == *gpio;
 362 }
 363
 364 /**
 365  *      devm_gpio_request - request a GPIO for a managed device
 366  *      @dev: device to request the GPIO for
 367  *      @gpio: GPIO to allocate
 368  *      @label: the name of the requested GPIO
 369  *
 370  *      Except for the extra @dev argument, this function takes the
 371  *      same arguments and performs the same function as
 372  *      gpio_request().  GPIOs requested with this function will be
 373  *      automatically freed on driver detach.
 374  *
 375  *      If an GPIO allocated with this function needs to be freed
 376  *      separately, devm_gpio_free() must be used.
 377  */
 378
 379 int devm_gpio_request(struct device *dev, unsigned gpio, const char *label)
 380 {
 381         unsigned *dr;
 382         int rc;
 383
 384         dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL);
 385         if (!dr)
 386                 return -ENOMEM;
 387
 388         rc = gpio_request(gpio, label);
 389         if (rc) {
 390                 devres_free(dr);
 391                 return rc;
 392         }
 393
 394         *dr = gpio;
 395         devres_add(dev, dr);
 396
 397         return 0;
 398 }
 399 EXPORT_SYMBOL(devm_gpio_request);
 400
 401 /**
 402  *      devm_gpio_request_one - request a single GPIO with initial setup
 403  *      @dev:   device to request for
 404  *      @gpio:  the GPIO number
 405  *      @flags: GPIO configuration as specified by GPIOF_*
 406  *      @label: a literal description string of this GPIO
 407  */
 408 int devm_gpio_request_one(struct device *dev, unsigned gpio,
 409                           unsigned long flags, const char *label)
 410 {
 411         unsigned *dr;
 412         int rc;
 413
 414         dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL);
 415         if (!dr)
 416                 return -ENOMEM;
 417
 418         rc = gpio_request_one(gpio, flags, label);
 419         if (rc) {
 420                 devres_free(dr);
 421                 return rc;
 422         }
 423
 424         *dr = gpio;
 425         devres_add(dev, dr);
 426
 427         return 0;
 428 }
 429 EXPORT_SYMBOL(devm_gpio_request_one);
 430
 431 /**
 432  *      devm_gpio_free - free a GPIO
 433  *      @dev: device to free GPIO for
 434  *      @gpio: GPIO to free
 435  *
 436  *      Except for the extra @dev argument, this function takes the
 437  *      same arguments and performs the same function as gpio_free().
 438  *      This function instead of gpio_free() should be used to manually
 439  *      free GPIOs allocated with devm_gpio_request().
 440  */
 441 void devm_gpio_free(struct device *dev, unsigned int gpio)
 442 {
 443
 444         WARN_ON(devres_release(dev, devm_gpio_release, devm_gpio_match,
 445                 &gpio));
 446 }
 447 EXPORT_SYMBOL(devm_gpio_free);