From: Bartosz Golaszewski Date: Tue, 12 Sep 2017 07:55:56 +0000 (+0200) Subject: README.md: rename to README X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=ee0b9c49705706034805b23130cc287aadbdcc4b;p=qemu-gpiodev%2Flibgpiod.git README.md: rename to README We now host libgpiod at kernel.org, so no need for the .md file. This also fixes 'make dist' as README.md was not being packaged by autotools. Signed-off-by: Bartosz Golaszewski --- diff --git a/README b/README new file mode 100644 index 0000000..b2e7238 --- /dev/null +++ b/README @@ -0,0 +1,137 @@ +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. 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. It does not depend on any +libraries other than the standard C library with GNU extensions. + +The autoconf version needed to compile the project is 2.61. + +Recent (as in >= v4.8) kernel headers are also required for the GPIO user +API definitions. + +To build the project (including command-line utilities) run: + + ./autogen.sh --enable-tools=yes --prefix= + make + make install + +The autogen script will execute ./configure and pass all the command-line +arguments to it. + +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 GPIO lines, specify which events to watch, + how many events to process before exiting or if the events + should be reported to the console + +Examples: + + # Read the value of a single GPIO line. + $ gpioget gpiochip1 23 + 0 + + # Read two values at the same time. Set the active state of the lines + # to low. + $ gpioget --active-low gpiochip1 23 24 + 1 1 + + # Set values of two lines, then daemonize and wait for a signal (SIGINT or + # SIGTERM) before releasing them. + $ gpioset --mode=signal --background gpiochip1 23=1 24=0 + + # Set the value of a single line, then exit immediately. This is useful + # for floating pins. + $ gpioset gpiochip1 23=1 + + # Find a GPIO line by name. + $ gpiofind "USR-LED-2" + gpiochip1 23 + + # Toggle a GPIO by name, then wait for the user to press ENTER. + $ gpioset --mode=wait `gpiofind "USR-LED-2"`=1 + + # Wait for three rising edge events on a single GPIO line, then exit. + $ gpiomon --num-events=3 --rising-edge gpiochip2 3 + event: RISING EDGE offset: 3 timestamp: [ 1151.814356387] + event: RISING EDGE offset: 3 timestamp: [ 1151.815449803] + event: RISING EDGE offset: 3 timestamp: [ 1152.091556803] + + # Wait for a single falling edge event. Specify a custom output format. + $ gpiomon --format="%e %o %s %n" --falling-edge gpiochip1 4 + 0 4 1156 615459801 + + # Pause execution until a single event of any type occurs. Don't print + # anything. Find the line by name. + $ gpiomon --num-events=1 --silent `gpiofind "USR-IN"` + + # Monitor multiple lines, exit after the first event. + $ gpiomon --silent --num-events=1 gpiochip0 2 3 5 + +TESTING +------- + +A comprehensive testing framework is included with the library and can be +used to test both the library code and the linux kernel user-space interface. + +The minimum kernel version required to run the tests is 4.11. The tests work +together with the gpio-mockup kernel module which must be enabled. NOTE: the +module must not be built-in. + +To build the testing executable run: + + ./configure --enable-tests + make check + +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: + + sudo ./tests/gpiod-test + +CONTRIBUTING +------------ + +Contributions are welcome - please use github pull-requests and issues and +stick to the linux kernel coding style when submitting new code. diff --git a/README.md b/README.md deleted file mode 100644 index b2e7238..0000000 --- a/README.md +++ /dev/null @@ -1,137 +0,0 @@ -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. 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. It does not depend on any -libraries other than the standard C library with GNU extensions. - -The autoconf version needed to compile the project is 2.61. - -Recent (as in >= v4.8) kernel headers are also required for the GPIO user -API definitions. - -To build the project (including command-line utilities) run: - - ./autogen.sh --enable-tools=yes --prefix= - make - make install - -The autogen script will execute ./configure and pass all the command-line -arguments to it. - -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 GPIO lines, specify which events to watch, - how many events to process before exiting or if the events - should be reported to the console - -Examples: - - # Read the value of a single GPIO line. - $ gpioget gpiochip1 23 - 0 - - # Read two values at the same time. Set the active state of the lines - # to low. - $ gpioget --active-low gpiochip1 23 24 - 1 1 - - # Set values of two lines, then daemonize and wait for a signal (SIGINT or - # SIGTERM) before releasing them. - $ gpioset --mode=signal --background gpiochip1 23=1 24=0 - - # Set the value of a single line, then exit immediately. This is useful - # for floating pins. - $ gpioset gpiochip1 23=1 - - # Find a GPIO line by name. - $ gpiofind "USR-LED-2" - gpiochip1 23 - - # Toggle a GPIO by name, then wait for the user to press ENTER. - $ gpioset --mode=wait `gpiofind "USR-LED-2"`=1 - - # Wait for three rising edge events on a single GPIO line, then exit. - $ gpiomon --num-events=3 --rising-edge gpiochip2 3 - event: RISING EDGE offset: 3 timestamp: [ 1151.814356387] - event: RISING EDGE offset: 3 timestamp: [ 1151.815449803] - event: RISING EDGE offset: 3 timestamp: [ 1152.091556803] - - # Wait for a single falling edge event. Specify a custom output format. - $ gpiomon --format="%e %o %s %n" --falling-edge gpiochip1 4 - 0 4 1156 615459801 - - # Pause execution until a single event of any type occurs. Don't print - # anything. Find the line by name. - $ gpiomon --num-events=1 --silent `gpiofind "USR-IN"` - - # Monitor multiple lines, exit after the first event. - $ gpiomon --silent --num-events=1 gpiochip0 2 3 5 - -TESTING -------- - -A comprehensive testing framework is included with the library and can be -used to test both the library code and the linux kernel user-space interface. - -The minimum kernel version required to run the tests is 4.11. The tests work -together with the gpio-mockup kernel module which must be enabled. NOTE: the -module must not be built-in. - -To build the testing executable run: - - ./configure --enable-tests - make check - -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: - - sudo ./tests/gpiod-test - -CONTRIBUTING ------------- - -Contributions are welcome - please use github pull-requests and issues and -stick to the linux kernel coding style when submitting new code.