architecture.html 10.5 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
<!-- HTML header for doxygen 1.8.8-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
<html xmlns="">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <!-- For Mobile Devices -->
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
        <meta name="generator" content="Doxygen 1.8.13"/>
        <script type="text/javascript" src=""></script>
        <title>libinput: libinput&#39;s internal architecture</title>
        <!--<link href="tabs.css" rel="stylesheet" type="text/css"/>-->
        <script type="text/javascript" src="dynsections.js"></script>
        <script type="text/x-mathjax-config">
    extensions: ["tex2jax.js"],
    jax: ["input/TeX","output/HTML-CSS"],
</script><script type="text/javascript" src=""></script>
        <link href="doxygen.css" rel="stylesheet" type="text/css" />
        <link href="bootstrap.css" rel="stylesheet" type="text/css"/>
<link href="customdoxygen.css" rel="stylesheet" type="text/css"/>
<link href="libinputdoxygen.css" rel="stylesheet" type="text/css"/>
        <script src=""></script>
        <script type="text/javascript" src="doxy-boot.js"></script>
        <nav class="navbar navbar-default" role="navigation">
            <div class="container">
                <div class="navbar-header">
                    <a class="navbar-brand">libinput 1.10.900</a>
        <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
            <div class="content" id="content">
                <div class="container">
                    <div class="row">
                        <div class="col-sm-12 panel panel-default" style="padding-bottom: 15px;">
                            <div style="margin-bottom: 15px;">
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
<div id="main-nav"></div>
<div id="nav-path" class="navpath">
<li class="navelem"><a class="el" href="developers.html">Developers</a></li>  </ul>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">libinput's internal architecture </div>  </div>
<div class="contents">
<div class="textblock"><p>This page provides an outline of libinput's internal architecture.</p>
<p>The goal here is to get the high-level picture across and point out the components and their interplay to new developers.</p>
<p>The public facing API is in <code>libinput.c</code>, this file is thus the entry point for almost all API calls. General device handling is in <code>evdev.c</code> with the device-type-specific implementations in <code>evdev-&lt;type&gt;.c</code>. It is not necessary to understand all of libinput to contribute a patch.</p>
<p><a class="el" href="architecture.html#architecture-contexts">The udev and path contexts</a> is the only user-visible implementation detail, everything else is purely internal implementation and may change when required.</p>
<h1><a class="anchor" id="architecture-contexts"></a>
The udev and path contexts</h1>
<p>The first building block is the "context" which can be one of two types, "path" and "udev". See <a class="el" href="group__base.html#ga363c6b6e47dcf410a3b3ebd5547c8b07" title="Create a new libinput context that requires the caller to manually add or remove devices with libinpu...">libinput_path_create_context()</a> and <a class="el" href="group__base.html#ga7512ea602d4b259085c47f6374b078d1" title="Create a new libinput context from udev. ">libinput_udev_create_context()</a>. The path/udev specific bits are in <code>path-seat.c</code> and <code>udev-seat.c</code>. This includes the functions that add new devices to a context.</p>
<div class="dotgraph">
<img src="dot_inline_dotgraph_1.png" alt="dot_inline_dotgraph_1.png" border="0" usemap=""/>
<map name="" id=""></map>
<p>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.</p>
<div class="dotgraph">
<img src="dot_inline_dotgraph_2.png" alt="dot_inline_dotgraph_2.png" border="0" usemap=""/>
<map name="" id=""></map>
<p>As a general rule: all Wayland compositors use a udev context, the stack uses a path context.</p>
<p>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.</p>
<h1><a class="anchor" id="architecture-device"></a>
Device initialization</h1>
<p>libinput only supports evdev devices, all the device initialization is done in <code>evdev.c</code>. Much of the libinput public API is also a thin wrapper around the matching implementation in the evdev device.</p>
<p>There is a 1:1 mapping between libinput devices and <code>/dev/input/eventX</code> device nodes.</p>
<div class="dotgraph">
<img src="dot_inline_dotgraph_3.png" alt="dot_inline_dotgraph_3.png" border="0" usemap=""/>
<map name="" id=""></map>
<p>Entry point for all devices is <code>evdev_device_create()</code>, this function decides to create a <code>struct evdev_device</code> for the given device node. Based on the udev tags (e.g. <code>ID_INPUT_TOUCHPAD</code>), a <a class="el" href="architecture.html#architecture-dispatch">Device-type specific event dispatch</a> is initialized. All event handling is then in this dispatch.</p>
<p>Rejection of devices and the application of quirks is generally handled in <code>evdev.c</code> as well. Common functionality shared across multiple device types (like button-scrolling) is also handled here.</p>
<h1><a class="anchor" id="architecture-dispatch"></a>
Device-type specific event dispatch</h1>
<p>Depending on the device type, <code>evdev_configure_device</code> creates the matching <code>struct evdev_dispatch</code>. 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.</p>
<div class="dotgraph">
<img src="dot_inline_dotgraph_4.png" alt="dot_inline_dotgraph_4.png" border="0" usemap=""/>
<map name="" id=""></map>
<p>While <code>evdev.c</code> pulls the event out of libevdev, the actual handling of the events is performed within the dispatch method.</p>
<div class="dotgraph">
<img src="dot_inline_dotgraph_5.png" alt="dot_inline_dotgraph_5.png" border="0" usemap=""/>
<map name="" id=""></map>
<p>The dispatch methods then look at the <code>struct input_event</code> 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 <code>SYN_REPORT</code> event is received.</p>
<h1><a class="anchor" id="architecture-configuration"></a>
Device configuration</h1>
<p>All device-specific configuration is handled through <code>struct libinput_device_config_FOO</code> instances. These are set up during device init and provide the function pointers for the <code>get</code>, <code>set</code>, <code>get_default</code> triplet of configuration queries (or more, where applicable).</p>
<p>For example, the <code>struct tablet_dispatch</code> for tablet devices has a <code>struct libinput_device_config_accel</code>. This struct is set up with the required function pointers to change the profiles.</p>
<div class="dotgraph">
<img src="dot_inline_dotgraph_6.png" alt="dot_inline_dotgraph_6.png" border="0" usemap=""/>
<map name="" id=""></map>
<p>When the matching <code>libinput_device_config_set_FOO()</code> 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.</p>
<div class="dotgraph">
<img src="dot_inline_dotgraph_7.png" alt="dot_inline_dotgraph_7.png" border="0" usemap=""/>
<map name="" id=""></map>
<h1><a class="anchor" id="architecture-filter"></a>
Pointer acceleration filters</h1>
<p>All pointer acceleration is handled in the <code>filter.c</code> file and its associated files.</p>
<p>The <code>struct motion_filter</code> is initialized during device init, whenever deltas are available they are passed to <code>filter_dispatch()</code>. This function returns a set of <a class="el" href="motion_normalization.html#motion_normalization_customization">normalized coordinates</a>.</p>
<p>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).</p>
<div class="dotgraph">
<img src="dot_inline_dotgraph_8.png" alt="dot_inline_dotgraph_8.png" border="0" usemap=""/>
<map name="" id=""></map>
<p>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 <a class="el" href="pointer-acceleration.html">Pointer acceleration</a> for more details. the current </p>
</div></div><!-- contents -->
<!-- HTML footer for doxygen 1.8.8-->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13