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