Crate gpiosim

Expand description

A library for creating and controlling GPIO simulators for testing users of the Linux GPIO uAPI (both v1 and v2).

The simulators are provided by the Linux gpio-sim kernel module and require a recent kernel (v5.19 or later) built with CONFIG_GPIO_SIM.

Simulators (Sim) contain one or more chips, each with a collection of lines being simulated. The Builder is responsible for constructing the Sim and taking it live. Configuring a simulator involves adding Banks, representing the chip, to the Builder.

Once live, the Chip exposes lines which may be manipulated to drive the GPIO uAPI from the kernel side. For input lines, applying a pull using Chip.set_pull and related methods controls the level of the simulated line. For output lines, Chip.get_level returns the level the simulated line is being driven to.

For simple tests that only require lines on a single chip, the Simpleton provides a simplified interface.

Configuring a simulator involves configfs, and manipulating the chips once live involves sysfs, so root permissions are typically required to run a simulator.

§Example Usage

Creating a simulator with two chips, with 8 and 42 lines respectively, each with several named lines and a hogged line:

use gpiosim::{Bank, Direction, Level};

let sim = gpiosim::builder()
    .with_name("some unique name")
    .with_bank(
        Bank::new(8, "left")
            .name(3, "LED0")
            .name(5, "BUTTON1")
            .hog(2, "hogster", Direction::OutputLow)
        )
    .with_bank(
        Bank::new(42, "right")
            .name(3, "BUTTON2")
            .name(4, "LED2")
            .hog(7, "hogster", Direction::OutputHigh),
    )
    .live()?;

let chips = sim.chips();
let c = &chips[0];
c.set_pull(5, Level::High);
let level = c.get_level(3)?;

Use a Simpleton to create a single chip simulator with 12 lines, for where multiple chips or named lines are not required:

use gpiosim::{Level, Simpleton};

let s = Simpleton::new(12);
let c = s.chip();
c.set_pull(5, Level::High);
c.set_pull(6, Level::Low);
let level = c.get_level(3)?;

Structs§

Bank: The configuration for a single simulated chip.
Builder: A builder of simulators.
Chip: A live simulated chip.
Hog: The configuration for a hogged line.
OffsetHasher: A simple identity hasher for maps using Offsets as keys.
Sim: A live simulator of one or more chips.
Simpleton: A basic single bank/chip sim.

Enums§

Direction: The direction, and for outputs the pulled value, of a hogged line.
Error: Errors returned by gpiosim functions.
Level: The physical value of a line.

Functions§

builder: Start building a GPIO simulator.
unique_name: Create a unique, but predictable, name for the simulator.

Type Aliases§