0001 .. SPDX-License-Identifier: GPL-2.0-or-later
0002
0003 Configfs GPIO Simulator
0004 =======================
0005
0006 The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO
0007 chips for testing purposes. The lines exposed by these chips can be accessed
0008 using the standard GPIO character device interface as well as manipulated
0009 using sysfs attributes.
0010
0011 Creating simulated chips
0012 ------------------------
0013
0014 The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For
0015 details of the configfs filesystem, please refer to the configfs documentation.
0016
0017 The user can create a hierarchy of configfs groups and items as well as modify
0018 values of exposed attributes. Once the chip is instantiated, this hierarchy
0019 will be translated to appropriate device properties. The general structure is:
0020
0021 **Group:** ``/config/gpio-sim``
0022
0023 This is the top directory of the gpio-sim configfs tree.
0024
0025 **Group:** ``/config/gpio-sim/gpio-device``
0026
0027 **Attribute:** ``/config/gpio-sim/gpio-device/dev_name``
0028
0029 **Attribute:** ``/config/gpio-sim/gpio-device/live``
0030
0031 This is a directory representing a GPIO platform device. The ``'dev_name'``
0032 attribute is read-only and allows the user-space to read the platform device
0033 name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the
0034 actual creation of the device once it's fully configured. The accepted values
0035 are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear
0036 it down.
0037
0038 **Group:** ``/config/gpio-sim/gpio-device/gpio-bankX``
0039
0040 **Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/chip_name``
0041
0042 **Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/num_lines``
0043
0044 This group represents a bank of GPIOs under the top platform device. The
0045 ``'chip_name'`` attribute is read-only and allows the user-space to read the
0046 device name of the bank device. The ``'num_lines'`` attribute allows to specify
0047 the number of lines exposed by this bank.
0048
0049 **Group:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY``
0050
0051 **Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/name``
0052
0053 This group represents a single line at the offset Y. The 'name' attribute
0054 allows to set the line name as represented by the 'gpio-line-names' property.
0055
0056 **Item:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog``
0057
0058 **Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name``
0059
0060 **Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction``
0061
0062 This item makes the gpio-sim module hog the associated line. The ``'name'``
0063 attribute specifies the in-kernel consumer name to use. The ``'direction'``
0064 attribute specifies the hog direction and must be one of: ``'input'``,
0065 ``'output-high'`` and ``'output-low'``.
0066
0067 Inside each bank directory, there's a set of attributes that can be used to
0068 configure the new chip. Additionally the user can ``mkdir()`` subdirectories
0069 inside the chip's directory that allow to pass additional configuration for
0070 specific lines. The name of those subdirectories must take the form of:
0071 ``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be
0072 used by the module to assign the config to the specific line at given offset.
0073
0074 Once the confiuration is complete, the ``'live'`` attribute must be set to 1 in
0075 order to instantiate the chip. It can be set back to 0 to destroy the simulated
0076 chip. The module will synchronously wait for the new simulated device to be
0077 successfully probed and if this doesn't happen, writing to ``'live'`` will
0078 result in an error.
0079
0080 Simulated GPIO chips can also be defined in device-tree. The compatible string
0081 must be: ``"gpio-simulator"``. Supported properties are:
0082
0083 ``"gpio-sim,label"`` - chip label
0084
0085 Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or
0086 ``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for
0087 details.
0088
0089 An example device-tree code defining a GPIO simulator:
0090
0091 .. code-block :: none
0092
0093 gpio-sim {
0094 compatible = "gpio-simulator";
0095
0096 bank0 {
0097 gpio-controller;
0098 #gpio-cells = <2>;
0099 ngpios = <16>;
0100 gpio-sim,label = "dt-bank0";
0101 gpio-line-names = "", "sim-foo", "", "sim-bar";
0102 };
0103
0104 bank1 {
0105 gpio-controller;
0106 #gpio-cells = <2>;
0107 ngpios = <8>;
0108 gpio-sim,label = "dt-bank1";
0109
0110 line3 {
0111 gpio-hog;
0112 gpios = <3 0>;
0113 output-high;
0114 line-name = "sim-hog-from-dt";
0115 };
0116 };
0117 };
0118
0119 Manipulating simulated lines
0120 ----------------------------
0121
0122 Each simulated GPIO chip creates a separate sysfs group under its device
0123 directory for each exposed line
0124 (e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group
0125 is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each
0126 group there are two attibutes:
0127
0128 ``pull`` - allows to read and set the current simulated pull setting for
0129 every line, when writing the value must be one of: ``'pull-up'``,
0130 ``'pull-down'``
0131
0132 ``value`` - allows to read the current value of the line which may be
0133 different from the pull if the line is being driven from
0134 user-space
