Merge tag 'gpio-updates-for-v5.18' of git://git.kernel.org/pub/scm/linux/kernel/git/brgl/linux

Pull gpio updates from Bartosz Golaszewski:
 "Relatively few updates for this release cycle. We have a single new
  driver and some minor changes in drivers, more work on limiting the
  usage of of_node in drivers and DT updates:

   - new driver: gpio-en7523

   - dt-bindings: convertion of faraday,ftgpio010 to YAML, new
     compatible string in gpio-vf610 and a bugfix in an example

   - gpiolib core: several improvements and some code shrink

   - documentation: convert all public docs into kerneldoc format

   - set IRQ bus token in gpio-crystalcove (addresses a debugfs issue)

   - add a missing return value check for kstrdup() in gpio-merrifield

   - allow gpio-tps68470 to be built as module

   - more work on limiting usage of of_node in GPIO drivers

   - several sysfs interface improvements

   - use SDPX in gpio-ts4900"

* tag 'gpio-updates-for-v5.18' of git://git.kernel.org/pub/scm/linux/kernel/git/brgl/linux:
  gpio: ts4900: Use SPDX header
  gpiolib: Use list_first_entry()/list_last_entry()
  gpiolib: sysfs: Simplify edge handling in the code
  gpiolib: sysfs: Move kstrtox() calls outside of the mutex lock
  gpiolib: sysfs: Move sysfs_emit() calls outside of the mutex lock
  gpiolib: make struct comments into real kernel docs
  dt-bindings: gpio: convert faraday,ftgpio01 to yaml
  dt-bindings: gpio: gpio-vf610: Add imx93 compatible string
  gpiolib: Simplify error path in gpiod_get_index() when requesting GPIO
  gpiolib: Use short form of ternary operator in gpiod_get_index()
  gpiolib: Introduce for_each_gpio_desc_with_flag() macro
  gpio: Add support for Airoha EN7523 GPIO controller
  dt-bindings: arm: airoha: Add binding for Airoha GPIO controller
  dt-bindings: gpio: fix gpio-hog example
  gpio: tps68470: Allow building as module
  gpio: tegra: Get rid of duplicate of_node assignment
  gpio: altera-a10sr: Switch to use fwnode instead of of_node
  gpio: merrifield: check the return value of devm_kstrdup()
  gpio: crystalcove: Set IRQ domain bus token to DOMAIN_BUS_WIRED

1 files changed, 41 insertions, 0 deletions

diff --git a/drivers/gpio/gpiolib.h b/drivers/gpio/gpiolib.h
index c31f4626915d..06f3faa9fbef 100644
--- a/drivers/gpio/gpiolib.h
+++ b/drivers/gpio/gpiolib.h
@@ -37,6 +37,9 @@
  * 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
@@ -72,6 +75,20 @@ struct gpio_device {
 /* 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;
@@ -82,6 +99,13 @@ struct gpio_array {
 };
 
 struct gpio_desc *gpiochip_get_desc(struct gpio_chip *gc, unsigned int hwnum);
+
+#define for_each_gpio_desc_with_flag(i, gc, desc, flag)		\
+	for (i = 0, desc = gpiochip_get_desc(gc, i);		\
+	     i < gc->ngpio;					\
+	     i++, desc = gpiochip_get_desc(gc, i))		\
+		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,
@@ -96,6 +120,23 @@ int gpiod_set_array_value_complex(bool raw, bool can_sleep,
 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 {
 	struct gpio_device	*gdev;
 	unsigned long		flags;