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