135 lines · plain
1.. SPDX-License-Identifier: GPL-2.0-or-later2 3Configfs GPIO Simulator4=======================5 6The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO7chips for testing purposes. The lines exposed by these chips can be accessed8using the standard GPIO character device interface as well as manipulated9using sysfs attributes.10 11Creating simulated chips12------------------------13 14The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For15details 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 modify18values of exposed attributes. Once the chip is instantiated, this hierarchy19will 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 device33name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the34actual creation of the device once it's fully configured. The accepted values35are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear36it 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. The45``'chip_name'`` attribute is read-only and allows the user-space to read the46device name of the bank device. The ``'num_lines'`` attribute allows to specify47the 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' attribute54allows 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 to68configure the new chip. Additionally the user can ``mkdir()`` subdirectories69inside the chip's directory that allow to pass additional configuration for70specific lines. The name of those subdirectories must take the form of:71``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be72used 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 in75order to instantiate the chip. It can be set back to 0 to destroy the simulated76chip. The module will synchronously wait for the new simulated device to be77successfully probed and if this doesn't happen, writing to ``'live'`` will78result in an error.79 80Simulated GPIO chips can also be defined in device-tree. The compatible string81must be: ``"gpio-simulator"``. Supported properties are:82 83 ``"gpio-sim,label"`` - chip label84 85Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or86``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for87details.88 89An example device-tree code defining a GPIO simulator:90 91.. code-block :: none92 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 lines120----------------------------121 122Each simulated GPIO chip creates a separate sysfs group under its device123directory for each exposed line124(e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group125is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each126group there are two attributes:127 128 ``pull`` - allows to read and set the current simulated pull setting for129 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 be133 different from the pull if the line is being driven from134 user-space135