1 .. SPDX-License-Identifier: GPL-2.0-only 1 .. SPDX-License-Identifier: GPL-2.0-only
2 2
3 GPIO Aggregator 3 GPIO Aggregator
4 =============== 4 ===============
5 5
6 The GPIO Aggregator provides a mechanism to ag 6 The GPIO Aggregator provides a mechanism to aggregate GPIOs, and expose them as
7 a new gpio_chip. This supports the following 7 a new gpio_chip. This supports the following use cases.
8 8
9 9
10 Aggregating GPIOs using Sysfs 10 Aggregating GPIOs using Sysfs
11 ----------------------------- 11 -----------------------------
12 12
13 GPIO controllers are exported to userspace usi 13 GPIO controllers are exported to userspace using /dev/gpiochip* character
14 devices. Access control to these devices is p 14 devices. Access control to these devices is provided by standard UNIX file
15 system permissions, on an all-or-nothing basis 15 system permissions, on an all-or-nothing basis: either a GPIO controller is
16 accessible for a user, or it is not. 16 accessible for a user, or it is not.
17 17
18 The GPIO Aggregator provides access control fo 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 c 19 aggregating them into a new gpio_chip, which can be assigned to a group or user
20 using standard UNIX file ownership and permiss 20 using standard UNIX file ownership and permissions. Furthermore, this
21 simplifies and hardens exporting GPIOs to a vi 21 simplifies and hardens exporting GPIOs to a virtual machine, as the VM can just
22 grab the full GPIO controller, and no longer n 22 grab the full GPIO controller, and no longer needs to care about which GPIOs to
23 grab and which not, reducing the attack surfac 23 grab and which not, reducing the attack surface.
24 24
25 Aggregated GPIO controllers are instantiated a 25 Aggregated GPIO controllers are instantiated and destroyed by writing to
26 write-only attribute files in sysfs. 26 write-only attribute files in sysfs.
27 27
28 /sys/bus/platform/drivers/gpio-aggregator/ 28 /sys/bus/platform/drivers/gpio-aggregator/
29 29
30 "new_device" ... 30 "new_device" ...
31 Userspace may ask the kernel t 31 Userspace may ask the kernel to instantiate an aggregated GPIO
32 controller by writing a string 32 controller by writing a string describing the GPIOs to
33 aggregate to the "new_device" 33 aggregate to the "new_device" file, using the format
34 34
35 .. code-block:: none 35 .. code-block:: none
36 36
37 [<gpioA>] [<gpiochipB> <of 37 [<gpioA>] [<gpiochipB> <offsets>] ...
38 38
39 Where: 39 Where:
40 40
41 "<gpioA>" ... 41 "<gpioA>" ...
42 is a GPIO line nam 42 is a GPIO line name,
43 43
44 "<gpiochipB>" ... 44 "<gpiochipB>" ...
45 is a GPIO chip lab 45 is a GPIO chip label, and
46 46
47 "<offsets>" ... 47 "<offsets>" ...
48 is a comma-separat 48 is a comma-separated list of GPIO offsets and/or
49 GPIO offset ranges 49 GPIO offset ranges denoted by dashes.
50 50
51 Example: Instantiate a new GPI 51 Example: Instantiate a new GPIO aggregator by aggregating GPIO
52 line 19 of "e6052000.gpio" and 52 line 19 of "e6052000.gpio" and GPIO lines 20-21 of
53 "e6050000.gpio" into a new gpi 53 "e6050000.gpio" into a new gpio_chip:
54 54
55 .. code-block:: sh 55 .. code-block:: sh
56 56
57 $ echo 'e6052000.gpio 19 e 57 $ echo 'e6052000.gpio 19 e6050000.gpio 20-21' > new_device
58 58
59 "delete_device" ... 59 "delete_device" ...
60 Userspace may ask the kernel t 60 Userspace may ask the kernel to destroy an aggregated GPIO
61 controller after use by writin 61 controller after use by writing its device name to the
62 "delete_device" file. 62 "delete_device" file.
63 63
64 Example: Destroy the previousl 64 Example: Destroy the previously-created aggregated GPIO
65 controller, assumed to be "gpi 65 controller, assumed to be "gpio-aggregator.0":
66 66
67 .. code-block:: sh 67 .. code-block:: sh
68 68
69 $ echo gpio-aggregator.0 > 69 $ echo gpio-aggregator.0 > delete_device
70 70
71 71
72 Generic GPIO Driver 72 Generic GPIO Driver
73 ------------------- 73 -------------------
74 74
75 The GPIO Aggregator can also be used as a gene 75 The GPIO Aggregator can also be used as a generic driver for a simple
76 GPIO-operated device described in DT, without 76 GPIO-operated device described in DT, without a dedicated in-kernel driver.
77 This is useful in industrial control, and is n 77 This is useful in industrial control, and is not unlike e.g. spidev, which
78 allows the user to communicate with an SPI dev 78 allows the user to communicate with an SPI device from userspace.
79 79
80 Binding a device to the GPIO Aggregator is per 80 Binding a device to the GPIO Aggregator is performed either by modifying the
81 gpio-aggregator driver, or by writing to the " 81 gpio-aggregator driver, or by writing to the "driver_override" file in Sysfs.
82 82
83 Example: If "door" is a GPIO-operated device d 83 Example: If "door" is a GPIO-operated device described in DT, using its own
84 compatible value:: 84 compatible value::
85 85
86 door { 86 door {
87 compatible = "myvendor,mydoor" 87 compatible = "myvendor,mydoor";
88 88
89 gpios = <&gpio2 19 GPIO_ACTIVE 89 gpios = <&gpio2 19 GPIO_ACTIVE_HIGH>,
90 <&gpio2 20 GPIO_ACTIVE 90 <&gpio2 20 GPIO_ACTIVE_LOW>;
91 gpio-line-names = "open", "loc 91 gpio-line-names = "open", "lock";
92 }; 92 };
93 93
94 it can be bound to the GPIO Aggregator by eith 94 it can be bound to the GPIO Aggregator by either:
95 95
96 1. Adding its compatible value to ``gpio_aggre 96 1. Adding its compatible value to ``gpio_aggregator_dt_ids[]``,
97 2. Binding manually using "driver_override": 97 2. Binding manually using "driver_override":
98 98
99 .. code-block:: sh 99 .. code-block:: sh
100 100
101 $ echo gpio-aggregator > /sys/bus/platform 101 $ echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override
102 $ echo door > /sys/bus/platform/drivers/gp 102 $ echo door > /sys/bus/platform/drivers/gpio-aggregator/bind
103 103
104 After that, a new gpiochip "door" has been cre 104 After that, a new gpiochip "door" has been created:
105 105
106 .. code-block:: sh 106 .. code-block:: sh
107 107
108 $ gpioinfo door 108 $ gpioinfo door
109 gpiochip12 - 2 lines: 109 gpiochip12 - 2 lines:
110 line 0: "open" unuse 110 line 0: "open" unused input active-high
111 line 1: "lock" unuse 111 line 1: "lock" unused input active-high
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.