From 08dbfb94b555e714bb09deb1f2e35d9881b399ef Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 21 Jun 2018 10:58:34 +1000 Subject: [PATCH] doc: update docs to drop hwdb references In favour of the device quirks system. Fixes #55 Signed-off-by: Peter Hutterer --- doc/building.dox | 4 ++ doc/device-configuration-via-udev.dox | 97 ++++----------------------- doc/faqs.dox | 12 +++- doc/touchpad-pressure.dox | 91 ++++++++++++++----------- doc/trackpoints.dox | 8 +-- 5 files changed, 82 insertions(+), 130 deletions(-) diff --git a/doc/building.dox b/doc/building.dox index 7a82646c..89c60167 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -23,6 +23,10 @@ $> cd libinput $> meson --prefix=/usr builddir/ $> ninja -C builddir/ $> sudo ninja -C builddir/ install +@endcode + +When running libinput versions 1.11.x or earlier, you must run +@code $> sudo udevadm hwdb --update @endcode diff --git a/doc/device-configuration-via-udev.dox b/doc/device-configuration-via-udev.dox index 3fc91661..a0ae345a 100644 --- a/doc/device-configuration-via-udev.dox +++ b/doc/device-configuration-via-udev.dox @@ -64,14 +64,6 @@ See @ref motion_normalization for details.
The angle in degrees for each click on a mouse wheel. See libinput_pointer_get_axis_source() for details.
-
LIBINPUT_MODEL_*
-
This prefix is reserved as private API, do not use. See @ref -model_specific_configuration for details. -
-
LIBINPUT_ATTR_*
-
This prefix is reserved as private API, do not use. See @ref -model_specific_configuration for details. -
Below is an example udev rule to assign "seat1" to a device from vendor @@ -131,15 +123,9 @@ treating this device normally. @section model_specific_configuration Model-specific configuration -libinput reserves the property prefixes LIBINPUT_MODEL_ and -LIBINPUT_ATTR_ for model-specific configuration. These prefixes -are reserved as private API, do not use. - -The effect of these properties may be to enable or disable certain -features on a specific device or set of devices, to change configuration -defaults or any other reason. The effects of setting these properties, the -format of the property and the value of the property are subject to change -at any time. +As of libinput 1.12, model-specific configuration is stored in the @ref +device-quirks and not in the hwdb anymore. Please see @ref device-quirks for +details. @subsection model_specific_configuration_x220fw81 Lenovo x220 with touchpad firmware v8.1 @@ -162,7 +148,7 @@ is guaranteed. @section hwdb Configuring the hwdb -This section outlines how to add an entry to the udev hwdb and reload properties so they are available to libinput. @@ -171,9 +157,9 @@ available to libinput when the device is connected and/or libinput is initialized. This section only describes the hwdb in relation to libinput, it is not a full documentation on how the hwdb works. -@note **The use of the hwdb by libinput is not part of the public API. It may -change at any time. Once tested, changes to the hwdb must be submitted -upstream.** +libinput's use of the hwdb is limited to properties systemd and custom +rules files (where available) provide. Hardware-specific quirks as used by +libinput are in the @ref device-quirks system. @subsection hwdb_querying Querying the hwdb @@ -234,70 +220,11 @@ in the udev rules files). @subsection hwdb_modifying Modifying the hwdb -This section applies to users that need to add, change, or remove a hwdb -entry for their device. Note that **the hwdb is not part of the public API -and may change at any time**. Once a device has been made to work, the -change must be submitted to the libinput bugzilla, see @ref reporting_bugs. +***This section has been removed as it no longer applies in libinput 1.12 +and later.*** libinput users should not need to modify the hwdb, any +device-specific quirks must go in to the @ref device-quirks system. -hwdb entries are only applied if a udev rules calls out to the hwdb with the -right match format. libinput ships with a set of rules to query the hwdb, -the different rules are reflected by their prefix. Again, **this is not part -of the public API**. libinput's matches are -composed of a literal "libinput", then either the device name and dmi -modalias, or the device types and the input modalias. Any part of the hwdb -match line can be a glob by using a literal `*`. For example: +For information about older libinput versions, please see the documentation +for your version avaialable in: https://wayland.freedesktop.org/libinput/doc/ - libinput:keyboard:input:b0011v* - libinput:touchpad:input:b0003v05ACp* - libinput:touchpad:input:b0003v05ACp021A* - -This type of matching is the preferred one for any removable device (USB, -Bluetooth, ...) that can be uniquely identified by the bustype, vendor and -product ID. The first line matches any keyboard device on the -serial bus (0x0011). The second line matches any touchpad device -with a vendor ID of 0x05AC. The third line matches any touchpad device -with a vendor ID of 0x05AC and a product ID of 0x021A. The `input:b...` -string is available in the device's modalias file -`/sys/class/input/eventX/device/modalias`. - -In the case of built-in devices that do not have a unique id, we -need to use the host system's dmi information. For example: - - libinput:name:*Lid Switch*:dmi:*svnLENOVO:*pvrThinkPadT440* - -This match applies to any device with a name **containing** "Led Switch" -that is on a Lenovo T440 system. The dmi modalias is available in -`/sys/class/dmi/id/modalias`. For example, on the T440 matched above, the -modalias is - - dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:pn3453453678:pvrThinkPadT440s:rvnLENOVO:rn2012345223:rvrABC123KKK123B:cvnLENOVO:ct10:cvrNotAvailable: - -The dmi should always be shortened to the sections that uniquely identify -the type system, in this case the vendor (svn) and the product version (pvr). -Failing to shorten the system may mean that the hwdb match rule only applies -to your specific system, rather than all systems of that type, or that the -rule no longer applies after a firmware update. - -The hwdb match string is the first portion of the hwdb entry. The second -portion is the property to set. Each hwdb entry may match on multiple -devices and may apply multiple properties. For example: - - - libinput:touchpad:input:b0003v05ACp* - THIS_IS_AN_APPLE_DEVICE=1 - - libinput:touchpad:input:b0003v05ACp* - libinput:name:*Lid Switch*:dmi:*svnLENOVO:*pvrThinkPadT440* - FOO=1 - BAR=2 - -In the example above, any matching touchpad device will have all three -properties applied, the lid switch device only has FOO and BAR. - -The hwdb does not allow removing properties. Where a property must be unset, -it should be set to 0. - -Any user-specific hwdb entries should be placed in a file -`/etc/udev/hwdb.d/99-somename.hwdb`. See @ref hwdb_reloading for -instructions on how to reload the hwdb once the file is in place. */ diff --git a/doc/faqs.dox b/doc/faqs.dox index cc117e06..6f91450e 100644 --- a/doc/faqs.dox +++ b/doc/faqs.dox @@ -19,9 +19,10 @@ motion_normalization for a detailed explanation. @section faq_fast_trackpoint My trackpoint moves too slow or too fast -This is a symptom of an invalid trackpoint range. These devices need a udev -hwdb entry to specify the range available so libinput can adjust the pointer -acceleration accordingly. See @ref trackpoint_range for a detailed explanation. +This is a symptom of an invalid trackpoint range. These devices need @ref +device-quirks to specify the range available so libinput can adjust the +pointer acceleration accordingly. See @ref trackpoint_range for a detailed +explanation. @section faq_enable_tapping Why isn't touchpad tap-to-click enabled by default @@ -198,6 +199,11 @@ href="https://www.freedesktop.org/software/systemd/man/hwdb.html">udev hwdb or patches that include a change to the hwdb. See @ref hwdb for details on the hwdb and how to modify it locally. +@note As of libinput 1.12, libinput-specific properties are now stored in +the @ref device-quirks system. There are no libinput-specific hwdb entries +anymore and any changes to the hwdb must be merged into the systemd +repository. + @section faq_timer_offset What causes the "timer offset negative" warning? libinput relies on the caller to call libinput_dispatch() whenever data is diff --git a/doc/touchpad-pressure.dox b/doc/touchpad-pressure.dox index 95d65cc6..b6fa064e 100644 --- a/doc/touchpad-pressure.dox +++ b/doc/touchpad-pressure.dox @@ -41,17 +41,17 @@ the ```ABS_MT_TOUCH_MAJOR/ABS_MT_TOUCH_MINOR``` axes and/or the ```ABS_MT_WIDTH_MAJOR/ABS_MT_WIDTH_MINOR``` axes. These axes specifcy the size of the touch ellipse. While the kernel documentation specifies how these axes are supposed to be mapped, few devices forward reliable -information. libinput uses these values together with a device-specific hwdb -entry. In other words, touch size detection does not work unless a hwdb -entry is present for the device. +information. libinput uses these values together with a device-specific +@ref device quirks entry. In other words, touch size detection does not work +unless a device quirk is present for the device. @section touchpad_pressure_hwdb Debugging touchpad pressure ranges This section describes how to determine the touchpad pressure ranges -required for a touchpad device and how to add the required hwdb entry -locally. Note that the hwdb entry is **not public API** and **may change at -any time**. Users are advised to @ref reporting_bugs "report a bug" with the -updated pressure ranges when testing has completed. +required for a touchpad device and how to add the required @ref +device-quirks locally. Note that the quirk is **not public API** and **may +change at any time**. Users are advised to @ref reporting_bugs "report a bug" +with the updated pressure ranges when testing has completed. Use the ```libinput measure touchpad-pressure``` tool provided by libinput. This tool will search for your touchpad device and print some pressure @@ -84,9 +84,9 @@ logically down at some point. This is an interactive tool and its output may change frequently. Refer to the libinput-measure-touchpad-pressure(1) man page for more details. -By default, this tool uses the udev hwdb entries for the pressure range. To +By default, this tool uses the @ref device-quirks for the pressure range. To narrow down on the best values for your device, specify the 'logically down' -and 'logically up' pressure thresholds with the ```--touch-thresholds`` +and 'logically up' pressure thresholds with the `--touch-thresholds` argument: 
 $ sudo libinput measure touchpad-pressure --touch-thresholds=10:8 --palm-threshold=20
