From: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx> We now have comprehensive documentation available online on readthedocs. Let's not duplicate docs in README - move all information into the sphinx files. While at it: make the remaining README use markdown. Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx> --- README | 384 -------------------------------------------------- README.md | 11 ++ docs/bindings.rst | 25 +++- docs/building.rst | 74 ++++++++++ docs/contributing.rst | 45 ++++++ docs/cpp_api.rst | 3 + docs/dbus.rst | 19 ++- docs/glib_api.rst | 3 + docs/gpio_tools.rst | 216 ++++++++++++++++++++++++++++ docs/gpiocli_top.rst | 81 +++++++++++ docs/index.rst | 23 ++- docs/python_api.rst | 8 ++ docs/testing.rst | 46 ++++++ 13 files changed, 544 insertions(+), 394 deletions(-) diff --git a/README b/README deleted file mode 100644 index 28a3dfd..0000000 --- a/README +++ /dev/null @@ -1,384 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# SPDX-FileCopyrightText: 2017-2023 Bartosz Golaszewski <brgl@xxxxxxxx> - -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@xxxxxxxxxxxxxxx -(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/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..664dbc5 --- /dev/null +++ b/README.md @@ -0,0 +1,11 @@ +<!-- SPDX-License-Identifier: CC-BY-SA-4.0 --> +<!-- SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx> --> + +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/. diff --git a/docs/bindings.rst b/docs/bindings.rst index 73f1262..7f0f6b7 100644 --- a/docs/bindings.rst +++ b/docs/bindings.rst @@ -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. + diff --git a/docs/building.rst b/docs/building.rst new file mode 100644 index 0000000..958c6fb --- /dev/null +++ b/docs/building.rst @@ -0,0 +1,74 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx> + +.. + 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``. diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..e46d50f --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,45 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx> + +.. + 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@xxxxxxxxxxxxxxx`` (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. diff --git a/docs/cpp_api.rst b/docs/cpp_api.rst index 83a6aa4..4c76b56 100644 --- a/docs/cpp_api.rst +++ b/docs/cpp_api.rst @@ -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 diff --git a/docs/dbus.rst b/docs/dbus.rst index 0dcbb81..98d2cbe 100644 --- a/docs/dbus.rst +++ b/docs/dbus.rst @@ -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 diff --git a/docs/glib_api.rst b/docs/glib_api.rst index 307f5f7..f6d8665 100644 --- a/docs/glib_api.rst +++ b/docs/glib_api.rst @@ -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 diff --git a/docs/gpio_tools.rst b/docs/gpio_tools.rst index 7372de4..e4bf584 100644 --- a/docs/gpio_tools.rst +++ b/docs/gpio_tools.rst @@ -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 diff --git a/docs/gpiocli_top.rst b/docs/gpiocli_top.rst index 52e3295..3b50b91 100644 --- a/docs/gpiocli_top.rst +++ b/docs/gpiocli_top.rst @@ -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 diff --git a/docs/index.rst b/docs/index.rst index 3101e14..8c02c6a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 diff --git a/docs/python_api.rst b/docs/python_api.rst index 00b30cb..2c4f59d 100644 --- a/docs/python_api.rst +++ b/docs/python_api.rst @@ -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``. diff --git a/docs/testing.rst b/docs/testing.rst new file mode 100644 index 0000000..e645e71 --- /dev/null +++ b/docs/testing.rst @@ -0,0 +1,46 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx> + +.. + 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. -- 2.45.2
[PATCH libgpiod v3 16/16] doc: move README contents to sphinx docs
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
- Subject: [PATCH libgpiod v3 16/16] doc: move README contents to sphinx docs
- From: Bartosz Golaszewski <brgl@xxxxxxxx>
- Date: Thu, 06 Feb 2025 13:22:13 +0100
- In-reply-to: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org>
- References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org>
- References:
- [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs
- From: Bartosz Golaszewski
- [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs
- Prev by Date: [PATCH libgpiod v3 13/16] doc: add documentation for GLib bindings
- Next by Date: Re: [PATCH v2 2/4] firmware: arm_scmi: Add machine_allowlist and machine_blocklist
- Previous by thread: [PATCH libgpiod v3 13/16] doc: add documentation for GLib bindings
- Index(es):
 |