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

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

4 files changed, 52 insertions, 1 deletions

diff --git a/doc/user/clickpad-with-right-button.rst b/doc/user/clickpad-with-right-button.rst
new file mode 100644
index 00000000..b874b2ed
--- /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 a1e77311..36c4fe3e 100644
--- 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 9ca9b9a2..eaf18c55 100644
--- 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 b0b5ae8e..75ddebb2 100644
--- 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) {