drivers/gpio/gpiolib-devres.c

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 /*
   3  * devres.c - managed gpio resources
   4  * This file is based on kernel/irq/devres.c
   5  *
   6  * Copyright (c) 2011 John Crispin <john@phrozen.org>
   7  */
   8
   9 #include <linux/module.h>
  10 #include <linux/err.h>
  11 #include <linux/gpio.h>
  12 #include <linux/gpio/consumer.h>
  13 #include <linux/device.h>
  14 #include <linux/gfp.h>
  15
  16 #include "gpiolib.h"
  17
  18 static void devm_gpiod_release(struct device *dev, void *res)
  19 {
  20         struct gpio_desc **desc = res;
  21
  22         gpiod_put(*desc);
  23 }
  24
  25 static int devm_gpiod_match(struct device *dev, void *res, void *data)
  26 {
  27         struct gpio_desc **this = res, **gpio = data;
  28
  29         return *this == *gpio;
  30 }
  31
  32 static void devm_gpiod_release_array(struct device *dev, void *res)
  33 {
  34         struct gpio_descs **descs = res;
  35
  36         gpiod_put_array(*descs);
  37 }
  38
  39 static int devm_gpiod_match_array(struct device *dev, void *res, void *data)
  40 {
  41         struct gpio_descs **this = res, **gpios = data;
  42
  43         return *this == *gpios;
  44 }
  45
  46 /**
  47  * devm_gpiod_get - Resource-managed gpiod_get()
  48  * @dev:        GPIO consumer
  49  * @con_id:     function within the GPIO consumer
  50  * @flags:      optional GPIO initialization flags
  51  *
  52  * Managed gpiod_get(). GPIO descriptors returned from this function are
  53  * automatically disposed on driver detach. See gpiod_get() for detailed
  54  * information about behavior and return values.
  55  */
  56 struct gpio_desc *__must_check devm_gpiod_get(struct device *dev,
  57                                               const char *con_id,
  58                                               enum gpiod_flags flags)
  59 {
  60         return devm_gpiod_get_index(dev, con_id, 0, flags);
  61 }
  62 EXPORT_SYMBOL_GPL(devm_gpiod_get);
  63
  64 /**
  65  * devm_gpiod_get_optional - Resource-managed gpiod_get_optional()
  66  * @dev: GPIO consumer
  67  * @con_id: function within the GPIO consumer
  68  * @flags: optional GPIO initialization flags
  69  *
  70  * Managed gpiod_get_optional(). GPIO descriptors returned from this function
  71  * are automatically disposed on driver detach. See gpiod_get_optional() for
  72  * detailed information about behavior and return values.
  73  */
  74 struct gpio_desc *__must_check devm_gpiod_get_optional(struct device *dev,
  75                                                        const char *con_id,
  76                                                        enum gpiod_flags flags)
  77 {
  78         return devm_gpiod_get_index_optional(dev, con_id, 0, flags);
  79 }
  80 EXPORT_SYMBOL_GPL(devm_gpiod_get_optional);
  81
  82 /**
  83  * devm_gpiod_get_index - Resource-managed gpiod_get_index()
  84  * @dev:        GPIO consumer
  85  * @con_id:     function within the GPIO consumer
  86  * @idx:        index of the GPIO to obtain in the consumer
  87  * @flags:      optional GPIO initialization flags
  88  *
  89  * Managed gpiod_get_index(). GPIO descriptors returned from this function are
  90  * automatically disposed on driver detach. See gpiod_get_index() for detailed
  91  * information about behavior and return values.
  92  */
  93 struct gpio_desc *__must_check devm_gpiod_get_index(struct device *dev,
  94                                                     const char *con_id,
  95                                                     unsigned int idx,
  96                                                     enum gpiod_flags flags)
  97 {
  98         struct gpio_desc **dr;
  99         struct gpio_desc *desc;
 100
 101         desc = gpiod_get_index(dev, con_id, idx, flags);
 102         if (IS_ERR(desc))
 103                 return desc;
 104
 105         /*
 106          * For non-exclusive GPIO descriptors, check if this descriptor is
 107          * already under resource management by this device.
 108          */
 109         if (flags & GPIOD_FLAGS_BIT_NONEXCLUSIVE) {
 110                 struct devres *dres;
 111
 112                 dres = devres_find(dev, devm_gpiod_release,
 113                                    devm_gpiod_match, &desc);
 114                 if (dres)
 115                         return desc;
 116         }
 117
 118         dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *),
 119                           GFP_KERNEL);
 120         if (!dr) {
 121                 gpiod_put(desc);
 122                 return ERR_PTR(-ENOMEM);
 123         }
 124
 125         *dr = desc;
 126         devres_add(dev, dr);
 127
 128         return desc;
 129 }
 130 EXPORT_SYMBOL_GPL(devm_gpiod_get_index);
 131
 132 /**
 133  * devm_fwnode_gpiod_get_index - get a GPIO descriptor from a given node
 134  * @dev:        GPIO consumer
 135  * @fwnode:     firmware node containing GPIO reference
 136  * @con_id:     function within the GPIO consumer
 137  * @index:      index of the GPIO to obtain in the consumer
 138  * @flags:      GPIO initialization flags
 139  * @label:      label to attach to the requested GPIO
 140  *
 141  * GPIO descriptors returned from this function are automatically disposed on
 142  * driver detach.
 143  *
 144  * On successful request the GPIO pin is configured in accordance with
 145  * provided @flags.
 146  */
 147 struct gpio_desc *devm_fwnode_gpiod_get_index(struct device *dev,
 148                                               struct fwnode_handle *fwnode,
 149                                               const char *con_id, int index,
 150                                               enum gpiod_flags flags,
 151                                               const char *label)
 152 {
 153         struct gpio_desc **dr;
 154         struct gpio_desc *desc;
 155
 156         dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *),
 157                           GFP_KERNEL);
 158         if (!dr)
 159                 return ERR_PTR(-ENOMEM);
 160
 161         desc = gpiod_find_and_request(dev, fwnode, con_id, index, flags, label, false);
 162         if (IS_ERR(desc)) {
 163                 devres_free(dr);
 164                 return desc;
 165         }
 166
 167         *dr = desc;
 168         devres_add(dev, dr);
 169
 170         return desc;
 171 }
 172 EXPORT_SYMBOL_GPL(devm_fwnode_gpiod_get_index);
 173
 174 /**
 175  * devm_gpiod_get_index_optional - Resource-managed gpiod_get_index_optional()
 176  * @dev: GPIO consumer
 177  * @con_id: function within the GPIO consumer
 178  * @index: index of the GPIO to obtain in the consumer
 179  * @flags: optional GPIO initialization flags
 180  *
 181  * Managed gpiod_get_index_optional(). GPIO descriptors returned from this
 182  * function are automatically disposed on driver detach. See
 183  * gpiod_get_index_optional() for detailed information about behavior and
 184  * return values.
 185  */
 186 struct gpio_desc *__must_check devm_gpiod_get_index_optional(struct device *dev,
 187                                                              const char *con_id,
 188                                                              unsigned int index,
 189                                                              enum gpiod_flags flags)
 190 {
 191         struct gpio_desc *desc;
 192
 193         desc = devm_gpiod_get_index(dev, con_id, index, flags);
 194         if (gpiod_not_found(desc))
 195                 return NULL;
 196
 197         return desc;
 198 }
 199 EXPORT_SYMBOL_GPL(devm_gpiod_get_index_optional);
 200
 201 /**
 202  * devm_gpiod_get_array - Resource-managed gpiod_get_array()
 203  * @dev:        GPIO consumer
 204  * @con_id:     function within the GPIO consumer
 205  * @flags:      optional GPIO initialization flags
 206  *
 207  * Managed gpiod_get_array(). GPIO descriptors returned from this function are
 208  * automatically disposed on driver detach. See gpiod_get_array() for detailed
 209  * information about behavior and return values.
 210  */
 211 struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev,
 212                                                      const char *con_id,
 213                                                      enum gpiod_flags flags)
 214 {
 215         struct gpio_descs **dr;
 216         struct gpio_descs *descs;
 217
 218         dr = devres_alloc(devm_gpiod_release_array,
 219                           sizeof(struct gpio_descs *), GFP_KERNEL);
 220         if (!dr)
 221                 return ERR_PTR(-ENOMEM);
 222
 223         descs = gpiod_get_array(dev, con_id, flags);
 224         if (IS_ERR(descs)) {
 225                 devres_free(dr);
 226                 return descs;
 227         }
 228
 229         *dr = descs;
 230         devres_add(dev, dr);
 231
 232         return descs;
 233 }
 234 EXPORT_SYMBOL_GPL(devm_gpiod_get_array);
 235
 236 /**
 237  * devm_gpiod_get_array_optional - Resource-managed gpiod_get_array_optional()
 238  * @dev:        GPIO consumer
 239  * @con_id:     function within the GPIO consumer
 240  * @flags:      optional GPIO initialization flags
 241  *
 242  * Managed gpiod_get_array_optional(). GPIO descriptors returned from this
 243  * function are automatically disposed on driver detach.
 244  * See gpiod_get_array_optional() for detailed information about behavior and
 245  * return values.
 246  */
 247 struct gpio_descs *__must_check
 248 devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
 249                               enum gpiod_flags flags)
 250 {
 251         struct gpio_descs *descs;
 252
 253         descs = devm_gpiod_get_array(dev, con_id, flags);
 254         if (gpiod_not_found(descs))
 255                 return NULL;
 256
 257         return descs;
 258 }
 259 EXPORT_SYMBOL_GPL(devm_gpiod_get_array_optional);
 260
 261 /**
 262  * devm_gpiod_put - Resource-managed gpiod_put()
 263  * @dev:        GPIO consumer
 264  * @desc:       GPIO descriptor to dispose of
 265  *
 266  * Dispose of a GPIO descriptor obtained with devm_gpiod_get() or
 267  * devm_gpiod_get_index(). Normally this function will not be called as the GPIO
 268  * will be disposed of by the resource management code.
 269  */
 270 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
 271 {
 272         WARN_ON(devres_release(dev, devm_gpiod_release, devm_gpiod_match,
 273                 &desc));
 274 }
 275 EXPORT_SYMBOL_GPL(devm_gpiod_put);
 276
 277 /**
 278  * devm_gpiod_unhinge - Remove resource management from a gpio descriptor
 279  * @dev:        GPIO consumer
 280  * @desc:       GPIO descriptor to remove resource management from
 281  *
 282  * Remove resource management from a GPIO descriptor. This is needed when
 283  * you want to hand over lifecycle management of a descriptor to another
 284  * mechanism.
 285  */
 286
 287 void devm_gpiod_unhinge(struct device *dev, struct gpio_desc *desc)
 288 {
 289         int ret;
 290
 291         if (IS_ERR_OR_NULL(desc))
 292                 return;
 293         ret = devres_destroy(dev, devm_gpiod_release,
 294                              devm_gpiod_match, &desc);
 295         /*
 296          * If the GPIO descriptor is requested as nonexclusive, we
 297          * may call this function several times on the same descriptor
 298          * so it is OK if devres_destroy() returns -ENOENT.
 299          */
 300         if (ret == -ENOENT)
 301                 return;
 302         /* Anything else we should warn about */
 303         WARN_ON(ret);
 304 }
 305 EXPORT_SYMBOL_GPL(devm_gpiod_unhinge);
 306
 307 /**
 308  * devm_gpiod_put_array - Resource-managed gpiod_put_array()
 309  * @dev:        GPIO consumer
 310  * @descs:      GPIO descriptor array to dispose of
 311  *
 312  * Dispose of an array of GPIO descriptors obtained with devm_gpiod_get_array().
 313  * Normally this function will not be called as the GPIOs will be disposed of
 314  * by the resource management code.
 315  */
 316 void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs)
 317 {
 318         WARN_ON(devres_release(dev, devm_gpiod_release_array,
 319                                devm_gpiod_match_array, &descs));
 320 }
 321 EXPORT_SYMBOL_GPL(devm_gpiod_put_array);
 322
 323 static void devm_gpio_release(struct device *dev, void *res)
 324 {
 325         unsigned *gpio = res;
 326
 327         gpio_free(*gpio);
 328 }
 329
 330 /**
 331  *      devm_gpio_request - request a GPIO for a managed device
 332  *      @dev: device to request the GPIO for
 333  *      @gpio: GPIO to allocate
 334  *      @label: the name of the requested GPIO
 335  *
 336  *      Except for the extra @dev argument, this function takes the
 337  *      same arguments and performs the same function as
 338  *      gpio_request().  GPIOs requested with this function will be
 339  *      automatically freed on driver detach.
 340  */
 341 int devm_gpio_request(struct device *dev, unsigned gpio, const char *label)
 342 {
 343         unsigned *dr;
 344         int rc;
 345
 346         dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL);
 347         if (!dr)
 348                 return -ENOMEM;
 349
 350         rc = gpio_request(gpio, label);
 351         if (rc) {
 352                 devres_free(dr);
 353                 return rc;
 354         }
 355
 356         *dr = gpio;
 357         devres_add(dev, dr);
 358
 359         return 0;
 360 }
 361 EXPORT_SYMBOL_GPL(devm_gpio_request);
 362
 363 /**
 364  *      devm_gpio_request_one - request a single GPIO with initial setup
 365  *      @dev:   device to request for
 366  *      @gpio:  the GPIO number
 367  *      @flags: GPIO configuration as specified by GPIOF_*
 368  *      @label: a literal description string of this GPIO
 369  */
 370 int devm_gpio_request_one(struct device *dev, unsigned gpio,
 371                           unsigned long flags, const char *label)
 372 {
 373         unsigned *dr;
 374         int rc;
 375
 376         dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL);
 377         if (!dr)
 378                 return -ENOMEM;
 379
 380         rc = gpio_request_one(gpio, flags, label);
 381         if (rc) {
 382                 devres_free(dr);
 383                 return rc;
 384         }
 385
 386         *dr = gpio;
 387         devres_add(dev, dr);
 388
 389         return 0;
 390 }
 391 EXPORT_SYMBOL_GPL(devm_gpio_request_one);
 392
 393 static void devm_gpio_chip_release(void *data)
 394 {
 395         struct gpio_chip *gc = data;
 396
 397         gpiochip_remove(gc);
 398 }
 399
 400 /**
 401  * devm_gpiochip_add_data_with_key() - Resource managed gpiochip_add_data_with_key()
 402  * @dev: pointer to the device that gpio_chip belongs to.
 403  * @gc: the GPIO chip to register
 404  * @data: driver-private data associated with this chip
 405  * @lock_key: lockdep class for IRQ lock
 406  * @request_key: lockdep class for IRQ request
 407  *
 408  * Context: potentially before irqs will work
 409  *
 410  * The gpio chip automatically be released when the device is unbound.
 411  *
 412  * Returns:
 413  * A negative errno if the chip can't be registered, such as because the
 414  * gc->base is invalid or already associated with a different chip.
 415  * Otherwise it returns zero as a success code.
 416  */
 417 int devm_gpiochip_add_data_with_key(struct device *dev, struct gpio_chip *gc, void *data,
 418                                     struct lock_class_key *lock_key,
 419                                     struct lock_class_key *request_key)
 420 {
 421         int ret;
 422
 423         ret = gpiochip_add_data_with_key(gc, data, lock_key, request_key);
 424         if (ret < 0)
 425                 return ret;
 426
 427         return devm_add_action_or_reset(dev, devm_gpio_chip_release, gc);
 428 }
 429 EXPORT_SYMBOL_GPL(devm_gpiochip_add_data_with_key);