Merge #30

30: Improve documentation about maintaining LineHandles r=nastevens a=kmdouglass

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

Co-authored-by: Kyle M. Douglass <[email protected]>

Author: bors[bot]

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

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")?;

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)?