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: *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: *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, idx: 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, index: 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(ptr: 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, release: devm_gpiod_release, |
113 | match: devm_gpiod_match, match_data: &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(error: -ENOMEM); |
123 | } |
124 | |
125 | *dr = desc; |
126 | devres_add(dev, res: 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(error: -ENOMEM); |
160 | |
161 | desc = fwnode_gpiod_get_index(fwnode, con_id, index, flags, label); |
162 | if (IS_ERR(ptr: desc)) { |
163 | devres_free(res: dr); |
164 | return desc; |
165 | } |
166 | |
167 | *dr = desc; |
168 | devres_add(dev, res: 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(error: -ENOMEM); |
222 | |
223 | descs = gpiod_get_array(dev, con_id, flags); |
224 | if (IS_ERR(ptr: descs)) { |
225 | devres_free(res: dr); |
226 | return descs; |
227 | } |
228 | |
229 | *dr = descs; |
230 | devres_add(dev, res: 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(ptr: desc)) |
292 | return; |
293 | ret = devres_destroy(dev, release: devm_gpiod_release, |
294 | match: devm_gpiod_match, match_data: &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: *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(res: dr); |
353 | return rc; |
354 | } |
355 | |
356 | *dr = gpio; |
357 | devres_add(dev, res: 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(res: dr); |
383 | return rc; |
384 | } |
385 | |
386 | *dr = gpio; |
387 | devres_add(dev, res: 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 | |