admin-guide/gpio/gpio-virtuser.rst

1 .. SPDX-License-Identifier: GPL-2.0-only
3 Virtual GPIO Consumer
6 The virtual GPIO Consumer module allows users to instantiate virtual devices
8 consumer devices can be instantiated from device-tree or over configfs.
10 A virtual consumer uses the driver-facing GPIO APIs and allows to cover it with
11 automated tests driven by user-space. The GPIOs are requested using
14 Creating GPIO consumers
15 -----------------------
17 The gpio-consumer module registers a configfs subsystem called
18 ``'gpio-virtuser'``. For details of the configfs filesystem, please refer to
21 The user can create a hierarchy of configfs groups and items as well as modify
25 **Group:** ``/config/gpio-virtuser``
27 This is the top directory of the gpio-consumer configfs tree.
29 **Group:** ``/config/gpio-consumer/example-name``
31 **Attribute:** ``/config/gpio-consumer/example-name/live``
33 **Attribute:** ``/config/gpio-consumer/example-name/dev_name``
35 This is a directory representing a GPIO consumer device.
37 The read-only ``dev_name`` attribute exposes the name of the device as it will
40 ``/sys/kernel/debug/gpio-virtuser/$dev_name``.
46 Creating GPIO lookup tables
47 ---------------------------
49 Users can create a number of configfs groups under the device group:
51 **Group:** ``/config/gpio-consumer/example-name/con_id``
53 The ``'con_id'`` directory represents a single GPIO lookup and its value maps
55 ``con_id`` == ``'reset'`` maps to the ``reset-gpios`` device property.
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'`` group.
60 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/key``
62 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/offset``
64 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/drive``
66 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/pull``
68 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/active_low``
70 **Attribute:** ``/config/gpio-consumer/example-name/con_id/0/transitory``
72 This is a group describing a single GPIO in the ``con_id-gpios`` property.
75 this group can be considered as a mapping between the filesystem and the fields
76 of a single entry in ``'struct gpiod_lookup'``.
78 The ``'key'`` attribute represents either the name of the chip this GPIO
79 belongs to or the GPIO line name. This depends on the value of the ``'offset'``
84 The remaining attributes map to the ``'flags'`` field of the GPIO lookup
87 **``'drive'``:** ``'push-pull'``, ``'open-drain'``, ``'open-source'``
88 **``'pull'``:** ``'pull-up'``, ``'pull-down'``, ``'pull-disabled'``, ``'as-is'``
92 Activating GPIO consumers
93 -------------------------
101 Device-tree
102 -----------
104 Virtual GPIO consumers can also be defined in device-tree. The compatible string
105 must be: ``"gpio-virtuser"`` with at least one property following the
106 standardized GPIO pattern.
108 An example device-tree code defining a virtual GPIO consumer:
110 .. code-block :: none
112     gpio-virt-consumer {
113         compatible = "gpio-virtuser";
115         foo-gpios = <&gpio0 5 GPIO_ACTIVE_LOW>, <&gpio1 2 0>;
116         bar-gpios = <&gpio0 6 0>;
119 Controlling virtual GPIO consumers
120 ----------------------------------
122 Once active, the device will export debugfs attributes for controlling GPIO
123 arrays as well as each requested GPIO line separately. Let's consider the
124 following device property: ``foo-gpios = <&gpio0 0 0>, <&gpio0 4 0>;``.
128 **Group:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/``
130 This is the group that will contain the attributes for the entire GPIO array.
132 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/values``
134 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/values_atomic``
136 Both attributes allow to read and set arrays of GPIO values. User must pass
137 exactly the number of values that the array contains in the form of a string
138 containing zeroes and ones representing inactive and active GPIO states
142 will execute the GPIO driver callbacks in interrupt context.
144 **Group:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/``
146 This is a group that represents a single GPIO with ``$index`` being its offset
149 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/consumer``
151 Allows to set and read the consumer label of the GPIO line.
153 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/debounce``
155 Allows to set and read the debounce period of the GPIO line.
157 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/direction``
159 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/direction_atomic``
161 These two attributes allow to set the direction of the GPIO line. They accept
165 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/interrupts``
168 make the module listen for edge interrupts on the GPIO. Writing ``0`` disables
172 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/value``
174 **Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/value_atomic``
176 Both attributes allow to read and set values of individual requested GPIO lines.