drivers/gpio/gpiolib.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * Internal GPIO functions.
0004  *
0005  * Copyright (C) 2013, Intel Corporation
0006  * Author: Mika Westerberg <mika.westerberg@linux.intel.com>
0007  */
0008
0009 #ifndef GPIOLIB_H
0010 #define GPIOLIB_H
0011
0012 #include <linux/gpio/driver.h>
0013 #include <linux/gpio/consumer.h> /* for enum gpiod_flags */
0014 #include <linux/err.h>
0015 #include <linux/device.h>
0016 #include <linux/module.h>
0017 #include <linux/cdev.h>
0018
0019 #define GPIOCHIP_NAME   "gpiochip"
0020
0021 /**
0022  * struct gpio_device - internal state container for GPIO devices
0023  * @id: numerical ID number for the GPIO chip
0024  * @dev: the GPIO device struct
0025  * @chrdev: character device for the GPIO device
0026  * @mockdev: class device used by the deprecated sysfs interface (may be
0027  * NULL)
0028  * @owner: helps prevent removal of modules exporting active GPIOs
0029  * @chip: pointer to the corresponding gpiochip, holding static
0030  * data for this device
0031  * @descs: array of ngpio descriptors.
0032  * @ngpio: the number of GPIO lines on this GPIO device, equal to the size
0033  * of the @descs array.
0034  * @base: GPIO base in the DEPRECATED global Linux GPIO numberspace, assigned
0035  * at device creation time.
0036  * @label: a descriptive name for the GPIO device, such as the part number
0037  * or name of the IP component in a System on Chip.
0038  * @data: per-instance data assigned by the driver
0039  * @list: links gpio_device:s together for traversal
0040  * @notifier: used to notify subscribers about lines being requested, released
0041  *            or reconfigured
0042  * @pin_ranges: range of pins served by the GPIO driver
0043  *
0044  * This state container holds most of the runtime variable data
0045  * for a GPIO device and can hold references and live on after the
0046  * GPIO chip has been removed, if it is still being used from
0047  * userspace.
0048  */
0049 struct gpio_device {
0050     int         id;
0051     struct device       dev;
0052     struct cdev     chrdev;
0053     struct device       *mockdev;
0054     struct module       *owner;
0055     struct gpio_chip    *chip;
0056     struct gpio_desc    *descs;
0057     int         base;
0058     u16         ngpio;
0059     const char      *label;
0060     void            *data;
0061     struct list_head        list;
0062     struct blocking_notifier_head notifier;
0063
0064 #ifdef CONFIG_PINCTRL
0065     /*
0066      * If CONFIG_PINCTRL is enabled, then gpio controllers can optionally
0067      * describe the actual pin range which they serve in an SoC. This
0068      * information would be used by pinctrl subsystem to configure
0069      * corresponding pins for gpio usage.
0070      */
0071     struct list_head pin_ranges;
0072 #endif
0073 };
0074
0075 /* gpio suffixes used for ACPI and device tree lookup */
0076 static __maybe_unused const char * const gpio_suffixes[] = { "gpios", "gpio" };
0077
0078 /**
0079  * struct gpio_array - Opaque descriptor for a structure of GPIO array attributes
0080  *
0081  * @desc:       Array of pointers to the GPIO descriptors
0082  * @size:       Number of elements in desc
0083  * @chip:       Parent GPIO chip
0084  * @get_mask:       Get mask used in fastpath
0085  * @set_mask:       Set mask used in fastpath
0086  * @invert_mask:    Invert mask used in fastpath
0087  *
0088  * This structure is attached to struct gpiod_descs obtained from
0089  * gpiod_get_array() and can be passed back to get/set array functions in order
0090  * to activate fast processing path if applicable.
0091  */
0092 struct gpio_array {
0093     struct gpio_desc    **desc;
0094     unsigned int        size;
0095     struct gpio_chip    *chip;
0096     unsigned long       *get_mask;
0097     unsigned long       *set_mask;
0098     unsigned long       invert_mask[];
0099 };
0100
0101 struct gpio_desc *gpiochip_get_desc(struct gpio_chip *gc, unsigned int hwnum);
0102
0103 #define for_each_gpio_desc(gc, desc)                    \
0104     for (unsigned int __i = 0;                  \
0105          __i < gc->ngpio && (desc = gpiochip_get_desc(gc, __i));    \
0106          __i++)                         \
0107
0108 #define for_each_gpio_desc_with_flag(gc, desc, flag)            \
0109     for_each_gpio_desc(gc, desc)                    \
0110         if (!test_bit(flag, &desc->flags)) {} else
0111
0112 int gpiod_get_array_value_complex(bool raw, bool can_sleep,
0113                   unsigned int array_size,
0114                   struct gpio_desc **desc_array,
0115                   struct gpio_array *array_info,
0116                   unsigned long *value_bitmap);
0117 int gpiod_set_array_value_complex(bool raw, bool can_sleep,
0118                   unsigned int array_size,
0119                   struct gpio_desc **desc_array,
0120                   struct gpio_array *array_info,
0121                   unsigned long *value_bitmap);
0122
0123 extern spinlock_t gpio_lock;
0124 extern struct list_head gpio_devices;
0125
0126
0127 /**
0128  * struct gpio_desc - Opaque descriptor for a GPIO
0129  *
0130  * @gdev:       Pointer to the parent GPIO device
0131  * @flags:      Binary descriptor flags
0132  * @label:      Name of the consumer
0133  * @name:       Line name
0134  * @hog:        Pointer to the device node that hogs this line (if any)
0135  * @debounce_period_us: Debounce period in microseconds
0136  *
0137  * These are obtained using gpiod_get() and are preferable to the old
0138  * integer-based handles.
0139  *
0140  * Contrary to integers, a pointer to a &struct gpio_desc is guaranteed to be
0141  * valid until the GPIO is released.
0142  */
0143 struct gpio_desc {
0144     struct gpio_device  *gdev;
0145     unsigned long       flags;
0146 /* flag symbols are bit numbers */
0147 #define FLAG_REQUESTED  0
0148 #define FLAG_IS_OUT 1
0149 #define FLAG_EXPORT 2   /* protected by sysfs_lock */
0150 #define FLAG_SYSFS  3   /* exported via /sys/class/gpio/control */
0151 #define FLAG_ACTIVE_LOW 6   /* value has active low */
0152 #define FLAG_OPEN_DRAIN 7   /* Gpio is open drain type */
0153 #define FLAG_OPEN_SOURCE 8  /* Gpio is open source type */
0154 #define FLAG_USED_AS_IRQ 9  /* GPIO is connected to an IRQ */
0155 #define FLAG_IRQ_IS_ENABLED 10  /* GPIO is connected to an enabled IRQ */
0156 #define FLAG_IS_HOGGED  11  /* GPIO is hogged */
0157 #define FLAG_TRANSITORY 12  /* GPIO may lose value in sleep or reset */
0158 #define FLAG_PULL_UP    13  /* GPIO has pull up enabled */
0159 #define FLAG_PULL_DOWN  14  /* GPIO has pull down enabled */
0160 #define FLAG_BIAS_DISABLE    15 /* GPIO has pull disabled */
0161 #define FLAG_EDGE_RISING     16 /* GPIO CDEV detects rising edge events */
0162 #define FLAG_EDGE_FALLING    17 /* GPIO CDEV detects falling edge events */
0163 #define FLAG_EVENT_CLOCK_REALTIME   18 /* GPIO CDEV reports REALTIME timestamps in events */
0164 #define FLAG_EVENT_CLOCK_HTE        19 /* GPIO CDEV reports hardware timestamps in events */
0165
0166     /* Connection label */
0167     const char      *label;
0168     /* Name of the GPIO */
0169     const char      *name;
0170 #ifdef CONFIG_OF_DYNAMIC
0171     struct device_node  *hog;
0172 #endif
0173 #ifdef CONFIG_GPIO_CDEV
0174     /* debounce period in microseconds */
0175     unsigned int        debounce_period_us;
0176 #endif
0177 };
0178
0179 #define gpiod_not_found(desc)       (IS_ERR(desc) && PTR_ERR(desc) == -ENOENT)
0180
0181 int gpiod_request(struct gpio_desc *desc, const char *label);
0182 void gpiod_free(struct gpio_desc *desc);
0183
0184 static inline int gpiod_request_user(struct gpio_desc *desc, const char *label)
0185 {
0186     int ret;
0187
0188     ret = gpiod_request(desc, label);
0189     if (ret == -EPROBE_DEFER)
0190         ret = -ENODEV;
0191
0192     return ret;
0193 }
0194
0195 int gpiod_configure_flags(struct gpio_desc *desc, const char *con_id,
0196         unsigned long lflags, enum gpiod_flags dflags);
0197 int gpio_set_debounce_timeout(struct gpio_desc *desc, unsigned int debounce);
0198 int gpiod_hog(struct gpio_desc *desc, const char *name,
0199         unsigned long lflags, enum gpiod_flags dflags);
0200
0201 /*
0202  * Return the GPIO number of the passed descriptor relative to its chip
0203  */
0204 static inline int gpio_chip_hwgpio(const struct gpio_desc *desc)
0205 {
0206     return desc - &desc->gdev->descs[0];
0207 }
0208
0209 /* With descriptor prefix */
0210
0211 #define gpiod_emerg(desc, fmt, ...)                        \
0212     pr_emerg("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?",\
0213          ##__VA_ARGS__)
0214 #define gpiod_crit(desc, fmt, ...)                         \
0215     pr_crit("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?", \
0216          ##__VA_ARGS__)
0217 #define gpiod_err(desc, fmt, ...)                          \
0218     pr_err("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?",  \
0219          ##__VA_ARGS__)
0220 #define gpiod_warn(desc, fmt, ...)                         \
0221     pr_warn("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?", \
0222          ##__VA_ARGS__)
0223 #define gpiod_info(desc, fmt, ...)                         \
0224     pr_info("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?", \
0225          ##__VA_ARGS__)
0226 #define gpiod_dbg(desc, fmt, ...)                          \
0227     pr_debug("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?",\
0228          ##__VA_ARGS__)
0229
0230 /* With chip prefix */
0231
0232 #define chip_emerg(gc, fmt, ...)                    \
0233     dev_emerg(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
0234 #define chip_crit(gc, fmt, ...)                 \
0235     dev_crit(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
0236 #define chip_err(gc, fmt, ...)                  \
0237     dev_err(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
0238 #define chip_warn(gc, fmt, ...)                 \
0239     dev_warn(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
0240 #define chip_info(gc, fmt, ...)                 \
0241     dev_info(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
0242 #define chip_dbg(gc, fmt, ...)                  \
0243     dev_dbg(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
0244
0245 #endif /* GPIOLIB_H */