@@ -101,28 +101,37 @@ touchpad. Attaching output logs to a bug will not help, only you with access
 to the hardware can figure out the correct ranges.**
 
 Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with
-the following hwdb file:
+@ref device-quirks entry similar to this:
 
 
-$> cat /etc/udev/hwdb.d/99-touchpad-pressure.hwdb
-libinput:name:*SynPS/2 Synaptics TouchPad:dmi:*svnHewlett-Packard:*pnHPCompaq6910p*
- LIBINPUT_ATTR_PRESSURE_RANGE=10:8
+$> cat /etc/libinput/local-overrides.quirks
+[Touchpad pressure override]
+MatchUdevType=touchpad
+MatchName=*SynPS/2 Synaptics TouchPad
+MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadX230*
+AttrPressureRange=10:8
 

 
-The first line is the match line and should be adjusted for the device name
-(see evemu-record's output) and for the local system, based on the
-information in ```/sys/class/dmi/id/modalias```. The modalias should be
-shortened to the specific system's information, usually system vendor (svn)
+The file name **must** be `/etc/libinput/local-overrides.quirks`. The
+The first line is the section name and can be free-form. The `Match`
+directives limit the quirk to your touchpad, make sure the device name
+matches your device's name (see `libinput record`'s output). The dmi
+modalias match should be based on the information in
+`/sys/class/dmi/id/modalias`.  This modalias should be shortened to the
+specific system's information, usually system vendor (svn)
 and product name (pn).
 
