Documentation/admin-guide/gpio/gpio-sim.rst

   1 .. SPDX-License-Identifier: GPL-2.0-or-later
   2
   3 Configfs GPIO Simulator
   4 =======================
   5
   6 The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO
   7 chips for testing purposes. The lines exposed by these chips can be accessed
   8 using the standard GPIO character device interface as well as manipulated
   9 using sysfs attributes.
  10
  11 Creating simulated chips
  12 ------------------------
  13
  14 The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For
  15 details of the configfs filesystem, please refer to the configfs documentation.
  16
  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 instantiated, this hierarchy
  19 will be translated to appropriate device properties. The general structure is:
  20
  21 **Group:** ``/config/gpio-sim``
  22
  23 This 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
  31 This is a directory representing a GPIO platform device. The ``'dev_name'``
  32 attribute is read-only and allows the user-space to read the platform device
  33 name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the
  34 actual creation of the device once it's fully configured. The accepted values
  35 are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear
  36 it 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
  44 This 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
  46 device name of the bank device. The ``'num_lines'`` attribute allows to specify
  47 the 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 This group represents a single line at the offset Y. The 'name' attribute
  54 allows 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
  62 This item makes the gpio-sim module hog the associated line. The ``'name'``
  63 attribute specifies the in-kernel consumer name to use. The ``'direction'``
  64 attribute specifies the hog direction and must be one of: ``'input'``,
  65 ``'output-high'`` and ``'output-low'``.
  66
  67 Inside each bank directory, there's a set of attributes that can be used to
  68 configure the new chip. Additionally the user can ``mkdir()`` subdirectories
  69 inside the chip's directory that allow to pass additional configuration for
  70 specific lines. The name of those subdirectories must take the form of:
  71 ``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be
  72 used by the module to assign the config to the specific line at given offset.
  73
  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 back to 0 to destroy the simulated
  76 chip. The module will synchronously wait for the new simulated device to be
  77 successfully probed and if this doesn't happen, writing to ``'live'`` will
  78 result in an error.
  79
  80 Simulated GPIO chips can also be defined in device-tree. The compatible string
  81 must be: ``"gpio-simulator"``. Supported properties are:
  82
  83   ``"gpio-sim,label"`` - chip label
  84
  85 Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or
  86 ``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for
  87 details.
  88
  89 An 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
 119 Manipulating simulated lines
 120 ----------------------------
 121
 122 Each simulated GPIO chip creates a separate sysfs group under its device
 123 directory for each exposed line
 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 offset of the line. Inside each
 126 group there are two attibutes:
 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