| 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. |