doc/user: add a page to troubleshoot right-click Clickpads

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

diff --git a/doc/user/clickpad-with-right-button.rst b/doc/user/clickpad-with-right-button.rst
new file mode 100644 (file)
index 0000000..b874b2e
--- /dev/null
+++ b/doc/user/clickpad-with-right-button.rst
@@ -0,0 +1,47 @@
+.. _clickpads_with_right_buttons:
+
+==============================================================================
+Clickpads with a fake right button
+==============================================================================
+
+libinput relies on the kernel to label :ref:`Clickpads <touchpads_buttons_clickpads>`
+with the ``INPUT_PROP_BUTTONPAD`` property so it can enable the correct
+:ref:`clickpad_softbuttons`. Clickpads are not expected to have a right button
+since the whole surface can be depressed.
+
+A common bug encountered with :ref:`Clickpads <touchpads_buttons_clickpads>`
+is that the device advertises a physical right button where no such button
+exists. This is usually a bug in the firmware of the device and causes the
+following warning to be emitted by libinput::
+
+    "<device name> clickpad advertising right button"
+
+The user-visible effect of this is usually negligible since these devices
+cannot actually trigger a right click and libinput's default behaviors for
+clickpads work as expected.
+
+However, we should nonetheless correct the device to get rid of this warning
+and avoid potential issues with future features. The :ref:`device-quirks`
+provide a simple way to disable the fake right button on the device. The
+following quirk disables the right button on the MyModel laptop from the
+MyVendor OEM::
+
+    [MyVendor MyModel Touchpad]
+    MatchName=Foo Bar Touchpad
+    MatchUdevtype=touchpad
+    MatchDMIModAlias=dmi:*svnMyVendor:pnMyModel:*
+    AttrEventCodeDisable=BTN_RIGHT
+
+The name of the device can be obtained using :ref:`libinput record <libinput-record>`,
+the modalias match is a shell-style glob against the value of ``/sys/class/dmi/id/modalias``.
+In most cases, matching should be against ``svn`` (system vendor) and one of
+``pn`` (product name) or ``pvr`` (product version), whichever provides a
+useful description of the individual laptop model. See the
+:ref:`device-quirks` documentation for details on testing local quirks.
+
+For reference, some example commits that add such a quirk are:
+
+ - `bf61ab9bb0694d0ac3d60a7f815779abfe4886e6 <https://gitlab.freedesktop.org/libinput/libinput/-/commit/bf61ab9bb0694d0ac3d60a7f815779abfe4886e6>`__
+ - `74fac6d040ac62048882dfb6f73da567ace6a6f5 <https://gitlab.freedesktop.org/libinput/libinput/-/commit/74fac6d040ac62048882dfb6f73da567ace6a6f5>`__
+ - `89cd0f990e3bee9906754d6ca8484ed5aa392249 <https://gitlab.freedesktop.org/libinput/libinput/-/commit/89cd0f990e3bee9906754d6ca8484ed5aa392249>`__
+

diff --git a/doc/user/meson.build b/doc/user/meson.build
index a1e7731..36c4fe3 100644 (file)
--- a/doc/user/meson.build
+++ b/doc/user/meson.build
@@ -139,6 +139,7 @@ src_rst = files(
        'building.rst',
        'button-debouncing.rst',
        'clickpad-softbuttons.rst',
+       'clickpad-with-right-button.rst',
        'contributing.rst',
        'device-configuration-via-udev.rst',
        'device-quirks.rst',

diff --git a/doc/user/troubleshooting.rst b/doc/user/troubleshooting.rst
index 9ca9b9a..eaf18c5 100644 (file)
--- a/doc/user/troubleshooting.rst
+++ b/doc/user/troubleshooting.rst
@@ -15,3 +15,4 @@ Troubleshooting
    trackpoint-configuration.rst
    tablet-debugging.rst
    incorrectly-enabled-hires.rst
+   clickpad-with-right-button.rst

diff --git a/src/evdev-mt-touchpad-buttons.c b/src/evdev-mt-touchpad-buttons.c
index b0b5ae8..75ddebb 100644 (file)
--- a/src/evdev-mt-touchpad-buttons.c
+++ b/src/evdev-mt-touchpad-buttons.c
@@ -945,7 +945,9 @@ tp_guess_clickpad(const struct tp_dispatch *tp, struct evdev_device *device)
        if (has_middle || has_right) {
                if (is_clickpad)
                        evdev_log_bug_kernel(device,
-                                            "clickpad advertising right button\n");
+                                            "clickpad advertising right button. "
+                                            "See %s/clickpad-with-right-button.html for details\n",
+                                            HTTP_DOC_LINK);
        } else if (has_left &
                   !is_clickpad &&
                   libevdev_get_id_vendor(device->evdev) != VENDOR_ID_APPLE) {