doc: update docs to drop hwdb references

In favour of the device quirks system.

Fixes #55

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

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.
 <dd>The angle in degrees for each click on a mouse wheel. See
 libinput_pointer_get_axis_source() for details.
 </dd>
-<dt>LIBINPUT_MODEL_*</dt>
-<dd><b>This prefix is reserved as private API, do not use.</b> See @ref
-model_specific_configuration for details.
-</dd>
-<dt>LIBINPUT_ATTR_*</dt>
-<dd><b>This prefix is reserved as private API, do not use.</b> See @ref
-model_specific_configuration for details.
-</dd>
 </dl>
 
 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 <b>LIBINPUT_MODEL_</b> and
-<b>LIBINPUT_ATTR_</b> for model-specific configuration. <b>These prefixes
-are reserved as private API, do not use.</b>
-
-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 <a
+This section outlines how to query the <a
 href="https://www.freedesktop.org/software/systemd/man/hwdb.html">udev
 hwdb</a> 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.
-
-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:
-
-    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.
+***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.
 
-The hwdb does not allow removing properties. Where a property must be unset,
-it should be set to 0.
+For information about older libinput versions, please see the documentation
+for your version avaialable in: https://wayland.freedesktop.org/libinput/doc/
 
-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</a> 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 <i>libinput-measure-touchpad-pressure(1)</i> 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:
 <pre>
 $ 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:
 
 <pre>
-$> 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
 </pre>
 
-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:
 <pre>
-    sudo udevadm hwdb --update
-    sudo udevadm test /sys/class/input/eventX
+$ sudo libinput list-quirks /dev/input/event10
+AttrPressureRange=10:8
 </pre>
+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 <i>libinput-measure-touch-size(1)</i> 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:
 
 <pre>
-$> 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
 </pre>
 
 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:
 <pre>
-    sudo udevadm hwdb --update
-    sudo udevadm test /sys/class/input/eventX
+$ sudo libinput list-quirks /dev/input/event10
+AttrTouchSizeRange=10:8
 </pre>
+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.
 
 */