From 65c71fd6b470d5e655d0ba08c210644ccbda2c95 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Mon, 12 Jun 2023 13:41:53 +1000 Subject: [PATCH] doc/user: move ignoring devices to separate page This is way too hidden to the point where i couldn't find it for quite a while despite knowing it exists. Move it to an entry under troubleshooting. Signed-off-by: Peter Hutterer --- doc/user/device-configuration-via-udev.rst | 36 ---------------------- doc/user/ignoring-devices.rst | 36 ++++++++++++++++++++++ doc/user/meson.build | 1 + doc/user/troubleshooting.rst | 1 + 4 files changed, 38 insertions(+), 36 deletions(-) create mode 100644 doc/user/ignoring-devices.rst diff --git a/doc/user/device-configuration-via-udev.rst b/doc/user/device-configuration-via-udev.rst index ee3345ca..e6848b64 100644 --- a/doc/user/device-configuration-via-udev.rst +++ b/doc/user/device-configuration-via-udev.rst @@ -108,42 +108,6 @@ for a device with the vendor/model ID of ``012a``/``034b``. :: ENV{ID_INPUT_TOUCHPAD}="", ENV{ID_INPUT_TABLET}="1" - -.. _ignoring_devices: - ------------------------------------------------------------------------------- -Ignoring specific devices ------------------------------------------------------------------------------- - -If a device has the **LIBINPUT_IGNORE_DEVICE** udev property set to any -value but "0", that device is not initialized by libinput. For a context -created with **libinput_udev_create_context()**, the device is silently ignored -and never shows up. If the device is added with **libinput_path_add_device()** -to a context created with **libinput_path_create_context()**, adding the device -will fail and return NULL (see that function's documentation for more -information). - -If the property value is exactly "0", then the property is considered unset -and libinput initializes the device normally. - -This property should be used for devices that are correctly detected as -input devices (see :ref:`udev_device_type`) but that should not be used by -libinput. It is recommended that devices that should not be handled as input -devices at all unset the **ID_INPUT** and related properties instead. The -**LIBINPUT_IGNORE_DEVICE** property signals that only libinput should -ignore this property but other parts of the stack (if any) should continue -treating this device normally. - -Below is an example udev rule to assign **LIBINPUT_IGNORE_DEVICE** to the -device with the vendor/model ID of ``012a``/``034b``. :: - - $ cat /etc/udev/rules.d/99-ignore-my-device.rules - ACTION=="add|change", KERNEL=="event[0-9]*", \ - ENV{ID_VENDOR_ID}=="012a", \ - ENV{ID_MODEL_ID}=="034b", \ - ENV{LIBINPUT_IGNORE_DEVICE}="1" - - .. _model_specific_configuration: ------------------------------------------------------------------------------ diff --git a/doc/user/ignoring-devices.rst b/doc/user/ignoring-devices.rst new file mode 100644 index 00000000..b6d27de2 --- /dev/null +++ b/doc/user/ignoring-devices.rst @@ -0,0 +1,36 @@ +.. _ignoring_devices: + +============================================================================== +Ignoring specific devices +============================================================================== + +If a device has the **LIBINPUT_IGNORE_DEVICE** udev property set to any +value but "0", that device is not initialized by libinput. +For a context created with **libinput_udev_create_context()**, the device is +silently ignored and never shows up. If the device is added with +**libinput_path_add_device()** to a context created with +**libinput_path_create_context()**, adding the device will fail and return NULL +(see that function's documentation for more +information). + +If the property value is exactly "0", then the property is considered unset +and libinput initializes the device normally. + +This property should be used for devices that are correctly detected as +input devices (see :ref:`udev_device_type`) but that should not be used by +libinput. It is recommended that devices that should not be handled as input +devices at all unset the **ID_INPUT** and related properties instead. The +**LIBINPUT_IGNORE_DEVICE** property signals that only libinput should +ignore this property but other parts of the stack (if any) should continue +treating this device normally. + +Below is an example udev rule to assign **LIBINPUT_IGNORE_DEVICE** to the +device with the vendor/model ID of ``012a``/``034b``. :: + + $ cat /etc/udev/rules.d/99-ignore-my-device.rules + ACTION=="add|change", KERNEL=="event[0-9]*", \ + ENV{ID_VENDOR_ID}=="012a", \ + ENV{ID_MODEL_ID}=="034b", \ + ENV{LIBINPUT_IGNORE_DEVICE}="1" + +See :ref:`udev_config` for more details on libinput's udev properties. diff --git a/doc/user/meson.build b/doc/user/meson.build index 36c4fe3e..86de6981 100644 --- a/doc/user/meson.build +++ b/doc/user/meson.build @@ -146,6 +146,7 @@ src_rst = files( 'faqs.rst', 'gestures.rst', 'incorrectly-enabled-hires.rst', + 'ignoring-devices.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 eaf18c55..1a70f93a 100644 --- a/doc/user/troubleshooting.rst +++ b/doc/user/troubleshooting.rst @@ -16,3 +16,4 @@ Troubleshooting tablet-debugging.rst incorrectly-enabled-hires.rst clickpad-with-right-button.rst + ignoring-devices.rst