| Message ID | 20200218151812.7816-5-geert+renesas@glider.be (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | gpio: Add GPIO Aggregator | expand |
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@glider.be> > Reviewed-by: Ulrich Hecht <uli+renesas@fpond.eu> > Reviewed-by: Eugeniu Rosca <erosca@de.adit-jv.com> > Tested-by: Eugeniu Rosca <erosca@de.adit-jv.com> > --- > 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.
Hi Randy, On Tue, Feb 18, 2020 at 7:30 PM Randy Dunlap <rdunlap@infradead.org> wrote: > 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@glider.be> > > --- /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 Thanks for the hint! > > + 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? Yes, it will be printed through the kernel log, cfr. the sample session in the cover letter. Gr{oetje,eeting}s, Geert
Hi Randy, On Tue, Feb 18, 2020 at 7:30 PM Randy Dunlap <rdunlap@infradead.org> wrote: > 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@glider.be> > > --- /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 > > +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 > > +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. > > +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
On 2/21/20 8:34 AM, Geert Uytterhoeven wrote: > Hi Randy, > Hi Geert, Those changes look good. Thanks.
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 +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 + + "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. + +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 diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst index a244ba4e87d5398a..ef2838638e967777 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