| Message ID | 20191127084253.16356-7-geert+renesas@glider.be |
|---|---|
| State | New |
| Headers | show |
| Series | gpio: Add GPIO Aggregator/Repeater | expand |
> On November 27, 2019 at 9:42 AM Geert Uytterhoeven <geert+renesas@glider.be> wrote: > > > Document the GPIO Aggregator/Repeater, and the three typical use-cases. > > Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be> > --- > v3: > - New. > --- > .../admin-guide/gpio/gpio-aggregator.rst | 111 ++++++++++++++++++ > Documentation/admin-guide/gpio/index.rst | 1 + > 2 files changed, 112 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..826146e260253299 > --- /dev/null > +++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst > @@ -0,0 +1,111 @@ > +.. SPDX-License-Identifier: GPL-2.0-only > + > +GPIO Aggregator/Repeater > +======================== > + > +The GPIO Aggregator/Repeater 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 > + > + > +GPIO Repeater in Device Tree > +---------------------------- > + > +A GPIO Repeater is a node in a Device Tree representing a repeater for one or > +more GPIOs, possibly including physical signal property translation (e.g. > +polarity inversion). This allows to model e.g. inverters in DT. > + > +See Documentation/devicetree/bindings/gpio/gpio-repeater.yaml > + > + > +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 not unlike e.g. spidev, which allows to communicated 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 "frobnicator" is a GPIO-operated device described in DT, using its > +own compatible value:: > + > + frobnicator { > + compatible = "myvendor,frobnicator"; > + > + gpios = <&gpio2 19 GPIO_ACTIVE_HIGH>, > + <&gpio2 20 GPIO_ACTIVE_LOW>; > + }; > + > +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/frobnicator/driver_override > + echo frobnicator > /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 > -- > 2.17.1 > Reviewed-by: Ulrich Hecht <uli+renesas@fpond.eu> CU Uli
On Wed, Nov 27, 2019 at 9:43 AM Geert Uytterhoeven <geert+renesas@glider.be> wrote: > +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. I suppose virtual machines will have a lengthy config file where they specify which GPIO lines to pick and use for their GPIO aggregator, and that will all be fine, the VM starts and the aggregator is there and we can start executing. I would perhaps point out a weakness as with all sysfs and with the current gpio sysfs: if a process creates an aggregator device, and then that process crashes, what happens when you try to restart the process and run e.g. your VM again? Time for a hard reboot? Or should we add some design guidelines for these machines so that they can cleanly tear down aggregators previously created by the crashed VM? Yours, Linus Walleij
Hi Linus, On Thu, Dec 12, 2019 at 3:42 PM Linus Walleij <linus.walleij@linaro.org> wrote: > On Wed, Nov 27, 2019 at 9:43 AM Geert Uytterhoeven > <geert+renesas@glider.be> wrote: > > +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. > > I suppose virtual machines will have a lengthy config file where > they specify which GPIO lines to pick and use for their GPIO > aggregator, and that will all be fine, the VM starts and the aggregator > is there and we can start executing. > > I would perhaps point out a weakness as with all sysfs and with the current > gpio sysfs: if a process creates an aggregator device, and then that > process crashes, what happens when you try to restart the process and > run e.g. your VM again? > > Time for a hard reboot? Or should we add some design guidelines for > these machines so that they can cleanly tear down aggregators > previously created by the crashed VM? No, the VM does not create the aggregator. The idea is for the user to create one or more aggregators, set up permissions on /dev/gpiochipX, and launch the VM, passing the aggregated /dev/gpiochipX as parameters. If the VM crashes, just launch it again. Destroying the aggregators is a manual and independent process, after the VM has exited. 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
On Thu, Dec 12, 2019 at 3:48 PM Geert Uytterhoeven <geert@linux-m68k.org> wrote: > On Thu, Dec 12, 2019 at 3:42 PM Linus Walleij <linus.walleij@linaro.org> wrote: > > On Wed, Nov 27, 2019 at 9:43 AM Geert Uytterhoeven > > <geert+renesas@glider.be> wrote: > > > +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. > > > > I suppose virtual machines will have a lengthy config file where > > they specify which GPIO lines to pick and use for their GPIO > > aggregator, and that will all be fine, the VM starts and the aggregator > > is there and we can start executing. > > > > I would perhaps point out a weakness as with all sysfs and with the current > > gpio sysfs: if a process creates an aggregator device, and then that > > process crashes, what happens when you try to restart the process and > > run e.g. your VM again? > > > > Time for a hard reboot? Or should we add some design guidelines for > > these machines so that they can cleanly tear down aggregators > > previously created by the crashed VM? > > No, the VM does not create the aggregator. > > The idea is for the user to create one or more aggregators, set up > permissions on /dev/gpiochipX, and launch the VM, passing the aggregated > /dev/gpiochipX as parameters. > If the VM crashes, just launch it again. > > Destroying the aggregators is a manual and independent process, after > the VM has exited. I'm thinking about someone making some industrial application for some control of a machinery say a robotic arm. And do make sure this VM is only controlling these GPIOs related to this robotic arm, they create a GPIO aggregator. And we care about cases like that since we provide this security argument. Surely that machine will be rebooted. Surely they don't have a printed paper with all the commands lying at the console, and asking whoever powers it back on to manually type it all in again. That feels a bit 1981. So they will have a script for this I suppose. Possibly in some initscript so it is set up on boot. And this script echos stuff all over the place to set up the aggregator. Is this the use case you're thinking of? I just like to have the whole picture here. Yours, Linus Walleij
Hi Linus, On Sat, Jan 4, 2020 at 1:21 AM Linus Walleij <linus.walleij@linaro.org> wrote: > On Thu, Dec 12, 2019 at 3:48 PM Geert Uytterhoeven <geert@linux-m68k.org> wrote: > > On Thu, Dec 12, 2019 at 3:42 PM Linus Walleij <linus.walleij@linaro.org> wrote: > > > On Wed, Nov 27, 2019 at 9:43 AM Geert Uytterhoeven > > > <geert+renesas@glider.be> wrote: > > > > +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. > > > > > > I suppose virtual machines will have a lengthy config file where > > > they specify which GPIO lines to pick and use for their GPIO > > > aggregator, and that will all be fine, the VM starts and the aggregator > > > is there and we can start executing. > > > > > > I would perhaps point out a weakness as with all sysfs and with the current > > > gpio sysfs: if a process creates an aggregator device, and then that > > > process crashes, what happens when you try to restart the process and > > > run e.g. your VM again? > > > > > > Time for a hard reboot? Or should we add some design guidelines for > > > these machines so that they can cleanly tear down aggregators > > > previously created by the crashed VM? > > > > No, the VM does not create the aggregator. > > > > The idea is for the user to create one or more aggregators, set up > > permissions on /dev/gpiochipX, and launch the VM, passing the aggregated > > /dev/gpiochipX as parameters. > > If the VM crashes, just launch it again. > > > > Destroying the aggregators is a manual and independent process, after > > the VM has exited. > > I'm thinking about someone making some industrial application for some > control of a machinery say a robotic arm. > > And do make sure this VM is only controlling these GPIOs related to > this robotic arm, they create a GPIO aggregator. And we care about > cases like that since we provide this security argument. > > Surely that machine will be rebooted. > > Surely they don't have a printed paper with all the commands lying > at the console, and asking whoever powers it back on to manually > type it all in again. That feels a bit 1981. > > So they will have a script for this I suppose. Possibly in some > initscript so it is set up on boot. And this script echos stuff > all over the place to set up the aggregator. > > Is this the use case you're thinking of? Exactly. And they can configure that by echoing the GPIO specifiers to /sys/bus/platform/drivers/gpio-aggregator/new_device. If their system has DT, another option is to describe the device in DT, and add its compatible value to gpio_aggregator_dt_ids[], cfr. the frobnicator example. > I just like to have the whole picture here. Sure. If anything is still unclear, please let me know! Thanks! Gr{oetje,eeting}s, Geert
diff --git a/Documentation/admin-guide/gpio/gpio-aggregator.rst b/Documentation/admin-guide/gpio/gpio-aggregator.rst new file mode 100644 index 0000000000000000..826146e260253299 --- /dev/null +++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst @@ -0,0 +1,111 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +GPIO Aggregator/Repeater +======================== + +The GPIO Aggregator/Repeater 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 + + +GPIO Repeater in Device Tree +---------------------------- + +A GPIO Repeater is a node in a Device Tree representing a repeater for one or +more GPIOs, possibly including physical signal property translation (e.g. +polarity inversion). This allows to model e.g. inverters in DT. + +See Documentation/devicetree/bindings/gpio/gpio-repeater.yaml + + +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 not unlike e.g. spidev, which allows to communicated 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 "frobnicator" is a GPIO-operated device described in DT, using its +own compatible value:: + + frobnicator { + compatible = "myvendor,frobnicator"; + + gpios = <&gpio2 19 GPIO_ACTIVE_HIGH>, + <&gpio2 20 GPIO_ACTIVE_LOW>; + }; + +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/frobnicator/driver_override + echo frobnicator > /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
Document the GPIO Aggregator/Repeater, and the three typical use-cases. Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be> --- v3: - New. --- .../admin-guide/gpio/gpio-aggregator.rst | 111 ++++++++++++++++++ Documentation/admin-guide/gpio/index.rst | 1 + 2 files changed, 112 insertions(+) create mode 100644 Documentation/admin-guide/gpio/gpio-aggregator.rst