mirror of
https://gitlab.freedesktop.org/libinput/libinput.git
synced 2026-02-04 09:20:29 +01:00
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>
This commit is contained in:
Peter Hutterer
parent
9873d68bf1
commit
08dbfb94b5
5 changed files with 82 additions and 130 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
***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.
|
||||
*/
|
||||
|
|
|
|||
12
doc/faqs.dox
12
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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
*/
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue