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_fwnode_gpiod_get_index - get a GPIO descriptor from a given node 134 * @dev: GPIO consumer 135 * @fwnode: firmware node containing GPIO reference 136 * @con_id: function within the GPIO consumer 137 * @index: index of the GPIO to obtain in the consumer 138 * @flags: GPIO initialization flags 139 * @label: label to attach to the requested GPIO 140 * 141 * GPIO descriptors returned from this function are automatically disposed on 142 * driver detach. 143 * 144 * On successful request the GPIO pin is configured in accordance with 145 * provided @flags. 146 */ 147 struct gpio_desc *devm_fwnode_gpiod_get_index(struct device *dev, 148 struct fwnode_handle *fwnode, 149 const char *con_id, int index, 150 enum gpiod_flags flags, 151 const char *label) 152 { 153 struct gpio_desc **dr; 154 struct gpio_desc *desc; 155 156 dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *), 157 GFP_KERNEL); 158 if (!dr) 159 return ERR_PTR(-ENOMEM); 160 161 desc = fwnode_gpiod_get_index(fwnode, con_id, index, flags, label); 162 if (IS_ERR(desc)) { 163 devres_free(dr); 164 return desc; 165 } 166 167 *dr = desc; 168 devres_add(dev, dr); 169 170 return desc; 171 } 172 EXPORT_SYMBOL_GPL(devm_fwnode_gpiod_get_index); 173 174 /** 175 * devm_gpiod_get_index_optional - Resource-managed gpiod_get_index_optional() 176 * @dev: GPIO consumer 177 * @con_id: function within the GPIO consumer 178 * @index: index of the GPIO to obtain in the consumer 179 * @flags: optional GPIO initialization flags 180 * 181 * Managed gpiod_get_index_optional(). GPIO descriptors returned from this 182 * function are automatically disposed on driver detach. See 183 * gpiod_get_index_optional() for detailed information about behavior and 184 * return values. 185 */ 186 struct gpio_desc *__must_check devm_gpiod_get_index_optional(struct device *dev, 187 const char *con_id, 188 unsigned int index, 189 enum gpiod_flags flags) 190 { 191 struct gpio_desc *desc; 192 193 desc = devm_gpiod_get_index(dev, con_id, index, flags); 194 if (gpiod_not_found(desc)) 195 return NULL; 196 197 return desc; 198 } 199 EXPORT_SYMBOL_GPL(devm_gpiod_get_index_optional); 200 201 /** 202 * devm_gpiod_get_array - Resource-managed gpiod_get_array() 203 * @dev: GPIO consumer 204 * @con_id: function within the GPIO consumer 205 * @flags: optional GPIO initialization flags 206 * 207 * Managed gpiod_get_array(). GPIO descriptors returned from this function are 208 * automatically disposed on driver detach. See gpiod_get_array() for detailed 209 * information about behavior and return values. 210 */ 211 struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev, 212 const char *con_id, 213 enum gpiod_flags flags) 214 { 215 struct gpio_descs **dr; 216 struct gpio_descs *descs; 217 218 dr = devres_alloc(devm_gpiod_release_array, 219 sizeof(struct gpio_descs *), GFP_KERNEL); 220 if (!dr) 221 return ERR_PTR(-ENOMEM); 222 223 descs = gpiod_get_array(dev, con_id, flags); 224 if (IS_ERR(descs)) { 225 devres_free(dr); 226 return descs; 227 } 228 229 *dr = descs; 230 devres_add(dev, dr); 231 232 return descs; 233 } 234 EXPORT_SYMBOL_GPL(devm_gpiod_get_array); 235 236 /** 237 * devm_gpiod_get_array_optional - Resource-managed gpiod_get_array_optional() 238 * @dev: GPIO consumer 239 * @con_id: function within the GPIO consumer 240 * @flags: optional GPIO initialization flags 241 * 242 * Managed gpiod_get_array_optional(). GPIO descriptors returned from this 243 * function are automatically disposed on driver detach. 244 * See gpiod_get_array_optional() for detailed information about behavior and 245 * return values. 246 */ 247 struct gpio_descs *__must_check 248 devm_gpiod_get_array_optional(struct device *dev, const char *con_id, 249 enum gpiod_flags flags) 250 { 251 struct gpio_descs *descs; 252 253 descs = devm_gpiod_get_array(dev, con_id, flags); 254 if (gpiod_not_found(descs)) 255 return NULL; 256 257 return descs; 258 } 259 EXPORT_SYMBOL_GPL(devm_gpiod_get_array_optional); 260 261 /** 262 * devm_gpiod_put - Resource-managed gpiod_put() 263 * @dev: GPIO consumer 264 * @desc: GPIO descriptor to dispose of 265 * 266 * Dispose of a GPIO descriptor obtained with devm_gpiod_get() or 267 * devm_gpiod_get_index(). Normally this function will not be called as the GPIO 268 * will be disposed of by the resource management code. 269 */ 270 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc) 271 { 272 WARN_ON(devres_release(dev, devm_gpiod_release, devm_gpiod_match, 273 &desc)); 274 } 275 EXPORT_SYMBOL_GPL(devm_gpiod_put); 276 277 /** 278 * devm_gpiod_unhinge - Remove resource management from a gpio descriptor 279 * @dev: GPIO consumer 280 * @desc: GPIO descriptor to remove resource management from 281 * 282 * Remove resource management from a GPIO descriptor. This is needed when 283 * you want to hand over lifecycle management of a descriptor to another 284 * mechanism. 285 */ 286 287 void devm_gpiod_unhinge(struct device *dev, struct gpio_desc *desc) 288 { 289 int ret; 290 291 if (IS_ERR_OR_NULL(desc)) 292 return; 293 ret = devres_destroy(dev, devm_gpiod_release, 294 devm_gpiod_match, &desc); 295 /* 296 * If the GPIO descriptor is requested as nonexclusive, we 297 * may call this function several times on the same descriptor 298 * so it is OK if devres_destroy() returns -ENOENT. 299 */ 300 if (ret == -ENOENT) 301 return; 302 /* Anything else we should warn about */ 303 WARN_ON(ret); 304 } 305 EXPORT_SYMBOL_GPL(devm_gpiod_unhinge); 306 307 /** 308 * devm_gpiod_put_array - Resource-managed gpiod_put_array() 309 * @dev: GPIO consumer 310 * @descs: GPIO descriptor array to dispose of 311 * 312 * Dispose of an array of GPIO descriptors obtained with devm_gpiod_get_array(). 313 * Normally this function will not be called as the GPIOs will be disposed of 314 * by the resource management code. 315 */ 316 void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs) 317 { 318 WARN_ON(devres_release(dev, devm_gpiod_release_array, 319 devm_gpiod_match_array, &descs)); 320 } 321 EXPORT_SYMBOL_GPL(devm_gpiod_put_array); 322 323 static void devm_gpio_release(struct device *dev, void *res) 324 { 325 unsigned *gpio = res; 326 327 gpio_free(*gpio); 328 } 329 330 /** 331 * devm_gpio_request - request a GPIO for a managed device 332 * @dev: device to request the GPIO for 333 * @gpio: GPIO to allocate 334 * @label: the name of the requested GPIO 335 * 336 * Except for the extra @dev argument, this function takes the 337 * same arguments and performs the same function as 338 * gpio_request(). GPIOs requested with this function will be 339 * automatically freed on driver detach. 340 */ 341 int devm_gpio_request(struct device *dev, unsigned gpio, const char *label) 342 { 343 unsigned *dr; 344 int rc; 345 346 dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL); 347 if (!dr) 348 return -ENOMEM; 349 350 rc = gpio_request(gpio, label); 351 if (rc) { 352 devres_free(dr); 353 return rc; 354 } 355 356 *dr = gpio; 357 devres_add(dev, dr); 358 359 return 0; 360 } 361 EXPORT_SYMBOL_GPL(devm_gpio_request); 362 363 /** 364 * devm_gpio_request_one - request a single GPIO with initial setup 365 * @dev: device to request for 366 * @gpio: the GPIO number 367 * @flags: GPIO configuration as specified by GPIOF_* 368 * @label: a literal description string of this GPIO 369 */ 370 int devm_gpio_request_one(struct device *dev, unsigned gpio, 371 unsigned long flags, const char *label) 372 { 373 unsigned *dr; 374 int rc; 375 376 dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL); 377 if (!dr) 378 return -ENOMEM; 379 380 rc = gpio_request_one(gpio, flags, label); 381 if (rc) { 382 devres_free(dr); 383 return rc; 384 } 385 386 *dr = gpio; 387 devres_add(dev, dr); 388 389 return 0; 390 } 391 EXPORT_SYMBOL_GPL(devm_gpio_request_one); 392 393 static void devm_gpio_chip_release(void *data) 394 { 395 struct gpio_chip *gc = data; 396 397 gpiochip_remove(gc); 398 } 399 400 /** 401 * devm_gpiochip_add_data_with_key() - Resource managed gpiochip_add_data_with_key() 402 * @dev: pointer to the device that gpio_chip belongs to. 403 * @gc: the GPIO chip to register 404 * @data: driver-private data associated with this chip 405 * @lock_key: lockdep class for IRQ lock 406 * @request_key: lockdep class for IRQ request 407 * 408 * Context: potentially before irqs will work 409 * 410 * The gpio chip automatically be released when the device is unbound. 411 * 412 * Returns: 413 * A negative errno if the chip can't be registered, such as because the 414 * gc->base is invalid or already associated with a different chip. 415 * Otherwise it returns zero as a success code. 416 */ 417 int devm_gpiochip_add_data_with_key(struct device *dev, struct gpio_chip *gc, void *data, 418 struct lock_class_key *lock_key, 419 struct lock_class_key *request_key) 420 { 421 int ret; 422 423 ret = gpiochip_add_data_with_key(gc, data, lock_key, request_key); 424 if (ret < 0) 425 return ret; 426 427 return devm_add_action_or_reset(dev, devm_gpio_chip_release, gc); 428 } 429 EXPORT_SYMBOL_GPL(devm_gpiochip_add_data_with_key); 430