In favour of the device quirks system.
Fixes #55
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
$> 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
<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
@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
@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.
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
@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.
*/
@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
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
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
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
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.
@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
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
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.
@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:
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.
*/
projects / platform / upstream / libinput.git / commitdiff