1dae5f0afSLinus Walleij /* SPDX-License-Identifier: GPL-2.0 */
2664e3e5aSMika Westerberg /*
3664e3e5aSMika Westerberg * Internal GPIO functions.
4664e3e5aSMika Westerberg *
5664e3e5aSMika Westerberg * Copyright (C) 2013, Intel Corporation
6664e3e5aSMika Westerberg * Author: Mika Westerberg <mika.westerberg@linux.intel.com>
7664e3e5aSMika Westerberg */
8664e3e5aSMika Westerberg
9664e3e5aSMika Westerberg #ifndef GPIOLIB_H
10664e3e5aSMika Westerberg #define GPIOLIB_H
11664e3e5aSMika Westerberg
120f93a345SBartosz Golaszewski #include <linux/cdev.h>
135ccff852SMika Westerberg #include <linux/device.h>
140f93a345SBartosz Golaszewski #include <linux/err.h>
150f93a345SBartosz Golaszewski #include <linux/gpio/consumer.h> /* for enum gpiod_flags */
160f93a345SBartosz Golaszewski #include <linux/gpio/driver.h>
17ff2b1359SLinus Walleij #include <linux/module.h>
18e2051394SBartosz Golaszewski #include <linux/notifier.h>
19bdbbae24SBartosz Golaszewski #include <linux/rwsem.h>
205ccff852SMika Westerberg
21ddd8891eSGeert Uytterhoeven #define GPIOCHIP_NAME "gpiochip"
22ddd8891eSGeert Uytterhoeven
235ccff852SMika Westerberg /**
24ff2b1359SLinus Walleij * struct gpio_device - internal state container for GPIO devices
25ff2b1359SLinus Walleij * @dev: the GPIO device struct
263c702e99SLinus Walleij * @chrdev: character device for the GPIO device
273b7c7478SAndy Shevchenko * @id: numerical ID number for the GPIO chip
28afbc4f31SLinus Walleij * @mockdev: class device used by the deprecated sysfs interface (may be
29afbc4f31SLinus Walleij * NULL)
30ff2b1359SLinus Walleij * @owner: helps prevent removal of modules exporting active GPIOs
31ff2b1359SLinus Walleij * @chip: pointer to the corresponding gpiochip, holding static
32ff2b1359SLinus Walleij * data for this device
331c3cdb18SLinus Walleij * @descs: array of ngpio descriptors.
34fdeb8e15SLinus Walleij * @ngpio: the number of GPIO lines on this GPIO device, equal to the size
35fdeb8e15SLinus Walleij * of the @descs array.
36fdeb8e15SLinus Walleij * @base: GPIO base in the DEPRECATED global Linux GPIO numberspace, assigned
37fdeb8e15SLinus Walleij * at device creation time.
38df4878e9SLinus Walleij * @label: a descriptive name for the GPIO device, such as the part number
39df4878e9SLinus Walleij * or name of the IP component in a System on Chip.
4043c54ecaSLinus Walleij * @data: per-instance data assigned by the driver
41ff2b1359SLinus Walleij * @list: links gpio_device:s together for traversal
4217a7ca35SBartosz Golaszewski * @line_state_notifier: used to notify subscribers about lines being
4317a7ca35SBartosz Golaszewski * requested, released or reconfigured
44a067419bSBartosz Golaszewski * @device_notifier: used to notify character device wait queues about the GPIO
45a067419bSBartosz Golaszewski * device being unregistered
46bdbbae24SBartosz Golaszewski * @sem: protects the structure from a NULL-pointer dereference of @chip by
47bdbbae24SBartosz Golaszewski * user-space operations when the device gets unregistered during
48bdbbae24SBartosz Golaszewski * a hot-unplug event
494398693aSBartosz Golaszewski * @pin_ranges: range of pins served by the GPIO driver
50ff2b1359SLinus Walleij *
51ff2b1359SLinus Walleij * This state container holds most of the runtime variable data
52ff2b1359SLinus Walleij * for a GPIO device and can hold references and live on after the
53ff2b1359SLinus Walleij * GPIO chip has been removed, if it is still being used from
54ff2b1359SLinus Walleij * userspace.
55ff2b1359SLinus Walleij */
56ff2b1359SLinus Walleij struct gpio_device {
57ff2b1359SLinus Walleij struct device dev;
583c702e99SLinus Walleij struct cdev chrdev;
593b7c7478SAndy Shevchenko int id;
60afbc4f31SLinus Walleij struct device *mockdev;
61ff2b1359SLinus Walleij struct module *owner;
62ff2b1359SLinus Walleij struct gpio_chip *chip;
631c3cdb18SLinus Walleij struct gpio_desc *descs;
64fdeb8e15SLinus Walleij int base;
65fdeb8e15SLinus Walleij u16 ngpio;
663b469b0aSBartosz Golaszewski const char *label;
6743c54ecaSLinus Walleij void *data;
68ff2b1359SLinus Walleij struct list_head list;
6917a7ca35SBartosz Golaszewski struct blocking_notifier_head line_state_notifier;
70a067419bSBartosz Golaszewski struct blocking_notifier_head device_notifier;
71bdbbae24SBartosz Golaszewski struct rw_semaphore sem;
7220ec3e39SLinus Walleij
7320ec3e39SLinus Walleij #ifdef CONFIG_PINCTRL
7420ec3e39SLinus Walleij /*
7520ec3e39SLinus Walleij * If CONFIG_PINCTRL is enabled, then gpio controllers can optionally
7620ec3e39SLinus Walleij * describe the actual pin range which they serve in an SoC. This
7720ec3e39SLinus Walleij * information would be used by pinctrl subsystem to configure
7820ec3e39SLinus Walleij * corresponding pins for gpio usage.
7920ec3e39SLinus Walleij */
8020ec3e39SLinus Walleij struct list_head pin_ranges;
8120ec3e39SLinus Walleij #endif
82ff2b1359SLinus Walleij };
83ff2b1359SLinus Walleij
to_gpio_device(struct device * dev)843b7c7478SAndy Shevchenko static inline struct gpio_device *to_gpio_device(struct device *dev)
853b7c7478SAndy Shevchenko {
863b7c7478SAndy Shevchenko return container_of(dev, struct gpio_device, dev);
873b7c7478SAndy Shevchenko }
883b7c7478SAndy Shevchenko
897f2e553aSRojhalat Ibrahim /* gpio suffixes used for ACPI and device tree lookup */
90b23ec599SAndy Shevchenko static __maybe_unused const char * const gpio_suffixes[] = { "gpios", "gpio" };
917f2e553aSRojhalat Ibrahim
924398693aSBartosz Golaszewski /**
934398693aSBartosz Golaszewski * struct gpio_array - Opaque descriptor for a structure of GPIO array attributes
944398693aSBartosz Golaszewski *
954398693aSBartosz Golaszewski * @desc: Array of pointers to the GPIO descriptors
964398693aSBartosz Golaszewski * @size: Number of elements in desc
974398693aSBartosz Golaszewski * @chip: Parent GPIO chip
984398693aSBartosz Golaszewski * @get_mask: Get mask used in fastpath
994398693aSBartosz Golaszewski * @set_mask: Set mask used in fastpath
1004398693aSBartosz Golaszewski * @invert_mask: Invert mask used in fastpath
1014398693aSBartosz Golaszewski *
1024398693aSBartosz Golaszewski * This structure is attached to struct gpiod_descs obtained from
1034398693aSBartosz Golaszewski * gpiod_get_array() and can be passed back to get/set array functions in order
1044398693aSBartosz Golaszewski * to activate fast processing path if applicable.
1054398693aSBartosz Golaszewski */
106bf9346f5SJanusz Krzysztofik struct gpio_array {
107bf9346f5SJanusz Krzysztofik struct gpio_desc **desc;
108bf9346f5SJanusz Krzysztofik unsigned int size;
109bf9346f5SJanusz Krzysztofik struct gpio_chip *chip;
110bf9346f5SJanusz Krzysztofik unsigned long *get_mask;
111bf9346f5SJanusz Krzysztofik unsigned long *set_mask;
112bf9346f5SJanusz Krzysztofik unsigned long invert_mask[];
113bf9346f5SJanusz Krzysztofik };
114bf9346f5SJanusz Krzysztofik
115a5e93436SGeert Uytterhoeven struct gpio_desc *gpiochip_get_desc(struct gpio_chip *gc, unsigned int hwnum);
11680c78fbeSAndy Shevchenko
11766f46e37SAndy Shevchenko #define for_each_gpio_desc(gc, desc) \
11857017eddSAndy Shevchenko for (unsigned int __i = 0; \
11957017eddSAndy Shevchenko __i < gc->ngpio && (desc = gpiochip_get_desc(gc, __i)); \
12057017eddSAndy Shevchenko __i++) \
12166f46e37SAndy Shevchenko
12266f46e37SAndy Shevchenko #define for_each_gpio_desc_with_flag(gc, desc, flag) \
12366f46e37SAndy Shevchenko for_each_gpio_desc(gc, desc) \
12480c78fbeSAndy Shevchenko if (!test_bit(flag, &desc->flags)) {} else
12580c78fbeSAndy Shevchenko
126eec1d566SLukas Wunner int gpiod_get_array_value_complex(bool raw, bool can_sleep,
127eec1d566SLukas Wunner unsigned int array_size,
128eec1d566SLukas Wunner struct gpio_desc **desc_array,
12977588c14SJanusz Krzysztofik struct gpio_array *array_info,
130b9762bebSJanusz Krzysztofik unsigned long *value_bitmap);
1313027743fSLaura Abbott int gpiod_set_array_value_complex(bool raw, bool can_sleep,
13244c7288fSLinus Walleij unsigned int array_size,
13344c7288fSLinus Walleij struct gpio_desc **desc_array,
13477588c14SJanusz Krzysztofik struct gpio_array *array_info,
135b9762bebSJanusz Krzysztofik unsigned long *value_bitmap);
1361bd6b601SAlexandre Courbot
137f0b40863SSebastian Andrzej Siewior extern spinlock_t gpio_lock;
138ff2b1359SLinus Walleij extern struct list_head gpio_devices;
1390eb4c6c2SAlexandre Courbot
1409ce4ed5bSBartosz Golaszewski void gpiod_line_state_notify(struct gpio_desc *desc, unsigned long action);
1414398693aSBartosz Golaszewski
1424398693aSBartosz Golaszewski /**
1434398693aSBartosz Golaszewski * struct gpio_desc - Opaque descriptor for a GPIO
1444398693aSBartosz Golaszewski *
1454398693aSBartosz Golaszewski * @gdev: Pointer to the parent GPIO device
1464398693aSBartosz Golaszewski * @flags: Binary descriptor flags
1474398693aSBartosz Golaszewski * @label: Name of the consumer
1484398693aSBartosz Golaszewski * @name: Line name
1494398693aSBartosz Golaszewski * @hog: Pointer to the device node that hogs this line (if any)
1504398693aSBartosz Golaszewski * @debounce_period_us: Debounce period in microseconds
1514398693aSBartosz Golaszewski *
1524398693aSBartosz Golaszewski * These are obtained using gpiod_get() and are preferable to the old
1534398693aSBartosz Golaszewski * integer-based handles.
1544398693aSBartosz Golaszewski *
1554398693aSBartosz Golaszewski * Contrary to integers, a pointer to a &struct gpio_desc is guaranteed to be
1564398693aSBartosz Golaszewski * valid until the GPIO is released.
1574398693aSBartosz Golaszewski */
1580eb4c6c2SAlexandre Courbot struct gpio_desc {
159fdeb8e15SLinus Walleij struct gpio_device *gdev;
1600eb4c6c2SAlexandre Courbot unsigned long flags;
1610eb4c6c2SAlexandre Courbot /* flag symbols are bit numbers */
1620eb4c6c2SAlexandre Courbot #define FLAG_REQUESTED 0
1630eb4c6c2SAlexandre Courbot #define FLAG_IS_OUT 1
1640eb4c6c2SAlexandre Courbot #define FLAG_EXPORT 2 /* protected by sysfs_lock */
1650eb4c6c2SAlexandre Courbot #define FLAG_SYSFS 3 /* exported via /sys/class/gpio/control */
1660eb4c6c2SAlexandre Courbot #define FLAG_ACTIVE_LOW 6 /* value has active low */
1670eb4c6c2SAlexandre Courbot #define FLAG_OPEN_DRAIN 7 /* Gpio is open drain type */
1680eb4c6c2SAlexandre Courbot #define FLAG_OPEN_SOURCE 8 /* Gpio is open source type */
1690eb4c6c2SAlexandre Courbot #define FLAG_USED_AS_IRQ 9 /* GPIO is connected to an IRQ */
1704e9439ddSHans Verkuil #define FLAG_IRQ_IS_ENABLED 10 /* GPIO is connected to an enabled IRQ */
171f625d460SBenoit Parrot #define FLAG_IS_HOGGED 11 /* GPIO is hogged */
172e10f72bfSAndrew Jeffery #define FLAG_TRANSITORY 12 /* GPIO may lose value in sleep or reset */
173d449991cSThomas Petazzoni #define FLAG_PULL_UP 13 /* GPIO has pull up enabled */
174d449991cSThomas Petazzoni #define FLAG_PULL_DOWN 14 /* GPIO has pull down enabled */
1752148ad77SKent Gibson #define FLAG_BIAS_DISABLE 15 /* GPIO has pull disabled */
17673e03419SKent Gibson #define FLAG_EDGE_RISING 16 /* GPIO CDEV detects rising edge events */
17773e03419SKent Gibson #define FLAG_EDGE_FALLING 17 /* GPIO CDEV detects falling edge events */
17826d060e4SKent Gibson #define FLAG_EVENT_CLOCK_REALTIME 18 /* GPIO CDEV reports REALTIME timestamps in events */
17942112dd7SDipen Patel #define FLAG_EVENT_CLOCK_HTE 19 /* GPIO CDEV reports hardware timestamps in events */
1800eb4c6c2SAlexandre Courbot
181c0017ed7SMarkus Pargmann /* Connection label */
1820eb4c6c2SAlexandre Courbot const char *label;
183c0017ed7SMarkus Pargmann /* Name of the GPIO */
184c0017ed7SMarkus Pargmann const char *name;
18563636d95SGeert Uytterhoeven #ifdef CONFIG_OF_DYNAMIC
18663636d95SGeert Uytterhoeven struct device_node *hog;
18763636d95SGeert Uytterhoeven #endif
18865cff704SKent Gibson #ifdef CONFIG_GPIO_CDEV
18965cff704SKent Gibson /* debounce period in microseconds */
19065cff704SKent Gibson unsigned int debounce_period_us;
19165cff704SKent Gibson #endif
1920eb4c6c2SAlexandre Courbot };
1930eb4c6c2SAlexandre Courbot
1947b58696dSAndy Shevchenko #define gpiod_not_found(desc) (IS_ERR(desc) && PTR_ERR(desc) == -ENOENT)
1957b58696dSAndy Shevchenko
1960eb4c6c2SAlexandre Courbot int gpiod_request(struct gpio_desc *desc, const char *label);
1970eb4c6c2SAlexandre Courbot void gpiod_free(struct gpio_desc *desc);
19895a4eed7SAndy Shevchenko
gpiod_request_user(struct gpio_desc * desc,const char * label)19995a4eed7SAndy Shevchenko static inline int gpiod_request_user(struct gpio_desc *desc, const char *label)
20095a4eed7SAndy Shevchenko {
20195a4eed7SAndy Shevchenko int ret;
20295a4eed7SAndy Shevchenko
20395a4eed7SAndy Shevchenko ret = gpiod_request(desc, label);
20495a4eed7SAndy Shevchenko if (ret == -EPROBE_DEFER)
20595a4eed7SAndy Shevchenko ret = -ENODEV;
20695a4eed7SAndy Shevchenko
20795a4eed7SAndy Shevchenko return ret;
20895a4eed7SAndy Shevchenko }
20995a4eed7SAndy Shevchenko
210*630ed2bbSStephen Boyd struct gpio_desc *gpiod_find_and_request(struct device *consumer,
211*630ed2bbSStephen Boyd struct fwnode_handle *fwnode,
212*630ed2bbSStephen Boyd const char *con_id,
213*630ed2bbSStephen Boyd unsigned int idx,
214*630ed2bbSStephen Boyd enum gpiod_flags flags,
215*630ed2bbSStephen Boyd const char *label,
216*630ed2bbSStephen Boyd bool platform_lookup_allowed);
217*630ed2bbSStephen Boyd
218c29fd9ebSAndy Shevchenko int gpiod_configure_flags(struct gpio_desc *desc, const char *con_id,
219c29fd9ebSAndy Shevchenko unsigned long lflags, enum gpiod_flags dflags);
220f725edd8SAndy Shevchenko int gpio_set_debounce_timeout(struct gpio_desc *desc, unsigned int debounce);
221f625d460SBenoit Parrot int gpiod_hog(struct gpio_desc *desc, const char *name,
222f625d460SBenoit Parrot unsigned long lflags, enum gpiod_flags dflags);
22355b2395eSAsmaa Mnebhi int gpiochip_get_ngpios(struct gpio_chip *gc, struct device *dev);
2240eb4c6c2SAlexandre Courbot
2250eb4c6c2SAlexandre Courbot /*
2260eb4c6c2SAlexandre Courbot * Return the GPIO number of the passed descriptor relative to its chip
2270eb4c6c2SAlexandre Courbot */
gpio_chip_hwgpio(const struct gpio_desc * desc)2284a5c886eSMasahiro Yamada static inline int gpio_chip_hwgpio(const struct gpio_desc *desc)
2290eb4c6c2SAlexandre Courbot {
230fdeb8e15SLinus Walleij return desc - &desc->gdev->descs[0];
2310eb4c6c2SAlexandre Courbot }
2320eb4c6c2SAlexandre Courbot
2330eb4c6c2SAlexandre Courbot /* With descriptor prefix */
2340eb4c6c2SAlexandre Courbot
2350eb4c6c2SAlexandre Courbot #define gpiod_emerg(desc, fmt, ...) \
2360eb4c6c2SAlexandre Courbot pr_emerg("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?",\
2370eb4c6c2SAlexandre Courbot ##__VA_ARGS__)
2380eb4c6c2SAlexandre Courbot #define gpiod_crit(desc, fmt, ...) \
2390eb4c6c2SAlexandre Courbot pr_crit("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?", \
2400eb4c6c2SAlexandre Courbot ##__VA_ARGS__)
2410eb4c6c2SAlexandre Courbot #define gpiod_err(desc, fmt, ...) \
2420eb4c6c2SAlexandre Courbot pr_err("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?", \
2430eb4c6c2SAlexandre Courbot ##__VA_ARGS__)
2440eb4c6c2SAlexandre Courbot #define gpiod_warn(desc, fmt, ...) \
2450eb4c6c2SAlexandre Courbot pr_warn("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?", \
2460eb4c6c2SAlexandre Courbot ##__VA_ARGS__)
2470eb4c6c2SAlexandre Courbot #define gpiod_info(desc, fmt, ...) \
2480eb4c6c2SAlexandre Courbot pr_info("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?", \
2490eb4c6c2SAlexandre Courbot ##__VA_ARGS__)
2500eb4c6c2SAlexandre Courbot #define gpiod_dbg(desc, fmt, ...) \
2510eb4c6c2SAlexandre Courbot pr_debug("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?",\
2520eb4c6c2SAlexandre Courbot ##__VA_ARGS__)
2530eb4c6c2SAlexandre Courbot
2540eb4c6c2SAlexandre Courbot /* With chip prefix */
2550eb4c6c2SAlexandre Courbot
256a5e93436SGeert Uytterhoeven #define chip_emerg(gc, fmt, ...) \
257a5e93436SGeert Uytterhoeven dev_emerg(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
258a5e93436SGeert Uytterhoeven #define chip_crit(gc, fmt, ...) \
259a5e93436SGeert Uytterhoeven dev_crit(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
260a5e93436SGeert Uytterhoeven #define chip_err(gc, fmt, ...) \
261a5e93436SGeert Uytterhoeven dev_err(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
262a5e93436SGeert Uytterhoeven #define chip_warn(gc, fmt, ...) \
263a5e93436SGeert Uytterhoeven dev_warn(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
264a5e93436SGeert Uytterhoeven #define chip_info(gc, fmt, ...) \
265a5e93436SGeert Uytterhoeven dev_info(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
266a5e93436SGeert Uytterhoeven #define chip_dbg(gc, fmt, ...) \
267a5e93436SGeert Uytterhoeven dev_dbg(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
2680eb4c6c2SAlexandre Courbot
269664e3e5aSMika Westerberg #endif /* GPIOLIB_H */
270