Merge tag 'gpio-v4.20-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw...
[sfrench/cifs-2.6.git] / include / linux / gpio / consumer.h
1 /* SPDX-License-Identifier: GPL-2.0 */
2 #ifndef __LINUX_GPIO_CONSUMER_H
3 #define __LINUX_GPIO_CONSUMER_H
4
5 #include <linux/bug.h>
6 #include <linux/err.h>
7 #include <linux/kernel.h>
8
9 struct device;
10
11 /**
12  * Opaque descriptor for a GPIO. These are obtained using gpiod_get() and are
13  * preferable to the old integer-based handles.
14  *
15  * Contrary to integers, a pointer to a gpio_desc is guaranteed to be valid
16  * until the GPIO is released.
17  */
18 struct gpio_desc;
19
20 /**
21  * Opaque descriptor for a structure of GPIO array attributes.  This structure
22  * is attached to struct gpiod_descs obtained from gpiod_get_array() and can be
23  * passed back to get/set array functions in order to activate fast processing
24  * path if applicable.
25  */
26 struct gpio_array;
27
28 /**
29  * Struct containing an array of descriptors that can be obtained using
30  * gpiod_get_array().
31  */
32 struct gpio_descs {
33         struct gpio_array *info;
34         unsigned int ndescs;
35         struct gpio_desc *desc[];
36 };
37
38 #define GPIOD_FLAGS_BIT_DIR_SET         BIT(0)
39 #define GPIOD_FLAGS_BIT_DIR_OUT         BIT(1)
40 #define GPIOD_FLAGS_BIT_DIR_VAL         BIT(2)
41 #define GPIOD_FLAGS_BIT_OPEN_DRAIN      BIT(3)
42 #define GPIOD_FLAGS_BIT_NONEXCLUSIVE    BIT(4)
43
44 /**
45  * Optional flags that can be passed to one of gpiod_* to configure direction
46  * and output value. These values cannot be OR'd.
47  */
48 enum gpiod_flags {
49         GPIOD_ASIS      = 0,
50         GPIOD_IN        = GPIOD_FLAGS_BIT_DIR_SET,
51         GPIOD_OUT_LOW   = GPIOD_FLAGS_BIT_DIR_SET | GPIOD_FLAGS_BIT_DIR_OUT,
52         GPIOD_OUT_HIGH  = GPIOD_FLAGS_BIT_DIR_SET | GPIOD_FLAGS_BIT_DIR_OUT |
53                           GPIOD_FLAGS_BIT_DIR_VAL,
54         GPIOD_OUT_LOW_OPEN_DRAIN = GPIOD_OUT_LOW | GPIOD_FLAGS_BIT_OPEN_DRAIN,
55         GPIOD_OUT_HIGH_OPEN_DRAIN = GPIOD_OUT_HIGH | GPIOD_FLAGS_BIT_OPEN_DRAIN,
56 };
57
58 #ifdef CONFIG_GPIOLIB
59
60 /* Return the number of GPIOs associated with a device / function */
61 int gpiod_count(struct device *dev, const char *con_id);
62
63 /* Acquire and dispose GPIOs */
64 struct gpio_desc *__must_check gpiod_get(struct device *dev,
65                                          const char *con_id,
66                                          enum gpiod_flags flags);
67 struct gpio_desc *__must_check gpiod_get_index(struct device *dev,
68                                                const char *con_id,
69                                                unsigned int idx,
70                                                enum gpiod_flags flags);
71 struct gpio_desc *__must_check gpiod_get_optional(struct device *dev,
72                                                   const char *con_id,
73                                                   enum gpiod_flags flags);
74 struct gpio_desc *__must_check gpiod_get_index_optional(struct device *dev,
75                                                         const char *con_id,
76                                                         unsigned int index,
77                                                         enum gpiod_flags flags);
78 struct gpio_descs *__must_check gpiod_get_array(struct device *dev,
79                                                 const char *con_id,
80                                                 enum gpiod_flags flags);
81 struct gpio_descs *__must_check gpiod_get_array_optional(struct device *dev,
82                                                         const char *con_id,
83                                                         enum gpiod_flags flags);
84 void gpiod_put(struct gpio_desc *desc);
85 void gpiod_put_array(struct gpio_descs *descs);
86
87 struct gpio_desc *__must_check devm_gpiod_get(struct device *dev,
88                                               const char *con_id,
89                                               enum gpiod_flags flags);
90 struct gpio_desc *__must_check devm_gpiod_get_index(struct device *dev,
91                                                     const char *con_id,
92                                                     unsigned int idx,
93                                                     enum gpiod_flags flags);
94 struct gpio_desc *__must_check devm_gpiod_get_optional(struct device *dev,
95                                                        const char *con_id,
96                                                        enum gpiod_flags flags);
97 struct gpio_desc *__must_check
98 devm_gpiod_get_index_optional(struct device *dev, const char *con_id,
99                               unsigned int index, enum gpiod_flags flags);
100 struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev,
101                                                      const char *con_id,
102                                                      enum gpiod_flags flags);
103 struct gpio_descs *__must_check
104 devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
105                               enum gpiod_flags flags);
106 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc);
107 void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs);
108
109 int gpiod_get_direction(struct gpio_desc *desc);
110 int gpiod_direction_input(struct gpio_desc *desc);
111 int gpiod_direction_output(struct gpio_desc *desc, int value);
112 int gpiod_direction_output_raw(struct gpio_desc *desc, int value);
113
114 /* Value get/set from non-sleeping context */
115 int gpiod_get_value(const struct gpio_desc *desc);
116 int gpiod_get_array_value(unsigned int array_size,
117                           struct gpio_desc **desc_array,
118                           struct gpio_array *array_info,
119                           unsigned long *value_bitmap);
120 void gpiod_set_value(struct gpio_desc *desc, int value);
121 int gpiod_set_array_value(unsigned int array_size,
122                           struct gpio_desc **desc_array,
123                           struct gpio_array *array_info,
124                           unsigned long *value_bitmap);
125 int gpiod_get_raw_value(const struct gpio_desc *desc);
126 int gpiod_get_raw_array_value(unsigned int array_size,
127                               struct gpio_desc **desc_array,
128                               struct gpio_array *array_info,
129                               unsigned long *value_bitmap);
130 void gpiod_set_raw_value(struct gpio_desc *desc, int value);
131 int gpiod_set_raw_array_value(unsigned int array_size,
132                               struct gpio_desc **desc_array,
133                               struct gpio_array *array_info,
134                               unsigned long *value_bitmap);
135
136 /* Value get/set from sleeping context */
137 int gpiod_get_value_cansleep(const struct gpio_desc *desc);
138 int gpiod_get_array_value_cansleep(unsigned int array_size,
139                                    struct gpio_desc **desc_array,
140                                    struct gpio_array *array_info,
141                                    unsigned long *value_bitmap);
142 void gpiod_set_value_cansleep(struct gpio_desc *desc, int value);
143 int gpiod_set_array_value_cansleep(unsigned int array_size,
144                                    struct gpio_desc **desc_array,
145                                    struct gpio_array *array_info,
146                                    unsigned long *value_bitmap);
147 int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc);
148 int gpiod_get_raw_array_value_cansleep(unsigned int array_size,
149                                        struct gpio_desc **desc_array,
150                                        struct gpio_array *array_info,
151                                        unsigned long *value_bitmap);
152 void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value);
153 int gpiod_set_raw_array_value_cansleep(unsigned int array_size,
154                                        struct gpio_desc **desc_array,
155                                        struct gpio_array *array_info,
156                                        unsigned long *value_bitmap);
157
158 int gpiod_set_debounce(struct gpio_desc *desc, unsigned debounce);
159 int gpiod_set_transitory(struct gpio_desc *desc, bool transitory);
160
161 int gpiod_is_active_low(const struct gpio_desc *desc);
162 int gpiod_cansleep(const struct gpio_desc *desc);
163
164 int gpiod_to_irq(const struct gpio_desc *desc);
165 void gpiod_set_consumer_name(struct gpio_desc *desc, const char *name);
166
167 /* Convert between the old gpio_ and new gpiod_ interfaces */
168 struct gpio_desc *gpio_to_desc(unsigned gpio);
169 int desc_to_gpio(const struct gpio_desc *desc);
170
171 /* Child properties interface */
172 struct device_node;
173 struct fwnode_handle;
174
175 struct gpio_desc *devm_gpiod_get_from_of_node(struct device *dev,
176                                               struct device_node *node,
177                                               const char *propname, int index,
178                                               enum gpiod_flags dflags,
179                                               const char *label);
180 struct gpio_desc *fwnode_get_named_gpiod(struct fwnode_handle *fwnode,
181                                          const char *propname, int index,
182                                          enum gpiod_flags dflags,
183                                          const char *label);
184 struct gpio_desc *devm_fwnode_get_index_gpiod_from_child(struct device *dev,
185                                                 const char *con_id, int index,
186                                                 struct fwnode_handle *child,
187                                                 enum gpiod_flags flags,
188                                                 const char *label);
189
190 #else /* CONFIG_GPIOLIB */
191
192 static inline int gpiod_count(struct device *dev, const char *con_id)
193 {
194         return 0;
195 }
196
197 static inline struct gpio_desc *__must_check gpiod_get(struct device *dev,
198                                                        const char *con_id,
199                                                        enum gpiod_flags flags)
200 {
201         return ERR_PTR(-ENOSYS);
202 }
203 static inline struct gpio_desc *__must_check
204 gpiod_get_index(struct device *dev,
205                 const char *con_id,
206                 unsigned int idx,
207                 enum gpiod_flags flags)
208 {
209         return ERR_PTR(-ENOSYS);
210 }
211
212 static inline struct gpio_desc *__must_check
213 gpiod_get_optional(struct device *dev, const char *con_id,
214                    enum gpiod_flags flags)
215 {
216         return NULL;
217 }
218
219 static inline struct gpio_desc *__must_check
220 gpiod_get_index_optional(struct device *dev, const char *con_id,
221                          unsigned int index, enum gpiod_flags flags)
222 {
223         return NULL;
224 }
225
226 static inline struct gpio_descs *__must_check
227 gpiod_get_array(struct device *dev, const char *con_id,
228                 enum gpiod_flags flags)
229 {
230         return ERR_PTR(-ENOSYS);
231 }
232
233 static inline struct gpio_descs *__must_check
234 gpiod_get_array_optional(struct device *dev, const char *con_id,
235                          enum gpiod_flags flags)
236 {
237         return NULL;
238 }
239
240 static inline void gpiod_put(struct gpio_desc *desc)
241 {
242         might_sleep();
243
244         /* GPIO can never have been requested */
245         WARN_ON(1);
246 }
247
248 static inline void gpiod_put_array(struct gpio_descs *descs)
249 {
250         might_sleep();
251
252         /* GPIO can never have been requested */
253         WARN_ON(1);
254 }
255
256 static inline struct gpio_desc *__must_check
257 devm_gpiod_get(struct device *dev,
258                  const char *con_id,
259                  enum gpiod_flags flags)
260 {
261         return ERR_PTR(-ENOSYS);
262 }
263 static inline
264 struct gpio_desc *__must_check
265 devm_gpiod_get_index(struct device *dev,
266                        const char *con_id,
267                        unsigned int idx,
268                        enum gpiod_flags flags)
269 {
270         return ERR_PTR(-ENOSYS);
271 }
272
273 static inline struct gpio_desc *__must_check
274 devm_gpiod_get_optional(struct device *dev, const char *con_id,
275                           enum gpiod_flags flags)
276 {
277         return NULL;
278 }
279
280 static inline struct gpio_desc *__must_check
281 devm_gpiod_get_index_optional(struct device *dev, const char *con_id,
282                                 unsigned int index, enum gpiod_flags flags)
283 {
284         return NULL;
285 }
286
287 static inline struct gpio_descs *__must_check
288 devm_gpiod_get_array(struct device *dev, const char *con_id,
289                      enum gpiod_flags flags)
290 {
291         return ERR_PTR(-ENOSYS);
292 }
293
294 static inline struct gpio_descs *__must_check
295 devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
296                               enum gpiod_flags flags)
297 {
298         return NULL;
299 }
300
301 static inline void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
302 {
303         might_sleep();
304
305         /* GPIO can never have been requested */
306         WARN_ON(1);
307 }
308
309 static inline void devm_gpiod_put_array(struct device *dev,
310                                         struct gpio_descs *descs)
311 {
312         might_sleep();
313
314         /* GPIO can never have been requested */
315         WARN_ON(1);
316 }
317
318
319 static inline int gpiod_get_direction(const struct gpio_desc *desc)
320 {
321         /* GPIO can never have been requested */
322         WARN_ON(1);
323         return -ENOSYS;
324 }
325 static inline int gpiod_direction_input(struct gpio_desc *desc)
326 {
327         /* GPIO can never have been requested */
328         WARN_ON(1);
329         return -ENOSYS;
330 }
331 static inline int gpiod_direction_output(struct gpio_desc *desc, int value)
332 {
333         /* GPIO can never have been requested */
334         WARN_ON(1);
335         return -ENOSYS;
336 }
337 static inline int gpiod_direction_output_raw(struct gpio_desc *desc, int value)
338 {
339         /* GPIO can never have been requested */
340         WARN_ON(1);
341         return -ENOSYS;
342 }
343
344
345 static inline int gpiod_get_value(const struct gpio_desc *desc)
346 {
347         /* GPIO can never have been requested */
348         WARN_ON(1);
349         return 0;
350 }
351 static inline int gpiod_get_array_value(unsigned int array_size,
352                                         struct gpio_desc **desc_array,
353                                         struct gpio_array *array_info,
354                                         unsigned long *value_bitmap)
355 {
356         /* GPIO can never have been requested */
357         WARN_ON(1);
358         return 0;
359 }
360 static inline void gpiod_set_value(struct gpio_desc *desc, int value)
361 {
362         /* GPIO can never have been requested */
363         WARN_ON(1);
364 }
365 static inline int gpiod_set_array_value(unsigned int array_size,
366                                         struct gpio_desc **desc_array,
367                                         struct gpio_array *array_info,
368                                         unsigned long *value_bitmap)
369 {
370         /* GPIO can never have been requested */
371         WARN_ON(1);
372         return 0;
373 }
374 static inline int gpiod_get_raw_value(const struct gpio_desc *desc)
375 {
376         /* GPIO can never have been requested */
377         WARN_ON(1);
378         return 0;
379 }
380 static inline int gpiod_get_raw_array_value(unsigned int array_size,
381                                             struct gpio_desc **desc_array,
382                                             struct gpio_array *array_info,
383                                             unsigned long *value_bitmap)
384 {
385         /* GPIO can never have been requested */
386         WARN_ON(1);
387         return 0;
388 }
389 static inline void gpiod_set_raw_value(struct gpio_desc *desc, int value)
390 {
391         /* GPIO can never have been requested */
392         WARN_ON(1);
393 }
394 static inline int gpiod_set_raw_array_value(unsigned int array_size,
395                                             struct gpio_desc **desc_array,
396                                             struct gpio_array *array_info,
397                                             unsigned long *value_bitmap)
398 {
399         /* GPIO can never have been requested */
400         WARN_ON(1);
401         return 0;
402 }
403
404 static inline int gpiod_get_value_cansleep(const struct gpio_desc *desc)
405 {
406         /* GPIO can never have been requested */
407         WARN_ON(1);
408         return 0;
409 }
410 static inline int gpiod_get_array_value_cansleep(unsigned int array_size,
411                                      struct gpio_desc **desc_array,
412                                      struct gpio_array *array_info,
413                                      unsigned long *value_bitmap)
414 {
415         /* GPIO can never have been requested */
416         WARN_ON(1);
417         return 0;
418 }
419 static inline void gpiod_set_value_cansleep(struct gpio_desc *desc, int value)
420 {
421         /* GPIO can never have been requested */
422         WARN_ON(1);
423 }
424 static inline int gpiod_set_array_value_cansleep(unsigned int array_size,
425                                             struct gpio_desc **desc_array,
426                                             struct gpio_array *array_info,
427                                             unsigned long *value_bitmap)
428 {
429         /* GPIO can never have been requested */
430         WARN_ON(1);
431         return 0;
432 }
433 static inline int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc)
434 {
435         /* GPIO can never have been requested */
436         WARN_ON(1);
437         return 0;
438 }
439 static inline int gpiod_get_raw_array_value_cansleep(unsigned int array_size,
440                                                struct gpio_desc **desc_array,
441                                                struct gpio_array *array_info,
442                                                unsigned long *value_bitmap)
443 {
444         /* GPIO can never have been requested */
445         WARN_ON(1);
446         return 0;
447 }
448 static inline void gpiod_set_raw_value_cansleep(struct gpio_desc *desc,
449                                                 int value)
450 {
451         /* GPIO can never have been requested */
452         WARN_ON(1);
453 }
454 static inline int gpiod_set_raw_array_value_cansleep(unsigned int array_size,
455                                                 struct gpio_desc **desc_array,
456                                                 struct gpio_array *array_info,
457                                                 unsigned long *value_bitmap)
458 {
459         /* GPIO can never have been requested */
460         WARN_ON(1);
461         return 0;
462 }
463
464 static inline int gpiod_set_debounce(struct gpio_desc *desc, unsigned debounce)
465 {
466         /* GPIO can never have been requested */
467         WARN_ON(1);
468         return -ENOSYS;
469 }
470
471 static inline int gpiod_set_transitory(struct gpio_desc *desc, bool transitory)
472 {
473         /* GPIO can never have been requested */
474         WARN_ON(1);
475         return -ENOSYS;
476 }
477
478 static inline int gpiod_is_active_low(const struct gpio_desc *desc)
479 {
480         /* GPIO can never have been requested */
481         WARN_ON(1);
482         return 0;
483 }
484 static inline int gpiod_cansleep(const struct gpio_desc *desc)
485 {
486         /* GPIO can never have been requested */
487         WARN_ON(1);
488         return 0;
489 }
490
491 static inline int gpiod_to_irq(const struct gpio_desc *desc)
492 {
493         /* GPIO can never have been requested */
494         WARN_ON(1);
495         return -EINVAL;
496 }
497
498 static inline void gpiod_set_consumer_name(struct gpio_desc *desc, const char *name)
499 {
500         /* GPIO can never have been requested */
501         WARN_ON(1);
502 }
503
504 static inline struct gpio_desc *gpio_to_desc(unsigned gpio)
505 {
506         return ERR_PTR(-EINVAL);
507 }
508
509 static inline int desc_to_gpio(const struct gpio_desc *desc)
510 {
511         /* GPIO can never have been requested */
512         WARN_ON(1);
513         return -EINVAL;
514 }
515
516 /* Child properties interface */
517 struct device_node;
518 struct fwnode_handle;
519
520 static inline
521 struct gpio_desc *devm_gpiod_get_from_of_node(struct device *dev,
522                                               struct device_node *node,
523                                               const char *propname, int index,
524                                               enum gpiod_flags dflags,
525                                               const char *label)
526 {
527         return ERR_PTR(-ENOSYS);
528 }
529
530 static inline
531 struct gpio_desc *fwnode_get_named_gpiod(struct fwnode_handle *fwnode,
532                                          const char *propname, int index,
533                                          enum gpiod_flags dflags,
534                                          const char *label)
535 {
536         return ERR_PTR(-ENOSYS);
537 }
538
539 static inline
540 struct gpio_desc *devm_fwnode_get_index_gpiod_from_child(struct device *dev,
541                                                 const char *con_id, int index,
542                                                 struct fwnode_handle *child,
543                                                 enum gpiod_flags flags,
544                                                 const char *label)
545 {
546         return ERR_PTR(-ENOSYS);
547 }
548
549 #endif /* CONFIG_GPIOLIB */
550
551 static inline
552 struct gpio_desc *devm_fwnode_get_gpiod_from_child(struct device *dev,
553                                                    const char *con_id,
554                                                    struct fwnode_handle *child,
555                                                    enum gpiod_flags flags,
556                                                    const char *label)
557 {
558         return devm_fwnode_get_index_gpiod_from_child(dev, con_id, 0, child,
559                                                       flags, label);
560 }
561
562 #if IS_ENABLED(CONFIG_GPIOLIB) && IS_ENABLED(CONFIG_GPIO_SYSFS)
563
564 int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
565 int gpiod_export_link(struct device *dev, const char *name,
566                       struct gpio_desc *desc);
567 void gpiod_unexport(struct gpio_desc *desc);
568
569 #else  /* CONFIG_GPIOLIB && CONFIG_GPIO_SYSFS */
570
571 static inline int gpiod_export(struct gpio_desc *desc,
572                                bool direction_may_change)
573 {
574         return -ENOSYS;
575 }
576
577 static inline int gpiod_export_link(struct device *dev, const char *name,
578                                     struct gpio_desc *desc)
579 {
580         return -ENOSYS;
581 }
582
583 static inline void gpiod_unexport(struct gpio_desc *desc)
584 {
585 }
586
587 #endif /* CONFIG_GPIOLIB && CONFIG_GPIO_SYSFS */
588
589 #endif