fdo-mirrors/libinput
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libinput.git synced 2026-05-08 21:48:05 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: update docs to drop hwdb references

Browse source 
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 2018-06-21 10:58:34 +10:00
parent 9873d68bf1
commit 08dbfb94b5
5 changed files with 82 additions and 130 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/building.dox
View file

@ -23,6 +23,10 @@ $> cd libinput
$> meson --prefix=/usr builddir/ $> meson --prefix=/usr builddir/
$> ninja -C builddir/ $> ninja -C builddir/
$> sudo ninja -C builddir/ install $> sudo ninja -C builddir/ install
@endcode
When running libinput versions 1.11.x or earlier, you must run
@code
$> sudo udevadm hwdb --update $> sudo udevadm hwdb --update
@endcode @endcode

97
doc/device-configuration-via-udev.dox
View file

@ -64,14 +64,6 @@ See @ref motion_normalization for details.
<dd>The angle in degrees for each click on a mouse wheel. See <dd>The angle in degrees for each click on a mouse wheel. See
libinput_pointer_get_axis_source() for details. libinput_pointer_get_axis_source() for details.
</dd> </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> </dl>
Below is an example udev rule to assign "seat1" to a device from vendor 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 @section model_specific_configuration Model-specific configuration
libinput reserves the property prefixes <b>LIBINPUT_MODEL_</b> and As of libinput 1.12, model-specific configuration is stored in the @ref
<b>LIBINPUT_ATTR_</b> for model-specific configuration. <b>These prefixes device-quirks and not in the hwdb anymore. Please see @ref device-quirks for
are reserved as private API, do not use.</b> details.
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.
@subsection model_specific_configuration_x220fw81 Lenovo x220 with touchpad firmware v8.1 @subsection model_specific_configuration_x220fw81 Lenovo x220 with touchpad firmware v8.1
@ -162,7 +148,7 @@ is guaranteed.
@section hwdb Configuring the hwdb @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 href="https://www.freedesktop.org/software/systemd/man/hwdb.html">udev
hwdb</a> and reload properties so they are available to libinput. 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, initialized. This section only describes the hwdb in relation to libinput,
it is not a full documentation on how the hwdb works. 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 libinput's use of the hwdb is limited to properties systemd and custom
change at any time. Once tested, changes to the hwdb must be submitted rules files (where available) provide. Hardware-specific quirks as used by
upstream.** libinput are in the @ref device-quirks system.
@subsection hwdb_querying Querying the hwdb @subsection hwdb_querying Querying the hwdb
@ -234,70 +220,11 @@ in the udev rules files).
@subsection hwdb_modifying Modifying the hwdb @subsection hwdb_modifying Modifying the hwdb
This section applies to users that need to add, change, or remove a hwdb ***This section has been removed as it no longer applies in libinput 1.12
entry for their device. Note that **the hwdb is not part of the public API and later.*** libinput users should not need to modify the hwdb, any
and may change at any time**. Once a device has been made to work, the device-specific quirks must go in to the @ref device-quirks system.
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 For information about older libinput versions, please see the documentation
right match format. libinput ships with a set of rules to query the hwdb, for your version avaialable in: https://wayland.freedesktop.org/libinput/doc/
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.
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
View file

@ -19,9 +19,10 @@ motion_normalization for a detailed explanation.
@section faq_fast_trackpoint My trackpoint moves too slow or too fast @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 This is a symptom of an invalid trackpoint range. These devices need @ref
hwdb entry to specify the range available so libinput can adjust the pointer device-quirks to specify the range available so libinput can adjust the
acceleration accordingly. See @ref trackpoint_range for a detailed explanation. 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 @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 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. 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? @section faq_timer_offset What causes the "timer offset negative" warning?
libinput relies on the caller to call libinput_dispatch() whenever data is libinput relies on the caller to call libinput_dispatch() whenever data is

91
doc/touchpad-pressure.dox
View file

