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