1 .. SPDX-License-Identifier: GPL-2.0-only 1 .. SPDX-License-Identifier: GPL-2.0-only
2 2
3 Virtual GPIO Consumer 3 Virtual GPIO Consumer
4 ===================== 4 =====================
5 5
6 The virtual GPIO Consumer module allows users 6 The virtual GPIO Consumer module allows users to instantiate virtual devices
7 that request GPIOs and then control their beha 7 that request GPIOs and then control their behavior over debugfs. Virtual
8 consumer devices can be instantiated from devi 8 consumer devices can be instantiated from device-tree or over configfs.
9 9
10 A virtual consumer uses the driver-facing GPIO 10 A virtual consumer uses the driver-facing GPIO APIs and allows to cover it with
11 automated tests driven by user-space. The GPIO 11 automated tests driven by user-space. The GPIOs are requested using
12 ``gpiod_get_array()`` and so we support multip 12 ``gpiod_get_array()`` and so we support multiple GPIOs per connector ID.
13 13
14 Creating GPIO consumers 14 Creating GPIO consumers
15 ----------------------- 15 -----------------------
16 16
17 The gpio-consumer module registers a configfs 17 The gpio-consumer module registers a configfs subsystem called
18 ``'gpio-virtuser'``. For details of the config 18 ``'gpio-virtuser'``. For details of the configfs filesystem, please refer to
19 the configfs documentation. 19 the configfs documentation.
20 20
21 The user can create a hierarchy of configfs gr 21 The user can create a hierarchy of configfs groups and items as well as modify
22 values of exposed attributes. Once the consume 22 values of exposed attributes. Once the consumer is instantiated, this hierarchy
23 will be translated to appropriate device prope 23 will be translated to appropriate device properties. The general structure is:
24 24
25 **Group:** ``/config/gpio-virtuser`` 25 **Group:** ``/config/gpio-virtuser``
26 26
27 This is the top directory of the gpio-consumer 27 This is the top directory of the gpio-consumer configfs tree.
28 28
29 **Group:** ``/config/gpio-consumer/example-nam 29 **Group:** ``/config/gpio-consumer/example-name``
30 30
31 **Attribute:** ``/config/gpio-consumer/example 31 **Attribute:** ``/config/gpio-consumer/example-name/live``
32 32
33 **Attribute:** ``/config/gpio-consumer/example 33 **Attribute:** ``/config/gpio-consumer/example-name/dev_name``
34 34
35 This is a directory representing a GPIO consum 35 This is a directory representing a GPIO consumer device.
36 36
37 The read-only ``dev_name`` attribute exposes t 37 The read-only ``dev_name`` attribute exposes the name of the device as it will
38 appear in the system on the platform bus. This 38 appear in the system on the platform bus. This is useful for locating the
39 associated debugfs directory under 39 associated debugfs directory under
40 ``/sys/kernel/debug/gpio-virtuser/$dev_name``. 40 ``/sys/kernel/debug/gpio-virtuser/$dev_name``.
41 41
42 The ``'live'`` attribute allows to trigger the 42 The ``'live'`` attribute allows to trigger the actual creation of the device
43 once it's fully configured. The accepted value 43 once it's fully configured. The accepted values are: ``'1'`` to enable the
44 virtual device and ``'0'`` to disable and tear 44 virtual device and ``'0'`` to disable and tear it down.
45 45
46 Creating GPIO lookup tables 46 Creating GPIO lookup tables
47 --------------------------- 47 ---------------------------
48 48
49 Users can create a number of configfs groups u 49 Users can create a number of configfs groups under the device group:
50 50
51 **Group:** ``/config/gpio-consumer/example-nam 51 **Group:** ``/config/gpio-consumer/example-name/con_id``
52 52
53 The ``'con_id'`` directory represents a single 53 The ``'con_id'`` directory represents a single GPIO lookup and its value maps
54 to the ``'con_id'`` argument of the ``gpiod_ge 54 to the ``'con_id'`` argument of the ``gpiod_get()`` function. For example:
55 ``con_id`` == ``'reset'`` maps to the ``reset- 55 ``con_id`` == ``'reset'`` maps to the ``reset-gpios`` device property.
56 56
57 Users can assign a number of GPIOs to each loo 57 Users can assign a number of GPIOs to each lookup. Each GPIO is a sub-directory
58 with a user-defined name under the ``'con_id'` 58 with a user-defined name under the ``'con_id'`` group.
59 59
60 **Attribute:** ``/config/gpio-consumer/example 60 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/key``
61 61
62 **Attribute:** ``/config/gpio-consumer/example 62 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/offset``
63 63
64 **Attribute:** ``/config/gpio-consumer/example 64 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/drive``
65 65
66 **Attribute:** ``/config/gpio-consumer/example 66 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/pull``
67 67
68 **Attribute:** ``/config/gpio-consumer/example 68 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/active_low``
69 69
70 **Attribute:** ``/config/gpio-consumer/example 70 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/transitory``
71 71
72 This is a group describing a single GPIO in th 72 This is a group describing a single GPIO in the ``con_id-gpios`` property.
73 73
74 For virtual consumers created using configfs w 74 For virtual consumers created using configfs we use machine lookup tables so
75 this group can be considered as a mapping betw 75 this group can be considered as a mapping between the filesystem and the fields
76 of a single entry in ``'struct gpiod_lookup'`` 76 of a single entry in ``'struct gpiod_lookup'``.
77 77
78 The ``'key'`` attribute represents either the 78 The ``'key'`` attribute represents either the name of the chip this GPIO
79 belongs to or the GPIO line name. This depends 79 belongs to or the GPIO line name. This depends on the value of the ``'offset'``
80 attribute: if its value is >= 0, then ``'key'` 80 attribute: if its value is >= 0, then ``'key'`` represents the label of the
81 chip to lookup while ``'offset'`` represents t 81 chip to lookup while ``'offset'`` represents the offset of the line in that
82 chip. If ``'offset'`` is < 0, then ``'key'`` r 82 chip. If ``'offset'`` is < 0, then ``'key'`` represents the name of the line.
83 83
84 The remaining attributes map to the ``'flags'` 84 The remaining attributes map to the ``'flags'`` field of the GPIO lookup
85 struct. The first two take string values as ar 85 struct. The first two take string values as arguments:
86 86
87 **``'drive'``:** ``'push-pull'``, ``'open-drai 87 **``'drive'``:** ``'push-pull'``, ``'open-drain'``, ``'open-source'``
88 **``'pull'``:** ``'pull-up'``, ``'pull-down'`` 88 **``'pull'``:** ``'pull-up'``, ``'pull-down'``, ``'pull-disabled'``, ``'as-is'``
89 89
90 ``'active_low'`` and ``'transitory'`` are bool 90 ``'active_low'`` and ``'transitory'`` are boolean attributes.
91 91
92 Activating GPIO consumers 92 Activating GPIO consumers
93 ------------------------- 93 -------------------------
94 94
95 Once the confiuration is complete, the ``'live 95 Once the confiuration is complete, the ``'live'`` attribute must be set to 1 in
96 order to instantiate the consumer. It can be s 96 order to instantiate the consumer. It can be set back to 0 to destroy the
97 virtual device. The module will synchronously 97 virtual device. The module will synchronously wait for the new simulated device
98 to be successfully probed and if this doesn't 98 to be successfully probed and if this doesn't happen, writing to ``'live'`` will
99 result in an error. 99 result in an error.
100 100
101 Device-tree 101 Device-tree
102 ----------- 102 -----------
103 103
104 Virtual GPIO consumers can also be defined in 104 Virtual GPIO consumers can also be defined in device-tree. The compatible string
105 must be: ``"gpio-virtuser"`` with at least one 105 must be: ``"gpio-virtuser"`` with at least one property following the
106 standardized GPIO pattern. 106 standardized GPIO pattern.
107 107
108 An example device-tree code defining a virtual 108 An example device-tree code defining a virtual GPIO consumer:
109 109
110 .. code-block :: none 110 .. code-block :: none
111 111
112 gpio-virt-consumer { 112 gpio-virt-consumer {
113 compatible = "gpio-virtuser"; 113 compatible = "gpio-virtuser";
114 114
115 foo-gpios = <&gpio0 5 GPIO_ACTIVE_LOW> 115 foo-gpios = <&gpio0 5 GPIO_ACTIVE_LOW>, <&gpio1 2 0>;
116 bar-gpios = <&gpio0 6 0>; 116 bar-gpios = <&gpio0 6 0>;
117 }; 117 };
118 118
119 Controlling virtual GPIO consumers 119 Controlling virtual GPIO consumers
120 ---------------------------------- 120 ----------------------------------
121 121
122 Once active, the device will export debugfs at 122 Once active, the device will export debugfs attributes for controlling GPIO
123 arrays as well as each requested GPIO line sep 123 arrays as well as each requested GPIO line separately. Let's consider the
124 following device property: ``foo-gpios = <&gpi 124 following device property: ``foo-gpios = <&gpio0 0 0>, <&gpio0 4 0>;``.
125 125
126 The following debugfs attribute groups will be 126 The following debugfs attribute groups will be created:
127 127
128 **Group:** ``/sys/kernel/debug/gpio-virtuser/$ 128 **Group:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/``
129 129
130 This is the group that will contain the attrib 130 This is the group that will contain the attributes for the entire GPIO array.
131 131
132 **Attribute:** ``/sys/kernel/debug/gpio-virtus 132 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/values``
133 133
134 **Attribute:** ``/sys/kernel/debug/gpio-virtus 134 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/values_atomic``
135 135
136 Both attributes allow to read and set arrays o 136 Both attributes allow to read and set arrays of GPIO values. User must pass
137 exactly the number of values that the array co 137 exactly the number of values that the array contains in the form of a string
138 containing zeroes and ones representing inacti 138 containing zeroes and ones representing inactive and active GPIO states
139 respectively. In this example: ``echo 11 > val 139 respectively. In this example: ``echo 11 > values``.
140 140
141 The ``values_atomic`` attribute works the same 141 The ``values_atomic`` attribute works the same as ``values`` but the kernel
142 will execute the GPIO driver callbacks in inte 142 will execute the GPIO driver callbacks in interrupt context.
143 143
144 **Group:** ``/sys/kernel/debug/gpio-virtuser/$ 144 **Group:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/``
145 145
146 This is a group that represents a single GPIO 146 This is a group that represents a single GPIO with ``$index`` being its offset
147 in the array. 147 in the array.
148 148
149 **Attribute:** ``/sys/kernel/debug/gpio-virtus 149 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/consumer``
150 150
151 Allows to set and read the consumer label of t 151 Allows to set and read the consumer label of the GPIO line.
152 152
153 **Attribute:** ``/sys/kernel/debug/gpio-virtus 153 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/debounce``
154 154
155 Allows to set and read the debounce period of 155 Allows to set and read the debounce period of the GPIO line.
156 156
157 **Attribute:** ``/sys/kernel/debug/gpio-virtus 157 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/direction``
158 158
159 **Attribute:** ``/sys/kernel/debug/gpio-virtus 159 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/direction_atomic``
160 160
161 These two attributes allow to set the directio 161 These two attributes allow to set the direction of the GPIO line. They accept
162 "input" and "output" as values. The atomic var 162 "input" and "output" as values. The atomic variant executes the driver callback
163 in interrupt context. 163 in interrupt context.
164 164
165 **Attribute:** ``/sys/kernel/debug/gpio-virtus 165 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/interrupts``
166 166
167 If the line is requested in input mode, writin 167 If the line is requested in input mode, writing ``1`` to this attribute will
168 make the module listen for edge interrupts on 168 make the module listen for edge interrupts on the GPIO. Writing ``0`` disables
169 the monitoring. Reading this attribute returns 169 the monitoring. Reading this attribute returns the current number of registered
170 interrupts (both edges). 170 interrupts (both edges).
171 171
172 **Attribute:** ``/sys/kernel/debug/gpio-virtus 172 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/value``
173 173
174 **Attribute:** ``/sys/kernel/debug/gpio-virtus 174 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/value_atomic``
175 175
176 Both attributes allow to read and set values o 176 Both attributes allow to read and set values of individual requested GPIO lines.
177 They accept the following values: ``1`` and `` 177 They accept the following values: ``1`` and ``0``.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.