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 const 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 (gpiod_not_found(desc)) 250 return NULL; 251 252 return desc; 253 } 254 EXPORT_SYMBOL_GPL(devm_gpiod_get_index_optional); 255 256 /** 257 * devm_gpiod_get_array - Resource-managed gpiod_get_array() 258 * @dev: GPIO consumer 259 * @con_id: function within the GPIO consumer 260 * @flags: optional GPIO initialization flags 261 * 262 * Managed gpiod_get_array(). GPIO descriptors returned from this function are 263 * automatically disposed on driver detach. See gpiod_get_array() for detailed 264 * information about behavior and return values. 265 */ 266 struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev, 267 const char *con_id, 268 enum gpiod_flags flags) 269 { 270 struct gpio_descs **dr; 271 struct gpio_descs *descs; 272 273 dr = devres_alloc(devm_gpiod_release_array, 274 sizeof(struct gpio_descs *), GFP_KERNEL); 275 if (!dr) 276 return ERR_PTR(-ENOMEM); 277 278 descs = gpiod_get_array(dev, con_id, flags); 279 if (IS_ERR(descs)) { 280 devres_free(dr); 281 return descs; 282 } 283 284 *dr = descs; 285 devres_add(dev, dr); 286 287 return descs; 288 } 289 EXPORT_SYMBOL_GPL(devm_gpiod_get_array); 290 291 /** 292 * devm_gpiod_get_array_optional - Resource-managed gpiod_get_array_optional() 293 * @dev: GPIO consumer 294 * @con_id: function within the GPIO consumer 295 * @flags: optional GPIO initialization flags 296 * 297 * Managed gpiod_get_array_optional(). GPIO descriptors returned from this 298 * function are automatically disposed on driver detach. 299 * See gpiod_get_array_optional() for detailed information about behavior and 300 * return values. 301 */ 302 struct gpio_descs *__must_check 303 devm_gpiod_get_array_optional(struct device *dev, const char *con_id, 304 enum gpiod_flags flags) 305 { 306 struct gpio_descs *descs; 307 308 descs = devm_gpiod_get_array(dev, con_id, flags); 309 if (gpiod_not_found(descs)) 310 return NULL; 311 312 return descs; 313 } 314 EXPORT_SYMBOL_GPL(devm_gpiod_get_array_optional); 315 316 /** 317 * devm_gpiod_put - Resource-managed gpiod_put() 318 * @dev: GPIO consumer 319 * @desc: GPIO descriptor to dispose of 320 * 321 * Dispose of a GPIO descriptor obtained with devm_gpiod_get() or 322 * devm_gpiod_get_index(). Normally this function will not be called as the GPIO 323 * will be disposed of by the resource management code. 324 */ 325 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc) 326 { 327 WARN_ON(devres_release(dev, devm_gpiod_release, devm_gpiod_match, 328 &desc)); 329 } 330 EXPORT_SYMBOL_GPL(devm_gpiod_put); 331 332 /** 333 * devm_gpiod_unhinge - Remove resource management from a gpio descriptor 334 * @dev: GPIO consumer 335 * @desc: GPIO descriptor to remove resource management from 336 * 337 * Remove resource management from a GPIO descriptor. This is needed when 338 * you want to hand over lifecycle management of a descriptor to another 339 * mechanism. 340 */ 341 342 void devm_gpiod_unhinge(struct device *dev, struct gpio_desc *desc) 343 { 344 int ret; 345 346 if (IS_ERR_OR_NULL(desc)) 347 return; 348 ret = devres_destroy(dev, devm_gpiod_release, 349 devm_gpiod_match, &desc); 350 /* 351 * If the GPIO descriptor is requested as nonexclusive, we 352 * may call this function several times on the same descriptor 353 * so it is OK if devres_destroy() returns -ENOENT. 354 */ 355 if (ret == -ENOENT) 356 return; 357 /* Anything else we should warn about */ 358 WARN_ON(ret); 359 } 360 EXPORT_SYMBOL_GPL(devm_gpiod_unhinge); 361 362 /** 363 * devm_gpiod_put_array - Resource-managed gpiod_put_array() 364 * @dev: GPIO consumer 365 * @descs: GPIO descriptor array to dispose of 366 * 367 * Dispose of an array of GPIO descriptors obtained with devm_gpiod_get_array(). 368 * Normally this function will not be called as the GPIOs will be disposed of 369 * by the resource management code. 370 */ 371 void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs) 372 { 373 WARN_ON(devres_release(dev, devm_gpiod_release_array, 374 devm_gpiod_match_array, &descs)); 375 } 376 EXPORT_SYMBOL_GPL(devm_gpiod_put_array); 377 378 379 380 381 static void devm_gpio_release(struct device *dev, void *res) 382 { 383 unsigned *gpio = res; 384 385 gpio_free(*gpio); 386 } 387 388 static int devm_gpio_match(struct device *dev, void *res, void *data) 389 { 390 unsigned *this = res, *gpio = data; 391 392 return *this == *gpio; 393 } 394 395 /** 396 * devm_gpio_request - request a GPIO for a managed device 397 * @dev: device to request the GPIO for 398 * @gpio: GPIO to allocate 399 * @label: the name of the requested GPIO 400 * 401 * Except for the extra @dev argument, this function takes the 402 * same arguments and performs the same function as 403 * gpio_request(). GPIOs requested with this function will be 404 * automatically freed on driver detach. 405 * 406 * If an GPIO allocated with this function needs to be freed 407 * separately, devm_gpio_free() must be used. 408 */ 409 410 int devm_gpio_request(struct device *dev, unsigned gpio, const char *label) 411 { 412 unsigned *dr; 413 int rc; 414 415 dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL); 416 if (!dr) 417 return -ENOMEM; 418 419 rc = gpio_request(gpio, label); 420 if (rc) { 421 devres_free(dr); 422 return rc; 423 } 424 425 *dr = gpio; 426 devres_add(dev, dr); 427 428 return 0; 429 } 430 EXPORT_SYMBOL_GPL(devm_gpio_request); 431 432 /** 433 * devm_gpio_request_one - request a single GPIO with initial setup 434 * @dev: device to request for 435 * @gpio: the GPIO number 436 * @flags: GPIO configuration as specified by GPIOF_* 437 * @label: a literal description string of this GPIO 438 */ 439 int devm_gpio_request_one(struct device *dev, unsigned gpio, 440 unsigned long flags, const char *label) 441 { 442 unsigned *dr; 443 int rc; 444 445 dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL); 446 if (!dr) 447 return -ENOMEM; 448 449 rc = gpio_request_one(gpio, flags, label); 450 if (rc) { 451 devres_free(dr); 452 return rc; 453 } 454 455 *dr = gpio; 456 devres_add(dev, dr); 457 458 return 0; 459 } 460 EXPORT_SYMBOL_GPL(devm_gpio_request_one); 461 462 /** 463 * devm_gpio_free - free a GPIO 464 * @dev: device to free GPIO for 465 * @gpio: GPIO to free 466 * 467 * Except for the extra @dev argument, this function takes the 468 * same arguments and performs the same function as gpio_free(). 469 * This function instead of gpio_free() should be used to manually 470 * free GPIOs allocated with devm_gpio_request(). 471 */ 472 void devm_gpio_free(struct device *dev, unsigned int gpio) 473 { 474 475 WARN_ON(devres_release(dev, devm_gpio_release, devm_gpio_match, 476 &gpio)); 477 } 478 EXPORT_SYMBOL_GPL(devm_gpio_free); 479 480 static void devm_gpio_chip_release(void *data) 481 { 482 struct gpio_chip *gc = data; 483 484 gpiochip_remove(gc); 485 } 486 487 /** 488 * devm_gpiochip_add_data_with_key() - Resource managed gpiochip_add_data_with_key() 489 * @dev: pointer to the device that gpio_chip belongs to. 490 * @gc: the GPIO chip to register 491 * @data: driver-private data associated with this chip 492 * @lock_key: lockdep class for IRQ lock 493 * @request_key: lockdep class for IRQ request 494 * 495 * Context: potentially before irqs will work 496 * 497 * The gpio chip automatically be released when the device is unbound. 498 * 499 * Returns: 500 * A negative errno if the chip can't be registered, such as because the 501 * gc->base is invalid or already associated with a different chip. 502 * Otherwise it returns zero as a success code. 503 */ 504 int devm_gpiochip_add_data_with_key(struct device *dev, struct gpio_chip *gc, void *data, 505 struct lock_class_key *lock_key, 506 struct lock_class_key *request_key) 507 { 508 int ret; 509 510 ret = gpiochip_add_data_with_key(gc, data, lock_key, request_key); 511 if (ret < 0) 512 return ret; 513 514 return devm_add_action_or_reset(dev, devm_gpio_chip_release, gc); 515 } 516 EXPORT_SYMBOL_GPL(devm_gpiochip_add_data_with_key); 517