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/device.h> 10 #include <linux/err.h> 11 #include <linux/export.h> 12 #include <linux/gfp.h> 13 #include <linux/types.h> 14 15 #include <linux/gpio/consumer.h> 16 17 #include "gpiolib.h" 18 19 struct fwnode_handle; 20 struct lock_class_key; 21 22 static void devm_gpiod_release(struct device *dev, void *res) 23 { 24 struct gpio_desc **desc = res; 25 26 gpiod_put(*desc); 27 } 28 29 static int devm_gpiod_match(struct device *dev, void *res, void *data) 30 { 31 struct gpio_desc **this = res, **gpio = data; 32 33 return *this == *gpio; 34 } 35 36 static void devm_gpiod_release_array(struct device *dev, void *res) 37 { 38 struct gpio_descs **descs = res; 39 40 gpiod_put_array(*descs); 41 } 42 43 static int devm_gpiod_match_array(struct device *dev, void *res, void *data) 44 { 45 struct gpio_descs **this = res, **gpios = data; 46 47 return *this == *gpios; 48 } 49 50 /** 51 * devm_gpiod_get - Resource-managed gpiod_get() 52 * @dev: GPIO consumer 53 * @con_id: function within the GPIO consumer 54 * @flags: optional GPIO initialization flags 55 * 56 * Managed gpiod_get(). GPIO descriptors returned from this function are 57 * automatically disposed on driver detach. See gpiod_get() for detailed 58 * information about behavior and return values. 59 * 60 * Returns: 61 * The GPIO descriptor corresponding to the function @con_id of device 62 * dev, %-ENOENT if no GPIO has been assigned to the requested function, or 63 * another IS_ERR() code if an error occurred while trying to acquire the GPIO. 64 */ 65 struct gpio_desc *__must_check devm_gpiod_get(struct device *dev, 66 const char *con_id, 67 enum gpiod_flags flags) 68 { 69 return devm_gpiod_get_index(dev, con_id, 0, flags); 70 } 71 EXPORT_SYMBOL_GPL(devm_gpiod_get); 72 73 /** 74 * devm_gpiod_get_optional - Resource-managed gpiod_get_optional() 75 * @dev: GPIO consumer 76 * @con_id: function within the GPIO consumer 77 * @flags: optional GPIO initialization flags 78 * 79 * Managed gpiod_get_optional(). GPIO descriptors returned from this function 80 * are automatically disposed on driver detach. See gpiod_get_optional() for 81 * detailed information about behavior and return values. 82 * 83 * Returns: 84 * The GPIO descriptor corresponding to the function @con_id of device 85 * dev, NULL if no GPIO has been assigned to the requested function, or 86 * another IS_ERR() code if an error occurred while trying to acquire the GPIO. 87 */ 88 struct gpio_desc *__must_check devm_gpiod_get_optional(struct device *dev, 89 const char *con_id, 90 enum gpiod_flags flags) 91 { 92 return devm_gpiod_get_index_optional(dev, con_id, 0, flags); 93 } 94 EXPORT_SYMBOL_GPL(devm_gpiod_get_optional); 95 96 /** 97 * devm_gpiod_get_index - Resource-managed gpiod_get_index() 98 * @dev: GPIO consumer 99 * @con_id: function within the GPIO consumer 100 * @idx: index of the GPIO to obtain in the consumer 101 * @flags: optional GPIO initialization flags 102 * 103 * Managed gpiod_get_index(). GPIO descriptors returned from this function are 104 * automatically disposed on driver detach. See gpiod_get_index() for detailed 105 * information about behavior and return values. 106 * 107 * Returns: 108 * The GPIO descriptor corresponding to the function @con_id of device 109 * dev, %-ENOENT if no GPIO has been assigned to the requested function, or 110 * another IS_ERR() code if an error occurred while trying to acquire the GPIO. 111 */ 112 struct gpio_desc *__must_check devm_gpiod_get_index(struct device *dev, 113 const char *con_id, 114 unsigned int idx, 115 enum gpiod_flags flags) 116 { 117 struct gpio_desc **dr; 118 struct gpio_desc *desc; 119 120 desc = gpiod_get_index(dev, con_id, idx, flags); 121 if (IS_ERR(desc)) 122 return desc; 123 124 /* 125 * For non-exclusive GPIO descriptors, check if this descriptor is 126 * already under resource management by this device. 127 */ 128 if (flags & GPIOD_FLAGS_BIT_NONEXCLUSIVE) { 129 struct devres *dres; 130 131 dres = devres_find(dev, devm_gpiod_release, 132 devm_gpiod_match, &desc); 133 if (dres) 134 return desc; 135 } 136 137 dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *), 138 GFP_KERNEL); 139 if (!dr) { 140 gpiod_put(desc); 141 return ERR_PTR(-ENOMEM); 142 } 143 144 *dr = desc; 145 devres_add(dev, dr); 146 147 return desc; 148 } 149 EXPORT_SYMBOL_GPL(devm_gpiod_get_index); 150 151 /** 152 * devm_fwnode_gpiod_get_index - get a GPIO descriptor from a given node 153 * @dev: GPIO consumer 154 * @fwnode: firmware node containing GPIO reference 155 * @con_id: function within the GPIO consumer 156 * @index: index of the GPIO to obtain in the consumer 157 * @flags: GPIO initialization flags 158 * @label: label to attach to the requested GPIO 159 * 160 * GPIO descriptors returned from this function are automatically disposed on 161 * driver detach. 162 * 163 * Returns: 164 * The GPIO descriptor corresponding to the function @con_id of device 165 * dev, %-ENOENT if no GPIO has been assigned to the requested function, or 166 * another IS_ERR() code if an error occurred while trying to acquire the GPIO. 167 */ 168 struct gpio_desc *devm_fwnode_gpiod_get_index(struct device *dev, 169 struct fwnode_handle *fwnode, 170 const char *con_id, int index, 171 enum gpiod_flags flags, 172 const char *label) 173 { 174 struct gpio_desc **dr; 175 struct gpio_desc *desc; 176 177 dr = devres_alloc(devm_gpiod_release, sizeof(struct gpio_desc *), 178 GFP_KERNEL); 179 if (!dr) 180 return ERR_PTR(-ENOMEM); 181 182 desc = gpiod_find_and_request(dev, fwnode, con_id, index, flags, label, false); 183 if (IS_ERR(desc)) { 184 devres_free(dr); 185 return desc; 186 } 187 188 *dr = desc; 189 devres_add(dev, dr); 190 191 return desc; 192 } 193 EXPORT_SYMBOL_GPL(devm_fwnode_gpiod_get_index); 194 195 /** 196 * devm_gpiod_get_index_optional - Resource-managed gpiod_get_index_optional() 197 * @dev: GPIO consumer 198 * @con_id: function within the GPIO consumer 199 * @index: index of the GPIO to obtain in the consumer 200 * @flags: optional GPIO initialization flags 201 * 202 * Managed gpiod_get_index_optional(). GPIO descriptors returned from this 203 * function are automatically disposed on driver detach. See 204 * gpiod_get_index_optional() for detailed information about behavior and 205 * return values. 206 * 207 * Returns: 208 * The GPIO descriptor corresponding to the function @con_id of device 209 * dev, %NULL if no GPIO has been assigned to the requested function, or 210 * another IS_ERR() code if an error occurred while trying to acquire the GPIO. 211 */ 212 struct gpio_desc *__must_check devm_gpiod_get_index_optional(struct device *dev, 213 const char *con_id, 214 unsigned int index, 215 enum gpiod_flags flags) 216 { 217 struct gpio_desc *desc; 218 219 desc = devm_gpiod_get_index(dev, con_id, index, flags); 220 if (gpiod_not_found(desc)) 221 return NULL; 222 223 return desc; 224 } 225 EXPORT_SYMBOL_GPL(devm_gpiod_get_index_optional); 226 227 /** 228 * devm_gpiod_get_array - Resource-managed gpiod_get_array() 229 * @dev: GPIO consumer 230 * @con_id: function within the GPIO consumer 231 * @flags: optional GPIO initialization flags 232 * 233 * Managed gpiod_get_array(). GPIO descriptors returned from this function are 234 * automatically disposed on driver detach. See gpiod_get_array() for detailed 235 * information about behavior and return values. 236 * 237 * Returns: 238 * The GPIO descriptors corresponding to the function @con_id of device 239 * dev, %-ENOENT if no GPIO has been assigned to the requested function, 240 * or another IS_ERR() code if an error occurred while trying to acquire 241 * the GPIOs. 242 */ 243 struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev, 244 const char *con_id, 245 enum gpiod_flags flags) 246 { 247 struct gpio_descs **dr; 248 struct gpio_descs *descs; 249 250 dr = devres_alloc(devm_gpiod_release_array, 251 sizeof(struct gpio_descs *), GFP_KERNEL); 252 if (!dr) 253 return ERR_PTR(-ENOMEM); 254 255 descs = gpiod_get_array(dev, con_id, flags); 256 if (IS_ERR(descs)) { 257 devres_free(dr); 258 return descs; 259 } 260 261 *dr = descs; 262 devres_add(dev, dr); 263 264 return descs; 265 } 266 EXPORT_SYMBOL_GPL(devm_gpiod_get_array); 267 268 /** 269 * devm_gpiod_get_array_optional - Resource-managed gpiod_get_array_optional() 270 * @dev: GPIO consumer 271 * @con_id: function within the GPIO consumer 272 * @flags: optional GPIO initialization flags 273 * 274 * Managed gpiod_get_array_optional(). GPIO descriptors returned from this 275 * function are automatically disposed on driver detach. 276 * See gpiod_get_array_optional() for detailed information about behavior and 277 * return values. 278 * 279 * Returns: 280 * The GPIO descriptors corresponding to the function @con_id of device 281 * dev, %NULL if no GPIO has been assigned to the requested function, 282 * or another IS_ERR() code if an error occurred while trying to acquire 283 * the GPIOs. 284 */ 285 struct gpio_descs *__must_check 286 devm_gpiod_get_array_optional(struct device *dev, const char *con_id, 287 enum gpiod_flags flags) 288 { 289 struct gpio_descs *descs; 290 291 descs = devm_gpiod_get_array(dev, con_id, flags); 292 if (gpiod_not_found(descs)) 293 return NULL; 294 295 return descs; 296 } 297 EXPORT_SYMBOL_GPL(devm_gpiod_get_array_optional); 298 299 /** 300 * devm_gpiod_put - Resource-managed gpiod_put() 301 * @dev: GPIO consumer 302 * @desc: GPIO descriptor to dispose of 303 * 304 * Dispose of a GPIO descriptor obtained with devm_gpiod_get() or 305 * devm_gpiod_get_index(). Normally this function will not be called as the GPIO 306 * will be disposed of by the resource management code. 307 */ 308 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc) 309 { 310 WARN_ON(devres_release(dev, devm_gpiod_release, devm_gpiod_match, 311 &desc)); 312 } 313 EXPORT_SYMBOL_GPL(devm_gpiod_put); 314 315 /** 316 * devm_gpiod_unhinge - Remove resource management from a gpio descriptor 317 * @dev: GPIO consumer 318 * @desc: GPIO descriptor to remove resource management from 319 * 320 * Remove resource management from a GPIO descriptor. This is needed when 321 * you want to hand over lifecycle management of a descriptor to another 322 * mechanism. 323 */ 324 325 void devm_gpiod_unhinge(struct device *dev, struct gpio_desc *desc) 326 { 327 int ret; 328 329 if (IS_ERR_OR_NULL(desc)) 330 return; 331 ret = devres_destroy(dev, devm_gpiod_release, 332 devm_gpiod_match, &desc); 333 /* 334 * If the GPIO descriptor is requested as nonexclusive, we 335 * may call this function several times on the same descriptor 336 * so it is OK if devres_destroy() returns -ENOENT. 337 */ 338 if (ret == -ENOENT) 339 return; 340 /* Anything else we should warn about */ 341 WARN_ON(ret); 342 } 343 EXPORT_SYMBOL_GPL(devm_gpiod_unhinge); 344 345 /** 346 * devm_gpiod_put_array - Resource-managed gpiod_put_array() 347 * @dev: GPIO consumer 348 * @descs: GPIO descriptor array to dispose of 349 * 350 * Dispose of an array of GPIO descriptors obtained with devm_gpiod_get_array(). 351 * Normally this function will not be called as the GPIOs will be disposed of 352 * by the resource management code. 353 */ 354 void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs) 355 { 356 WARN_ON(devres_release(dev, devm_gpiod_release_array, 357 devm_gpiod_match_array, &descs)); 358 } 359 EXPORT_SYMBOL_GPL(devm_gpiod_put_array); 360 361 static void devm_gpio_chip_release(void *data) 362 { 363 struct gpio_chip *gc = data; 364 365 gpiochip_remove(gc); 366 } 367 368 /** 369 * devm_gpiochip_add_data_with_key() - Resource managed gpiochip_add_data_with_key() 370 * @dev: pointer to the device that gpio_chip belongs to. 371 * @gc: the GPIO chip to register 372 * @data: driver-private data associated with this chip 373 * @lock_key: lockdep class for IRQ lock 374 * @request_key: lockdep class for IRQ request 375 * 376 * Context: potentially before irqs will work 377 * 378 * The gpio chip automatically be released when the device is unbound. 379 * 380 * Returns: 381 * A negative errno if the chip can't be registered, such as because the 382 * gc->base is invalid or already associated with a different chip. 383 * Otherwise it returns zero as a success code. 384 */ 385 int devm_gpiochip_add_data_with_key(struct device *dev, struct gpio_chip *gc, void *data, 386 struct lock_class_key *lock_key, 387 struct lock_class_key *request_key) 388 { 389 int ret; 390 391 ret = gpiochip_add_data_with_key(gc, data, lock_key, request_key); 392 if (ret < 0) 393 return ret; 394 395 return devm_add_action_or_reset(dev, devm_gpio_chip_release, gc); 396 } 397 EXPORT_SYMBOL_GPL(devm_gpiochip_add_data_with_key); 398