Debian Codegraph @

doc/user/device-quirks.rst

raw
1 .. _device-quirks:
2
3 ==============================================================================
4 Device quirks
5 ==============================================================================
6
7 libinput requires extra information from devices that is not always readily
8 available. For example, some touchpads are known to have jumping cursors
9 under specific conditions. libinput ships a set of files containing the
10 so-called model quirks to provide that information. Model quirks are usually
11 installed under ``/usr/share/libinput/<filename>.quirks`` and are standard
12 ``.ini`` files. A file may contain multiple section headers (``[some
13 identifier]``) followed by one or more :ref:`MatchFoo=Bar <device-quirks-matches>`
14 directives, followed by at least one of ``ModelFoo=1`` or ``AttrFoo=bar`` directive.
15 See the ``quirks/README.md`` file in the libinput source repository for more
16 details on their contents.
17
18 .. warning:: Model quirks are internal API and may change at any time. No
19 backwards-compatibility is guaranteed.
20
21 For example, a quirks file may have this content to label all keyboards on
22 the serial bus (PS/2) as internal keyboards: ::
23
24 [Serial Keyboards]
25 MatchUdevType=keyboard
26 MatchBus=serial
27 AttrKeyboardIntegration=internal
28
29
30 The model quirks are part of the source distribution and should never be
31 modified locally. Updates to libinput may overwrite modifications or even
32 stop parsing any property. For temporary local workarounds, see
33 :ref:`device-quirks-local`.
34
35 Device quirks are parsed on libinput initialization. A parsing error in the
36 device quirks disables **all** device quirks and may negatively impact
37 device behavior on the host. If the quirks cannot be loaded, an error
38 message is posted to the log and users should use the information in
39 :ref:`device-quirks-debugging` to verify their quirks files.
40
41 .. _device-quirks-local:
42
43 ------------------------------------------------------------------------------
44 Installing temporary local device quirks
45 ------------------------------------------------------------------------------
46
47 The model quirks are part of the source distribution and should never be
48 modified. For temporary local workarounds, libinput reads the
49 ``/etc/libinput/local-overrides.quirks`` file. Users may add a sections to
50 this file to add a device quirk for a local device but beware that **any
51 modification must be upstreamed** or it may cease to work at any time.
52
53 .. warning:: Model quirks are internal API and may change at any time. No
54 backwards-compatibility is guaranteed. Local overrides should only
55 be used until the distribution updates the libinput packages.
56
57 The ``local-overrides.quirks`` file usually needs to be created by the user.
58 Once the required section has been added, use the information from section
59 :ref:`device-quirks-debugging` to validate and test the quirks.
60
61 .. _device-quirks-debugging:
62
63 ------------------------------------------------------------------------------
64 Debugging device quirks
65 ------------------------------------------------------------------------------
66
67 libinput provides the ``libinput quirks`` tool to debug the quirks database.
68 This tool takes an action as first argument, the most common invocation is
69 ``libinput quirks list`` to list model quirks that apply to one or more local
70 devices. ::
71
72 $ libinput quirks list /dev/input/event19
73 $ libinput quirks list /dev/input/event0
74 AttrLidSwitchReliability=unreliable
75
76 The device `event19` does not have any quirks assigned.
77
78 When called with the ``--verbose`` argument, ``libinput quirks list`` prints
79 information about all files and its attempts to match the device: ::
80
81 $ libinput quirks list --verbose /dev/input/event0
82 quirks debug: /usr/share/share/libinput is data root
83 quirks debug: /usr/share/share/libinput/10-generic-keyboard.quirks
84 quirks debug: /usr/share/share/libinput/10-generic-lid.quirks
85 [...]
86 quirks debug: /usr/share/etc/libinput/local-overrides.quirks
87 quirks debug: /dev/input/event0: fetching quirks
88 quirks debug: [Serial Keyboards] (10-generic-keyboard.quirks) wants MatchBus but we don't have that
89 quirks debug: [Lid Switch Ct9] (10-generic-lid.quirks) matches for MatchName
90 quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) matches for MatchName
91 quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) matches for MatchDMIModalias
92 quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) is full match
93 quirks debug: property added: AttrLidSwitchReliability from [Lid Switch Ct10] (10-generic-lid.quirks)
94 quirks debug: [Aiptek No Tilt Tablet] (30-vendor-aiptek.quirks) wants MatchBus but we don't have that
95 [...]
96 quirks debug: [HUION PenTablet] (30-vendor-huion.quirks) wants MatchBus but we don't have that
97 quirks debug: [Logitech Marble Mouse Trackball] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
98 quirks debug: [Logitech K400] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
99 quirks debug: [Logitech K400r] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
100 quirks debug: [Logitech K830] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
101 quirks debug: [Logitech K400Plus] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
102 quirks debug: [Logitech Wireless Touchpad] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
103 quirks debug: [Microsoft Surface 3 Lid Switch] (30-vendor-microsoft.quirks) matches for MatchName
104 [...]
105 AttrLidSwitchReliability
106
107
108 Note that this is an example only, the output may change over time. The tool
109 uses the same parser as libinput and any parsing errors will show up in the
110 output.
111
112 .. _device-quirks-list:
113
114 ------------------------------------------------------------------------------
115 List of currently available device quirks
116 ------------------------------------------------------------------------------
117
118 This list is a guide for developers to ease the process of submitting
119 patches upstream. This section shows device quirks currently available in
120 |git_version|.
121
122 .. warning:: Quirks are internal API and may change at any time for any reason.
123 No guarantee is given that any quirk below works on your version of
124 libinput.
125
126 In the documentation below, the letters N, M, O, P refer to arbitrary integer
127 values.
128
129 Quirks starting with **Model*** triggers implementation-defined behaviour
130 for this device not needed for any other device. Only the more
131 general-purpose **Model*** flags are listed here.
132
133 ModelALPSTouchpad, ModelAppleTouchpad, ModelWacomTouchpad, ModelChromebook
134 Reserved for touchpads made by the respective vendors
135 ModelTouchpadVisibleMarker
136 Indicates the touchpad has a drawn-on visible marker between the software
137 buttons.
138 ModelTabletModeNoSuspend
139 Indicates that the device does not need to be
140 suspended in :ref:`switches_tablet_mode`.
141 ModelTabletModeSwitchUnreliable
142 Indicates that this tablet mode switch's state cannot be relied upon.
143 ModelTrackball
144 Reserved for trackballs
145 ModelBouncingKeys
146 Indicates that the device may send fake bouncing key events and
147 timestamps can not be relied upon.
148 ModelSynapticsSerialTouchpad
149 Reserved for touchpads made by Synaptics on the serial bus
150 ModelPressurePad
151 .. warning:: This quirk is no longer in use. Use
152 ``AttrInputProp=+INPUT_PROP_PRESSUREPAD`` instead.
153
154 Unlike in traditional touchpads, whose pressure value equals contact size,
155 on pressure pads pressure is a real physical axis.
156 Indicates that the device is a pressure pad.
157 ModelTouchpadPhantomClicks
158 Some laptops are prone to registering touchpad clicks when the case is
159 bent. Indicates that clicks should be ignored if no fingers are on the
160 touchpad.
161 ModelScrollOnMiddleClick
162 Some mice can generate unwanted high-resolution scroll events when the wheel
163 is pressed. Increases the scroll threshold required to start scrolling to
164 avoid accidentally scrolling when middle clicking.
165 AttrSizeHint=NxM, AttrResolutionHint=N
166 Hints at the width x height of the device in mm, or the resolution
167 of the x/y axis in units/mm. These may only be used where they apply to
168 a large proportion of matching devices. They should not be used for any
169 specific device, override ``EVDEV_ABS_*`` instead, see
170 :ref:`absolute_coordinate_ranges_fix`.
171 AttrTouchSizeRange=N:M, AttrPalmSizeThreshold=O
172 Specifies the touch size required to trigger a press (N) and to trigger
173 a release (M). O > N > M. See :ref:`touchpad_touch_size_hwdb` for more
174 details.
175 An AttrPalmSizeThreshold of zero unsets any threshold that has been
176 inherited from another quirk.
177 AttrPressureRange=N:M, AttrPalmPressureThreshold=O, AttrThumbPressureThreshold=P
178 Specifies the touch pressure required to trigger a press (N) and to
179 trigger a release (M), when a palm touch is triggered (O) and when a
180 thumb touch is triggered (P). O > P > N > M. See
181 :ref:`touchpad_pressure_hwdb` for more details.
182 An AttrPalmPressureThreshold of zero unsets any threshold that has been
183 inherited from another quirk.
184 AttrLidSwitchReliability=reliable|unreliable|write_open
185 Indicates the reliability of the lid switch. This is a string enum.
186 Very few devices need this, if in doubt do not set. See :ref:`switches_lid`
187 for details. libinput 1.21.0 changed the default from unreliable to
188 reliable, which may be removed from local overrides.
189 AttrKeyboardIntegration=internal|external
190 Indicates the integration of the keyboard. This is a string enum.
191 Generally only needed for USB keyboards.
192 AttrTPKComboLayout=below
193 Indicates the position of the touchpad on an external touchpad+keyboard
194 combination device. This is a string enum. Don't specify it unless the
195 touchpad is below.
196 AttrEventCode=+EV_ABS;-BTN_STYLUS;+EV_KEY:0x123;
197 Enables or disables the evdev event type/code tuples on the device. The prefix
198 for each entry is either '+' (enable) or '-' (disable). Entries may be
199 a named event type, or a named event code, or a named event type with a
200 hexadecimal event code, separated by a single colon.
201 AttrInputProp=+INPUT_PROP_BUTTONPAD;-INPUT_PROP_POINTER;
202 Enables or disables the evdev input property on the device. The prefix
203 for each entry is either '+' (enable) or '-' (disable). Entries may be
204 a named input property or the hexadecimal value of that property.
205
206 The most common use of this is ``AttrInputProp=+INPUT_PROP_PRESSUREPAD``
207 which marks a touchpad as a :ref:`forcepad or pressurepad <touchpads_buttons_forcepads>`.
208 AttrPointingStickIntegration=internal|external
209 Indicates the integration of the pointing stick. This is a string enum.
210 Only needed for external pointing sticks. These are rare.
211 AttrTabletSmoothing=1|0
212 Enables (1) or disables (0) input smoothing for tablet devices. Smoothing is enabled
213 by default, except on AES devices.
214
215 .. _device-quirks-matches:
216
217 ------------------------------------------------------------------------------
218 List of currently available matches
219 ------------------------------------------------------------------------------
220
221 ``Match*`` statements are how quirks are assigned to a device. Quirks with multiple
222 match statements must match all of those to apply.
223
224 .. warning:: Quirks are internal API and may change at any time for any reason.
225 No guarantee is given that any ``Match`` statement below works on
226 your version of libinput.
227
228 MatchName, MatchUniq
229 Match on the ``NAME`` or ``UNIQ`` udev property on this device. These properties
230 are typically derived from the device's kernel name or uniq but may be overridden
231 by a udev rule. These matches use ``fnmatch()`` globs.
232 MatchBus
233 A lower-case bus name. Currently supported are ``usb``, ``bluetooth``, ``ps2``,
234 ``rmi``, ``i2c``, and ``spi``.
235 MatchVendor, MatchProduct, MatchVersion
236 The hexadecimal 4-digit vendor ID, product ID or driver version as
237 exported, uppercase with a ``0x`` prefix, e.g. ``0x12AB```.
238 MatchDMIModalias, MatchDeviceTree
239 An ``fnmatch()`` glob for the DMI modalias or the DeviceTree ``compatible`` string.
240 See ``/sys/class/dmi/id/modalias`` and ``/sys/firmware/devicetree/base/compatible``.
241 MatchUdevType
242 One of ``touchpad``, ``mouse``, ``pointingstick``, ``keyboard``, ``joystick``,
243 ``tablet``, ``tablet-pad``. Matches the corresponding ``ID_INPUT_*`` udev
244 property.