Hi Geert,
Just a few comments. Please see below.
On 2/18/20 7:18 AM, Geert Uytterhoeven wrote:
> Document the GPIO Aggregator, and the two typical use-cases.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@xxxxxxxxx>
> Reviewed-by: Ulrich Hecht <uli+renesas@xxxxxxxx>
> Reviewed-by: Eugeniu Rosca <erosca@xxxxxxxxxxxxxx>
> Tested-by: Eugeniu Rosca <erosca@xxxxxxxxxxxxxx>
> ---
> v5:
> - Add Reviewed-by, Tested-by,
> - Fix inconsistent indentation.
>
> v4:
> - Add Reviewed-by,
> - Drop controversial GPIO repeater,
> - Clarify industrial control use case,
> - Fix typo s/communicated/communicate/,
> - Replace abstract frobnicator example by concrete door example with
> gpio-line-names,
>
> v3:
> - New.
> ---
> .../admin-guide/gpio/gpio-aggregator.rst | 102 ++++++++++++++++++
> Documentation/admin-guide/gpio/index.rst | 1 +
> 2 files changed, 103 insertions(+)
> create mode 100644 Documentation/admin-guide/gpio/gpio-aggregator.rst
>
> diff --git a/Documentation/admin-guide/gpio/gpio-aggregator.rst b/Documentation/admin-guide/gpio/gpio-aggregator.rst
> new file mode 100644
> index 0000000000000000..114f72be33c2571e
> --- /dev/null
> +++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst
> @@ -0,0 +1,102 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +GPIO Aggregator
> +===============
> +
> +The GPIO Aggregator allows to aggregate GPIOs, and expose them as a new
"allows" really wants an object following the verb [although the kernel sources
and docs have many cases of it not having an object]. Something like
allows {you, one, someone, users, a user} to aggregate
> +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 allows access control for individual 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 or name, 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
> + 19 of "e6052000.gpio" and GPIOs 20-21 of "gpiochip2" into a new
> + gpio_chip:
> +
> + .. code-block:: bash
> +
> + echo 'e6052000.gpio 19 gpiochip2 20-21' > new_device
> +
Does the above command tell the user that the new device is named
"gpio-aggregator.0", as used below?
> + "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 "gpio-aggregator.0":
> +
> + .. code-block:: bash
> +
> + 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 to communicate with an SPI device from userspace.
allows {choose an object} to communicate
> +
> +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:: bash
> +
> + echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override
> + echo door > /sys/bus/platform/drivers/gpio-aggregator/bind
HTH. Thanks.
--
~Randy
