| 1 |
.. _reporting_bugs: |
| 2 |
|
| 3 |
============================================================================== |
| 4 |
Reporting bugs |
| 5 |
============================================================================== |
| 6 |
|
| 7 |
A new bug can be filed here: |
| 8 |
https://gitlab.freedesktop.org/libinput/libinput/issues/new |
| 9 |
|
| 10 |
.. hint:: libinput has lots of users but very few developers. It is in your |
| 11 |
own interest to follow the steps here precisely to ensure your bug can be |
| 12 |
dealt with efficiently. |
| 13 |
|
| 14 |
When reporting bugs against libinput, you will need: |
| 15 |
|
| 16 |
- a reliable :ref:`reproducer <reporting_bugs_reproducer>` for the bug |
| 17 |
- a :ref:`recording <libinput-record>` of the device while the bug is reproduced |
| 18 |
- device-specific information, see |
| 19 |
|
| 20 |
- :ref:`reporting_bugs_touchpad` |
| 21 |
- :ref:`reporting_bugs_mouse` |
| 22 |
- :ref:`reporting_bugs_keyboard` |
| 23 |
- :ref:`reporting_bugs_trackpoint` |
| 24 |
- :ref:`reporting_bugs_other` |
| 25 |
|
| 26 |
- the :ref:`libinput version <reporting_bugs_version>` you are on. |
| 27 |
- the :ref:`configuration options <reporting_bugs_options>` you have set |
| 28 |
- a `gitlab account <https://gitlab.freedesktop.org/users/sign_in>`_ |
| 29 |
|
| 30 |
Stay technical, on-topic, and keep the description concise. |
| 31 |
|
| 32 |
.. _reporting_bugs_version: |
| 33 |
|
| 34 |
------------------------------------------------------------------------------ |
| 35 |
Obtaining the libinput version |
| 36 |
------------------------------------------------------------------------------ |
| 37 |
|
| 38 |
If your libinput version is older than the current stable branch, please try |
| 39 |
the latest version. If you run a distribution-provided |
| 40 |
libinput, use the package manager to get the **full** package name and |
| 41 |
version of libinput, e.g. |
| 42 |
|
| 43 |
- ``rpm -q libinput`` |
| 44 |
- ``dpkg -s libinput10`` |
| 45 |
|
| 46 |
If you run a self-compiled version of libinput provide the git commit you |
| 47 |
have built or the tarball name. |
| 48 |
|
| 49 |
As a last resort, use ``libinput --version`` |
| 50 |
|
| 51 |
.. _reporting_bugs_reproducer: |
| 52 |
|
| 53 |
------------------------------------------------------------------------------ |
| 54 |
Reproducing bugs |
| 55 |
------------------------------------------------------------------------------ |
| 56 |
|
| 57 |
Try to identify the bug by reproducing it reliably. Bugs without a |
| 58 |
reliable reproducer will have lowest priority. The more specific a bug |
| 59 |
description and reproducer is, the easier it is to fix. |
| 60 |
|
| 61 |
Try to replicate the series of events that lead to the bug being triggered. |
| 62 |
Narrow it down until you have a reliable sequence that can trigger the bug. |
| 63 |
For the vast majority of bugs you should not take longer than 5 seconds or |
| 64 |
three interactions (clicks, touches, taps, ...) with the device to |
| 65 |
reproduce. If it takes longer than that, you can narrow it down further. |
| 66 |
|
| 67 |
Once you can reproduce it, use the :ref:`libinput-debug-events` helper |
| 68 |
tool:: |
| 69 |
|
| 70 |
$> libinput debug-events --verbose |
| 71 |
|
| 72 |
The output is textual and can help identify whether the bug is in libinput |
| 73 |
at all. Note that any configuration options you have set must be specified |
| 74 |
on the commandline, see the :ref:`libinput-debug-events` |
| 75 |
man page. Use the ``--verbose`` flag to get more information about how |
| 76 |
libinput processes events. |
| 77 |
|
| 78 |
If the bug cannot be reproduced with the :ref:`libinput-debug-events` helper, |
| 79 |
even with the correct configuration options set, it is likely not a bug in |
| 80 |
libinput. |
| 81 |
|
| 82 |
.. _reporting_bugs_options: |
| 83 |
|
| 84 |
------------------------------------------------------------------------------ |
| 85 |
libinput configuration settings |
| 86 |
------------------------------------------------------------------------------ |
| 87 |
|
| 88 |
libinput has a number of device-specific default configuration settings that |
| 89 |
may differ from the ones your desktop environment picks by default. You may |
| 90 |
have changed some options in a settings panel or in an the xorg.conf snippet |
| 91 |
yourself. |
| 92 |
|
| 93 |
You must provide these options in the bug report, otherwise a developer |
| 94 |
reproducing the issue may not be able to do so. |
| 95 |
|
| 96 |
If you are on X11, the current settings can be can be obtained with |
| 97 |
``xinput list-props "your device name"``. Use ``xinput list`` to |
| 98 |
obtain the device name. |
| 99 |
|
| 100 |
If you are on Wayland, provide a manual summary of the options you have |
| 101 |
changed from the default (e.g. "I enabled tap-to-click"). |
| 102 |
|
| 103 |
.. _reporting_bugs_touchpad: |
| 104 |
|
| 105 |
------------------------------------------------------------------------------ |
| 106 |
Reporting touchpad bugs |
| 107 |
------------------------------------------------------------------------------ |
| 108 |
|
| 109 |
When you file a bug, please attach the following information: |
| 110 |
|
| 111 |
- a virtual description of your input device, see :ref:`libinput-record`. |
| 112 |
This is the most important piece of information, do not forget it! |
| 113 |
- the output from udevadm info, see :ref:`udev_info`. |
| 114 |
- the vendor model number of your laptop (e.g. "Lenovo Thinkpad T440s") |
| 115 |
- and the content of ``/sys/class/dmi/id/modalias``. |
| 116 |
- run ``libinput measure touchpad-size`` tool (see :ref:`absolute_coordinate_ranges_fix`) |
| 117 |
and verify that the ranges and sizes it prints match the touchpad (up to 5mm |
| 118 |
difference is ok) |
| 119 |
|
| 120 |
If you are reporting a bug related to button event generation: |
| 121 |
|
| 122 |
- does your touchpad have (separate) physical hardware buttons or is the |
| 123 |
whole touchpad clickable? |
| 124 |
- Are you using software buttons or clickfinger? See :ref:`clickpad_softbuttons`. |
| 125 |
- Do you have :ref:`tapping` enabled? |
| 126 |
|
| 127 |
.. _reporting_bugs_mouse: |
| 128 |
|
| 129 |
------------------------------------------------------------------------------ |
| 130 |
Reporting mouse bugs |
| 131 |
------------------------------------------------------------------------------ |
| 132 |
|
| 133 |
When you file a bug, please attach the following information: |
| 134 |
|
| 135 |
- a virtual description of your input device, see :ref:`libinput-record`. |
| 136 |
This is the most important piece of information, do not forget it! |
| 137 |
- the vendor model number of the device (e.g. "Logitech M325") |
| 138 |
- the output from udevadm info, see :ref:`udev_info`. |
| 139 |
|
| 140 |
If the bug is related to the :ref:`speed of the mouse <motion_normalization_customization>`: |
| 141 |
|
| 142 |
- the resolution of the mouse as specified by the vendor (in DPI) |
| 143 |
- the output of the ``mouse-dpi-tool`` (provided by libevdev) |
| 144 |
|
| 145 |
.. _reporting_bugs_keyboard: |
| 146 |
|
| 147 |
------------------------------------------------------------------------------ |
| 148 |
Reporting keyboard bugs |
| 149 |
------------------------------------------------------------------------------ |
| 150 |
|
| 151 |
Is your bug related to a keyboard layout? libinput does not handle keyboard |
| 152 |
layouts and merely forwards the physical key events. File the bug with your |
| 153 |
desktop environment instead (e.g. GNOME, KDE, ...), that's most likely where |
| 154 |
the issue is. |
| 155 |
|
| 156 |
When you file a bug, please attach the following information: |
| 157 |
|
| 158 |
- a virtual description of your input device, see :ref:`libinput-record`. |
| 159 |
This is the most important piece of information, do not forget it! |
| 160 |
|
| 161 |
.. _reporting_bugs_trackpoint: |
| 162 |
|
| 163 |
------------------------------------------------------------------------------ |
| 164 |
Reporting trackpoint bugs |
| 165 |
------------------------------------------------------------------------------ |
| 166 |
|
| 167 |
When you file a bug, please attach the following information: |
| 168 |
|
| 169 |
- a virtual description of your input device, see :ref:`libinput-record`. |
| 170 |
This is the most important piece of information, do not forget it! |
| 171 |
- the vendor model number of the device (e.g. "Logitech M325") |
| 172 |
- the output from udevadm info, see :ref:`udev_info`. |
| 173 |
- the sensitivity of the trackpoint if it exists (adjust the event node number as needed): :: |
| 174 |
|
| 175 |
$ cat /sys/class/input/event17/device/device/sensitivity |
| 176 |
|
| 177 |
|
| 178 |
.. _reporting_bugs_other: |
| 179 |
|
| 180 |
------------------------------------------------------------------------------ |
| 181 |
All other devices |
| 182 |
------------------------------------------------------------------------------ |
| 183 |
|
| 184 |
When you file a bug, please attach the following information: |
| 185 |
|
| 186 |
- a virtual description of your input device, see :ref:`libinput-record`. |
| 187 |
This is the most important piece of information, do not forget it! |
| 188 |
- the vendor model number of the device (e.g. "Sony Plastation3 controller") |
| 189 |
|
| 190 |
.. _udev_info: |
| 191 |
|
| 192 |
------------------------------------------------------------------------------ |
| 193 |
udev information for the device |
| 194 |
------------------------------------------------------------------------------ |
| 195 |
|
| 196 |
In many cases, we require the udev properties assigned to the device to |
| 197 |
verify whether device-specific quirks were applied. This can be obtained |
| 198 |
with ``udevadm info /sys/class/input/eventX``, with the correct event |
| 199 |
node for your device. An example output is below: :: |
| 200 |
|
| 201 |
$ udevadm info /sys/class/input/event4 |
| 202 |
P: /devices/platform/i8042/serio1/input/input5/event4 |
| 203 |
N: input/event4 |
| 204 |
E: DEVNAME=/dev/input/event4 |
| 205 |
E: DEVPATH=/devices/platform/i8042/serio1/input/input5/event4 |
| 206 |
E: EVDEV_ABS_00=::41 |
| 207 |
E: EVDEV_ABS_01=::37 |
| 208 |
E: EVDEV_ABS_35=::41 |
| 209 |
E: EVDEV_ABS_36=::37 |
| 210 |
E: ID_INPUT=1 |
| 211 |
E: ID_INPUT_HEIGHT_MM=66 |
| 212 |
E: ID_INPUT_TOUCHPAD=1 |
| 213 |
E: ID_INPUT_WIDTH_MM=97 |
| 214 |
E: MAJOR=13 |
| 215 |
E: MINOR=68 |
| 216 |
E: SUBSYSTEM=input |
| 217 |
E: USEC_INITIALIZED=5463031 |
| 218 |
|
| 219 |
|
| 220 |
.. _evemu: |
| 221 |
|
| 222 |
------------------------------------------------------------------------------ |
| 223 |
Recording devices with evemu |
| 224 |
------------------------------------------------------------------------------ |
| 225 |
|
| 226 |
.. warning:: Where available, the :ref:`libinput-record` tools should be used instead |
| 227 |
of evemu |
| 228 |
|
| 229 |
`evemu-record <https://www.freedesktop.org/wiki/Evemu/>`_ records the |
| 230 |
device capabilities together with the event stream from the kernel. On our |
| 231 |
side, this allows us to recreate a virtual device identical to your device |
| 232 |
and re-play the event sequence, hopefully triggering the same bug. |
| 233 |
|
| 234 |
evemu-record takes a ``/dev/input/eventX`` event node, but without arguments |
| 235 |
it will simply show the list of devices and let you select: :: |
| 236 |
|
| 237 |
$ sudo evemu-record > scroll.evemu |
| 238 |
Available devices: |
| 239 |
/dev/input/event0: Lid Switch |
| 240 |
/dev/input/event1: Sleep Button |
| 241 |
/dev/input/event2: Power Button |
| 242 |
/dev/input/event3: AT Translated Set 2 keyboard |
| 243 |
/dev/input/event4: SynPS/2 Synaptics TouchPad |
| 244 |
/dev/input/event5: Video Bus |
| 245 |
/dev/input/event6: ELAN Touchscreen |
| 246 |
/dev/input/event10: ThinkPad Extra Buttons |
| 247 |
/dev/input/event11: HDA Intel HDMI HDMI/DP,pcm=3 |
| 248 |
/dev/input/event12: HDA Intel HDMI HDMI/DP,pcm=7 |
| 249 |
/dev/input/event13: HDA Intel HDMI HDMI/DP,pcm=8 |
| 250 |
/dev/input/event14: HDA Intel PCH Dock Mic |
| 251 |
/dev/input/event15: HDA Intel PCH Mic |
| 252 |
/dev/input/event16: HDA Intel PCH Dock Headphone |
| 253 |
/dev/input/event17: HDA Intel PCH Headphone |
| 254 |
/dev/input/event18: Integrated Camera |
| 255 |
/dev/input/event19: TPPS/2 IBM TrackPoint |
| 256 |
Select the device event number [0-19]: |
| 257 |
|
| 258 |
|
| 259 |
Select the device that triggers the issue, then reproduce the bug and Ctrl+C |
| 260 |
the process. The resulting recording, ("scroll.evemu" in this example) will |
| 261 |
contain the sequence required to reproduce the bug. If the bug fails to |
| 262 |
reproduce during recording, simply Ctrl+C and restart evemu-record. |
| 263 |
Always start the recording from a neutral state, i.e. without any buttons or |
| 264 |
keys down, with the position of the device in the neutral position, without |
| 265 |
touching the screen/touchpad. |
| 266 |
|
| 267 |
.. note:: The longer the recording, the harder it is to identify the event |
| 268 |
sequence triggering the bug. Please keep the event sequence as short |
| 269 |
as possible. |
| 270 |
|
| 271 |
To verify that the recording contains the bug, you can replay it on your |
| 272 |
device. For example, to replay the sequence recorded in the example above: :: |
| 273 |
|
| 274 |
$ sudo evemu-play /dev/input/event4 < scroll.evemu |
| 275 |
|
| 276 |
|
| 277 |
If the bug is triggered by replaying on your device, attach the recording to |
| 278 |
the bug report. |
| 279 |
|
| 280 |
libinput does not affect the evemu recording. libinput and evemu talk |
| 281 |
directly to the kernel's device nodes. An evemu recording is not |
| 282 |
influenced by the libinput version or whether a libinput context is |
| 283 |
currently active. |
| 284 |
|
| 285 |
.. graphviz:: evemu.gv |
| 286 |
|
| 287 |
.. _fixed_bugs: |
| 288 |
|
| 289 |
------------------------------------------------------------------------------ |
| 290 |
My bug was closed as fixed, what now? |
| 291 |
------------------------------------------------------------------------------ |
| 292 |
|
| 293 |
libinput's policy on closing bugs is: once the fix for a given bug is on git |
| 294 |
master, the bug is considered fixed and the gitlab issue will be closed |
| 295 |
accordingly. |
| 296 |
|
| 297 |
Of course, unless you actually run git master, the bug will continue to |
| 298 |
affect you on your local machine. You are most likely running the |
| 299 |
distribution's package and you will need to wait until the distribution has |
| 300 |
updated its package accordingly. |
| 301 |
|
| 302 |
.. warning:: Do not re-open a bug just because it hasn't trickled down to |
| 303 |
your distribution's package version yet. |
| 304 |
|
| 305 |
Whether the bug fix ends up in your distribution depends on a number of |
| 306 |
things. Any given bug fix **may** be cherry-picked into the current stable |
| 307 |
branch, depending on its severity, impact, and likelihood to cause |
| 308 |
regressions. Once cherry-picked it will land in the next stable branch |
| 309 |
release. These are usually a few weeks apart. |
| 310 |
|
| 311 |
.. warning:: Do not re-open a bug because it wasn't picked into a stable branch |
| 312 |
release or because your distribution didn't update to the latest stable |
| 313 |
branch release. |
| 314 |
|
| 315 |
Stable branches are usually discontinued when the next release comes out. |
| 316 |
|
| 317 |
Your distribution may pick a patch up immediately and ship the fix |
| 318 |
even before the next stable branch update is released. For example, Fedora |
| 319 |
does this frequently. |
| 320 |
|
| 321 |
.. hint:: If a bug needs to be fixed urgently, file a bug in your |
| 322 |
distribution's bug tracker. |
| 323 |
|
| 324 |
Patches on git master will end up in the next libinput release. Once your |
| 325 |
distribution updates to that release, your local libinput version will |
| 326 |
contain the fix. |
| 327 |
|
| 328 |
.. warning:: Do not re-open a bug because your distribution didn't update to |
| 329 |
the release. |
| 330 |
|
| 331 |
You can always run libinput from git master (see :ref:`building_libinput`). |
| 332 |
Even while in development, libinput is very stable so this option isn't as |
| 333 |
scary as it may sounds. |
| 334 |
|
| 335 |
.. _reporting_bugs_reopen: |
| 336 |
|
| 337 |
.............................................................................. |
| 338 |
When is it ok to re-open a fixed bug? |
| 339 |
.............................................................................. |
| 340 |
|
| 341 |
Any time the bug was considered fixed but it turns out that the fix is |
| 342 |
insufficient and/or causes a regression. |
| 343 |
|
| 344 |
However, if the regression is in behavior unrelated to the fix itself it is |
| 345 |
usually better to file a new bug to reduce the noise. For example, if a fix |
| 346 |
to improve tapping breaks two-finger scrolling behavior, you should file a |
| 347 |
new bug but reference the original bug. |
| 348 |
|
| 349 |
.. _reporting_bugs_tags: |
| 350 |
|
| 351 |
------------------------------------------------------------------------------ |
| 352 |
Gitlab issue tracker tags |
| 353 |
------------------------------------------------------------------------------ |
| 354 |
|
| 355 |
The gitlab issue tracker allows developers to add tags to bugs to classify |
| 356 |
them. |
| 357 |
|
| 358 |
- **being worked on**: someone is currently working on this feature. This |
| 359 |
tag is used for features that will take a long time to implement fully and |
| 360 |
prevents others from having to duplicate the work. Do reach out and ask if |
| 361 |
help and/or further testing is needed. |
| 362 |
- **bug**: issue is confirmed to be a bug |
| 363 |
- **cantfix**: for technical reasons, this bug cannot be fixed, or at least |
| 364 |
it cannot be fixed in libinput. |
| 365 |
- **enhancement**: this issue describes a future feature, not a bug. |
| 366 |
- **help needed**: this issue requires someone outside the libinput core |
| 367 |
developer team to implement it. It is unlikely to be implemented |
| 368 |
without someone stepping up to do the work. If you do see this tag, do ask |
| 369 |
for guidance on how to implement it. |
| 370 |
- **hw issue**: an issue that affects a specific device and is a hardware |
| 371 |
bug, not a software bug. Often these needs to be worked around in libinput |
| 372 |
but there are cases where a hw issue ends up as *cantfix*. |
| 373 |
- **janitor**: a cleanup task that does not substantially affect how |
| 374 |
libinput works. These are usually good bugs for newcomers to start on. |
| 375 |
- **kernel**: this issue is a kernel bug, not a libinput bug. Often closed |
| 376 |
as *cantfix* of *wontfix* as we wait for the kernel to address the issue |
| 377 |
instead. |
| 378 |
- **needs triage**: bug has not yet been confirmed by a core developer. |
| 379 |
- **not our bug**: the issue is in some other component of the stack and |
| 380 |
needs to be addressed there. |
| 381 |
- **please test**: a fix is available but not yet merged and should be |
| 382 |
tested by the reporter or others affected by the issue. |
| 383 |
- **quirk**: this is issue needs :ref:`device-quirks` to be fixed |
| 384 |
- **regression**: the issue is a regression to previous versions of |
| 385 |
libinput. These issues get priorities. |
| 386 |
- **waiting on reporter**: some more information is required from the |
| 387 |
reporter and the issue cannot be fixed until the issue has been provided. |
| 388 |
Where a bug is left in this state for too long, the bug will be closed as |
| 389 |
*cantfix*. |
| 390 |
- **wontfix**: this issue will not get fixed. This tag is usually assigned |
| 391 |
to feature requests that are outside the scope of libinput or would put an |
| 392 |
unreasonable maintenance burdern on the maintainers. |
| 393 |
|
| 394 |
These tags are high-level categories only, always look for the comments in |
| 395 |
the issue to get further details. |