-Once in place, you need to run the following to commands, adjusted for your
-device's event node (see @ref faq_hwdb_changes):
+Once in place, run the following command to verify the quirk is valid and
+works for your device:
 
-    sudo udevadm hwdb --update
-    sudo udevadm test /sys/class/input/eventX
+$ sudo libinput list-quirks /dev/input/event10
+AttrPressureRange=10:8
 

+Replace the event node with the one from your device. If the
+`AttrPressureRange` quirk does not show up, re-run with `--verbose` and
+check the output for any error messages.
 
-If the pressure range property shows up correctly, restart X or the
+If the pressure range quirk shows up correctly, restart X or the
 Wayland compositor and libinput should now use the correct pressure
 thresholds. The @ref tools can be used to verify the correct
 functionality first without the need for a restart.
@@ -133,11 +142,11 @@ repository.
 
 @section touchpad_touch_size_hwdb Debugging touch size ranges
 
-This section describes how to determine the touchpad touch size ranges
-required for a touchpad device and how to add the required hwdb entry
-locally. Note that the hwdb entry is **not public API** and **may change at
-any time**. Users are advised to @ref reporting_bugs "report a bug" with the
-updated pressure ranges when testing has completed.
+This section describes how to determine the touchpad size ranges
+required for a touchpad device and how to add the required @ref
+device-quirks locally. Note that the quirk is **not public API** and **may
+change at any time**. Users are advised to @ref reporting_bugs "report a bug"
+with the updated pressure ranges when testing has completed.
 
 Use the ```libinput measure touch-size``` tool provided by libinput.
 This tool will search for your touchpad device and print some touch size
