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 static void devm_gpio_release(struct device *dev, void *res) 379 { 380 unsigned *gpio = res; 381 382 gpio_free(*gpio); 383 } 384 385 /** 386 * devm_gpio_request - request a GPIO for a managed device 387 * @dev: device to request the GPIO for 388 * @gpio: GPIO to allocate 389 * @label: the name of the requested GPIO 390 * 391 * Except for the extra @dev argument, this function takes the 392 * same arguments and performs the same function as 393 * gpio_request(). GPIOs requested with this function will be 394 * automatically freed on driver detach. 395 */ 396 int devm_gpio_request(struct device *dev, unsigned gpio, const char *label) 397 { 398 unsigned *dr; 399 int rc; 400 401 dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL); 402 if (!dr) 403 return -ENOMEM; 404 405 rc = gpio_request(gpio, label); 406 if (rc) { 407 devres_free(dr); 408 return rc; 409 } 410 411 *dr = gpio; 412 devres_add(dev, dr); 413 414 return 0; 415 } 416 EXPORT_SYMBOL_GPL(devm_gpio_request); 417 418 /** 419 * devm_gpio_request_one - request a single GPIO with initial setup 420 * @dev: device to request for 421 * @gpio: the GPIO number 422 * @flags: GPIO configuration as specified by GPIOF_* 423 * @label: a literal description string of this GPIO 424 */ 425 int devm_gpio_request_one(struct device *dev, unsigned gpio, 426 unsigned long flags, const char *label) 427 { 428 unsigned *dr; 429 int rc; 430 431 dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL); 432 if (!dr) 433 return -ENOMEM; 434 435 rc = gpio_request_one(gpio, flags, label); 436 if (rc) { 437 devres_free(dr); 438 return rc; 439 } 440 441 *dr = gpio; 442 devres_add(dev, dr); 443 444 return 0; 445 } 446 EXPORT_SYMBOL_GPL(devm_gpio_request_one); 447 448 static void devm_gpio_chip_release(void *data) 449 { 450 struct gpio_chip *gc = data; 451 452 gpiochip_remove(gc); 453 } 454 455 /** 456 * devm_gpiochip_add_data_with_key() - Resource managed gpiochip_add_data_with_key() 457 * @dev: pointer to the device that gpio_chip belongs to. 458 * @gc: the GPIO chip to register 459 * @data: driver-private data associated with this chip 460 * @lock_key: lockdep class for IRQ lock 461 * @request_key: lockdep class for IRQ request 462 * 463 * Context: potentially before irqs will work 464 * 465 * The gpio chip automatically be released when the device is unbound. 466 * 467 * Returns: 468 * A negative errno if the chip can't be registered, such as because the 469 * gc->base is invalid or already associated with a different chip. 470 * Otherwise it returns zero as a success code. 471 */ 472 int devm_gpiochip_add_data_with_key(struct device *dev, struct gpio_chip *gc, void *data, 473 struct lock_class_key *lock_key, 474 struct lock_class_key *request_key) 475 { 476 int ret; 477 478 ret = gpiochip_add_data_with_key(gc, data, lock_key, request_key); 479 if (ret < 0) 480 return ret; 481 482 return devm_add_action_or_reset(dev, devm_gpio_chip_release, gc); 483 } 484 EXPORT_SYMBOL_GPL(devm_gpiochip_add_data_with_key); 485