xref: /openbmc/linux/drivers/gpio/gpiolib-devres.c (revision 32ced09d)
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 					      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 (IS_ERR(desc)) {
250 		if (PTR_ERR(desc) == -ENOENT)
251 			return NULL;
252 	}
253 
254 	return desc;
255 }
256 EXPORT_SYMBOL_GPL(devm_gpiod_get_index_optional);
257 
258 /**
259  * devm_gpiod_get_array - Resource-managed gpiod_get_array()
260  * @dev:	GPIO consumer
261  * @con_id:	function within the GPIO consumer
262  * @flags:	optional GPIO initialization flags
263  *
264  * Managed gpiod_get_array(). GPIO descriptors returned from this function are
265  * automatically disposed on driver detach. See gpiod_get_array() for detailed
266  * information about behavior and return values.
267  */
268 struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev,
269 						     const char *con_id,
270 						     enum gpiod_flags flags)
271 {
272 	struct gpio_descs **dr;
273 	struct gpio_descs *descs;
274 
275 	dr = devres_alloc(devm_gpiod_release_array,
276 			  sizeof(struct gpio_descs *), GFP_KERNEL);
277 	if (!dr)
278 		return ERR_PTR(-ENOMEM);
279 
280 	descs = gpiod_get_array(dev, con_id, flags);
281 	if (IS_ERR(descs)) {
282 		devres_free(dr);
283 		return descs;
284 	}
285 
286 	*dr = descs;
287 	devres_add(dev, dr);
288 
289 	return descs;
290 }
291 EXPORT_SYMBOL_GPL(devm_gpiod_get_array);
292 
293 /**
294  * devm_gpiod_get_array_optional - Resource-managed gpiod_get_array_optional()
295  * @dev:	GPIO consumer
296  * @con_id:	function within the GPIO consumer
297  * @flags:	optional GPIO initialization flags
298  *
299  * Managed gpiod_get_array_optional(). GPIO descriptors returned from this
300  * function are automatically disposed on driver detach.
301  * See gpiod_get_array_optional() for detailed information about behavior and
302  * return values.
303  */
304 struct gpio_descs *__must_check
305 devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
306 			      enum gpiod_flags flags)
307 {
308 	struct gpio_descs *descs;
309 
310 	descs = devm_gpiod_get_array(dev, con_id, flags);
311 	if (PTR_ERR(descs) == -ENOENT)
312 		return NULL;
313 
314 	return descs;
315 }
316 EXPORT_SYMBOL_GPL(devm_gpiod_get_array_optional);
317 
318 /**
319  * devm_gpiod_put - Resource-managed gpiod_put()
320  * @dev:	GPIO consumer
321  * @desc:	GPIO descriptor to dispose of
322  *
323  * Dispose of a GPIO descriptor obtained with devm_gpiod_get() or
324  * devm_gpiod_get_index(). Normally this function will not be called as the GPIO
325  * will be disposed of by the resource management code.
326  */
327 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
328 {
329 	WARN_ON(devres_release(dev, devm_gpiod_release, devm_gpiod_match,
330 		&desc));
331 }
332 EXPORT_SYMBOL_GPL(devm_gpiod_put);
333 
334 /**
335  * devm_gpiod_unhinge - Remove resource management from a gpio descriptor
336  * @dev:	GPIO consumer
337  * @desc:	GPIO descriptor to remove resource management from
338  *
339  * Remove resource management from a GPIO descriptor. This is needed when
340  * you want to hand over lifecycle management of a descriptor to another
341  * mechanism.
342  */
343 
344 void devm_gpiod_unhinge(struct device *dev, struct gpio_desc *desc)
345 {
346 	int ret;
347 
348 	if (IS_ERR_OR_NULL(desc))
349 		return;
350 	ret = devres_destroy(dev, devm_gpiod_release,
351 			     devm_gpiod_match, &desc);
352 	/*
353 	 * If the GPIO descriptor is requested as nonexclusive, we
354 	 * may call this function several times on the same descriptor
355 	 * so it is OK if devres_destroy() returns -ENOENT.
356 	 */
357 	if (ret == -ENOENT)
358 		return;
359 	/* Anything else we should warn about */
360 	WARN_ON(ret);
361 }
362 EXPORT_SYMBOL_GPL(devm_gpiod_unhinge);
363 
364 /**
365  * devm_gpiod_put_array - Resource-managed gpiod_put_array()
366  * @dev:	GPIO consumer
367  * @descs:	GPIO descriptor array to dispose of
368  *
369  * Dispose of an array of GPIO descriptors obtained with devm_gpiod_get_array().
370  * Normally this function will not be called as the GPIOs will be disposed of
371  * by the resource management code.
372  */
373 void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs)
374 {
375 	WARN_ON(devres_release(dev, devm_gpiod_release_array,
376 			       devm_gpiod_match_array, &descs));
377 }
378 EXPORT_SYMBOL_GPL(devm_gpiod_put_array);
379 
380 
381 
382 
383 static void devm_gpio_release(struct device *dev, void *res)
384 {
385 	unsigned *gpio = res;
386 
387 	gpio_free(*gpio);
388 }
389 
390 static int devm_gpio_match(struct device *dev, void *res, void *data)
391 {
392 	unsigned *this = res, *gpio = data;
393 
394 	return *this == *gpio;
395 }
396 
397 /**
398  *      devm_gpio_request - request a GPIO for a managed device
399  *      @dev: device to request the GPIO for
400  *      @gpio: GPIO to allocate
401  *      @label: the name of the requested GPIO
402  *
403  *      Except for the extra @dev argument, this function takes the
404  *      same arguments and performs the same function as
405  *      gpio_request().  GPIOs requested with this function will be
406  *      automatically freed on driver detach.
407  *
408  *      If an GPIO allocated with this function needs to be freed
409  *      separately, devm_gpio_free() must be used.
410  */
411 
412 int devm_gpio_request(struct device *dev, unsigned gpio, const char *label)
413 {
414 	unsigned *dr;
415 	int rc;
416 
417 	dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL);
418 	if (!dr)
419 		return -ENOMEM;
420 
421 	rc = gpio_request(gpio, label);
422 	if (rc) {
423 		devres_free(dr);
424 		return rc;
425 	}
426 
427 	*dr = gpio;
428 	devres_add(dev, dr);
429 
430 	return 0;
431 }
432 EXPORT_SYMBOL_GPL(devm_gpio_request);
433 
434 /**
435  *	devm_gpio_request_one - request a single GPIO with initial setup
436  *	@dev:   device to request for
437  *	@gpio:	the GPIO number
438  *	@flags:	GPIO configuration as specified by GPIOF_*
439  *	@label:	a literal description string of this GPIO
440  */
441 int devm_gpio_request_one(struct device *dev, unsigned gpio,
442 			  unsigned long flags, const char *label)
443 {
444 	unsigned *dr;
445 	int rc;
446 
447 	dr = devres_alloc(devm_gpio_release, sizeof(unsigned), GFP_KERNEL);
448 	if (!dr)
449 		return -ENOMEM;
450 
451 	rc = gpio_request_one(gpio, flags, label);
452 	if (rc) {
453 		devres_free(dr);
454 		return rc;
455 	}
456 
457 	*dr = gpio;
458 	devres_add(dev, dr);
459 
460 	return 0;
461 }
462 EXPORT_SYMBOL_GPL(devm_gpio_request_one);
463 
464 /**
465  *      devm_gpio_free - free a GPIO
466  *      @dev: device to free GPIO for
467  *      @gpio: GPIO to free
468  *
469  *      Except for the extra @dev argument, this function takes the
470  *      same arguments and performs the same function as gpio_free().
471  *      This function instead of gpio_free() should be used to manually
472  *      free GPIOs allocated with devm_gpio_request().
473  */
474 void devm_gpio_free(struct device *dev, unsigned int gpio)
475 {
476 
477 	WARN_ON(devres_release(dev, devm_gpio_release, devm_gpio_match,
478 		&gpio));
479 }
480 EXPORT_SYMBOL_GPL(devm_gpio_free);
481