admin-guide/gpio/gpio-aggregator.rst

1 .. SPDX-License-Identifier: GPL-2.0-only
3 GPIO Aggregator
6 The GPIO Aggregator provides a mechanism to aggregate GPIOs, and expose them as
7 a new gpio_chip.  This supports the following use cases.
11 -----------------------------
13 GPIO controllers are exported to userspace using /dev/gpiochip* character
15 system permissions, on an all-or-nothing basis: either a GPIO controller is
16 accessible for a user, or it is not.
18 The GPIO Aggregator provides access control for a set of one or more GPIOs, by
19 aggregating them into a new gpio_chip, which can be assigned to a group or user
21 simplifies and hardens exporting GPIOs to a virtual machine, as the VM can just
22 grab the full GPIO controller, and no longer needs to care about which GPIOs to
25 Aggregated GPIO controllers are instantiated and destroyed by writing to
26 write-only attribute files in sysfs.
28     /sys/bus/platform/drivers/gpio-aggregator/
31 		Userspace may ask the kernel to instantiate an aggregated GPIO
32 		controller by writing a string describing the GPIOs to
35 		.. code-block:: none
42 			    is a GPIO line name,
45 			    is a GPIO chip label, and
48 			    is a comma-separated list of GPIO offsets and/or
49 			    GPIO offset ranges denoted by dashes.
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:
55 		.. code-block:: sh
57 		    $ echo 'e6052000.gpio 19 e6050000.gpio 20-21' > new_device
60 		Userspace may ask the kernel to destroy an aggregated GPIO
64 		Example: Destroy the previously-created aggregated GPIO
65 		controller, assumed to be "gpio-aggregator.0":
67 		.. code-block:: sh
69 		    $ echo gpio-aggregator.0 > delete_device
72 Generic GPIO Driver
73 -------------------
75 The GPIO Aggregator can also be used as a generic driver for a simple
76 GPIO-operated device described in DT, without a dedicated in-kernel driver.
80 Binding a device to the GPIO Aggregator is performed either by modifying the
81 gpio-aggregator driver, or by writing to the "driver_override" file in Sysfs.
83 Example: If "door" is a GPIO-operated device described in DT, using its own
91 		gpio-line-names = "open", "lock";
94 it can be bound to the GPIO Aggregator by either:
99 .. code-block:: sh
101     $ echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override
102     $ echo door > /sys/bus/platform/drivers/gpio-aggregator/bind
104 After that, a new gpiochip "door" has been created:
106 .. code-block:: sh
109     gpiochip12 - 2 lines:
110 	    line   0:       "open"       unused   input  active-high
111 	    line   1:       "lock"       unused   input  active-high