@ -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 ```ABS_MT_WIDTH_MAJOR/ABS_MT_WIDTH_MINOR``` axes. These axes specifcy
the size of the touch ellipse. While the kernel documentation specifies how the size of the touch ellipse. While the kernel documentation specifies how
these axes are supposed to be mapped, few devices forward reliable these axes are supposed to be mapped, few devices forward reliable
information. libinput uses these values together with a device-specific hwdb information. libinput uses these values together with a device-specific
entry. In other words, touch size detection does not work unless a hwdb @ref device quirks entry. In other words, touch size detection does not work
entry is present for the device. unless a device quirk is present for the device.
@section touchpad_pressure_hwdb Debugging touchpad pressure ranges @section touchpad_pressure_hwdb Debugging touchpad pressure ranges
This section describes how to determine the 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 required for a touchpad device and how to add the required @ref
locally. Note that the hwdb entry is **not public API** and **may change at device-quirks locally. Note that the quirk is **not public API** and **may
any time**. Users are advised to @ref reporting_bugs "report a bug" with the change at any time**. Users are advised to @ref reporting_bugs "report a bug"
updated pressure ranges when testing has completed. with the updated pressure ranges when testing has completed.
Use the ```libinput measure touchpad-pressure``` tool provided by libinput. Use the ```libinput measure touchpad-pressure``` tool provided by libinput.
This tool will search for your touchpad device and print some pressure 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 change frequently. Refer to the <i>libinput-measure-touchpad-pressure(1)</i> man
page for more details. 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' 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: argument:
<pre> <pre>
$ sudo libinput measure touchpad-pressure --touch-thresholds=10:8 --palm-threshold=20 $ 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.** 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 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> <pre>
$> cat /etc/udev/hwdb.d/99-touchpad-pressure.hwdb $> cat /etc/libinput/local-overrides.quirks
libinput:name:*SynPS/2 Synaptics TouchPad:dmi:*svnHewlett-Packard:*pnHPCompaq6910p* [Touchpad pressure override]
LIBINPUT_ATTR_PRESSURE_RANGE=10:8 MatchUdevType=touchpad
MatchName=*SynPS/2 Synaptics TouchPad
MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadX230*
AttrPressureRange=10:8
</pre> </pre>
The first line is the match line and should be adjusted for the device name The file name **must** be `/etc/libinput/local-overrides.quirks`. The
(see evemu-record's output) and for the local system, based on the The first line is the section name and can be free-form. The `Match`
information in ```/sys/class/dmi/id/modalias```. The modalias should be directives limit the quirk to your touchpad, make sure the device name
shortened to the specific system's information, usually system vendor (svn) 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). and product name (pn).
Once in place, you need to run the following to commands, adjusted for your Once in place, run the following command to verify the quirk is valid and
device's event node (see @ref faq_hwdb_changes): works for your device:
<pre> <pre>
sudo udevadm hwdb --update $ sudo libinput list-quirks /dev/input/event10
sudo udevadm test /sys/class/input/eventX AttrPressureRange=10:8
</pre> </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 Wayland compositor and libinput should now use the correct pressure
thresholds. The @ref tools can be used to verify the correct thresholds. The @ref tools can be used to verify the correct
functionality first without the need for a restart. functionality first without the need for a restart.
@ -133,11 +142,11 @@ repository.
@section touchpad_touch_size_hwdb Debugging touch size ranges @section touchpad_touch_size_hwdb Debugging touch size ranges
This section describes how to determine the touchpad touch size ranges This section describes how to determine the touchpad size ranges
required for a touchpad device and how to add the required hwdb entry required for a touchpad device and how to add the required @ref
locally. Note that the hwdb entry is **not public API** and **may change at device-quirks locally. Note that the quirk is **not public API** and **may
any time**. Users are advised to @ref reporting_bugs "report a bug" with the change at any time**. Users are advised to @ref reporting_bugs "report a bug"
updated pressure ranges when testing has completed. with the updated pressure ranges when testing has completed.
Use the ```libinput measure touch-size``` tool provided by libinput. Use the ```libinput measure touch-size``` tool provided by libinput.
This tool will search for your touchpad device and print some touch size 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 output may change frequently. Refer to the <i>libinput-measure-touch-size(1)</i> man
page for more details. 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' 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. arguments as in the example above.
Interact with the touchpad and check if the output of this tool matches your 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.** 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 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> <pre>
$> cat /etc/udev/hwdb.d/99-touchpad-pressure.hwdb $> cat /etc/libinput/local-overrides.quirks
libinput:name:*SynPS/2 Synaptics TouchPad:dmi:*svnHewlett-Packard:*pnHPCompaq6910p* [Touchpad touch size override]
LIBINPUT_ATTR_TOUCH_SIZE_RANGE=10:8 MatchUdevType=touchpad
MatchName=*SynPS/2 Synaptics TouchPad
MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadX230*
AttrTouchSizeRange=10:8
</pre> </pre>
The first line is the match line and should be adjusted for the device name 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 (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) shortened to the specific system's information, usually system vendor (svn)
and product name (pn). and product name (pn).
Once in place, you need to run the following to commands, adjusted for your Once in place, run the following command to verify the quirk is valid and
device's event node (see @ref faq_hwdb_changes): works for your device:
<pre> <pre>
sudo udevadm hwdb --update $ sudo libinput list-quirks /dev/input/event10
sudo udevadm test /sys/class/input/eventX AttrTouchSizeRange=10:8
</pre> </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 If the touch size range property shows up correctly, restart X or the
Wayland compositor and libinput should now use the correct thresholds. Wayland compositor and libinput should now use the correct thresholds.

8
doc/trackpoints.dox
View file

@ -38,8 +38,8 @@ see @ref trackpoint_range_measure.
@section trackpoint_range_measure Measuring the trackpoint range @section trackpoint_range_measure Measuring the trackpoint range
This section describes how to measure the trackpoint range and apply a hwdb This section describes how to measure the trackpoint range and apply @ref
entry to make this range known to libinput. libinput provides the tool device-quirks to make this range known to libinput. libinput provides the tool
`libinput measure trackpoint-range` for this task. This is an interactive `libinput measure trackpoint-range` for this task. This is an interactive
tool and prints its instructions on the commandline. Example output from tool and prints its instructions on the commandline. Example output from
this tool is below: 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 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. 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 The device quirk set is `AttrTrackpointRange=25`. See @ref
hwdb_modifying for details on how to apply this property. device-quirks for details on how to apply device quirks.
*/ */