Crate evdev

Linux event device handling.

The Linux kernel’s “evdev” subsystem exposes input devices to userspace in a generic, consistent way. I’ll try to explain the device model as completely as possible. The upstream kernel documentation is split across two files:

• https://www.kernel.org/doc/Documentation/input/event-codes.txt
• https://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt

Devices emit events, represented by the InputEvent type. Each device supports a few different kinds of events, specified by the EventType struct and the Device::supported_events() method. Most event types also have a “subtype”, e.g. a KEY event with a KEY_ENTER code. This type+subtype combo is represented by InputEventKind/InputEvent::kind(). The individual subtypes of a type that a device supports can be retrieved through the Device::supported_*() methods, e.g. Device::supported_keys():

use evdev::{Device, Key};
let device = Device::open("/dev/input/event0")?;
// check if the device has an ENTER key
if device.supported_keys().map_or(false, |keys| keys.contains(Key::KEY_ENTER)) {
    println!("are you prepared to ENTER the world of evdev?");
} else {
    println!(":(");
}

The evdev crate exposes functions to query the current state of a device from the kernel, as well as a function that can be called continuously to provide an iterator over update events as they arrive.

Synchronizing versus Raw modes

This library can be used in either Raw or Synchronizing modes, which correspond roughly to evdev’s LIBEVDEV_READ_FLAG_NORMAL and LIBEVDEV_READ_FLAG_SYNC modes, respectively. In both modes, calling fetch_events and driving the resulting iterator to completion will provide a stream of real-time events from the underlying kernel device state. As the state changes, the kernel will write events into a ring buffer. If the buffer becomes full, the kernel will drop events from the ring buffer and leave an event telling userspace that it did so. At this point, if the application were using the events it received to update its internal idea of what state the hardware device is in, it will be wrong: it is missing some events.

In synchronous mode, this library tries to ease that pain by removing the corrupted events and injecting fake events as if the device had updated normally. Note that this is best-effort; events can never be recovered once lost. This synchronization comes at a performance cost: each set of input events read from the kernel in turn updates an internal state buffer, and events must be internally held back until the end of each frame. If this latency is unacceptable or for any reason you want to see every event directly, a raw stream reader is also provided.

As an example of how synchronization behaves, if a switch is toggled twice there will be two switch events in the buffer. However, if the kernel needs to drop events, when the device goes to synchronize state with the kernel only one (or zero, if the switch is in the same state as it was before the sync) switch events will be visible in the stream.

This cache can also be queried. For example, the DeviceState::led_vals method will tell you which LEDs are currently lit on the device. As calling code consumes each iterator, this state will be updated, and it will be fully re-synchronized with the kernel if the stream drops any events.

It is recommended that you dedicate a thread to processing input events, or use epoll or an async runtime with the fd returned by <Device as AsRawFd>::as_raw_fd to process events when they are ready.

For demonstrations of how to use this library in blocking, nonblocking, and async (tokio) modes, please reference the “examples” directory.

Modules

raw_stream
uinput	Virtual device emulation for evdev via uinput.

Structs

AbsoluteAxisType	A type of absolute axis measurement, typically used for touch events and joysticks.
AttributeSet
AttributeSetRef	A collection of bits representing either device capability or state.
BusType
Device	A physical or virtual device supported by evdev.
DeviceState	A cached representation of device state at a certain time.
EnumerateDevices
EventType	Event types supported by the device.
FetchEventsSynced	An iterator over events of a Device, produced by Device::fetch_events.
InputEvent	A wrapped libc::input_event returned by the input device via the kernel.
InputId
Key	Scancodes for key presses.
LedType	LEDs specified by USB HID.
MiscType	Various miscellaneous event types.
PropType	Device properties.
RelativeAxisType	A type of relative axis measurement, typically produced by mice.
SoundType	A type associated with simple sounds, such as beeps or tones.
SwitchType	An event type corresponding to a physical or virtual switch.
Synchronization	A “synchronization” message type published by the kernel into the events stream.

Enums

InputEventKind

A convenience mapping from an event (type, code) to an enumeration.

Functions

enumerate

Crawls /dev/input for evdev devices.