@@ -171,9 +180,9 @@ logically down or a palm at some point. This is an interactive tool and its
 output may change frequently. Refer to the libinput-measure-touch-size(1) man
 page for more details.
 
-By default, this tool uses the udev hwdb entries for the touch size range. To
+By default, this tool uses the @ref device-quirks for the touch size range. To
 narrow down on the best values for your device, specify the 'logically down'
-and 'logically up' pressure thresholds with the  ```--touch-thresholds``
+and 'logically up' pressure thresholds with the  `--touch-thresholds`
 arguments as in the example above.
 
 Interact with the touchpad and check if the output of this tool matches your
@@ -185,26 +194,32 @@ touchpad. Attaching output logs to a bug will not help, only you with access
 to the hardware can figure out the correct ranges.**
 
 Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with
-the following hwdb file:
+@ref device-quirks entry similar to this:
 
 
-$> cat /etc/udev/hwdb.d/99-touchpad-pressure.hwdb
-libinput:name:*SynPS/2 Synaptics TouchPad:dmi:*svnHewlett-Packard:*pnHPCompaq6910p*
- LIBINPUT_ATTR_TOUCH_SIZE_RANGE=10:8
+$> cat /etc/libinput/local-overrides.quirks
+[Touchpad touch size override]
+MatchUdevType=touchpad
+MatchName=*SynPS/2 Synaptics TouchPad
+MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadX230*
+AttrTouchSizeRange=10:8
 

 
 The first line is the match line and should be adjusted for the device name
 (see evemu-record's output) and for the local system, based on the
-information in ```/sys/class/dmi/id/modalias```. The modalias should be
+information in `/sys/class/dmi/id/modalias`. The modalias should be
 shortened to the specific system's information, usually system vendor (svn)
 and product name (pn).
 
-Once in place, you need to run the following to commands, adjusted for your
-device's event node (see @ref faq_hwdb_changes):
+Once in place, run the following command to verify the quirk is valid and
+works for your device:
 
-    sudo udevadm hwdb --update
-    sudo udevadm test /sys/class/input/eventX
+$ sudo libinput list-quirks /dev/input/event10
+AttrTouchSizeRange=10:8
 

+Replace the event node with the one from your device. If the
+`AttrTouchSizeRange` quirk does not show up, re-run with `--verbose` and
+check the output for any error messages.
 
 If the touch size range property shows up correctly, restart X or the
 Wayland compositor and libinput should now use the correct thresholds.
diff --git a/doc/trackpoints.dox b/doc/trackpoints.dox
index affad637..ab0876f3 100644
--- a/doc/trackpoints.dox
+++ b/doc/trackpoints.dox
@@ -38,8 +38,8 @@ see @ref trackpoint_range_measure.
 
 @section trackpoint_range_measure Measuring the trackpoint range
 
-This section describes how to measure the trackpoint range and apply a hwdb
-entry to make this range known to libinput. libinput provides the tool
+This section describes how to measure the trackpoint range and apply @ref
+device-quirks to make this range known to libinput. libinput provides the tool
 `libinput measure trackpoint-range` for this task. This is an interactive
 tool and prints its instructions on the commandline. Example output from
 this tool is below:
@@ -146,8 +146,8 @@ device would be 25. Note how there is a fair bit of guesswork involved, a
 trackpoint's data is never clean enough to get a definitive value. It is
 generally better to take a (slightly) smaller range than one too large.
 
-The udev property to set is `LIBINPUT_ATTR_TRACKPOINT_RANGE=25`. See @ref
-hwdb_modifying for details on how to apply this property.
+The device quirk set is `AttrTrackpointRange=25`. See @ref
+device-quirks for details on how to apply device quirks.
 
 */