112 lines · plain
1.. SPDX-License-Identifier: GPL-2.0-only2 3GPIO Aggregator4===============5 6The GPIO Aggregator provides a mechanism to aggregate GPIOs, and expose them as7a new gpio_chip. This supports the following use cases.8 9 10Aggregating GPIOs using Sysfs11-----------------------------12 13GPIO controllers are exported to userspace using /dev/gpiochip* character14devices. Access control to these devices is provided by standard UNIX file15system permissions, on an all-or-nothing basis: either a GPIO controller is16accessible for a user, or it is not.17 18The GPIO Aggregator provides access control for a set of one or more GPIOs, by19aggregating them into a new gpio_chip, which can be assigned to a group or user20using standard UNIX file ownership and permissions. Furthermore, this21simplifies and hardens exporting GPIOs to a virtual machine, as the VM can just22grab the full GPIO controller, and no longer needs to care about which GPIOs to23grab and which not, reducing the attack surface.24 25Aggregated GPIO controllers are instantiated and destroyed by writing to26write-only attribute files in sysfs.27 28 /sys/bus/platform/drivers/gpio-aggregator/29 30 "new_device" ...31 Userspace may ask the kernel to instantiate an aggregated GPIO32 controller by writing a string describing the GPIOs to33 aggregate to the "new_device" file, using the format34 35 .. code-block:: none36 37 [<gpioA>] [<gpiochipB> <offsets>] ...38 39 Where:40 41 "<gpioA>" ...42 is a GPIO line name,43 44 "<gpiochipB>" ...45 is a GPIO chip label, and46 47 "<offsets>" ...48 is a comma-separated list of GPIO offsets and/or49 GPIO offset ranges denoted by dashes.50 51 Example: Instantiate a new GPIO aggregator by aggregating GPIO52 line 19 of "e6052000.gpio" and GPIO lines 20-21 of53 "e6050000.gpio" into a new gpio_chip:54 55 .. code-block:: sh56 57 $ echo 'e6052000.gpio 19 e6050000.gpio 20-21' > new_device58 59 "delete_device" ...60 Userspace may ask the kernel to destroy an aggregated GPIO61 controller after use by writing its device name to the62 "delete_device" file.63 64 Example: Destroy the previously-created aggregated GPIO65 controller, assumed to be "gpio-aggregator.0":66 67 .. code-block:: sh68 69 $ echo gpio-aggregator.0 > delete_device70 71 72Generic GPIO Driver73-------------------74 75The GPIO Aggregator can also be used as a generic driver for a simple76GPIO-operated device described in DT, without a dedicated in-kernel driver.77This is useful in industrial control, and is not unlike e.g. spidev, which78allows the user to communicate with an SPI device from userspace.79 80Binding a device to the GPIO Aggregator is performed either by modifying the81gpio-aggregator driver, or by writing to the "driver_override" file in Sysfs.82 83Example: If "door" is a GPIO-operated device described in DT, using its own84compatible value::85 86 door {87 compatible = "myvendor,mydoor";88 89 gpios = <&gpio2 19 GPIO_ACTIVE_HIGH>,90 <&gpio2 20 GPIO_ACTIVE_LOW>;91 gpio-line-names = "open", "lock";92 };93 94it can be bound to the GPIO Aggregator by either:95 961. Adding its compatible value to ``gpio_aggregator_dt_ids[]``,972. Binding manually using "driver_override":98 99.. code-block:: sh100 101 $ echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override102 $ echo door > /sys/bus/platform/drivers/gpio-aggregator/bind103 104After that, a new gpiochip "door" has been created:105 106.. code-block:: sh107 108 $ gpioinfo door109 gpiochip12 - 2 lines:110 line 0: "open" unused input active-high111 line 1: "lock" unused input active-high112