Re: [PATCH v5 4/5] docs: gpio: Add GPIO Aggregator documentation

Hi Randy,

On Tue, Feb 18, 2020 at 7:30 PM Randy Dunlap [off-list ref] wrote:

On 2/18/20 7:18 AM, Geert Uytterhoeven wrote:

quoted

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

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>

quoted

--- /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

Changing to:

    provides a mechanism to aggregate GPIOs

quoted

+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

Changing to:

    provides access control for a set of one or more GPIOs

quoted

+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.

quoted

+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

Changing to:

    allows the user to communicate

Gr{oetje,eeting}s,

                        Geert

-- 
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds