From 6808b65117b95f7a982901e6f43d7e9243a90226 Mon Sep 17 00:00:00 2001 From: Bartosz Golaszewski Date: Tue, 17 Jan 2017 19:53:37 +0100 Subject: [PATCH] README: update Signed-off-by: Bartosz Golaszewski --- README | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 61 insertions(+), 3 deletions(-) diff --git a/README b/README index 6a13e7c..8249ad4 100644 --- a/README +++ b/README @@ -1,3 +1,6 @@ +libgpiod +======== + libgpiod - C library and tools for interacting with the linux GPIO character device @@ -5,7 +8,62 @@ Since linux 4.7 the GPIO sysfs interface is deprecated. User space should use the character device instead. This library encapsulates the ioctl calls and data structures behind a straightforward API. -This is still work-in-progress and no interfaces are stable yet. +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. It does not depend on any +libraries other than the standard C library with GNU extensions. + +Recent (as in >= v4.7) kernel headers are also required for the GPIO user +API definitions. + +To build the project (including command-line utilities) run: + + ./autogen.sh + ./configure --enable-tools=yes --prefix= + make + make install + +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 all lines of specified gpiochips, their names, consumers, + direction, active state and additional flags + + gpioget - read values of specified GPIO lines + + gpioset - set values of specified GPIO lines, potentially keep the lines + exported and wait until timeout, user input or signal + + gpiofind - find the gpiochip name and line offset given the line name + + gpiomon - wait for events on a GPIO line, specify which events to watch, + how many events to process before exiting or if the events + should be reported to the console + +CONTRIBUTING +------------ -Contributions are welcome - please use github pull-requests and stick to the -linux kernel coding style. +Contributions are welcome - please use github pull-requests and issues and +stick to the linux kernel coding style when submitting new code. -- 2.30.2