WSL2-Linux-Kernel/drivers/gpio/gpiolib.h

246 строки
8.3 KiB
C
Исходник Обычный вид История

/* SPDX-License-Identifier: GPL-2.0 */
/*
* Internal GPIO functions.
*
* Copyright (C) 2013, Intel Corporation
* Author: Mika Westerberg <mika.westerberg@linux.intel.com>
*/
#ifndef GPIOLIB_H
#define GPIOLIB_H
#include <linux/gpio/driver.h>
#include <linux/gpio/consumer.h> /* for enum gpiod_flags */
#include <linux/err.h>
#include <linux/device.h>
#include <linux/module.h>
#include <linux/cdev.h>
#define GPIOCHIP_NAME "gpiochip"
/**
* struct gpio_device - internal state container for GPIO devices
* @id: numerical ID number for the GPIO chip
* @dev: the GPIO device struct
gpio: add a userspace chardev ABI for GPIOs A new chardev that is to be used for userspace GPIO access is added in this patch. It is intended to gradually replace the horribly broken sysfs ABI. Using a chardev has many upsides: - All operations are per-gpiochip, which is the actual device underlying the GPIOs, making us tie in to the kernel device model properly. - Hotpluggable GPIO controllers can come and go, as this kind of problem has been know to userspace for character devices since ages, and if a gpiochip handle is held in userspace we know we will break something, whereas the sysfs is stateless. - The one-value-per-file rule of sysfs is really hard to maintain when you want to twist more than one knob at a time, for example have in-kernel APIs to switch several GPIO lines at the same time, and this will be possible to do with a single ioctl() from userspace, saving a lot of context switching. We also need to add a new bus type for GPIO. This is necessary for example for userspace coldplug, where sysfs is traversed to find the boot-time device nodes and create the character devices in /dev. This new chardev ABI is *non* *optional* and can be counted on to be present in the future, emphasizing the preference of this ABI. The ABI only implements one single ioctl() to get the name and number of GPIO lines of a chip. Even this is debatable: see it as a minimal example for review. This ABI shall be ruthlessly reviewed and etched in stone. The old /sys/class/gpio is still optional to compile in, but will be deprecated. Unique device IDs are created using IDR, which is overkill and insanely scalable, but also well tested. Cc: Johan Hovold <johan@kernel.org> Cc: Michael Welling <mwelling@ieee.org> Cc: Markus Pargmann <mpa@pengutronix.de> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Arnd Bergmann <arnd@arndb.de> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2015-10-21 16:29:53 +03:00
* @chrdev: character device for the GPIO device
* @mockdev: class device used by the deprecated sysfs interface (may be
* NULL)
* @owner: helps prevent removal of modules exporting active GPIOs
* @chip: pointer to the corresponding gpiochip, holding static
* data for this device
* @descs: array of ngpio descriptors.
gpio: reflect base and ngpio into gpio_device Some information about the GPIO chip need to stay around also after the gpio_chip has been removed and only the gpio_device persist. The base and ngpio are such things, for example we don't want a new chip arriving to overlap the number space of a dangling gpio_device, and the chardev may still query the device for the number of lines etc. Note that the code that assigns base and insert gpio_device into the global list no longer check for a missing gpio_chip: we respect the number space allocated by any other gpio_device. As a consequence of the gdev being referenced directly from the gpio_desc, we need to verify it differently from all in-kernel API calls that fall through to direct queries to the gpio_chip vtable: we first check that desc is !NULL, then that desc->gdev is !NULL, then, if desc->gdev->chip is NULL, we *BAIL OUT* without any error, so as to manage the case where operations are requested on a device that is gone. These checks were non-uniform and partly missing in the past: so to simplify: create the macros VALIDATE_DESC() that will return -EINVAL if the desc or desc->gdev is missing and just 0 if the chip is gone, and conversely VALIDATE_DESC_VOID() for the case where the function does not return an error. By using these macros, we get warning messages about missing gdev with reference to the right function in the kernel log. Despite the macro business this simplifies the code and make it more readable than if we copy/paste the same descriptor checking code into all code ABI call sites (IMHO). Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-02-10 12:57:36 +03:00
* @ngpio: the number of GPIO lines on this GPIO device, equal to the size
* of the @descs array.
* @base: GPIO base in the DEPRECATED global Linux GPIO numberspace, assigned
* at device creation time.
* @label: a descriptive name for the GPIO device, such as the part number
* or name of the IP component in a System on Chip.
* @data: per-instance data assigned by the driver
* @list: links gpio_device:s together for traversal
* @notifier: used to notify subscribers about lines being requested, released
* or reconfigured
* @pin_ranges: range of pins served by the GPIO driver
*
* This state container holds most of the runtime variable data
* for a GPIO device and can hold references and live on after the
* GPIO chip has been removed, if it is still being used from
* userspace.
*/
struct gpio_device {
int id;
struct device dev;
gpio: add a userspace chardev ABI for GPIOs A new chardev that is to be used for userspace GPIO access is added in this patch. It is intended to gradually replace the horribly broken sysfs ABI. Using a chardev has many upsides: - All operations are per-gpiochip, which is the actual device underlying the GPIOs, making us tie in to the kernel device model properly. - Hotpluggable GPIO controllers can come and go, as this kind of problem has been know to userspace for character devices since ages, and if a gpiochip handle is held in userspace we know we will break something, whereas the sysfs is stateless. - The one-value-per-file rule of sysfs is really hard to maintain when you want to twist more than one knob at a time, for example have in-kernel APIs to switch several GPIO lines at the same time, and this will be possible to do with a single ioctl() from userspace, saving a lot of context switching. We also need to add a new bus type for GPIO. This is necessary for example for userspace coldplug, where sysfs is traversed to find the boot-time device nodes and create the character devices in /dev. This new chardev ABI is *non* *optional* and can be counted on to be present in the future, emphasizing the preference of this ABI. The ABI only implements one single ioctl() to get the name and number of GPIO lines of a chip. Even this is debatable: see it as a minimal example for review. This ABI shall be ruthlessly reviewed and etched in stone. The old /sys/class/gpio is still optional to compile in, but will be deprecated. Unique device IDs are created using IDR, which is overkill and insanely scalable, but also well tested. Cc: Johan Hovold <johan@kernel.org> Cc: Michael Welling <mwelling@ieee.org> Cc: Markus Pargmann <mpa@pengutronix.de> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Arnd Bergmann <arnd@arndb.de> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2015-10-21 16:29:53 +03:00
struct cdev chrdev;
struct device *mockdev;
struct module *owner;
struct gpio_chip *chip;
struct gpio_desc *descs;
gpio: reflect base and ngpio into gpio_device Some information about the GPIO chip need to stay around also after the gpio_chip has been removed and only the gpio_device persist. The base and ngpio are such things, for example we don't want a new chip arriving to overlap the number space of a dangling gpio_device, and the chardev may still query the device for the number of lines etc. Note that the code that assigns base and insert gpio_device into the global list no longer check for a missing gpio_chip: we respect the number space allocated by any other gpio_device. As a consequence of the gdev being referenced directly from the gpio_desc, we need to verify it differently from all in-kernel API calls that fall through to direct queries to the gpio_chip vtable: we first check that desc is !NULL, then that desc->gdev is !NULL, then, if desc->gdev->chip is NULL, we *BAIL OUT* without any error, so as to manage the case where operations are requested on a device that is gone. These checks were non-uniform and partly missing in the past: so to simplify: create the macros VALIDATE_DESC() that will return -EINVAL if the desc or desc->gdev is missing and just 0 if the chip is gone, and conversely VALIDATE_DESC_VOID() for the case where the function does not return an error. By using these macros, we get warning messages about missing gdev with reference to the right function in the kernel log. Despite the macro business this simplifies the code and make it more readable than if we copy/paste the same descriptor checking code into all code ABI call sites (IMHO). Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-02-10 12:57:36 +03:00
int base;
u16 ngpio;
const char *label;
void *data;
struct list_head list;
struct blocking_notifier_head notifier;
#ifdef CONFIG_PINCTRL
/*
* If CONFIG_PINCTRL is enabled, then gpio controllers can optionally
* describe the actual pin range which they serve in an SoC. This
* information would be used by pinctrl subsystem to configure
* corresponding pins for gpio usage.
*/
struct list_head pin_ranges;
#endif
};
/* gpio suffixes used for ACPI and device tree lookup */
static __maybe_unused const char * const gpio_suffixes[] = { "gpios", "gpio" };
/**
* struct gpio_array - Opaque descriptor for a structure of GPIO array attributes
*
* @desc: Array of pointers to the GPIO descriptors
* @size: Number of elements in desc
* @chip: Parent GPIO chip
* @get_mask: Get mask used in fastpath
* @set_mask: Set mask used in fastpath
* @invert_mask: Invert mask used in fastpath
*
* This structure is attached to struct gpiod_descs obtained from
* gpiod_get_array() and can be passed back to get/set array functions in order
* to activate fast processing path if applicable.
*/
struct gpio_array {
struct gpio_desc **desc;
unsigned int size;
struct gpio_chip *chip;
unsigned long *get_mask;
unsigned long *set_mask;
unsigned long invert_mask[];
};
struct gpio_desc *gpiochip_get_desc(struct gpio_chip *gc, unsigned int hwnum);
#define for_each_gpio_desc(gc, desc) \
for (unsigned int __i = 0; \
__i < gc->ngpio && (desc = gpiochip_get_desc(gc, __i)); \
__i++) \
#define for_each_gpio_desc_with_flag(gc, desc, flag) \
for_each_gpio_desc(gc, desc) \
if (!test_bit(flag, &desc->flags)) {} else
int gpiod_get_array_value_complex(bool raw, bool can_sleep,
unsigned int array_size,
struct gpio_desc **desc_array,
gpiolib: Pass array info to get/set array functions In order to make use of array info obtained from gpiod_get_array() and speed up processing of arrays matching single GPIO chip layout, that information must be passed to get/set array functions. Extend the functions' API with that additional parameter and update all users. Pass NULL if a user builds an array itself from single GPIOs. Cc: Jonathan Corbet <corbet@lwn.net> Cc: Miguel Ojeda Sandonis <miguel.ojeda.sandonis@gmail.com> Cc: Geert Uytterhoeven <geert@linux-m68k.org> Cc: Sebastien Bourdelin <sebastien.bourdelin@savoirfairelinux.com> Cc: Lukas Wunner <lukas@wunner.de> Cc: Peter Korsgaard <peter.korsgaard@barco.com> Cc: Peter Rosin <peda@axentia.se> Cc: Andrew Lunn <andrew@lunn.ch> Cc: Florian Fainelli <f.fainelli@gmail.com> Cc: "David S. Miller" <davem@davemloft.net> Cc: Rojhalat Ibrahim <imr@rtschenk.de> Cc: Dominik Brodowski <linux@dominikbrodowski.net> Cc: Russell King <rmk+kernel@armlinux.org.uk> Cc: Kishon Vijay Abraham I <kishon@ti.com> Cc: Tony Lindgren <tony@atomide.com> Cc: Lars-Peter Clausen <lars@metafoo.de> Cc: Michael Hennerich <Michael.Hennerich@analog.com> Cc: Jonathan Cameron <jic23@kernel.org> Cc: Hartmut Knaack <knaack.h@gmx.de> Cc: Peter Meerwald-Stadler <pmeerw@pmeerw.net> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Jiri Slaby <jslaby@suse.com> Cc: Yegor Yefremov <yegorslists@googlemail.com> Cc: Uwe Kleine-König <u.kleine-koenig@pengutronix.de> Signed-off-by: Janusz Krzysztofik <jmkrzyszt@gmail.com> Acked-by: Ulf Hansson <ulf.hansson@linaro.org> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2018-09-06 00:50:07 +03:00
struct gpio_array *array_info,
gpiolib: Pass bitmaps, not integer arrays, to get/set array Most users of get/set array functions iterate consecutive bits of data, usually a single integer, while processing array of results obtained from, or building an array of values to be passed to those functions. Save time wasted on those iterations by changing the functions' API to accept bitmaps. All current users are updated as well. More benefits from the change are expected as soon as planned support for accepting/passing those bitmaps directly from/to respective GPIO chip callbacks if applicable is implemented. Cc: Jonathan Corbet <corbet@lwn.net> Cc: Miguel Ojeda Sandonis <miguel.ojeda.sandonis@gmail.com> Cc: Sebastien Bourdelin <sebastien.bourdelin@savoirfairelinux.com> Cc: Lukas Wunner <lukas@wunner.de> Cc: Peter Korsgaard <peter.korsgaard@barco.com> Cc: Peter Rosin <peda@axentia.se> Cc: Andrew Lunn <andrew@lunn.ch> Cc: Florian Fainelli <f.fainelli@gmail.com> Cc: "David S. Miller" <davem@davemloft.net> Cc: Rojhalat Ibrahim <imr@rtschenk.de> Cc: Dominik Brodowski <linux@dominikbrodowski.net> Cc: Russell King <rmk+kernel@armlinux.org.uk> Cc: Kishon Vijay Abraham I <kishon@ti.com> Cc: Tony Lindgren <tony@atomide.com> Cc: Lars-Peter Clausen <lars@metafoo.de> Cc: Michael Hennerich <Michael.Hennerich@analog.com> Cc: Jonathan Cameron <jic23@kernel.org> Cc: Hartmut Knaack <knaack.h@gmx.de> Cc: Peter Meerwald-Stadler <pmeerw@pmeerw.net> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Jiri Slaby <jslaby@suse.com> Cc: Yegor Yefremov <yegorslists@googlemail.com> Cc: Uwe Kleine-König <u.kleine-koenig@pengutronix.de> Signed-off-by: Janusz Krzysztofik <jmkrzyszt@gmail.com> Acked-by: Ulf Hansson <ulf.hansson@linaro.org> Reviewed-by: Geert Uytterhoeven <geert+renesas@glider.be> Tested-by: Geert Uytterhoeven <geert+renesas@glider.be> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2018-09-06 00:50:05 +03:00
unsigned long *value_bitmap);
int gpiod_set_array_value_complex(bool raw, bool can_sleep,
unsigned int array_size,
struct gpio_desc **desc_array,
struct gpio_array *array_info,
unsigned long *value_bitmap);
extern spinlock_t gpio_lock;
extern struct list_head gpio_devices;
/**
* struct gpio_desc - Opaque descriptor for a GPIO
*
* @gdev: Pointer to the parent GPIO device
* @flags: Binary descriptor flags
* @label: Name of the consumer
* @name: Line name
* @hog: Pointer to the device node that hogs this line (if any)
* @debounce_period_us: Debounce period in microseconds
*
* These are obtained using gpiod_get() and are preferable to the old
* integer-based handles.
*
* Contrary to integers, a pointer to a &struct gpio_desc is guaranteed to be
* valid until the GPIO is released.
*/
struct gpio_desc {
gpio: reflect base and ngpio into gpio_device Some information about the GPIO chip need to stay around also after the gpio_chip has been removed and only the gpio_device persist. The base and ngpio are such things, for example we don't want a new chip arriving to overlap the number space of a dangling gpio_device, and the chardev may still query the device for the number of lines etc. Note that the code that assigns base and insert gpio_device into the global list no longer check for a missing gpio_chip: we respect the number space allocated by any other gpio_device. As a consequence of the gdev being referenced directly from the gpio_desc, we need to verify it differently from all in-kernel API calls that fall through to direct queries to the gpio_chip vtable: we first check that desc is !NULL, then that desc->gdev is !NULL, then, if desc->gdev->chip is NULL, we *BAIL OUT* without any error, so as to manage the case where operations are requested on a device that is gone. These checks were non-uniform and partly missing in the past: so to simplify: create the macros VALIDATE_DESC() that will return -EINVAL if the desc or desc->gdev is missing and just 0 if the chip is gone, and conversely VALIDATE_DESC_VOID() for the case where the function does not return an error. By using these macros, we get warning messages about missing gdev with reference to the right function in the kernel log. Despite the macro business this simplifies the code and make it more readable than if we copy/paste the same descriptor checking code into all code ABI call sites (IMHO). Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-02-10 12:57:36 +03:00
struct gpio_device *gdev;
unsigned long flags;
/* flag symbols are bit numbers */
#define FLAG_REQUESTED 0
#define FLAG_IS_OUT 1
#define FLAG_EXPORT 2 /* protected by sysfs_lock */
#define FLAG_SYSFS 3 /* exported via /sys/class/gpio/control */
#define FLAG_ACTIVE_LOW 6 /* value has active low */
#define FLAG_OPEN_DRAIN 7 /* Gpio is open drain type */
#define FLAG_OPEN_SOURCE 8 /* Gpio is open source type */
#define FLAG_USED_AS_IRQ 9 /* GPIO is connected to an IRQ */
#define FLAG_IRQ_IS_ENABLED 10 /* GPIO is connected to an enabled IRQ */
#define FLAG_IS_HOGGED 11 /* GPIO is hogged */
#define FLAG_TRANSITORY 12 /* GPIO may lose value in sleep or reset */
#define FLAG_PULL_UP 13 /* GPIO has pull up enabled */
#define FLAG_PULL_DOWN 14 /* GPIO has pull down enabled */
#define FLAG_BIAS_DISABLE 15 /* GPIO has pull disabled */
#define FLAG_EDGE_RISING 16 /* GPIO CDEV detects rising edge events */
#define FLAG_EDGE_FALLING 17 /* GPIO CDEV detects falling edge events */
#define FLAG_EVENT_CLOCK_REALTIME 18 /* GPIO CDEV reports REALTIME timestamps in events */
#define FLAG_EVENT_CLOCK_HTE 19 /* GPIO CDEV reports hardware timestamps in events */
/* Connection label */
const char *label;
/* Name of the GPIO */
const char *name;
#ifdef CONFIG_OF_DYNAMIC
struct device_node *hog;
#endif
#ifdef CONFIG_GPIO_CDEV
/* debounce period in microseconds */
unsigned int debounce_period_us;
#endif
};
#define gpiod_not_found(desc) (IS_ERR(desc) && PTR_ERR(desc) == -ENOENT)
int gpiod_request(struct gpio_desc *desc, const char *label);
void gpiod_free(struct gpio_desc *desc);
static inline int gpiod_request_user(struct gpio_desc *desc, const char *label)
{
int ret;
ret = gpiod_request(desc, label);
if (ret == -EPROBE_DEFER)
ret = -ENODEV;
return ret;
}
int gpiod_configure_flags(struct gpio_desc *desc, const char *con_id,
unsigned long lflags, enum gpiod_flags dflags);
int gpio_set_debounce_timeout(struct gpio_desc *desc, unsigned int debounce);
int gpiod_hog(struct gpio_desc *desc, const char *name,
unsigned long lflags, enum gpiod_flags dflags);
/*
* Return the GPIO number of the passed descriptor relative to its chip
*/
static inline int gpio_chip_hwgpio(const struct gpio_desc *desc)
{
gpio: reflect base and ngpio into gpio_device Some information about the GPIO chip need to stay around also after the gpio_chip has been removed and only the gpio_device persist. The base and ngpio are such things, for example we don't want a new chip arriving to overlap the number space of a dangling gpio_device, and the chardev may still query the device for the number of lines etc. Note that the code that assigns base and insert gpio_device into the global list no longer check for a missing gpio_chip: we respect the number space allocated by any other gpio_device. As a consequence of the gdev being referenced directly from the gpio_desc, we need to verify it differently from all in-kernel API calls that fall through to direct queries to the gpio_chip vtable: we first check that desc is !NULL, then that desc->gdev is !NULL, then, if desc->gdev->chip is NULL, we *BAIL OUT* without any error, so as to manage the case where operations are requested on a device that is gone. These checks were non-uniform and partly missing in the past: so to simplify: create the macros VALIDATE_DESC() that will return -EINVAL if the desc or desc->gdev is missing and just 0 if the chip is gone, and conversely VALIDATE_DESC_VOID() for the case where the function does not return an error. By using these macros, we get warning messages about missing gdev with reference to the right function in the kernel log. Despite the macro business this simplifies the code and make it more readable than if we copy/paste the same descriptor checking code into all code ABI call sites (IMHO). Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-02-10 12:57:36 +03:00
return desc - &desc->gdev->descs[0];
}
/* With descriptor prefix */
#define gpiod_emerg(desc, fmt, ...) \
pr_emerg("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?",\
##__VA_ARGS__)
#define gpiod_crit(desc, fmt, ...) \
pr_crit("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?", \
##__VA_ARGS__)
#define gpiod_err(desc, fmt, ...) \
pr_err("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?", \
##__VA_ARGS__)
#define gpiod_warn(desc, fmt, ...) \
pr_warn("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?", \
##__VA_ARGS__)
#define gpiod_info(desc, fmt, ...) \
pr_info("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?", \
##__VA_ARGS__)
#define gpiod_dbg(desc, fmt, ...) \
pr_debug("gpio-%d (%s): " fmt, desc_to_gpio(desc), desc->label ? : "?",\
##__VA_ARGS__)
/* With chip prefix */
#define chip_emerg(gc, fmt, ...) \
dev_emerg(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
#define chip_crit(gc, fmt, ...) \
dev_crit(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
#define chip_err(gc, fmt, ...) \
dev_err(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
#define chip_warn(gc, fmt, ...) \
dev_warn(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
#define chip_info(gc, fmt, ...) \
dev_info(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
#define chip_dbg(gc, fmt, ...) \
dev_dbg(&gc->gpiodev->dev, "(%s): " fmt, gc->label, ##__VA_ARGS__)
#endif /* GPIOLIB_H */