Linux GPIO Character Device v2: Line Requests and Event Lifetimes

The Linux GPIO character-device API gives userspace a descriptor-based way to inspect chips, request lines, configure direction and bias, and receive edge events. It replaces global GPIO number assumptions with explicit requests associated with a chip and set of lines. The API does not make every electrical property available: capabilities depend on the controller, firmware description, kernel, and line constraints.

GPIO is a hardware control interface. Driving the wrong line can reset a board, switch power, or change external circuitry. Start with the schematic, board documentation, and the chip’s line names. A name alone is not proof of function, and a line index is local to one chip rather than a globally stable identifier.

Discover chips and line capabilities safely

Use gpio-tools such as gpioinfo to enumerate chips and lines when installed. Record the chip path, line offset, name, consumer label, and reported direction or use state. Avoid bulk toggling tools as a discovery method. A line marked unused can still be electrically connected to a critical circuit or reserved by firmware outside Linux.

gpioinfo
gpiodetect
ls -l /dev/gpiochip*

The exact output depends on libgpiod version and chip driver. These commands inspect state; they do not prove the line’s voltage or board function. If an oscilloscope or logic analyzer is needed, use a safe ground reference and board-specific procedures.

The character-device API is organized around chip file descriptors and line-request file descriptors. A request can cover one or several offsets and carry per-line configuration. Request ownership is exclusive at the kernel interface level for the requested lines. A failed request because a line is busy should be investigated, not worked around by poking sysfs or forcing a second owner.

Make a request with explicit direction and polarity

For an output, define the initial logical value as part of the request so the line does not briefly transition through an unintended state. If the board uses active-low wiring, configure active-low semantics rather than manually inverting values at scattered call sites. Bias, drive, debounce, and edge detection are optional capabilities; the kernel or controller may reject a request that the hardware cannot implement.

For inputs, distinguish physical voltage from logical active state. Active-low changes the interpretation exposed by the API. Open-drain and open-source behavior can require external pull resistors and may be approximated or unsupported on a controller. Do not assume an API flag changes the electrical circuit if the controller lacks that capability.

A production application should open the intended chip, request only needed lines, check each ioctl error, and retain the returned file descriptor for the period it owns the lines. On error, close the request descriptor and report which line and configuration failed. Never leave a partially configured group and assume all lines changed atomically unless the API documents that guarantee.

Edge events are queued records, not interrupts in userspace

GPIO v2 edge events include line identity, event type, timestamps, and sequence information. The kernel captures events and queues records for userspace to read. The event timestamp clock must be selected and interpreted consistently; wall clock can jump, while monotonic or hardware-related clocks have different semantics and availability.

Event buffers are finite. If userspace blocks or processes too slowly, events can be lost or sequence gaps can indicate overflow. Configure buffer size based on expected burst rate, keep the read loop responsive, and measure queue backlog. Do not interpret a missing event as proof that the electrical transition never occurred.

Edge detection may be limited by controller hardware, interrupt latency, debounce configuration, and line noise. Software polling at a slow cadence cannot recover edges that occurred between samples. For high-rate signals, use a subsystem designed for counting or capture, such as a counter, PWM, IIO, or a device-specific driver, instead of turning GPIO into a general-purpose high-speed analyzer.

The v2 event records expose both a per-line sequence number and a request-wide sequence number. Those counters help detect dropped or reordered observations at the userspace boundary, but they do not reconstruct an edge that the controller never captured. Treat a sequence gap as evidence of lost records and resynchronize from the current physical or protocol state. If an edge is a one-shot command, the device protocol should provide a level or acknowledgement that can be queried after reconnect rather than relying solely on a transient event.

Line configuration can be updated on an existing request with the v2 reconfiguration ioctl, subject to the API and controller’s supported flags. Reconfiguration is not a board-level transaction across unrelated chips. If several outputs must change without an intermediate state, use hardware designed to latch them together or a documented external protocol. Software issuing several independent ioctls cannot promise simultaneous electrical transitions.

Descriptor lifetime and hotplug

The line-request descriptor is the ownership token. When it closes, the kernel releases the request and may restore or alter the line state according to driver behavior. Decide explicitly what should happen on normal exit, crash, service restart, and suspend. A process death is not a safe electrical-state policy unless the controller and board default are known.

If a GPIO chip disappears or the controller resets, reads and writes can fail and the request may become unusable. Handle poll errors, hangup, and ioctl failures. Do not cache /dev/gpiochipN as permanent hardware identity when devices can enumerate in a different order. Match by stable device-tree path or another board-supported identity, then verify the line names and offsets after open.

For systemd-managed applications, make startup fail closed when the intended chip or line does not match. A service should not silently fall back to another chip with the same offset. Log the resolved device path, line identity, requested flags, and kernel error, while avoiding sensitive hardware inventory in broadly accessible logs.

Permissions are not a substitute for board ownership

Access to GPIO device nodes is mediated by normal device permissions and service policy. Grant the smallest access needed to a dedicated service account and ensure only one component owns each output. A udev rule can name a device or assign group access, but it does not establish the electrical safety of the line or coordinate two writers.

Kernel consumers should use the GPIO descriptor API rather than userspace character-device access when the function is a fixed part of a device driver or platform description. That allows the kernel to manage pin control, suspend, and dependencies coherently. Userspace is appropriate for board-specific control tools and applications whose ownership contract is documented.

Test with known-safe lines

Use a development board or an isolated input/output loopback with current-limited wiring. Begin with input observation, then test one output at a time with a known safe load. Confirm active-low behavior, startup value, event direction, timestamp source, event ordering, process exit, and controller suspend/resume. Do not connect a GPIO directly to a voltage outside the controller’s specification.

An acceptance record should include chip identity, line offset and name, board revision, electrical voltage domain, active polarity, requested flags, libgpiod version, kernel version, event rate, and observed errors. Test that a duplicate request fails safely and that process termination leaves the board in its documented safe state.

Also test both ABI discovery and behavioral recovery. Verify that the target kernel exposes the expected GPIO v2 request interface, then try the supported line configuration on a safe loopback. Generate a burst within the expected rate, deliberately pause the event reader in a lab, and verify that sequence gaps are reported rather than silently treated as complete history. Confirm the service can close and reacquire a request after a controlled restart without leaving the output at an unsafe level.

The useful abstraction is not “GPIO 17.” It is a line request tied to a specific controller, board signal, electrical mode, owner, and lifetime. The v2 character API makes those contracts explicit, but the schematic and the application still determine whether an operation is safe.

Related:

Sources: