1.. SPDX-License-Identifier: GPL-2.0-or-later
2
3Configfs GPIO Simulator
4=======================
5
6The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO
7chips for testing purposes. The lines exposed by these chips can be accessed
8using the standard GPIO character device interface as well as manipulated
9using sysfs attributes.
10
11Creating simulated chips
12------------------------
13
14The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For
15details of the configfs filesystem, please refer to the configfs documentation.
16
17The user can create a hierarchy of configfs groups and items as well as modify
18values of exposed attributes. Once the chip is instantiated, this hierarchy
19will be translated to appropriate device properties. The general structure is:
20
21**Group:** ``/config/gpio-sim``
22
23This is the top directory of the gpio-sim configfs tree.
24
25**Group:** ``/config/gpio-sim/gpio-device``
26
27**Attribute:** ``/config/gpio-sim/gpio-device/dev_name``
28
29**Attribute:** ``/config/gpio-sim/gpio-device/live``
30
31This is a directory representing a GPIO platform device. The ``'dev_name'``
32attribute is read-only and allows the user-space to read the platform device
33name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the
34actual creation of the device once it's fully configured. The accepted values
35are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear
36it down.
37
38**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX``
39
40**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/chip_name``
41
42**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/num_lines``
43
44This group represents a bank of GPIOs under the top platform device. The
45``'chip_name'`` attribute is read-only and allows the user-space to read the
46device name of the bank device. The ``'num_lines'`` attribute allows to specify
47the number of lines exposed by this bank.
48
49**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY``
50
51**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/name``
52
53**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/valid``
54
55This group represents a single line at the offset Y. The ``valid`` attribute
56indicates whether the line can be used as GPIO. The ``name`` attribute allows
57to set the line name as represented by the 'gpio-line-names' property.
58
59**Item:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog``
60
61**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name``
62
63**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction``
64
65This item makes the gpio-sim module hog the associated line. The ``'name'``
66attribute specifies the in-kernel consumer name to use. The ``'direction'``
67attribute specifies the hog direction and must be one of: ``'input'``,
68``'output-high'`` and ``'output-low'``.
69
70Inside each bank directory, there's a set of attributes that can be used to
71configure the new chip. Additionally the user can ``mkdir()`` subdirectories
72inside the chip's directory that allow to pass additional configuration for
73specific lines. The name of those subdirectories must take the form of:
74``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be
75used by the module to assign the config to the specific line at given offset.
76
77Once the configuration is complete, the ``'live'`` attribute must be set to 1 in
78order to instantiate the chip. It can be set back to 0 to destroy the simulated
79chip. The module will synchronously wait for the new simulated device to be
80successfully probed and if this doesn't happen, writing to ``'live'`` will
81result in an error.
82
83Simulated GPIO chips can also be defined in device-tree. The compatible string
84must be: ``"gpio-simulator"``. Supported properties are:
85
86  ``"gpio-sim,label"`` - chip label
87
88Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or
89``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for
90details.
91
92An example device-tree code defining a GPIO simulator:
93
94.. code-block :: none
95
96    gpio-sim {
97        compatible = "gpio-simulator";
98
99        bank0 {
100            gpio-controller;
101            #gpio-cells = <2>;
102            ngpios = <16>;
103            gpio-sim,label = "dt-bank0";
104            gpio-line-names = "", "sim-foo", "", "sim-bar";
105        };
106
107        bank1 {
108            gpio-controller;
109            #gpio-cells = <2>;
110            ngpios = <8>;
111            gpio-sim,label = "dt-bank1";
112
113            line3 {
114                gpio-hog;
115                gpios = <3 0>;
116                output-high;
117                line-name = "sim-hog-from-dt";
118            };
119        };
120    };
121
122Manipulating simulated lines
123----------------------------
124
125Each simulated GPIO chip creates a separate sysfs group under its device
126directory for each exposed line
127(e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group
128is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each
129group there are two attributes:
130
131    ``pull`` - allows to read and set the current simulated pull setting for
132               every line, when writing the value must be one of: ``'pull-up'``,
133               ``'pull-down'``
134
135    ``value`` - allows to read the current value of the line which may be
136                different from the pull if the line is being driven from
137                user-space
138