Crate gpio_cdev

The gpio-cdev crate provides access to the GPIO character device ABI. This API, stabilized with Linux v4.4, deprecates the legacy sysfs interface to GPIOs that is planned to be removed from the upstream kernel after year 2020 (which is coming up quickly).

This crate attempts to wrap this interface in a moderately direction fashion while retaining safety and using Rust idioms (where doing so could be mapped to the underlying abstraction without significant overhead or loss of functionality).

For additional context for why the kernel is moving from the sysfs API to the character device API, please see the main README on Github.

Examples

The following example reads the state of a GPIO line/pin and writes the matching state to another line/pin.

use gpio_cdev::{Chip, LineRequestFlags, EventRequestFlags, EventType};

// Lines are offset within gpiochip0; see docs for more info on chips/lines
fn mirror_gpio(inputline: u32, outputline: u32) -> Result<(), gpio_cdev::Error> {
    let mut chip = Chip::new("/dev/gpiochip0")?;
    let input = chip.get_line(inputline)?;
    let output = chip.get_line(outputline)?;
    let output_handle = output.request(LineRequestFlags::OUTPUT, 0, "mirror-gpio")?;
    for event in input.events(
        LineRequestFlags::INPUT,
        EventRequestFlags::BOTH_EDGES,
        "mirror-gpio",
    )? {
        let evt = event?;
        println!("{:?}", evt);
        match evt.event_type() {
            EventType::RisingEdge => {
                output_handle.set_value(1)?;
            }
            EventType::FallingEdge => {
                output_handle.set_value(0)?;
            }
        }
    }

    Ok(())
}

To get the state of a GPIO Line on a given chip:

use gpio_cdev::{Chip, LineRequestFlags};

// 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)?
    .request(LineRequestFlags::INPUT, 0, "read-input")?;
for _ in 1..4 {
    println!("Value: {:?}", handle.get_value()?);
}

Re-exports

pub use errors::*;

Modules

errors

This module is deprecated and types are exported from the top-level of the crate

Structs

AsyncLineEventHandleasync-tokio

Wrapper around a LineEventHandle which implements a futures::stream::Stream for interrupts.

Chip

A GPIO Chip maps to the actual device driver instance in hardware that one interacts with to interact with individual GPIOs. Often these chips map to IP chunks on an SoC but could also be enumerated within the kernel via something like a PCI or USB bus.

ChipIterator

Iterator over chips

EventRequestFlags

Event request flags

Line

Access to a specific GPIO Line

LineEvent

Information about a change to the state of a Line

LineEventHandle

Handle for retrieving events from the kernel for a line

LineFlags

Informational Flags

LineHandle

Handle for interacting with a “requested” line

LineInfo

Information about a specific GPIO Line

LineIterator

Iterator over GPIO Lines for a given chip.

LineRequestFlags

Line Request Flags

Lines

A collection of lines that can be accesses simultaneously

MultiLineHandle

Handle for interacting with a “requested” line

Enums

EventType

Did the Line rise (go active) or fall (go inactive)?

IoctlKind

LineDirection

In or Out

Functions

chips

Iterate over all GPIO chips currently present on this system