summaryrefslogtreecommitdiff
path: root/doc/device-quirks.dox
blob: d436866434f2cf2a93e51650b18dd8e060a3005e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
/**
@page device-quirks Device quirks

libinput requires extra information from devices that is not always readily
available. For example, some touchpads are known to have jumping cursors
under specific conditions. libinput ships a set of files containting the
so-called model quirks to provide that information. Model quirks are usually
installed under `/usr/share/libinput/<filename>.quirks` and are standard
`.ini` files. A file may contain multiple section headers (`[some
identifier]`) followed by one or more `MatchFoo=Bar` directives, followed by
at least one of `ModelFoo=1` or `AttrFoo=bar` directive. See the
`data/README.md` file in the libinput source repository for more details on
their contents.

@note Model quirks are internal API and may change at any time. No
backwards-compatibility is guaranteed.

For example, a quirks file may have this content to label all keyboards on
the serial bus (PS/2) as internal keyboards:

@verbatim
[Serial Keyboards]
MatchUdevType=keyboard
MatchBus=serial
AttrKeyboardIntegration=internal
@endverbatim

The model quirks are part of the source distribution and should never be
modified locally. Updates to libinput may overwrite modifications or even
stop parsing any property. For temporary local workarounds, see @ref
device-quirks-local.

Device quirks are parsed on libinput initialization. A parsing error in the
device quirks disables **all** device quirks and may negatively impact
device behavior on the host. If the quirks cannot be loaded, an error
message is posted to the log and users should use the information in @ref
device-quirks-debugging to verify their quirks files.

@section device-quirks-local Installing temporary local device quirks

The model quirks are part of the source distribution and should never be
modified. For temporary local workarounds, libinput reads the
`/etc/libinput/local-overrides.quirks` file. Users may add a sections to
this file to add a device quirk for a local device but beware that **any
modification must be upstreamed** or it may cease to work at any time.

@note Model quirks are internal API and may change at any time. No
backwards-compatibility is guaranteed. Local overrides should only be used
until the distribution updates the libinput packages.

The `local-overrides.quirks` file usually needs to be created by the user.
Once the required section has been added, use the information from section
@ref device-quirks-debugging to validate and test the quirks.

@section device-quirks-debugging Debugging device quirks

libinput provides the `libinput quirks` tool to debug the quirks database.
This tool takes an action as first argument, the most common invocation is
`libinput quirks list` to list model quirks that apply to one or more local
devices.

@verbatim
$ libinput quirks list /dev/input/event19
Device has no quirks defined
$ libinput quirks list /dev/input/event0
AttrLidSwitchReliability
@endverbatim

When called with the `--verbose` argument, `libinput quirks list` prints
information about all files and its attempts to match the device:

@verbatim
$ libinput quirks list --verbose /dev/input/event0
quirks debug: /usr/share/share/libinput is data root
quirks debug: /usr/share/share/libinput/10-generic-keyboard.quirks
quirks debug: /usr/share/share/libinput/10-generic-lid.quirks
[...]
quirks debug: /usr/share/etc/libinput/local-overrides.quirks
quirks debug: /dev/input/event0: fetching quirks
quirks debug: [Serial Keyboards] (10-generic-keyboard.quirks) wants MatchBus but we don't have that
quirks debug: [Lid Switch Ct9] (10-generic-lid.quirks) matches for MatchName
quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) matches for MatchName
quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) matches for MatchDMIModalias
quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) is full match
quirks debug: property added: AttrLidSwitchReliability from [Lid Switch Ct10] (10-generic-lid.quirks)
quirks debug: [Aiptek No Tilt Tablet] (30-vendor-aiptek.quirks) wants MatchBus but we don't have that
[...]
quirks debug: [HUION PenTablet] (30-vendor-huion.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech Marble Mouse Trackball] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K400] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K400r] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K830] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K400Plus] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech Wireless Touchpad] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Microsoft Surface 3 Lid Switch] (30-vendor-microsoft.quirks) matches for MatchName
[...]
AttrLidSwitchReliability
@endverbatim

Note that this is an example only, the output may change over time. The tool
uses the same parser as libinput and any parsing errors will show up in the
output.

*/