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