Debian Codegraph @

doc/user/absolute-coordinate-ranges.rst

raw
1 .. _absolute_coordinate_ranges:
2
3 ==============================================================================
4 Coordinate ranges for absolute axes
5 ==============================================================================
6
7 libinput requires that all touchpads provide a correct axis range and
8 resolution. These are used to enable or disable certain features or adapt
9 the interaction with the touchpad. For example, the software button area is
10 narrower on small touchpads to avoid reducing the interactive surface too
11 much. Likewise, palm detection works differently on small touchpads as palm
12 interference is less likely to happen.
13
14 Touchpads with incorrect axis ranges generate error messages
15 in the form:
16 <blockquote>
17 Axis 0x35 value 4000 is outside expected range [0, 3000]
18 </blockquote>
19
20 This error message indicates that the ABS_MT_POSITION_X axis (i.e. the x
21 axis) generated an event outside the expected range of 0-3000. In this case
22 the value was 4000.
23 This discrepancy between the coordinate range the kernels advertises vs.
24 what the touchpad sends can be the source of a number of perceived
25 bugs in libinput.
26
27 .. _absolute_coordinate_ranges_fix:
28
29 ------------------------------------------------------------------------------
30 Measuring and fixing touchpad ranges
31 ------------------------------------------------------------------------------
32
33 To fix the touchpad you need to:
34
35 #. measure the physical size of your touchpad in mm
36 #. run the ``libinput measure touchpad-size`` tool
37 #. verify the hwdb entry provided by this tool
38 #. test locally
39 #. send a patch to the `systemd project <https://github.com/systemd/systemd>`_.
40
41 Detailed explanations are below.
42
43 The ``libinput measure touchpad-size`` tool is an interactive tool. It must
44 be called with the physical dimensions of the touchpad in mm. In the example
45 below, we use 100mm wide and 55mm high. The tool will find the touchpad device
46 automatically.
47
48 ::
49
50 $> sudo libinput measure touchpad-size 100x55
51 Using "Touchpad SynPS/2 Synaptics TouchPad": /dev/input/event4
52
53 Kernel specified touchpad size: 99.7x75.9mm
54 User specified touchpad size: 100.0x55.0mm
55
56 Kernel axis range: x [1024..5112], y [2024..4832]
57 Detected axis range: x [ 0.. 0], y [ 0.. 0]
58
59 Move one finger along all edges of the touchpad
60 until the detected axis range stops changing.
61
62 ...
63
64 Move the finger around until the detected axis range matches the data sent
65 by the device. ``Ctrl+C`` terminates the tool and prints a
66 suggested hwdb entry. ::
67
68 ...
69 Kernel axis range: x [1024..5112], y [2024..4832]
70 ^C
71 Detected axis range: x [2072..4880], y [2159..4832]
72 Resolutions calculated based on user-specified size: x 28, y 49 units/mm
73
74 Suggested hwdb entry:
75 Note: the dmi modalias match is a guess based on your machine's modalias:
76 dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:pn20ARS25701:pvrThinkPadT440s:rvnLENOVO:rn20ARS25701:rvrSDK0E50512STD:cvnLENOVO:ct10:cvrNotAvailable:
77 Please verify that this is the most sensible match and adjust if necessary.
78 -8<--------------------------
79 # Laptop model description (e.g. Lenovo X1 Carbon 5th)
80 evdev:name:SynPS/2 Synaptics TouchPad:dmi:*svnLENOVO:*pvrThinkPadT440s*
81 EVDEV_ABS_00=2072:4880:28
82 EVDEV_ABS_01=2159:4832:49
83 EVDEV_ABS_35=2072:4880:28
84 EVDEV_ABS_36=2159:4832:49
85 -8<--------------------------
86 Instructions on what to do with this snippet are in /usr/lib/udev/hwdb.d/60-evdev.hwdb
87
88
89 If there are discrepancies between the coordinate range the kernels
90 advertises and what what the touchpad sends, the hwdb entry should be added to the
91 ``60-evdev.hwdb`` file provided by the `systemd project <https://github.com/systemd/systemd>`_.
92 An example commit can be found
93 `here <https://github.com/systemd/systemd/commit/26f667eac1c5e89b689aa0a1daef6a80f473e045>`_.
94
95 The ``libinput measure touchpad-size`` tool attempts to provide the correct
96 dmi match but it does require user verification.
97
98 In most cases the dmi match can and should be trimmed to the system vendor (``svn``)
99 and the product version (``pvr``) or product name (``pn``), with everything else
100 replaced by a wildcard (``*``). In the above case, the match string is:
101
102 ::
103
104 evdev:name:SynPS/2 Synaptics TouchPad:dmi:*svnLENOVO:*pvrThinkPadT440s*
105
106 As a general rule: for Lenovo devices use ``pvr`` and for all others use
107 ``pn``.
108
109 .. note:: hwdb match strings only allow for alphanumeric ascii characters. Use a
110 wildcard (* or ?, whichever appropriate) for special characters.
111
112 The actual axis overrides are in the form:
113
114 ::
115
116 # axis number=min:max:resolution
117 EVDEV_ABS_00=2072:4880:28
118
119 or, if the range is correct but the resolution is wrong
120
121 ::
122
123 # axis number=::resolution
124 EVDEV_ABS_00=::28
125
126
127 Note the leading single space. The axis numbers are in hex and can be found
128 in ``linux/input-event-codes.h``. For touchpads ``ABS_X``, ``ABS_Y``,
129 ``ABS_MT_POSITION_X`` and ``ABS_MT_POSITION_Y`` are required.
130
131 .. note:: The touchpad's ranges and/or resolution should only be fixed when
132 there is a significant discrepancy. A few units do not make a
133 difference and a resolution that is off by 2 or less usually does
134 not matter either.
135
136 Once a match and override rule has been found, follow the instructions at
137 the top of the
138 `60-evdev.hwdb <https://github.com/systemd/systemd/blob/main/hwdb.d/60-evdev.hwdb>`_
139 file to save it locally and trigger the udev hwdb reload. Rebooting is
140 always a good idea. If the match string is correct, the new properties will
141 show up in the
142 output of
143
144 ::
145
146 udevadm info /sys/class/input/event4
147
148
149 Adjust the command for the event node of your touchpad.
150 A udev builtin will apply the new axis ranges automatically.
151
152 When the axis override is confirmed to work, please submit it as a pull
153 request to the `systemd project <https://github.com/systemd/systemd>`_.