docs: gpio: Add GPIO Aggregator documentation

Document the GPIO Aggregator, and the two typical use-cases.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Tested-by: Eugeniu Rosca <erosca@de.adit-jv.com>
Reviewed-by: Ulrich Hecht <uli+renesas@fpond.eu>
Reviewed-by: Eugeniu Rosca <erosca@de.adit-jv.com>
Link: https://lore.kernel.org/r/20200511145257.22970-6-geert+renesas@glider.be
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

diff --git a/Documentation/admin-guide/gpio/gpio-aggregator.rst b/Documentation/admin-guide/gpio/gpio-aggregator.rst
new file mode 100644 (file)
index 0000000..5cd1e72
--- /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 a244ba4..ef28386 100644 (file)
--- 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