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 53This group represents a single line at the offset Y. The 'name' attribute 54allows to set the line name as represented by the 'gpio-line-names' property. 55 56**Item:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog`` 57 58**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name`` 59 60**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction`` 61 62This item makes the gpio-sim module hog the associated line. The ``'name'`` 63attribute specifies the in-kernel consumer name to use. The ``'direction'`` 64attribute specifies the hog direction and must be one of: ``'input'``, 65``'output-high'`` and ``'output-low'``. 66 67Inside each bank directory, there's a set of attributes that can be used to 68configure the new chip. Additionally the user can ``mkdir()`` subdirectories 69inside the chip's directory that allow to pass additional configuration for 70specific lines. The name of those subdirectories must take the form of: 71``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be 72used by the module to assign the config to the specific line at given offset. 73 74Once the confiuration is complete, the ``'live'`` attribute must be set to 1 in 75order to instantiate the chip. It can be set back to 0 to destroy the simulated 76chip. The module will synchronously wait for the new simulated device to be 77successfully probed and if this doesn't happen, writing to ``'live'`` will 78result in an error. 79 80Simulated GPIO chips can also be defined in device-tree. The compatible string 81must be: ``"gpio-simulator"``. Supported properties are: 82 83 ``"gpio-sim,label"`` - chip label 84 85Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or 86``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for 87details. 88 89An example device-tree code defining a GPIO simulator: 90 91.. code-block :: none 92 93 gpio-sim { 94 compatible = "gpio-simulator"; 95 96 bank0 { 97 gpio-controller; 98 #gpio-cells = <2>; 99 ngpios = <16>; 100 gpio-sim,label = "dt-bank0"; 101 gpio-line-names = "", "sim-foo", "", "sim-bar"; 102 }; 103 104 bank1 { 105 gpio-controller; 106 #gpio-cells = <2>; 107 ngpios = <8>; 108 gpio-sim,label = "dt-bank1"; 109 110 line3 { 111 gpio-hog; 112 gpios = <3 0>; 113 output-high; 114 line-name = "sim-hog-from-dt"; 115 }; 116 }; 117 }; 118 119Manipulating simulated lines 120---------------------------- 121 122Each simulated GPIO chip creates a separate sysfs group under its device 123directory for each exposed line 124(e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group 125is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each 126group there are two attributes: 127 128 ``pull`` - allows to read and set the current simulated pull setting for 129 every line, when writing the value must be one of: ``'pull-up'``, 130 ``'pull-down'`` 131 132 ``value`` - allows to read the current value of the line which may be 133 different from the pull if the line is being driven from 134 user-space 135