From 872abf5eff530a9be2cd1460623e019904eb262b Mon Sep 17 00:00:00 2001 From: "Kyle M. Douglass" Date: Fri, 13 Dec 2019 06:49:24 +0100 Subject: [PATCH] Improve documentation about maintaining LineHandles This commit addresses \#29 by expanding the documentation to explain the importance of maintaining valid LineHandles in a program that uses this library. - A comment was added to the Read State code example in the README to explain that the LineHandle must be maintained for the line to work - A similar comment was added to the `driveoutput.rs` example - A brief explanation was added to the section entitled "Exporting" a GPIO of the README about the file descriptor that is associated with a line --- README.md | 4 +++- examples/driveoutput.rs | 7 ++++++- src/lib.rs | 3 +++ 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ade5bb7..abb6aef 100644 --- a/README.md +++ b/README.md @@ -139,7 +139,9 @@ Using the sysfs API, one would write the global GPIO number to the "export" file to perform further operations using new files on the filesystem. Using the gpiochip character device, a handle for performing operations on one or more GPIO offsets within a chip are available via a "linehandle" fd created using the -`GPIO_GET_LINEHANDLE_IOCTL`. +`GPIO_GET_LINEHANDLE_IOCTL`. A consequence of this is that a line will remember +its state only for as long as the fd is open; the line's state will be reset +once the fd is closed. When a linehandle is requested, additional information is also included about how the individual GPIOs will be used (input, output, as-is, active-low, open diff --git a/examples/driveoutput.rs b/examples/driveoutput.rs index f049bf7..cd047be 100644 --- a/examples/driveoutput.rs +++ b/examples/driveoutput.rs @@ -27,7 +27,12 @@ fn do_main(args: Cli) -> std::result::Result<(), errors::Error> { let mut chip = Chip::new(args.chip)?; // NOTE: we set the default value to the desired state so - // setting it separately is not required + // setting it separately is not required. The LineHandle + // instance that is returned by request must be owned by a + // variable for the duration of the time that the line will + // be used. If the instance is not assigned to a variable, + // then the LineHandle will be immediately dropped after + // request returns and the pin will appear to do nothing. let _handle = chip.get_line(args.line)? .request(LineRequestFlags::OUTPUT, args.value, "driveoutput")?; diff --git a/src/lib.rs b/src/lib.rs index 6a8cac4..5556d9e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -69,6 +69,9 @@ //! # fn main() -> Result<()> { //! // Read the state of GPIO4 on a raspberry pi. /dev/gpiochip0 //! // maps to the driver for the SoC (builtin) GPIO controller. +//! // The LineHandle returned by request must be assigned to a +//! // variable (in this case the variable handle) to ensure that +//! // the corresponding file descriptor is not closed. //! let mut chip = Chip::new("/dev/gpiochip0")?; //! let handle = chip //! .get_line(4)?