deleted file mode 100644
@@ -1,384 +0,0 @@
-# SPDX-License-Identifier: CC-BY-SA-4.0
-# SPDX-FileCopyrightText: 2017-2023 Bartosz Golaszewski <brgl@bgdev.pl>
-
-libgpiod
-========
-
- libgpiod - C library and tools for interacting with the linux GPIO
- character device (gpiod stands for GPIO device)
-
-Since linux 4.8 the GPIO sysfs interface is deprecated. User space should use
-the character device instead. Version 2 of libgpiod requires GPIO character
-device uAPI v2 which was first released in linux 5.10. This library
-encapsulates the ioctl calls and data structures behind a straightforward API.
-
-RATIONALE
----------
-
-The new character device interface guarantees all allocated resources are
-freed after closing the device file descriptor and adds several new features
-that are not present in the obsolete sysfs interface (like event polling,
-setting/reading multiple values at once or open-source and open-drain GPIOs).
-
-Unfortunately interacting with the linux device file can no longer be done
-using only standard command-line tools. This is the reason for creating a
-library encapsulating the cumbersome, ioctl-based kernel-userspace interaction
-in a set of convenient functions and opaque data structures.
-
-Additionally this project contains a set of command-line tools that should
-allow an easy conversion of user scripts to using the character device.
-
-BUILDING
---------
-
-This is a pretty standard autotools project. The core C library does not have
-any external dependencies other than the standard C library with GNU extensions.
-
-The build system requires autotools, autoconf-archive, libtool and pkg-config
-to be installed on the host system for the basic build. Development files for
-additional libraries may be required depending on selected options. The
-configure script will report any missing additional required dependencies.
-
-The command-line tools optionally depend on libedit for the interactive feature.
-
-To build the project (including command-line utilities) run:
-
- ./autogen.sh --enable-tools=yes --prefix=<install path>
- make
- make install
-
-The autogen script will execute ./configure and pass all the command-line
-arguments to it.
-
-If building from release tarballs, the configure script is already provided and
-there's no need to invoke autogen.sh.
-
-For all configure features, see: ./configure --help.
-
-TOOLS
------
-
-There are currently six command-line tools available:
-
-* gpiodetect - list all gpiochips present on the system, their names, labels
- and number of GPIO lines
-
-* gpioinfo - list lines, their gpiochip, offset, name, and direction, and
- if in use then the consumer name and any other configured
- attributes, such as active state, bias, drive, edge detection
- and debounce period
-
-* gpioget - read values of specified GPIO lines
-
-* gpioset - set values of specified GPIO lines, holding the lines until the
- process is killed or otherwise exits
-
-* gpiomon - wait for edge events on GPIO lines, specify which edges to watch
- for, how many events to process before exiting, or if the events
- should be reported to the console
-
-* gpionotify - wait for changed to the info for GPIO lines, specify which
- changes to watch for, how many events to process before exiting,
- or if the events should be reported to the console
-
-Examples:
-
- (using a Raspberry Pi 4B)
-
- # Detect the available gpiochips.
- $ gpiodetect
- gpiochip0 [pinctrl-bcm2711] (58 lines)
- gpiochip1 [raspberrypi-exp-gpio] (8 lines)
-
- # Read the info for all the lines on a gpiochip.
- $ gpioinfo -c 1
- gpiochip1 - 8 lines:
- line 0: "BT_ON" output
- line 1: "WL_ON" output
- line 2: "PWR_LED_OFF" output active-low consumer="led1"
- line 3: "GLOBAL_RESET" output
- line 4: "VDD_SD_IO_SEL" output consumer="vdd-sd-io"
- line 5: "CAM_GPIO" output consumer="cam1_regulator"
- line 6: "SD_PWR_ON" output consumer="sd_vcc_reg"
- line 7: "SD_OC_N" input
-
- # Read the info for particular lines.
- $ ./gpioinfo PWR_LED_OFF STATUS_LED_G_CLK GLOBAL_RESET
- gpiochip0 42 "STATUS_LED_G_CLK" output consumer="led0"
- gpiochip1 2 "PWR_LED_OFF" output active-low consumer="led1"
- gpiochip1 3 "GLOBAL_RESET" output
-
- # Read the value of a single GPIO line by name.
- $ gpioget RXD1
- "RXD1"=active
-
- # Read the value of a single GPIO line by chip and offset.
- $ gpioget -c 0 15
- "15"=active
-
- # Read the value of a single GPIO line as a numeric value.
- $ gpioget --numeric RXD1
- 1
-
- # Read two values at the same time. Set the active state of the lines
- # to low and without quoted names.
- $ gpioget --active-low --unquoted GPIO23 GPIO24
- GPIO23=active GPIO24=active
-
- # Set the value of a line and hold the line until killed.
- $ gpioset GPIO23=1
-
- # Set values of two lines, then daemonize and hold the lines.
- $ gpioset --daemonize GPIO23=1 GPIO24=0
-
- # Set the value of a single line, hold it for 20ms, then exit.
- $ gpioset --hold-period 20ms -t0 GPIO23=1
-
- # Blink an LED on GPIO22 at 1Hz
- $ gpioset -t500ms GPIO22=1
-
- # Blink an LED on GPIO22 at 1Hz with a 20% duty cycle
- $ gpioset -t200ms,800ms GPIO22=1
-
- # Set some lines interactively (requires --enable-gpioset-interactive)
- $ gpioset --interactive --unquoted GPIO23=inactive GPIO24=active
- gpioset> get
- GPIO23=inactive GPIO24=active
- gpioset> toggle
- gpioset> get
- GPIO23=active GPIO24=inactive
- gpioset> set GPIO24=1
- gpioset> get
- GPIO23=active GPIO24=active
- gpioset> toggle
- gpioset> get
- GPIO23=inactive GPIO24=inactive
- gpioset> toggle GPIO23
- gpioset> get
- GPIO23=active GPIO24=inactive
- gpioset> exit
-
- # Wait for three rising edge events on a single GPIO line, then exit.
- $ gpiomon --num-events=3 --edges=rising GPIO22
- 10002.907638045 rising "GPIO22"
- 10037.132562259 rising "GPIO22"
- 10047.179790748 rising "GPIO22"
-
- # Wait for three edge events on a single GPIO line, with time in local time
- # and with unquoted line name, then exit.
- $ gpiomon --num-events=3 --edges=both --localtime --unquoted GPIO22
- 2022-11-15T10:36:59.109615508 rising GPIO22
- 2022-11-15T10:36:59.129681898 falling GPIO22
- 2022-11-15T10:36:59.698971886 rising GPIO22
-
- # Wait for falling edge events with a custom output format.
- $ gpiomon --format="%e %c %o %l %S" --edges=falling -c gpiochip0 22
- 2 gpiochip0 22 GPIO22 10946.693481859
- 2 gpiochip0 22 GPIO22 10947.025347604
- 2 gpiochip0 22 GPIO22 10947.283716669
- 2 gpiochip0 22 GPIO22 10947.570109430
- ...
-
- # Block until an edge event occurs. Don't print anything.
- $ gpiomon --num-events=1 --quiet GPIO22
-
- # Monitor multiple lines, exit after the first edge event.
- $ gpiomon --quiet --num-events=1 GPIO5 GPIO6 GPIO12 GPIO17
-
- # Monitor a line for changes to info.
- $ gpionotify GPIO23
- 11571.816473718 requested "GPIO23"
- 11571.816535124 released "GPIO23"
- 11572.722894029 requested "GPIO23"
- 11572.722932843 released "GPIO23"
- 11573.222998598 requested "GPIO23"
- ...
-
- # Monitor a line for requests, reporting UTC time and unquoted line name.
- $ gpionotify --utc --unquoted GPIO23
- 2022-11-15T03:05:23.807090687Z requested GPIO23
- 2022-11-15T03:05:23.807151390Z released GPIO23
- 2022-11-15T03:05:24.784984280Z requested GPIO23
- 2022-11-15T03:05:24.785023873Z released GPIO23
- ...
-
- # Monitor multiple lines, exit after the first is requested.
- $ gpionotify --quiet --num-events=1 --event=requested GPIO5 GPIO6 GPIO12 GPIO17
-
- # Block until a line is released.
- $ gpionotify --quiet --num-events=1 --event=released GPIO6
-
-BINDINGS
---------
-
-High-level, object-oriented bindings for C++, GLib, python3 and Rust are
-provided. They can be enabled by passing --enable-bindings-cxx,
---enable-bindings-glib, --enable-bindings-python and --enable-bindings-rust
-arguments respectively to configure.
-
-C++ bindings require C++11 support and autoconf-archive collection if building
-from git.
-
-GLib bindings requires GLib (as well as GObject, GIO and GIO-Unix) v2.54.
-
-Python bindings require python3 support and libpython development files. Please
-refer to bindings/python/README.md for more information.
-
-Rust bindings require cargo support. When building the Rust bindings along the
-C library using make, they will be automatically configured to build against the
-build results of the C library. Please refer to bindings/rust/libgpiod/README.md
-for more information.
-
-DBUS
-----
-
-A commonly requested feature for the GPIO character device was state persistence
-after releasing the lines (as a kernel feature) or providing a central authority
-(in user-space) that would be in charge of keeping the lines requested and in a
-certain state (similarily to how the sysfs ABI works). DBus API has been
-provided to address this requirement. We define an interface covering the
-majority of the GPIO chardev's functionality and implement it from both the
-server and client sides in the form of the gpio-manager daemon and the gpiocli
-command-line utility for talking to the manager.
-
-DBus support can be built by passing --enable-dbus to configure. The daemon
-is bundled with a systemd unit file and an example configuration file for the
-io.gpiod1 interface that allows all users to access basic information about the
-GPIOs in the system but only root to request lines or change their values.
-
-With the manager running the user can run gpiocli to control GPIOs by asking
-gpio-manager to act on their behalf:
-
- # Detect chips in the system.
- $ gpiocli detect
- gpiochip0 [INT34C6:00] (463 lines)
-
- # Request a set of lines. Note that gpiocli exits immediately but the
- # state of the lines is retained because it's the gpio-manager that
- # requested them.
- $ gpiocli request --output foo=active
- request0
-
- # Previous invocation printed out the name of the request by which the
- # caller can refer to it later. All active requests can also be inspected
- # at any time.
- $ gpiocli requests
- request0 (gpiochip1) Offsets: [5]
-
- # We can print the information about the requested line using the
- # information above.
- $ gpiocli info --chip=gpiochip1 5
- gpiochip1 5: "foo" [used,consumer="gpiocli request",managed="request0",output,push-pull]
-
- # We can now change the value of the line.
- $ gpiocli set foo=inactive
-
- # And read it.
- $ gpiocli get foo
- "foo"=inactive
-
- # We can even reconfigure it to input and enable edge-detection.
- $ gpiocli reconfigure --input --both-edges request0
-
- # And wait for edge events.
- $ gpiocli monitor cos
- 21763952894920 rising "foo"
-
- # And finally release the request.
- $ gpiocli release request0
-
-For more information please refer to the output of gpiocli --help as well as
-gpiocli <command> --help which prints detailed info on every available command.
-
-Of course - this being DBus - users can talk to gpio-manager using any DBus
-library available and are not limited to the provided client.
-
-TESTING
--------
-
-A comprehensive testing framework is included with the library and can be
-used to test both the core library code as well as the kernel-to-user-space
-interface.
-
-The minimum kernel version required to run the tests can be checked in the
-tests/gpiod-test.c source file (it's subject to change if new features are
-added to the kernel). The tests work together with the gpio-sim kernel module
-which must either be built-in or available for loading using kmod. A helper
-library - libgpiosim - is included to enable straightforward interaction with
-the module.
-
-To build the testing executable add the '--enable-tests' option when running
-the configure script. If enabled, the tests will be installed next to
-gpio-tools.
-
-As opposed to standard autotools projects, libgpiod doesn't execute any tests
-when invoking 'make check'. Instead the user must run them manually with
-superuser privileges.
-
-The testing framework uses the GLib unit testing library so development package
-for GLib must be installed.
-
-The gpio-tools programs can be tested separately using the gpio-tools-test.bash
-script. It requires shunit2[1] to run and assumes that the tested executables are
-in the same directory as the script.
-
-C++, Rust and Python bindings also include their own test-suites. All three
-reuse the libgpiosim library to avoid code duplication when interacting with
-gpio-sim.
-
-Python test-suite uses the standard unittest package. C++ tests use an external
-testing framework - Catch2 - which must be installed in the system. Rust
-bindings use the standard tests module layout and the #[test] attribute.
-
-DOCUMENTATION
--------------
-
-The project uses sphinx to automatically generate the documentation. The system
-needs to provide doxygen and sphinx-build programs. With those in place, the
-build can be invoked with 'make docs'. This generates documentation for the
-core C API as well as C++ and python bindings.
-
-Rust bindings use rustdoc, GLib bindings use gi-docgen.
-
-Man pages for command-line programs are generated automatically if gpio-tools
-were selected and help2man is available in the system.
-
-CONTRIBUTING
-------------
-
-Contributions are welcome - please send questions, patches and bug reports
-to the linux-gpio mailing list[2] by e-mailing to linux-gpio@vger.kernel.org
-(add the [libgpiod] prefix to the e-mail subject line).
-Note that the mailing list quietly drops HTML formatted e-mail, so be sure
-to send plain text[3].
-
-Code submissions should stick to the linux kernel coding style[4] and
-follow the kernel patch submission process[5] as applied to the libgpiod
-source tree. All shell scripts must pass `shellcheck` tests[9]. All files
-must have a license and copyright SPDX headers and the repo is expected to
-pass the `reuse lint` check[10].
-
-The mailing list archive[6] contains all the historical mails to the list,
-and is the place to check to ensure your e-mail has been received.
-Search for "libgpiod" to filter the list down to relevant messages.
-Those also provide examples of the expected formatting.
-Allow some time for your e-mail to propagate to the list before retrying,
-particularly if there are no e-mails in the list more recent than yours.
-
-There is a libgpiod github page[7] available for reporting bugs and general
-discussions and although PRs can be submitted and discussed, upstreambound
-patches need to go through the mailing list nevertheless while release
-tarballs should be fetched from kernel.org[8].
-
-For more information, refer to CONTRIBUTING.md in this repository.
-
-[1] https://github.com/kward/shunit2
-[2] http://vger.kernel.org/vger-lists.html#linux-gpio
-[3] https://docs.kernel.org/process/email-clients.html
-[4] https://docs.kernel.org/process/coding-style.html
-[5] https://docs.kernel.org/process/submitting-patches.html
-[6] https://lore.kernel.org/linux-gpio/
-[7] https://github.com/brgl/libgpiod
-[8] https://mirrors.edge.kernel.org/pub/software/libs/libgpiod/
-[9] https://www.shellcheck.net/
-[10] https://reuse.software/
new file mode 100644
@@ -0,0 +1,11 @@
+<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
+<!-- SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org> -->
+
+libgpiod
+========
+
+C library and tools for interacting with the linux GPIO character device.
+
+The project is hosted at https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/.
+
+Documentation is available at https://libgpiod.readthedocs.io/.
@@ -10,8 +10,12 @@
High-level language bindings to libgpiod
========================================
-The bindings provide a more straightforward interface to the base, low-level
-C library.
+Bindings provide a more straightforward interface to the core, low-level
+C library. Object-oriented bindings for C++, GLib, python3 and Rust are
+provided as part of the project. They can be enabled by passing
+``--enable-bindings-cxx``, ``--enable-bindings-glib``,
+``--enable-bindings-python`` and ``--enable-bindings-rust`` arguments to
+configure respectively.
.. toctree::
:maxdepth: 1
@@ -20,3 +24,20 @@ C library.
cpp_api
python_api
glib_api
+
+.. warning::
+ There's currently no good way of integrating rust documentation with sphinx.
+ Rust bindings should be documented on https://docs.rs/ but due to a yet
+ unsolved build problem, this is currently not the case. Please refer to the
+ in-source comments for now.
+
+.. note::
+ Rust bindings are available on https://crates.io/ as the ``libgpiod``
+ package.
+
+.. note::
+ When building the Rust bindings along the C library using make, they will
+ be automatically configured to build against the build results of the
+ C library. Building rust bindings requires cargo to be available on the
+ system.
+
new file mode 100644
@@ -0,0 +1,74 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+Downloading, building & installing
+==================================
+
+Downloading
+-----------
+
+Libgpiod is packaged by several linux distributions. You should typically be
+able to install it using your package manager. If you want to build libgpiod
+from sources, the upstream git repository for libgpiod is hosted at
+`kernel.org <https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/>`_.
+together with
+`release tarballs <https://mirrors.edge.kernel.org/pub/software/libs/libgpiod/>`_.
+
+Building
+--------
+
+This is a pretty standard autotools project. The core C library does not have
+any external dependencies other than the standard C library with GNU extensions.
+
+The build system requires the following packages to be installed on the host
+system for the basic build:
+
+ * ``autotools``
+ * ``autoconf-archive``
+ * ``libtool``
+ * ``pkg-config``
+
+.. note::
+ Development files for additional libraries may be required depending on
+ selected options. The configure script will report any missing additional
+ required dependencies.
+
+To build the project (including command-line utilities) run:
+
+.. code-block:: none
+
+ ./autogen.sh --enable-tools=yes
+ make
+
+.. note::
+ The command-line tools optionally depend on libedit for the interactive
+ feature.
+
+The autogen script will execute ``./configure`` and pass all the command-line
+arguments to it.
+
+.. note::
+ If building from release tarballs, the configure script is already provided
+ and there's no need to invoke autogen.sh.
+
+For all configure features, see: ``./configure --help``.
+
+Installing
+----------
+
+To install the project run:
+
+.. code-block:: none
+
+ make install
+
+.. note::
+ The above may require superuser privileges.
+
+This will install libgpiod under the default system paths. If you want to
+install it under non-standard path, pass the ``--prefix=<install path>``
+option to ``configure``.
new file mode 100644
@@ -0,0 +1,45 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+ Contribution guide.
+
+Contributing
+============
+
+Contributions are welcome - please send questions, patches and bug reports to
+the `linux-gpio mailing list
+<http://vger.kernel.org/vger-lists.html#linux-gpio>`_
+by e-mailing to ``linux-gpio@vger.kernel.org`` (add the ``[libgpiod]`` prefix
+to the e-mail subject line). Note that the mailing list quietly drops HTML
+formatted e-mail, so be sure to `send plain text
+<https://docs.kernel.org/process/email-clients.html>`_.
+
+Code submissions should stick to the `linux kernel coding style
+<https://docs.kernel.org/process/coding-style.html>`_ and follow the kernel
+`patch submission process
+<https://docs.kernel.org/process/submitting-patches.html>`_ as applied to the
+libgpiod source tree. All shell scripts must pass `shellcheck tests
+<https://www.shellcheck.net/>`_. All files must have a license and copyright
+SPDX headers and the repo is expected to pass the `reuse lint check
+<https://reuse.software/>`_.
+
+The `mailing list archive <https://lore.kernel.org/linux-gpio/>`_ contains all
+the historical mails to the list, and is the place to check to ensure your
+e-mail has been received.
+Search for `"libgpiod"` to filter the list down to relevant messages. Those
+also provide examples of the expected formatting. Allow some time for your
+e-mail to propagate to the list before retrying, particularly if there are no
+e-mails in the list more recent than yours.
+
+There is a `libgpiod github page <https://github.com/brgl/libgpiod>`_
+available for reporting bugs and general discussions and although PRs can be
+submitted and discussed, upstreambound patches need to go through the mailing
+list nevertheless.
+
+.. note::
+ For more information, please refer to the ``CONTRIBUTING.md`` file in the
+ libgpiod source tree.
@@ -15,6 +15,9 @@ core C API. These bindings make it easier to work with GPIO lines in C++ by
offering an **object-oriented** approach and **RAII** (Resource Acquisition
Is Initialization) principles for managing resources.
+.. note::
+ C++17 compiler support is required to build the bindings.
+
.. toctree::
:maxdepth: 1
:caption: Contents
@@ -10,11 +10,24 @@
D-Bus interface
===============
-The **libgpiod D-Bus API** provides an abstraction for interacting with GPIO
-chips on Linux systems via the D-Bus messaging system. It enables relatively
-efficient, asynchronous control of GPIO lines, offering methods for
+A commonly requested feature for the GPIO character device was state persistence
+after releasing the lines (as a kernel feature) or providing a central authority
+(in user-space) that would be in charge of keeping the lines requested and in a
+certain state (similarily to how the sysfs ABI works). **GPIO D-Bus API** has
+been provided to address this requirement. We define an interface covering the
+majority of the GPIO chardev's functionality and implement it from both the
+server and client sides in the form of the **gpio-manager** daemon and the
+**gpiocli** command-line utility for talking to the manager. It enables
+relatively efficient, asynchronous control of GPIO lines, offering methods for
configuring, monitoring, and manipulating GPIOs.
+.. note::
+ DBus support can be built by passing ``--enable-dbus`` to configure. The
+ daemon is bundled with a systemd unit file and an example configuration file
+ for the ``io.gpiod1`` interface that allows all users to access basic
+ information about the GPIOs in the system but only root to request lines or
+ change their values.
+
.. toctree::
:maxdepth: 1
:caption: Contents
@@ -15,6 +15,9 @@ interface to interact with GPIO (General Purpose Input/Output) lines on Linux
systems. These bindings leverage the **GObject framework**, commonly used in
GNOME and GTK+ applications, to wrap the lower-level C API of libgpiod.
+.. note::
+ GLib bindings require GLib (as well as GObject, GIO and GIO-Unix) v2.80.
+
.. warning::
The documentation for GObject bindings is generated using gi-docgen and
cannot be easily integrated with sphinx documentation. Please navigate to
@@ -10,9 +10,29 @@
Command-line tools
==================
+Overview
+--------
+
The **libgpiod** project includes a suite of **command-line tools** to
facilitate GPIO manipulation from console and shell scripts.
+There are currently six command-line tools available:
+
+* **gpiodetect**: list all gpiochips present on the system, their names, labels
+ and number of GPIO lines
+* **gpioinfo**: list lines, their gpiochip, offset, name, and direction, and if
+ in use then the consumer name and any other configured attributes, such as
+ active state, bias, drive, edge detection and debounce period
+* **gpioget**: read values of specified GPIO lines
+* **gpioset**: set values of specified GPIO lines, holding the lines until the
+ process is killed or otherwise exits
+* **gpiomon**: wait for edge events on GPIO lines, specify which edges to watch
+ for, how many events to process before exiting, or if the events should be
+ reported to the console
+* **gpionotify**: wait for changed to the info for GPIO lines, specify which
+ changes to watch for, how many events to process before exiting, or if the
+ events should be reported to the console
+
.. toctree::
:maxdepth: 1
:caption: Manual entries
@@ -23,3 +43,199 @@ facilitate GPIO manipulation from console and shell scripts.
gpioset<gpioset>
gpiomon<gpiomon>
gpionotify<gpionotify>
+
+Examples
+--------
+
+.. note::
+ The following examples where creating using a Raspberry Pi 4B. The pins
+ will be different on other board.
+
+Detect the available gpiochips:
+
+.. code-block:: none
+
+ $ gpiodetect
+ gpiochip0 [pinctrl-bcm2711] (58 lines)
+ gpiochip1 [raspberrypi-exp-gpio] (8 lines)
+
+Read the info for all the lines on a gpiochip:
+
+.. code-block:: none
+
+ $ gpioinfo -c 1
+ gpiochip1 - 8 lines:
+ line 0: "BT_ON" output
+ line 1: "WL_ON" output
+ line 2: "PWR_LED_OFF" output active-low consumer="led1"
+ line 3: "GLOBAL_RESET" output
+ line 4: "VDD_SD_IO_SEL" output consumer="vdd-sd-io"
+ line 5: "CAM_GPIO" output consumer="cam1_regulator"
+ line 6: "SD_PWR_ON" output consumer="sd_vcc_reg"
+ line 7: "SD_OC_N" input
+
+Read the info for particular lines:
+
+.. code-block:: none
+
+ $ ./gpioinfo PWR_LED_OFF STATUS_LED_G_CLK GLOBAL_RESET
+ gpiochip0 42 "STATUS_LED_G_CLK" output consumer="led0"
+ gpiochip1 2 "PWR_LED_OFF" output active-low consumer="led1"
+ gpiochip1 3 "GLOBAL_RESET" output
+
+Read the value of a single GPIO line by name:
+
+.. code-block:: none
+
+ $ gpioget RXD1
+ "RXD1"=active
+
+Read the value of a single GPIO line by chip and offset:
+
+.. code-block:: none
+
+ $ gpioget -c 0 15
+ "15"=active
+
+Read the value of a single GPIO line as a numeric value:
+
+.. code-block:: none
+
+ $ gpioget --numeric RXD1
+ 1
+
+Read two values at the same time, set the active state of the lines to low and
+without quoted names:
+
+.. code-block:: none
+
+ $ gpioget --active-low --unquoted GPIO23 GPIO24
+ GPIO23=active GPIO24=active
+
+Set the value of a line and hold the line until killed:
+
+.. code-block:: none
+
+ $ gpioset GPIO23=1
+
+Set values of two lines, then daemonize and hold the lines:
+
+.. code-block:: none
+
+ $ gpioset --daemonize GPIO23=1 GPIO24=0
+
+Set the value of a single line, hold it for 20ms, then exit:
+
+.. code-block:: none
+
+ $ gpioset --hold-period 20ms -t0 GPIO23=1
+
+Blink an LED on GPIO22 at 1Hz:
+
+.. code-block:: none
+
+ $ gpioset -t500ms GPIO22=1
+
+Blink an LED on GPIO22 at 1Hz with a 20% duty cycle:
+
+.. code-block:: none
+
+ $ gpioset -t200ms,800ms GPIO22=1
+
+Set some lines interactively (requires ``--enable-gpioset-interactive``):
+
+.. code-block:: none
+
+ $ gpioset --interactive --unquoted GPIO23=inactive GPIO24=active
+ gpioset> get
+ GPIO23=inactive GPIO24=active
+ gpioset> toggle
+ gpioset> get
+ GPIO23=active GPIO24=inactive
+ gpioset> set GPIO24=1
+ gpioset> get
+ GPIO23=active GPIO24=active
+ gpioset> toggle
+ gpioset> get
+ GPIO23=inactive GPIO24=inactive
+ gpioset> toggle GPIO23
+ gpioset> get
+ GPIO23=active GPIO24=inactive
+ gpioset> exit
+
+Wait for three rising edge events on a single GPIO line, then exit:
+
+.. code-block:: none
+
+ $ gpiomon --num-events=3 --edges=rising GPIO22
+ 10002.907638045 rising "GPIO22"
+ 10037.132562259 rising "GPIO22"
+ 10047.179790748 rising "GPIO22"
+
+Wait for three edge events on a single GPIO line, with time in local time and
+with unquoted line name, then exit:
+
+.. code-block:: none
+
+ $ gpiomon --num-events=3 --edges=both --localtime --unquoted GPIO22
+ 2022-11-15T10:36:59.109615508 rising GPIO22
+ 2022-11-15T10:36:59.129681898 falling GPIO22
+ 2022-11-15T10:36:59.698971886 rising GPIO22
+
+Wait for falling edge events with a custom output format:
+
+.. code-block:: none
+
+ $ gpiomon --format="%e %c %o %l %S" --edges=falling -c gpiochip0 22
+ 2 gpiochip0 22 GPIO22 10946.693481859
+ 2 gpiochip0 22 GPIO22 10947.025347604
+ 2 gpiochip0 22 GPIO22 10947.283716669
+ 2 gpiochip0 22 GPIO22 10947.570109430
+ ...
+
+Block until an edge event occurs, don't print anything:
+
+.. code-block:: none
+
+ $ gpiomon --num-events=1 --quiet GPIO22
+
+Monitor multiple lines, exit after the first edge event:
+
+.. code-block:: none
+
+ $ gpiomon --quiet --num-events=1 GPIO5 GPIO6 GPIO12 GPIO17
+
+Monitor a line for changes to info:
+
+.. code-block:: none
+
+ $ gpionotify GPIO23
+ 11571.816473718 requested "GPIO23"
+ 11571.816535124 released "GPIO23"
+ 11572.722894029 requested "GPIO23"
+ 11572.722932843 released "GPIO23"
+ 11573.222998598 requested "GPIO23"
+ ...
+
+Monitor a line for requests, reporting UTC time and unquoted line name:
+
+.. code-block:: none
+
+ $ gpionotify --utc --unquoted GPIO23
+ 2022-11-15T03:05:23.807090687Z requested GPIO23
+ 2022-11-15T03:05:23.807151390Z released GPIO23
+ 2022-11-15T03:05:24.784984280Z requested GPIO23
+ 2022-11-15T03:05:24.785023873Z released GPIO23
+ ...
+
+Monitor multiple lines, exit after the first is requested:
+
+.. code-block:: none
+
+ $ gpionotify --quiet --num-events=1 --event=requested GPIO5 GPIO6 GPIO12 GPIO17
+
+Block until a line is released:
+
+.. code-block:: none
+
+ $ gpionotify --quiet --num-events=1 --event=released GPIO6
@@ -10,6 +10,87 @@
Command-line client
===================
+With the manager running the user can run ``gpiocli`` to control GPIOs by
+asking the ``gpio-manager`` to act on their behalf.
+
+Examples
+--------
+
+Detect chips in the system:
+
+.. code-block:: none
+
+ $ gpiocli detect
+ gpiochip0 [INT34C6:00] (463 lines)
+
+Request a set of lines:
+
+.. note::
+ **gpiocli** exits immediately but the state of the lines is retained
+ because it's the **gpio-manager** that requested them.
+
+.. code-block:: none
+
+ $ gpiocli request --output foo=active
+ request0
+
+Previous invocation printed out the name of the request by which the caller
+can refer to it later. All active requests can also be inspected at any time:
+
+.. code-block:: none
+
+ $ gpiocli requests
+ request0 (gpiochip1) Offsets: [5]
+
+
+Print the information about the requested line using the information above:
+
+.. code-block:: none
+
+ $ gpiocli info --chip=gpiochip1 5
+ gpiochip1 5: "foo" [used,consumer="gpiocli request",managed="request0",output,push-pull]
+
+Change the value of the line:
+
+.. code-block:: none
+
+ $ gpiocli set foo=inactive
+
+Read it back:
+
+.. code-block:: none
+
+ $ gpiocli get foo
+ "foo"=inactive
+
+We can even reconfigure it to input and enable edge-detection:
+
+.. code-block:: none
+
+ $ gpiocli reconfigure --input --both-edges request0
+
+And wait for edge events:
+
+.. code-block:: none
+
+ $ gpiocli monitor cos
+ 21763952894920 rising "foo"
+
+And finally release the request:
+
+.. code-block:: none
+
+ $ gpiocli release request0
+
+.. note::
+ For more information please refer to the output of ``gpiocli --help`` as
+ well as ``gpiocli <command> --help`` which prints detailed info on every
+ available command.
+
+.. note::
+ Users can talk to **gpio-manager** using any **D-Bus** library available
+ and are not limited to the provided client.
+
.. toctree::
:maxdepth: 1
:caption: Manual entries
@@ -14,17 +14,30 @@ The **libgpiod** project provides a low-level C library, bindings to high-level
languages and tools for interacting with the GPIO (General Purpose Input/Output)
lines on Linux systems.
-It replaces the older, legacy GPIO sysfs interface, which has been deprecated
-in the Linux kernel. The newer GPIO character device interface (introduced in
-Linux kernel version 4.8) provides a more flexible and efficient way to
-interact with GPIO lines, and libgpiod is the primary tool for working with
-this interface.
+It replaces the older, **legacy GPIO sysfs interface**, which has been
+deprecated in the Linux kernel. The newer **GPIO character device** interface
+(introduced in **Linux kernel version 4.8**) provides a more flexible and
+efficient way to interact with GPIO lines, and libgpiod is the **primary tool**
+for working with this interface.
+
+The character device interface guarantees all allocated resources are freed
+after closing the device file descriptor and adds several new features that
+are not present in the obsolete sysfs interface (like reliable event polling,
+setting/reading multiple values at once or open-source and open-drain GPIOs).
+
+Unfortunately interacting with the linux device file can no longer be done
+using only standard command-line tools. This is the reason for creating a
+library encapsulating the cumbersome, ioctl-based kernel-userspace interaction
+in a set of convenient functions and opaque data structures.
.. toctree::
:maxdepth: 1
:caption: Contents
+ building
core_api
bindings
gpio_tools
dbus
+ testing
+ contributing
@@ -17,6 +17,10 @@ easily through Python scripts, enabling tasks such as reading input values,
setting outputs, monitoring events, and configuring more fine-grained pin
options.
+.. note::
+ Python bindings require python3 support and libpython development files for
+ building from sources.
+
.. toctree::
:maxdepth: 1
:caption: Contents
@@ -31,3 +35,7 @@ options.
python_line_settings
python_line_request
python_misc
+
+.. note::
+ Python bindings can be installed from https://pypi.org/ with pip by running
+ ``pip install gpiod``.
new file mode 100644
@@ -0,0 +1,46 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+ Contribution guide.
+
+Testing
+=======
+
+A comprehensive testing framework is included with the library and can be used
+to test both the core library code as well as the kernel-to-user-space
+interface.
+
+The minimum kernel version required to run the tests can be checked in the
+``tests/gpiod-test.c`` source file (it's subject to change if new features are
+added to the kernel). The tests work together with the **gpio-sim** kernel
+module which must either be built-in or available for loading using kmod.
+A helper library - **libgpiosim** - is included to enable straightforward
+interaction with the module.
+
+To build the testing executable add the ``--enable-tests`` option when running
+the configure script. If enabled, the tests will be installed next to
+**gpio-tools**.
+
+As opposed to standard autotools projects, libgpiod doesn't execute any tests
+when invoking ``make check``. Instead the user must run them manually with
+superuser privileges.
+
+The testing framework uses the **GLib unit testing** library so development
+package for GLib must be installed.
+
+The **gpio-tools** programs can be tested separately using the
+``gpio-tools-test.bash`` script. It requires `shunit2
+<https://github.com/kward/shunit2>`_ to run and assumes that the tested
+executables are in the same directory as the script.
+
+C++, Rust and Python bindings also include their own test-suites. All three
+reuse the **libgpiosim** library to avoid code duplication when interacting
+with **gpio-sim**.
+
+Python test-suite uses the standard unittest package. C++ tests use an external
+testing framework - **Catch2** - which must be installed in the system. Rust
+bindings use the standard tests module layout and the ``#[test]`` attribute.