Debian Codegraph @

doc/user/architecture.rst

raw
1 .. _architecture:
2
3 ==============================================================================
4 libinput's internal architecture
5 ==============================================================================
6
7 This page provides an outline of libinput's internal architecture. The goal
8 here is to get the high-level picture across and point out the components
9 and their interplay to new developers.
10
11 The public facing API is in ``libinput.c``, this file is thus the entry point
12 for almost all API calls. General device handling is in ``evdev.c`` with the
13 device-type-specific implementations in ``evdev-<type>.c``. It is not
14 necessary to understand all of libinput to contribute a patch.
15
16 As of libinput 1.29 libinput has an internal plugin pipeline that modifies
17 the event stream before libinput proper sees it, see
18 :ref:`architecture-plugins`.
19
20 :ref:`architecture-contexts` is the only user-visible implementation detail,
21 everything else is purely internal implementation and may change when
22 required.
23
24 .. _architecture-contexts:
25
26 ------------------------------------------------------------------------------
27 The udev and path contexts
28 ------------------------------------------------------------------------------
29
30 The first building block is the "context" which can be one of
31 two types, "path" and "udev". See **libinput_path_create_context()** and
32 **libinput_udev_create_context()**. The path/udev specific bits are in
33 ``path-seat.c`` and ``udev-seat.c``. This includes the functions that add new
34 devices to a context.
35
36
37 .. graphviz::
38
39
40 digraph context
41 {
42 compound=true;
43 rankdir="LR";
44 node [
45 shape="box";
46 ]
47
48 libudev [label="libudev 'add' event"]
49 udev [label="**libinput_udev_create_context()**"];
50 udev_backend [label="udev-specific backend"];
51 context [label="libinput context"]
52 udev -> udev_backend;
53 libudev -> udev_backend;
54 udev_backend -> context;
55 }
56
57
58 The udev context provides automatic device hotplugging as udev's "add"
59 events are handled directly by libinput. The path context requires that the
60 caller adds devices.
61
62
63 .. graphviz::
64
65
66 digraph context
67 {
68 compound=true;
69 rankdir="LR";
70 node [
71 shape="box";
72 ]
73
74 path [label="**libinput_path_create_context()**"];
75 path_backend [label="path-specific backend"];
76 xdriver [label="**libinput_path_add_device()**"]
77 context [label="libinput context"]
78 path -> path_backend;
79 xdriver -> path_backend;
80 path_backend -> context;
81 }
82
83
84 As a general rule: all Wayland compositors use a udev context, the X.org
85 stack uses a path context.
86
87 Which context was initialized only matters for creating/destroying a context
88 and adding devices. The device handling itself is the same for both types of
89 context.
90
91 .. _architecture-device:
92
93 ------------------------------------------------------------------------------
94 Device initialization
95 ------------------------------------------------------------------------------
96
97 libinput only supports evdev devices, all the device initialization is done
98 in ``evdev.c``. Much of the libinput public API is also a thin wrapper around
99 the matching implementation in the evdev device.
100
101 There is a 1:1 mapping between libinput devices and ``/dev/input/eventX``
102 device nodes.
103
104
105
106 .. graphviz::
107
108
109 digraph context
110 {
111 compound=true;
112 rankdir="LR";
113 node [
114 shape="box";
115 ]
116
117 devnode [label="/dev/input/event0"]
118
119 libudev [label="libudev 'add' event"]
120 xdriver [label="**libinput_path_add_device()**"]
121 context [label="libinput context"]
122
123 evdev [label="evdev_device_create()"]
124
125 devnode -> xdriver;
126 devnode -> libudev;
127 xdriver -> context;
128 libudev -> context;
129
130 context->evdev;
131
132 }
133
134
135 Entry point for all devices is ``evdev_device_create()``, this function
136 decides to create a ``struct evdev_device`` for the given device node.
137 Based on the udev tags (e.g. ``ID_INPUT_TOUCHPAD``), a
138 :ref:`architecture-dispatch` is initialized. All event handling is then in this
139 dispatch.
140
141 Rejection of devices and the application of quirks is generally handled in
142 ``evdev.c`` as well. Common functionality shared across multiple device types
143 (like button-scrolling) is also handled here.
144
145 .. _architecture-dispatch:
146
147 ------------------------------------------------------------------------------
148 Device-type specific event dispatch
149 ------------------------------------------------------------------------------
150
151 Depending on the device type, ``evdev_configure_device`` creates the matching
152 ``struct evdev_dispatch``. This dispatch interface contains the function
153 pointers to handle events. Four such dispatch methods are currently
154 implemented: touchpad, tablet, tablet pad, and the fallback dispatch which
155 handles mice, keyboards and touchscreens.
156
157 .. graphviz::
158
159 digraph context
160 {
161 compound=true;
162 rankdir="LR";
163 node [
164 shape="box";
165 ]
166
167 evdev [label="evdev_device_create()"]
168
169 fallback [label="evdev-fallback.c"]
170 touchpad [label="evdev-mt-touchpad.c"]
171 tablet [label="evdev-tablet.c"]
172 pad [label="evdev-tablet-pad.c"]
173
174 evdev -> fallback;
175 evdev -> touchpad;
176 evdev -> tablet;
177 evdev -> pad;
178
179 }
180
181
182 Event dispatch is done per "evdev frame", a collection of events up until including
183 the ``SYN_REPORT``. One such ``struct evdev_frame`` represents all state **updates**
184 to the previous frame.
185
186 While ``evdev.c`` pulls the event out of libevdev, the actual handling of the
187 events is performed within the dispatch method.
188
189 .. graphviz::
190
191 digraph context
192 {
193 compound=true;
194 rankdir="LR";
195 node [
196 shape="box";
197 ]
198
199 evdev [label="evdev_device_dispatch()"]
200
201 plugins [label="plugin pipline"]
202
203 fallback [label="fallback_interface_process()"];
204 touchpad [label="tp_interface_process()"]
205 tablet [label="tablet_process()"]
206 pad [label="pad_process()"]
207
208 evdev -> plugins;
209 plugins -> fallback;
210 plugins -> touchpad;
211 plugins -> tablet;
212 plugins -> pad;
213 }
214
215
216 The dispatch methods then look at the ``struct evdev_frame`` and proceed to
217 update the state.
218
219 .. _architecture-plugins:
220
221 ------------------------------------------------------------------------------
222 The Plugin Pipeline
223 ------------------------------------------------------------------------------
224
225 As of libinput 1.29 libinput has an **internal** plugin pipeline. These plugins
226 logically sit between libevdev and the :ref:`architecture-dispatch` and modify
227 the device and/or event stream. The primary motivation of such plugins is that
228 modifying the event stream is often simpler than analyzing the state later.
229
230 Plugins are loaded on libinput context startup and are executed in-order. The last
231 plugin is the hardcoded `evdev-plugin.c` which takes the modified event stream and
232 passes the events to the dispatch.
233
234 .. graphviz::
235
236 digraph context
237 {
238 compound=true;
239 rankdir="LR";
240 node [
241 shape="box";
242 ]
243
244 evdev [label="evdev_device_dispatch()"]
245
246 p1 [label="P1"]
247 p2 [label="P2"]
248 p3 [label="P3"]
249 ep [label="evdev-plugin"]
250
251 fallback [label="fallback_interface_process()"];
252 touchpad [label="tp_interface_process()"]
253 tablet [label="tablet_process()"]
254 pad [label="pad_process()"]
255
256 evdev -> p1;
257 p1 -> p2;
258 p2 -> p3;
259 p3 -> ep;
260 ep -> fallback;
261 ep -> touchpad;
262 ep -> tablet;
263 ep -> pad;
264 }
265
266 Each plugin may not only modify the current event frame (this includes adding/removing events
267 from the frame), it may also append or prepend additional event frames. For
268 example the tablet proximity-timer plugin adds proximity in/out events to the
269 event stream.
270
271 .. graphviz::
272
273 digraph context
274 {
275 compound=true;
276 rankdir="LR";
277 node [
278 shape="box";
279 ]
280 n0 [label= "", shape=none,height=.0,width=.0]
281 n1 [label= "", shape=none,height=.0,width=.0]
282
283 p1 [label="P1"]
284 p2 [label="P2"]
285 p3 [label="P3"]
286 ep [label="evdev-plugin"]
287
288 n0 -> p1 [label="F1"];
289 p1 -> p2 [label="F1"];
290 p2 -> p3 [label="F1,F2"];
291 p3 -> ep [label="F3,F1,F2"];
292 ep -> n1 [label="F3,F1,F2"];
293 }
294
295 In the diagram above, the plugin ``P2`` *appends* a new frame (``F2``), the plugin ``P3``
296 *prepends* a new frame (``F3``). The original event frame ``F1`` thus becomes the event frame
297 sequence ``F3``, ``F1``, ``F2`` by the time it reaches the :ref:`architecture-dispatch`.
298
299 Note that each plugin only sees one event frame at a time, so ``P3`` would see ``F1`` first,
300 decides to prepend ``F3`` and passes ``F1`` through. It then sees ``F2`` but does nothing with
301 it (optionally modified in-place).
302
303 .. _architecture-configuration:
304
305 ------------------------------------------------------------------------------
306 Device configuration
307 ------------------------------------------------------------------------------
308
309 All device-specific configuration is handled through ``struct
310 libinput_device_config_FOO`` instances. These are set up during device init
311 and provide the function pointers for the ``get``, ``set``, ``get_default``
312 triplet of configuration queries (or more, where applicable).
313
314 For example, the ``struct tablet_dispatch`` for tablet devices has a
315 ``struct libinput_device_config_accel``. This struct is set up with the
316 required function pointers to change the profiles.
317
318
319 .. graphviz::
320
321
322 digraph context
323 {
324 compound=true;
325 rankdir="LR";
326 node [
327 shape="box";
328 ]
329
330 tablet [label="struct tablet_dispatch"]
331 config [label="struct libinput_device_config_accel"];
332 tablet_config [label="tablet_accel_config_set_profile()"];
333 tablet->config;
334 config->tablet_config;
335 }
336
337
338 When the matching ``**libinput_device_config_set_FOO()**`` is called, this goes
339 through to the config struct and invokes the function there. Thus, it is
340 possible to have different configuration functions for a mouse vs a
341 touchpad, even though the interface is the same.
342
343
344 .. graphviz::
345
346
347 digraph context
348 {
349 compound=true;
350 rankdir="LR";
351 node [
352 shape="box";
353 ]
354
355 libinput [label="**libinput_device_config_accel_set_profile()**"];
356 tablet_config [label="tablet_accel_config_set_profile()"];
357 libinput->tablet_config;
358 }
359
360
361 .. _architecture-filter:
362
363 ------------------------------------------------------------------------------
364 Pointer acceleration filters
365 ------------------------------------------------------------------------------
366
367 All pointer acceleration is handled in the ``filter.c`` file and its
368 associated files.
369
370 The ``struct motion_filter`` is initialized during device init, whenever
371 deltas are available they are passed to ``filter_dispatch()``. This function
372 returns a set of :ref:`normalized coordinates <motion_normalization_customization>`.
373
374 All actual acceleration is handled within the filter, the device itself has
375 no further knowledge. Thus it is possible to have different acceleration
376 filters for the same device types (e.g. the Lenovo X230 touchpad has a
377 custom filter).
378
379
380 .. graphviz::
381
382
383 digraph context
384 {
385 compound=true;
386 rankdir="LR";
387 node [
388 shape="box";
389 ]
390
391 fallback [label="fallback deltas"];
392 touchpad [label="touchpad deltas"];
393 tablet [label="tablet deltas"];
394
395 filter [label="filter_dispatch"];
396
397 fallback->filter;
398 touchpad->filter;
399 tablet->filter;
400
401 flat [label="accelerator_interface_flat()"];
402 x230 [label="accelerator_filter_x230()"];
403 pen [label="tablet_accelerator_filter_flat_pen()"];
404
405 filter->flat;
406 filter->x230;
407 filter->pen;
408
409 }
410
411
412 Most filters convert the deltas (incl. timestamps) to a motion speed and
413 then apply a so-called profile function. This function returns a factor that
414 is then applied to the current delta, converting it into an accelerated
415 delta. See :ref:`pointer-acceleration` for more details.
416 the current