mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
134 lines
5.1 KiB
134 lines
5.1 KiB
.. SPDX-License-Identifier: GPL-2.0-or-later |
|
|
|
Configfs GPIO Simulator |
|
======================= |
|
|
|
The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO |
|
chips for testing purposes. The lines exposed by these chips can be accessed |
|
using the standard GPIO character device interface as well as manipulated |
|
using sysfs attributes. |
|
|
|
Creating simulated chips |
|
------------------------ |
|
|
|
The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For |
|
details of the configfs filesystem, please refer to the configfs documentation. |
|
|
|
The user can create a hierarchy of configfs groups and items as well as modify |
|
values of exposed attributes. Once the chip is instantiated, this hierarchy |
|
will be translated to appropriate device properties. The general structure is: |
|
|
|
**Group:** ``/config/gpio-sim`` |
|
|
|
This is the top directory of the gpio-sim configfs tree. |
|
|
|
**Group:** ``/config/gpio-sim/gpio-device`` |
|
|
|
**Attribute:** ``/config/gpio-sim/gpio-device/dev_name`` |
|
|
|
**Attribute:** ``/config/gpio-sim/gpio-device/live`` |
|
|
|
This is a directory representing a GPIO platform device. The ``'dev_name'`` |
|
attribute is read-only and allows the user-space to read the platform device |
|
name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the |
|
actual creation of the device once it's fully configured. The accepted values |
|
are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear |
|
it down. |
|
|
|
**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX`` |
|
|
|
**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/chip_name`` |
|
|
|
**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/num_lines`` |
|
|
|
This group represents a bank of GPIOs under the top platform device. The |
|
``'chip_name'`` attribute is read-only and allows the user-space to read the |
|
device name of the bank device. The ``'num_lines'`` attribute allows to specify |
|
the number of lines exposed by this bank. |
|
|
|
**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY`` |
|
|
|
**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/name`` |
|
|
|
This group represents a single line at the offset Y. The 'name' attribute |
|
allows to set the line name as represented by the 'gpio-line-names' property. |
|
|
|
**Item:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog`` |
|
|
|
**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name`` |
|
|
|
**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction`` |
|
|
|
This item makes the gpio-sim module hog the associated line. The ``'name'`` |
|
attribute specifies the in-kernel consumer name to use. The ``'direction'`` |
|
attribute specifies the hog direction and must be one of: ``'input'``, |
|
``'output-high'`` and ``'output-low'``. |
|
|
|
Inside each bank directory, there's a set of attributes that can be used to |
|
configure the new chip. Additionally the user can ``mkdir()`` subdirectories |
|
inside the chip's directory that allow to pass additional configuration for |
|
specific lines. The name of those subdirectories must take the form of: |
|
``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be |
|
used by the module to assign the config to the specific line at given offset. |
|
|
|
Once the confiuration is complete, the ``'live'`` attribute must be set to 1 in |
|
order to instantiate the chip. It can be set back to 0 to destroy the simulated |
|
chip. The module will synchronously wait for the new simulated device to be |
|
successfully probed and if this doesn't happen, writing to ``'live'`` will |
|
result in an error. |
|
|
|
Simulated GPIO chips can also be defined in device-tree. The compatible string |
|
must be: ``"gpio-simulator"``. Supported properties are: |
|
|
|
``"gpio-sim,label"`` - chip label |
|
|
|
Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or |
|
``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for |
|
details. |
|
|
|
An example device-tree code defining a GPIO simulator: |
|
|
|
.. code-block :: none |
|
|
|
gpio-sim { |
|
compatible = "gpio-simulator"; |
|
|
|
bank0 { |
|
gpio-controller; |
|
#gpio-cells = <2>; |
|
ngpios = <16>; |
|
gpio-sim,label = "dt-bank0"; |
|
gpio-line-names = "", "sim-foo", "", "sim-bar"; |
|
}; |
|
|
|
bank1 { |
|
gpio-controller; |
|
#gpio-cells = <2>; |
|
ngpios = <8>; |
|
gpio-sim,label = "dt-bank1"; |
|
|
|
line3 { |
|
gpio-hog; |
|
gpios = <3 0>; |
|
output-high; |
|
line-name = "sim-hog-from-dt"; |
|
}; |
|
}; |
|
}; |
|
|
|
Manipulating simulated lines |
|
---------------------------- |
|
|
|
Each simulated GPIO chip creates a separate sysfs group under its device |
|
directory for each exposed line |
|
(e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group |
|
is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each |
|
group there are two attibutes: |
|
|
|
``pull`` - allows to read and set the current simulated pull setting for |
|
every line, when writing the value must be one of: ``'pull-up'``, |
|
``'pull-down'`` |
|
|
|
``value`` - allows to read the current value of the line which may be |
|
different from the pull if the line is being driven from |
|
user-space
|
|
|