1.. SPDX-License-Identifier: GPL-2.0-only
  2
  3GPIO Aggregator
  4===============
  5
  6The GPIO Aggregator provides a mechanism to aggregate GPIOs, and expose them as
  7a new gpio_chip.  This supports the following use cases.
  8
  9
 10Aggregating GPIOs using Sysfs
 11-----------------------------
 12
 13GPIO controllers are exported to userspace using /dev/gpiochip* character
 14devices.  Access control to these devices is provided by standard UNIX file
 15system permissions, on an all-or-nothing basis: either a GPIO controller is
 16accessible for a user, or it is not.
 17
 18The GPIO Aggregator provides access control for a set of one or more GPIOs, by
 19aggregating them into a new gpio_chip, which can be assigned to a group or user
 20using standard UNIX file ownership and permissions.  Furthermore, this
 21simplifies and hardens exporting GPIOs to a virtual machine, as the VM can just
 22grab the full GPIO controller, and no longer needs to care about which GPIOs to
 23grab and which not, reducing the attack surface.
 24
 25Aggregated GPIO controllers are instantiated and destroyed by writing to
 26write-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 GPIO
 32		controller by writing a string describing the GPIOs to
 33		aggregate to the "new_device" file, using the format
 34
 35		.. code-block:: none
 36
 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, and
 46
 47		    "<offsets>" ...
 48			    is a comma-separated list of GPIO offsets and/or
 49			    GPIO offset ranges denoted by dashes.
 50
 51		Example: Instantiate a new GPIO aggregator by aggregating GPIO
 52		line 19 of "e6052000.gpio" and GPIO lines 20-21 of
 53		"e6050000.gpio" into a new gpio_chip:
 54
 55		.. code-block:: sh
 56
 57		    $ echo 'e6052000.gpio 19 e6050000.gpio 20-21' > new_device
 58
 59	"delete_device" ...
 60		Userspace may ask the kernel to destroy an aggregated GPIO
 61		controller after use by writing its device name to the
 62		"delete_device" file.
 63
 64		Example: Destroy the previously-created aggregated GPIO
 65		controller, assumed to be "gpio-aggregator.0":
 66
 67		.. code-block:: sh
 68
 69		    $ echo gpio-aggregator.0 > delete_device
 70
 71
 72Generic GPIO Driver
 73-------------------
 74
 75The GPIO Aggregator can also be used as a generic driver for a simple
 76GPIO-operated device described in DT, without a dedicated in-kernel driver.
 77This is useful in industrial control, and is not unlike e.g. spidev, which
 78allows the user to communicate with an SPI device from userspace.
 79
 80Binding a device to the GPIO Aggregator is performed either by modifying the
 81gpio-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 own
 84compatible 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:: sh
100
101    $ echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override
102    $ echo door > /sys/bus/platform/drivers/gpio-aggregator/bind
103
104After that, a new gpiochip "door" has been created:
105
106.. code-block:: sh
107
108    $ gpioinfo door
109    gpiochip12 - 2 lines:
110	    line   0:       "open"       unused   input  active-high
111	    line   1:       "lock"       unused   input  active-high