fallback: hires scroll heuristics for buggy devices

Some devices might announce support for high-resolution scroll wheel
by enabling REL_WHEEL_HI_RES and/or REL_HWHEEL_HI_RES but never send
a high-resolution scroll event.

When the first low-resolution scroll event is received without any
previous high-resolution event, print a kernel bug warning and start
emulating high-resolution scroll events.

Fix #668

Signed-off-by: José Expósito <jose.exposito89@gmail.com>

3 files changed, 65 insertions, 0 deletions

diff --git a/doc/user/incorrectly-enabled-hires.rst b/doc/user/incorrectly-enabled-hires.rst
new file mode 100644
index 00000000..7dffca79
--- /dev/null
+++ b/doc/user/incorrectly-enabled-hires.rst
@@ -0,0 +1,62 @@
+.. _incorrectly_enabled_hires:
+
+==============================================================================
+Incorrectly enabled high-resolution scroll
+==============================================================================
+
+Some devices might announce support for high-resolution scroll wheel by enabling
+``REL_WHEEL_HI_RES`` and/or ``REL_HWHEEL_HI_RES`` but never send a
+high-resolution scroll event.
+
+When the first low-resolution scroll event is received without any previous
+high-resolution event, libinput prints a bug warning with the text **"device
+supports high-resolution scroll but only low-resolution events have been
+received"** and a link to this page.
+
+.. note:: This warning will be printed only once
+
+In most cases this is a bug on the device firmware, the kernel driver or in a
+software used to create user-space devices through uinput.
+
+Once the bug is detected, libinput will start emulating high-resolution scroll
+events.
+
+------------------------------------------------------------------------------
+Detecting and fixing the issue
+------------------------------------------------------------------------------
+
+Events sent by a buggy device can be shown in the
+:ref:`libinput record <libinput-record>` output for the device. Notice that
+``REL_WHEEL_HI_RES`` and ``REL_HWHEEL_HI_RES`` are set but only ``REL_WHEEL``
+events are sent: ::
+
+    # Supported Events:
+    # Event type 0 (EV_SYN)
+    # Event type 1 (EV_KEY)
+    #   Event code 272 (BTN_LEFT)
+    # Event type 2 (EV_REL)
+    #   Event code 0 (REL_X)
+    #   Event code 1 (REL_Y)
+    #   Event code 6 (REL_HWHEEL)
+    #   Event code 8 (REL_WHEEL)
+    #   Event code 11 (REL_WHEEL_HI_RES)
+    #   Event code 12 (REL_HWHEEL_HI_RES)
+    [...]
+    quirks:
+    events:
+    - evdev:
+        - [  0,      0,   2,   8,       1] # EV_REL / REL_WHEEL                 1
+        - [  0,      0,   0,   0,       0] # ------------ SYN_REPORT (0) ---------- +0ms
+    - evdev:
+        - [  0,  15126,   2,   8,       1] # EV_REL / REL_WHEEL                 1
+        - [  0,  15126,   0,   0,       0] # ------------ SYN_REPORT (0) ---------- +15ms
+    - evdev:
+        - [  0,  30250,   2,   8,       1] # EV_REL / REL_WHEEL                 1
+        - [  0,  30250,   0,   0,       0] # ------------ SYN_REPORT (0) ---------- +15ms
+
+The issue can be fixed by adding a quirk to unset the ``REL_WHEEL_HI_RES`` and
+``REL_HWHEEL_HI_RES`` event codes: ::
+
+    AttrEventCodeDisable=REL_WHEEL_HI_RES;REL_HWHEEL_HI_RES;
+
+Please see :ref:`device-quirks` for details.
diff --git a/doc/user/meson.build b/doc/user/meson.build
index 332f67b9..a5e7737d 100644
--- a/doc/user/meson.build
+++ b/doc/user/meson.build
@@ -50,6 +50,7 @@ src_404s = [
 	[ 'faqs.rst', 'faq.html'],
 	[ 'features.rst', 'features.html'],
 	[ 'gestures.rst', 'gestures.html'],
+	[ 'incorrectly-enabled-hires.rst', 'incorrectly-enabled-hires.html'],
 	[ 'middle-button-emulation.rst', 'middle_button_emulation.html'],
 	[ 'normalization-of-relative-motion.rst', 'motion_normalization.html'],
 	[ 'palm-detection.rst', 'palm_detection.html'],
@@ -143,6 +144,7 @@ src_rst = files(
 	'device-quirks.rst',
 	'faqs.rst',
 	'gestures.rst',
+	'incorrectly-enabled-hires.rst',
 	'middle-button-emulation.rst',
 	'normalization-of-relative-motion.rst',
 	'palm-detection.rst',
diff --git a/doc/user/troubleshooting.rst b/doc/user/troubleshooting.rst
index a66f96c2..9ca9b9a2 100644
--- a/doc/user/troubleshooting.rst
+++ b/doc/user/troubleshooting.rst
@@ -14,3 +14,4 @@ Troubleshooting
    touchpad-pressure-debugging.rst
    trackpoint-configuration.rst
    tablet-debugging.rst
+   incorrectly-enabled-hires.rst