Merge tag 'gpio-v5.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio

Pull GPIO updates from Linus Walleij:
 "This is the bulk of GPIO changes for the v5.8 kernel cycle.

  Core changes:

   - A new GPIO aggregator driver has been merged: this can join a few
     select GPIO lines into a new aggregated GPIO chip. This can be used
     for security: a process can be granted access to only these lines,
     for example for industrial control. Another way to use this is to
     reexpose certain select lines to a virtual machine or container.

   - Warn if the gpio-line-names is too long in he DT parser core.

   - GPIO lines can now be looked up by line name in addition to being
     looked up by offset.

  New drivers:

   - A new generic regmap GPIO driver has been merged. Too many regmap
     drivers are starting to look like each other so we need to create
     some common ground and try to move drivers over to using that.

   - The F7188X driver now supports F81865.

  Driver improvements:

   - Large improvements to the PCA953x expander, get multiple lines and
     several cleanups.

   - Large improvements to the DesignWare DWAPB driver, and Sergey Semin
     has volunteered to maintain it.

   - PL061 can now be built as a module, this is part of a bigger effort
     to make the ARM platforms more modular"

* tag 'gpio-v5.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio: (77 commits)
  gpio: pca953x: Drop unneeded ACPI_PTR()
  MAINTAINERS: Add gpio regmap section
  gpio: add a reusable generic gpio_chip using regmap
  gpiolib: Introduce gpiochip_irqchip_add_domain()
  gpio: gpiolib: Allow GPIO IRQs to lazy disable
  gpiolib: Separate GPIO_GET_LINEINFO_WATCH_IOCTL conditional
  gpio: rcar: Fix runtime PM imbalance on error
  gpio: pca935x: Allow IRQ support for driver built as a module
  gpio: pxa: Add COMPILE_TEST support
  dt-bindings: gpio: Add renesas,em-gio bindings
  MAINTAINERS: Fix file name for DesignWare GPIO DT schema
  gpio: dwapb: Remove unneeded has_irq member in struct dwapb_port_property
  gpio: dwapb: Don't use IRQ 0 as valid Linux interrupt
  gpio: dwapb: avoid error message for optional IRQ
  gpio: dwapb: Call acpi_gpiochip_free_interrupts() on GPIO chip de-registration
  gpio: max730x: bring gpiochip_add_data after port config
  MAINTAINERS: Add GPIO Aggregator section
  docs: gpio: Add GPIO Aggregator documentation
  gpio: Add GPIO Aggregator
  gpiolib: Add support for GPIO lookup by line name
  ...

2 files changed, 112 insertions, 0 deletions

diff --git a/Documentation/admin-guide/gpio/gpio-aggregator.rst b/Documentation/admin-guide/gpio/gpio-aggregator.rst
new file mode 100644
index 000000000000..5cd1e7221756
--- /dev/null
+++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+GPIO Aggregator
+===============
+
+The GPIO Aggregator provides a mechanism to aggregate GPIOs, and expose them as
+a new gpio_chip.  This supports the following use cases.
+
+
+Aggregating GPIOs using Sysfs
+-----------------------------
+
+GPIO controllers are exported to userspace using /dev/gpiochip* character
+devices.  Access control to these devices is provided by standard UNIX file
+system permissions, on an all-or-nothing basis: either a GPIO controller is
+accessible for a user, or it is not.
+
+The GPIO Aggregator provides access control for a set of one or more GPIOs, by
+aggregating them into a new gpio_chip, which can be assigned to a group or user
+using standard UNIX file ownership and permissions.  Furthermore, this
+simplifies and hardens exporting GPIOs to a virtual machine, as the VM can just
+grab the full GPIO controller, and no longer needs to care about which GPIOs to
+grab and which not, reducing the attack surface.
+
+Aggregated GPIO controllers are instantiated and destroyed by writing to
+write-only attribute files in sysfs.
+
+    /sys/bus/platform/drivers/gpio-aggregator/
+
+	"new_device" ...
+		Userspace may ask the kernel to instantiate an aggregated GPIO
+		controller by writing a string describing the GPIOs to
+		aggregate to the "new_device" file, using the format
+
+		.. code-block:: none
+
+		    [<gpioA>] [<gpiochipB> <offsets>] ...
+
+		Where:
+
+		    "<gpioA>" ...
+			    is a GPIO line name,
+
+		    "<gpiochipB>" ...
+			    is a GPIO chip label, and
+
+		    "<offsets>" ...
+			    is a comma-separated list of GPIO offsets and/or
+			    GPIO offset ranges denoted by dashes.
+
+		Example: Instantiate a new GPIO aggregator by aggregating GPIO
+		line 19 of "e6052000.gpio" and GPIO lines 20-21 of
+		"e6050000.gpio" into a new gpio_chip:
+
+		.. code-block:: sh
+
+		    $ echo 'e6052000.gpio 19 e6050000.gpio 20-21' > new_device
+
+	"delete_device" ...
+		Userspace may ask the kernel to destroy an aggregated GPIO
+		controller after use by writing its device name to the
+		"delete_device" file.
+
+		Example: Destroy the previously-created aggregated GPIO
+		controller, assumed to be "gpio-aggregator.0":
+
+		.. code-block:: sh
+
+		    $ echo gpio-aggregator.0 > delete_device
+
+
+Generic GPIO Driver
+-------------------
+
+The GPIO Aggregator can also be used as a generic driver for a simple
+GPIO-operated device described in DT, without a dedicated in-kernel driver.
+This is useful in industrial control, and is not unlike e.g. spidev, which
+allows the user to communicate with an SPI device from userspace.
+
+Binding a device to the GPIO Aggregator is performed either by modifying the
+gpio-aggregator driver, or by writing to the "driver_override" file in Sysfs.
+
+Example: If "door" is a GPIO-operated device described in DT, using its own
+compatible value::
+
+	door {
+		compatible = "myvendor,mydoor";
+
+		gpios = <&gpio2 19 GPIO_ACTIVE_HIGH>,
+			<&gpio2 20 GPIO_ACTIVE_LOW>;
+		gpio-line-names = "open", "lock";
+	};
+
+it can be bound to the GPIO Aggregator by either:
+
+1. Adding its compatible value to ``gpio_aggregator_dt_ids[]``,
+2. Binding manually using "driver_override":
+
+.. code-block:: sh
+
+    $ echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override
+    $ echo door > /sys/bus/platform/drivers/gpio-aggregator/bind
+
+After that, a new gpiochip "door" has been created:
+
+.. code-block:: sh
+
+    $ gpioinfo door
+    gpiochip12 - 2 lines:
+	    line   0:       "open"       unused   input  active-high
+	    line   1:       "lock"       unused   input  active-high
diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
index a244ba4e87d5..ef2838638e96 100644
--- a/Documentation/admin-guide/gpio/index.rst
+++ b/Documentation/admin-guide/gpio/index.rst
@@ -7,6 +7,7 @@ gpio
 .. toctree::
     :maxdepth: 1
 
+    gpio-aggregator
     sysfs
 
 .. only::  subproject and html