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(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(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         dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *),
 102                           GFP_KERNEL);
 103         if (!dr)
 104                 return ERR_PTR(-ENOMEM);
 105
 106         desc = gpiod_get_index(dev, con_id, idx, flags);
 107         if (IS_ERR(desc)) {
 108                 devres_free(dr);
 109                 return desc;
 110         }
 111
 112         *dr = desc;
 113         devres_add(dev, dr);
 114
 115         return desc;
 116 }
 117 EXPORT_SYMBOL(devm_gpiod_get_index);
 118
 119 /**
 120  * devm_gpiod_get_from_of_node() - obtain a GPIO from an OF node
 121  * @dev:        device for lifecycle management
 122  * @node:       handle of the OF node
 123  * @propname:   name of the DT property representing the GPIO
 124  * @index:      index of the GPIO to obtain for the consumer
 125  * @dflags:     GPIO initialization flags
 126  * @label:      label to attach to the requested GPIO
 127  *
 128  * Returns:
 129  * On successful request the GPIO pin is configured in accordance with
 130  * provided @dflags.
 131  *
 132  * In case of error an ERR_PTR() is returned.
 133  */
 134 struct gpio_desc *devm_gpiod_get_from_of_node(struct device *dev,
 135                                               struct device_node *node,
 136                                               const char *propname, int index,
 137                                               enum gpiod_flags dflags,
 138                                               const char *label)
 139 {
 140         struct gpio_desc **dr;
 141         struct gpio_desc *desc;
 142
 143         dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *),
 144                           GFP_KERNEL);
 145         if (!dr)
 146                 return ERR_PTR(-ENOMEM);
 147
 148         desc = gpiod_get_from_of_node(node, propname, index, dflags, label);
 149         if (IS_ERR(desc)) {
 150                 devres_free(dr);
 151                 return desc;
 152         }
 153
 154         *dr = desc;
 155         devres_add(dev, dr);
 156
 157         return desc;
 158 }
 159 EXPORT_SYMBOL(devm_gpiod_get_from_of_node);
 160
 161 /**
 162  * devm_fwnode_get_index_gpiod_from_child - get a GPIO descriptor from a
 163  *                                          device's child node
 164  * @dev:        GPIO consumer
 165  * @con_id:     function within the GPIO consumer
 166  * @index:      index of the GPIO to obtain in the consumer
 167  * @child:      firmware node (child of @dev)
 168  * @flags:      GPIO initialization flags
 169  * @label:      label to attach to the requested GPIO
 170  *
 171  * GPIO descriptors returned from this function are automatically disposed on
 172  * driver detach.
 173  *
 174  * On successful request the GPIO pin is configured in accordance with
 175  * provided @flags.
 176  */
 177 struct gpio_desc *devm_fwnode_get_index_gpiod_from_child(struct device *dev,
 178                                                 const char *con_id, int index,
 179                                                 struct fwnode_handle *child,
 180                                                 enum gpiod_flags flags,
 181                                                 const char *label)
 182 {
 183         char prop_name[32]; /* 32 is max size of property name */
 184         struct gpio_desc **dr;
 185         struct gpio_desc *desc;
 186         unsigned int i;
 187
 188         dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *),
 189                           GFP_KERNEL);
 190         if (!dr)
 191                 return ERR_PTR(-ENOMEM);
 192
 193         for (i = 0; i < ARRAY_SIZE(gpio_suffixes); i++) {
 194                 if (con_id)
 195                         snprintf(prop_name, sizeof(prop_name), "%s-%s",
 196                                             con_id, gpio_suffixes[i]);
 197                 else
 198                         snprintf(prop_name, sizeof(prop_name), "%s",
 199                                             gpio_suffixes[i]);
 200
 201                 desc = fwnode_get_named_gpiod(child, prop_name, index, flags,
 202                                               label);
 203                 if (!IS_ERR(desc) || (PTR_ERR(desc) != -ENOENT))
 204                         break;
 205         }
 206         if (IS_ERR(desc)) {
 207                 devres_free(dr);
 208                 return desc;
 209         }
 210
 211         *dr = desc;
 212         devres_add(dev, dr);
 213
 214         return desc;
 215 }
 216 EXPORT_SYMBOL(devm_fwnode_get_index_gpiod_from_child);
 217
 218 /**
 219  * devm_gpiod_get_index_optional - Resource-managed gpiod_get_index_optional()
 220  * @dev: GPIO consumer
 221  * @con_id: function within the GPIO consumer
 222  * @index: index of the GPIO to obtain in the consumer
 223  * @flags: optional GPIO initialization flags
 224  *
 225  * Managed gpiod_get_index_optional(). GPIO descriptors returned from this
 226  * function are automatically disposed on driver detach. See
 227  * gpiod_get_index_optional() for detailed information about behavior and
 228  * return values.
 229  */
 230 struct gpio_desc *__must_check devm_gpiod_get_index_optional(struct device *dev,
 231                                                              const char *con_id,
 232                                                              unsigned int index,
 233                                                              enum gpiod_flags flags)
 234 {
 235         struct gpio_desc *desc;
 236
 237         desc = devm_gpiod_get_index(dev, con_id, index, flags);
 238         if (IS_ERR(desc)) {
 239                 if (PTR_ERR(desc) == -ENOENT)
 240                         return NULL;
 241         }
 242
 243         return desc;
 244 }
 245 EXPORT_SYMBOL(devm_gpiod_get_index_optional);
 246
 247 /**
 248  * devm_gpiod_get_array - Resource-managed gpiod_get_array()
 249  * @dev:        GPIO consumer
 250  * @con_id:     function within the GPIO consumer
 251  * @flags:      optional GPIO initialization flags
 252  *
 253  * Managed gpiod_get_array(). GPIO descriptors returned from this function are
 254  * automatically disposed on driver detach. See gpiod_get_array() for detailed
 255  * information about behavior and return values.
 256  */
 257 struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev,
 258                                                      const char *con_id,
 259                                                      enum gpiod_flags flags)
 260 {
 261         struct gpio_descs **dr;
 262         struct gpio_descs *descs;
 263
 264         dr = devres_alloc(devm_gpiod_release_array,
 265                           sizeof(struct gpio_descs *), GFP_KERNEL);
 266         if (!dr)
 267                 return ERR_PTR(-ENOMEM);
 268
 269         descs = gpiod_get_array(dev, con_id, flags);
 270         if (IS_ERR(descs)) {
 271                 devres_free(dr);
 272                 return descs;
 273         }
 274
 275         *dr = descs;
 276         devres_add(dev, dr);
 277
 278         return descs;
 279 }
 280 EXPORT_SYMBOL(devm_gpiod_get_array);
 281
 282 /**
 283  * devm_gpiod_get_array_optional - Resource-managed gpiod_get_array_optional()
 284  * @dev:        GPIO consumer
 285  * @con_id:     function within the GPIO consumer
 286  * @flags:      optional GPIO initialization flags
 287  *
 288  * Managed gpiod_get_array_optional(). GPIO descriptors returned from this
 289  * function are automatically disposed on driver detach.
 290  * See gpiod_get_array_optional() for detailed information about behavior and
 291  * return values.
 292  */
 293 struct gpio_descs *__must_check
 294 devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
 295                               enum gpiod_flags flags)
 296 {
 297         struct gpio_descs *descs;
 298
 299         descs = devm_gpiod_get_array(dev, con_id, flags);
 300         if (IS_ERR(descs) && (PTR_ERR(descs) == -ENOENT))
 301                 return NULL;
 302
 303         return descs;
 304 }
 305 EXPORT_SYMBOL(devm_gpiod_get_array_optional);
 306
 307 /**
 308  * devm_gpiod_put - Resource-managed gpiod_put()
 309  * @dev:        GPIO consumer
 310  * @desc:       GPIO descriptor to dispose of
 311  *
 312  * Dispose of a GPIO descriptor obtained with devm_gpiod_get() or
 313  * devm_gpiod_get_index(). Normally this function will not be called as the GPIO
 314  * will be disposed of by the resource management code.
 315  */
 316 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
 317 {
 318         WARN_ON(devres_release(dev, devm_gpiod_release, devm_gpiod_match,
 319                 &desc));
 320 }
 321 EXPORT_SYMBOL(devm_gpiod_put);
 322
 323 /**
 324  * devm_gpiod_put_array - Resource-managed gpiod_put_array()
 325  * @dev:        GPIO consumer
 326  * @descs:      GPIO descriptor array to dispose of
 327  *
 328  * Dispose of an array of GPIO descriptors obtained with devm_gpiod_get_array().
 329  * Normally this function will not be called as the GPIOs will be disposed of
 330  * by the resource management code.
 331  */
 332 void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs)
 333 {
 334         WARN_ON(devres_release(dev, devm_gpiod_release_array,
 335                                devm_gpiod_match_array, &descs));
 336 }
 337 EXPORT_SYMBOL(devm_gpiod_put_array);
 338
 339
 340
 341
 342 static void devm_gpio_release(struct device *dev, void *res)
 343 {
 344         unsigned *gpio = res;
 345
 346         gpio_free(*gpio);
 347 }
 348
 349 static int devm_gpio_match(struct device *dev, void *res, void *data)
 350 {
 351         unsigned *this = res, *gpio = data;
 352
 353         return *this == *gpio;
 354 }
 355
 356 /**
 357  *      devm_gpio_request - request a GPIO for a managed device
 358  *      @dev: device to request the GPIO for
 359  *      @gpio: GPIO to allocate
 360  *      @label: the name of the requested GPIO
 361  *
 362  *      Except for the extra @dev argument, this function takes the
 363  *      same arguments and performs the same function as
 364  *      gpio_request().  GPIOs requested with this function will be
 365  *      automatically freed on driver detach.
 366  *
 367  *      If an GPIO allocated with this function needs to be freed
 368  *      separately, devm_gpio_free() must be used.
 369  */
 370
 371 int devm_gpio_request(struct device *dev, unsigned gpio, 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(gpio, 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(devm_gpio_request);
 392
 393 /**
 394  *      devm_gpio_request_one - request a single GPIO with initial setup
 395  *      @dev:   device to request for
 396  *      @gpio:  the GPIO number
 397  *      @flags: GPIO configuration as specified by GPIOF_*
 398  *      @label: a literal description string of this GPIO
 399  */
 400 int devm_gpio_request_one(struct device *dev, unsigned gpio,
 401                           unsigned long flags, const char *label)
 402 {
 403         unsigned *dr;
 404         int rc;
 405
 406         dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL);
 407         if (!dr)
 408                 return -ENOMEM;
 409
 410         rc = gpio_request_one(gpio, flags, label);
 411         if (rc) {
 412                 devres_free(dr);
 413                 return rc;
 414         }
 415
 416         *dr = gpio;
 417         devres_add(dev, dr);
 418
 419         return 0;
 420 }
 421 EXPORT_SYMBOL(devm_gpio_request_one);
 422
 423 /**
 424  *      devm_gpio_free - free a GPIO
 425  *      @dev: device to free GPIO for
 426  *      @gpio: GPIO to free
 427  *
 428  *      Except for the extra @dev argument, this function takes the
 429  *      same arguments and performs the same function as gpio_free().
 430  *      This function instead of gpio_free() should be used to manually
 431  *      free GPIOs allocated with devm_gpio_request().
 432  */
 433 void devm_gpio_free(struct device *dev, unsigned int gpio)
 434 {
 435
 436         WARN_ON(devres_release(dev, devm_gpio_release, devm_gpio_match,
 437                 &gpio));
 438 }
 439 EXPORT_SYMBOL(devm_gpio_free);