tablet: print what capability is missing when rejecting a device

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

1 files changed, 27 insertions, 0 deletions

diff --git a/doc/tablet-support.dox b/doc/tablet-support.dox
index 19c5d8ff..054ef570 100644
--- a/doc/tablet-support.dox
+++ b/doc/tablet-support.dox
@@ -344,4 +344,31 @@ libinput uses the @ref libinput_device_group to decide on touch arbitration
 and automatically discards touch events whenever a tool is in proximity.
 The exact behavior is device-dependent.
 
+@section tablet-capabilities Required tablet capabilities
+
+To handle a tablet correctly, libinput requires a set of capabilities
+on the device. When these capabilities are missing, libinput ignores the
+device and prints an error to the log. This error messages reads
+<pre>
+missing tablet capabilities: xy pen btn-stylus resolution. Ignoring this device.
+</pre>
+or in older versions of libinput simply:
+<pre>
+libinput bug: device does not meet tablet criteria. Ignoring this device.
+</pre>
+
+When a tablet is rejected, it is usually possible to check the issue with
+the `evemu-descibe` tool.
+
+- **xy** indicates that the tablet is missing the `ABS_X` and/or `ABS_Y`
+  axis. This indicates that the device is mislabelled and the udev tag
+  `ID_INPUT_TABLET` is applied to a device that is not a tablet.
+- **pen** or **btn-stylus** indicates that the tablet does not have the
+  `BTN_TOOL_PEN` or `BTN_STYLUS` bit set. libinput requires either or both
+  of them to be present. This usually indicates a bug in the kernel driver
+  or the HID descriptors of the device.
+- **resolution** indicates that the device does not have a resolution set
+  for the x and y axes. This can be fixed with a hwdb entry, locate and read
+  the 60-evdev.hwdb file on your machine to address this.
+
 */