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_gpiod_get_from_of_node() - obtain a GPIO from an OF node 134 * @dev: device for lifecycle management 135 * @node: handle of the OF node 136 * @propname: name of the DT property representing the GPIO 137 * @index: index of the GPIO to obtain for the consumer 138 * @dflags: GPIO initialization flags 139 * @label: label to attach to the requested GPIO 140 * 141 * Returns: 142 * On successful request the GPIO pin is configured in accordance with 143 * provided @dflags. 144 * 145 * In case of error an ERR_PTR() is returned. 146 */ 147 struct gpio_desc *devm_gpiod_get_from_of_node(struct device *dev, 148 struct device_node *node, 149 const char *propname, int index, 150 enum gpiod_flags dflags, 151 const char *label) 152 { 153 struct gpio_desc **dr; 154 struct gpio_desc *desc; 155 156 desc = gpiod_get_from_of_node(node, propname, index, dflags, label); 157 if (IS_ERR(desc)) 158 return desc; 159 160 /* 161 * For non-exclusive GPIO descriptors, check if this descriptor is 162 * already under resource management by this device. 163 */ 164 if (dflags & GPIOD_FLAGS_BIT_NONEXCLUSIVE) { 165 struct devres *dres; 166 167 dres = devres_find(dev, devm_gpiod_release, 168 devm_gpiod_match, &desc); 169 if (dres) 170 return desc; 171 } 172 173 dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *), 174 GFP_KERNEL); 175 if (!dr) { 176 gpiod_put(desc); 177 return ERR_PTR(-ENOMEM); 178 } 179 180 *dr = desc; 181 devres_add(dev, dr); 182 183 return desc; 184 } 185 EXPORT_SYMBOL_GPL(devm_gpiod_get_from_of_node); 186 187 /** 188 * devm_fwnode_gpiod_get_index - get a GPIO descriptor from a given node 189 * @dev: GPIO consumer 190 * @fwnode: firmware node containing GPIO reference 191 * @con_id: function within the GPIO consumer 192 * @index: index of the GPIO to obtain in the consumer 193 * @flags: GPIO initialization flags 194 * @label: label to attach to the requested GPIO 195 * 196 * GPIO descriptors returned from this function are automatically disposed on 197 * driver detach. 198 * 199 * On successful request the GPIO pin is configured in accordance with 200 * provided @flags. 201 */ 202 struct gpio_desc *devm_fwnode_gpiod_get_index(struct device *dev, 203 struct fwnode_handle *fwnode, 204 const char *con_id, int index, 205 enum gpiod_flags flags, 206 const char *label) 207 { 208 struct gpio_desc **dr; 209 struct gpio_desc *desc; 210 211 dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *), 212 GFP_KERNEL); 213 if (!dr) 214 return ERR_PTR(-ENOMEM); 215 216 desc = fwnode_gpiod_get_index(fwnode, con_id, index, flags, label); 217 if (IS_ERR(desc)) { 218 devres_free(dr); 219 return desc; 220 } 221 222 *dr = desc; 223 devres_add(dev, dr); 224 225 return desc; 226 } 227 EXPORT_SYMBOL_GPL(devm_fwnode_gpiod_get_index); 228 229 /** 230 * devm_gpiod_get_index_optional - Resource-managed gpiod_get_index_optional() 231 * @dev: GPIO consumer 232 * @con_id: function within the GPIO consumer 233 * @index: index of the GPIO to obtain in the consumer 234 * @flags: optional GPIO initialization flags 235 * 236 * Managed gpiod_get_index_optional(). GPIO descriptors returned from this 237 * function are automatically disposed on driver detach. See 238 * gpiod_get_index_optional() for detailed information about behavior and 239 * return values. 240 */ 241 struct gpio_desc *__must_check devm_gpiod_get_index_optional(struct device *dev, 242 const char *con_id, 243 unsigned int index, 244 enum gpiod_flags flags) 245 { 246 struct gpio_desc *desc; 247 248 desc = devm_gpiod_get_index(dev, con_id, index, flags); 249 if (IS_ERR(desc)) { 250 if (PTR_ERR(desc) == -ENOENT) 251 return NULL; 252 } 253 254 return desc; 255 } 256 EXPORT_SYMBOL_GPL(devm_gpiod_get_index_optional); 257 258 /** 259 * devm_gpiod_get_array - Resource-managed gpiod_get_array() 260 * @dev: GPIO consumer 261 * @con_id: function within the GPIO consumer 262 * @flags: optional GPIO initialization flags 263 * 264 * Managed gpiod_get_array(). GPIO descriptors returned from this function are 265 * automatically disposed on driver detach. See gpiod_get_array() for detailed 266 * information about behavior and return values. 267 */ 268 struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev, 269 const char *con_id, 270 enum gpiod_flags flags) 271 { 272 struct gpio_descs **dr; 273 struct gpio_descs *descs; 274 275 dr = devres_alloc(devm_gpiod_release_array, 276 sizeof(struct gpio_descs *), GFP_KERNEL); 277 if (!dr) 278 return ERR_PTR(-ENOMEM); 279 280 descs = gpiod_get_array(dev, con_id, flags); 281 if (IS_ERR(descs)) { 282 devres_free(dr); 283 return descs; 284 } 285 286 *dr = descs; 287 devres_add(dev, dr); 288 289 return descs; 290 } 291 EXPORT_SYMBOL_GPL(devm_gpiod_get_array); 292 293 /** 294 * devm_gpiod_get_array_optional - Resource-managed gpiod_get_array_optional() 295 * @dev: GPIO consumer 296 * @con_id: function within the GPIO consumer 297 * @flags: optional GPIO initialization flags 298 * 299 * Managed gpiod_get_array_optional(). GPIO descriptors returned from this 300 * function are automatically disposed on driver detach. 301 * See gpiod_get_array_optional() for detailed information about behavior and 302 * return values. 303 */ 304 struct gpio_descs *__must_check 305 devm_gpiod_get_array_optional(struct device *dev, const char *con_id, 306 enum gpiod_flags flags) 307 { 308 struct gpio_descs *descs; 309 310 descs = devm_gpiod_get_array(dev, con_id, flags); 311 if (PTR_ERR(descs) == -ENOENT) 312 return NULL; 313 314 return descs; 315 } 316 EXPORT_SYMBOL_GPL(devm_gpiod_get_array_optional); 317 318 /** 319 * devm_gpiod_put - Resource-managed gpiod_put() 320 * @dev: GPIO consumer 321 * @desc: GPIO descriptor to dispose of 322 * 323 * Dispose of a GPIO descriptor obtained with devm_gpiod_get() or 324 * devm_gpiod_get_index(). Normally this function will not be called as the GPIO 325 * will be disposed of by the resource management code. 326 */ 327 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc) 328 { 329 WARN_ON(devres_release(dev, devm_gpiod_release, devm_gpiod_match, 330 &desc)); 331 } 332 EXPORT_SYMBOL_GPL(devm_gpiod_put); 333 334 /** 335 * devm_gpiod_unhinge - Remove resource management from a gpio descriptor 336 * @dev: GPIO consumer 337 * @desc: GPIO descriptor to remove resource management from 338 * 339 * Remove resource management from a GPIO descriptor. This is needed when 340 * you want to hand over lifecycle management of a descriptor to another 341 * mechanism. 342 */ 343 344 void devm_gpiod_unhinge(struct device *dev, struct gpio_desc *desc) 345 { 346 int ret; 347 348 if (IS_ERR_OR_NULL(desc)) 349 return; 350 ret = devres_destroy(dev, devm_gpiod_release, 351 devm_gpiod_match, &desc); 352 /* 353 * If the GPIO descriptor is requested as nonexclusive, we 354 * may call this function several times on the same descriptor 355 * so it is OK if devres_destroy() returns -ENOENT. 356 */ 357 if (ret == -ENOENT) 358 return; 359 /* Anything else we should warn about */ 360 WARN_ON(ret); 361 } 362 EXPORT_SYMBOL_GPL(devm_gpiod_unhinge); 363 364 /** 365 * devm_gpiod_put_array - Resource-managed gpiod_put_array() 366 * @dev: GPIO consumer 367 * @descs: GPIO descriptor array to dispose of 368 * 369 * Dispose of an array of GPIO descriptors obtained with devm_gpiod_get_array(). 370 * Normally this function will not be called as the GPIOs will be disposed of 371 * by the resource management code. 372 */ 373 void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs) 374 { 375 WARN_ON(devres_release(dev, devm_gpiod_release_array, 376 devm_gpiod_match_array, &descs)); 377 } 378 EXPORT_SYMBOL_GPL(devm_gpiod_put_array); 379 380 381 382 383 static void devm_gpio_release(struct device *dev, void *res) 384 { 385 unsigned *gpio = res; 386 387 gpio_free(*gpio); 388 } 389 390 static int devm_gpio_match(struct device *dev, void *res, void *data) 391 { 392 unsigned *this = res, *gpio = data; 393 394 return *this == *gpio; 395 } 396 397 /** 398 * devm_gpio_request - request a GPIO for a managed device 399 * @dev: device to request the GPIO for 400 * @gpio: GPIO to allocate 401 * @label: the name of the requested GPIO 402 * 403 * Except for the extra @dev argument, this function takes the 404 * same arguments and performs the same function as 405 * gpio_request(). GPIOs requested with this function will be 406 * automatically freed on driver detach. 407 * 408 * If an GPIO allocated with this function needs to be freed 409 * separately, devm_gpio_free() must be used. 410 */ 411 412 int devm_gpio_request(struct device *dev, unsigned gpio, const char *label) 413 { 414 unsigned *dr; 415 int rc; 416 417 dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL); 418 if (!dr) 419 return -ENOMEM; 420 421 rc = gpio_request(gpio, label); 422 if (rc) { 423 devres_free(dr); 424 return rc; 425 } 426 427 *dr = gpio; 428 devres_add(dev, dr); 429 430 return 0; 431 } 432 EXPORT_SYMBOL_GPL(devm_gpio_request); 433 434 /** 435 * devm_gpio_request_one - request a single GPIO with initial setup 436 * @dev: device to request for 437 * @gpio: the GPIO number 438 * @flags: GPIO configuration as specified by GPIOF_* 439 * @label: a literal description string of this GPIO 440 */ 441 int devm_gpio_request_one(struct device *dev, unsigned gpio, 442 unsigned long flags, const char *label) 443 { 444 unsigned *dr; 445 int rc; 446 447 dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL); 448 if (!dr) 449 return -ENOMEM; 450 451 rc = gpio_request_one(gpio, flags, label); 452 if (rc) { 453 devres_free(dr); 454 return rc; 455 } 456 457 *dr = gpio; 458 devres_add(dev, dr); 459 460 return 0; 461 } 462 EXPORT_SYMBOL_GPL(devm_gpio_request_one); 463 464 /** 465 * devm_gpio_free - free a GPIO 466 * @dev: device to free GPIO for 467 * @gpio: GPIO to free 468 * 469 * Except for the extra @dev argument, this function takes the 470 * same arguments and performs the same function as gpio_free(). 471 * This function instead of gpio_free() should be used to manually 472 * free GPIOs allocated with devm_gpio_request(). 473 */ 474 void devm_gpio_free(struct device *dev, unsigned int gpio) 475 { 476 477 WARN_ON(devres_release(dev, devm_gpio_release, devm_gpio_match, 478 &gpio)); 479 } 480 EXPORT_SYMBOL_GPL(devm_gpio_free); 481 482 static void devm_gpio_chip_release(struct device *dev, void *res) 483 { 484 struct gpio_chip *gc = *(struct gpio_chip **)res; 485 486 gpiochip_remove(gc); 487 } 488 489 /** 490 * devm_gpiochip_add_data_with_key() - Resource managed gpiochip_add_data_with_key() 491 * @dev: pointer to the device that gpio_chip belongs to. 492 * @gc: the GPIO chip to register 493 * @data: driver-private data associated with this chip 494 * @lock_key: lockdep class for IRQ lock 495 * @request_key: lockdep class for IRQ request 496 * 497 * Context: potentially before irqs will work 498 * 499 * The gpio chip automatically be released when the device is unbound. 500 * 501 * Returns: 502 * A negative errno if the chip can't be registered, such as because the 503 * gc->base is invalid or already associated with a different chip. 504 * Otherwise it returns zero as a success code. 505 */ 506 int devm_gpiochip_add_data_with_key(struct device *dev, struct gpio_chip *gc, void *data, 507 struct lock_class_key *lock_key, 508 struct lock_class_key *request_key) 509 { 510 struct gpio_chip **ptr; 511 int ret; 512 513 ptr = devres_alloc(devm_gpio_chip_release, sizeof(*ptr), 514 GFP_KERNEL); 515 if (!ptr) 516 return -ENOMEM; 517 518 ret = gpiochip_add_data_with_key(gc, data, lock_key, request_key); 519 if (ret < 0) { 520 devres_free(ptr); 521 return ret; 522 } 523 524 *ptr = gc; 525 devres_add(dev, ptr); 526 527 return 0; 528 } 529 EXPORT_SYMBOL_GPL(devm_gpiochip_add_data_with_key); 530