libinput’s internal architecture

This page provides an outline of libinput’s internal architecture. The goal here is to get the high-level picture across and point out the components and their interplay to new developers.

The public facing API is in libinput.c, this file is thus the entry point for almost all API calls. General device handling is in evdev.c with the device-type-specific implementations in evdev-<type>.c. It is not necessary to understand all of libinput to contribute a patch.

As of libinput 1.29 libinput has an internal plugin pipeline that modifies the event stream before libinput proper sees it, see The Plugin Pipeline.

The udev and path contexts is the only user-visible implementation detail, everything else is purely internal implementation and may change when required.

The udev and path contexts

The first building block is the “context” which can be one of two types, “path” and “udev”. See libinput_path_create_context() and libinput_udev_create_context(). The path/udev specific bits are in path-seat.c and udev-seat.c. This includes the functions that add new devices to a context.

The udev context provides automatic device hotplugging as udev’s “add” events are handled directly by libinput. The path context requires that the caller adds devices.

As a general rule: all Wayland compositors use a udev context, the X.org stack uses a path context.

Which context was initialized only matters for creating/destroying a context and adding devices. The device handling itself is the same for both types of context.

Device initialization

libinput only supports evdev devices, all the device initialization is done in evdev.c. Much of the libinput public API is also a thin wrapper around the matching implementation in the evdev device.

There is a 1:1 mapping between libinput devices and /dev/input/eventX device nodes.

Entry point for all devices is evdev_device_create(), this function decides to create a struct evdev_device for the given device node. Based on the udev tags (e.g. ID_INPUT_TOUCHPAD), a Device-type specific event dispatch is initialized. All event handling is then in this dispatch.

Rejection of devices and the application of quirks is generally handled in evdev.c as well. Common functionality shared across multiple device types (like button-scrolling) is also handled here.

Device-type specific event dispatch

Depending on the device type, evdev_configure_device creates the matching struct evdev_dispatch. This dispatch interface contains the function pointers to handle events. Four such dispatch methods are currently implemented: touchpad, tablet, tablet pad, and the fallback dispatch which handles mice, keyboards and touchscreens.

Event dispatch is done per “evdev frame”, a collection of events up until including the SYN_REPORT. One such struct evdev_frame represents all state updates to the previous frame.

While evdev.c pulls the event out of libevdev, the actual handling of the events is performed within the dispatch method.

The dispatch methods then look at the struct evdev_frame and proceed to update the state.

The Plugin Pipeline

As of libinput 1.29 libinput has an internal plugin pipeline. These plugins logically sit between libevdev and the Device-type specific event dispatch and modify the device and/or event stream. The primary motivation of such plugins is that modifying the event stream is often simpler than analyzing the state later.

Plugins are loaded on libinput context startup and are executed in-order. The last plugin is the hardcoded evdev-plugin.c which takes the modified event stream and passes the events to the dispatch.

Each plugin may not only modify the current event frame (this includes adding/removing events from the frame), it may also append or prepend additional event frames. For example the tablet proximity-timer plugin adds proximity in/out events to the event stream.

In the diagram above, the plugin P2 appends a new frame (F2), the plugin P3 prepends a new frame (F3). The original event frame F1 thus becomes the event frame sequence F3, F1, F2 by the time it reaches the Device-type specific event dispatch.

Note that each plugin only sees one event frame at a time, so P3 would see F1 first, decides to prepend F3 and passes F1 through. It then sees F2 but does nothing with it (optionally modified in-place).

Device configuration

All device-specific configuration is handled through struct libinput_device_config_FOO instances. These are set up during device init and provide the function pointers for the get, set, get_default triplet of configuration queries (or more, where applicable).

For example, the struct tablet_dispatch for tablet devices has a struct libinput_device_config_accel. This struct is set up with the required function pointers to change the profiles.

When the matching **libinput_device_config_set_FOO()** is called, this goes through to the config struct and invokes the function there. Thus, it is possible to have different configuration functions for a mouse vs a touchpad, even though the interface is the same.

Pointer acceleration filters

All pointer acceleration is handled in the filter.c file and its associated files.

The struct motion_filter is initialized during device init, whenever deltas are available they are passed to filter_dispatch(). This function returns a set of normalized coordinates.

All actual acceleration is handled within the filter, the device itself has no further knowledge. Thus it is possible to have different acceleration filters for the same device types (e.g. the Lenovo X230 touchpad has a custom filter).

Most filters convert the deltas (incl. timestamps) to a motion speed and then apply a so-called profile function. This function returns a factor that is then applied to the current delta, converting it into an accelerated delta. See Pointer acceleration for more details. the current