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.
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
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.
libinput only supports evdev devices, all the device initialization is done
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
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.
Device-type specific event dispatch is initialized. All event handling is then in this
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.
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 input_event and proceed to
update the state. Note: the serialized nature of the kernel evdev protocol
requires that the device updates the state with each event but to delay
processing until the
SYN_REPORT event is received.
All device-specific configuration is handled through
libinput_device_config_FOO instances. These are set up during device init
and provide the function pointers for the
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
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