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