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