1.. _device-quirks: 2 3============================================================================== 4Device quirks 5============================================================================== 6 7libinput requires extra information from devices that is not always readily 8available. For example, some touchpads are known to have jumping cursors 9under specific conditions. libinput ships a set of files containing the 10so-called model quirks to provide that information. Model quirks are usually 11installed under ``/usr/share/libinput/<filename>.quirks`` and are standard 12``.ini`` files. A file may contain multiple section headers (``[some 13identifier]``) followed by one or more ``MatchFoo=Bar`` directives, followed by 14at least one of ``ModelFoo=1`` or ``AttrFoo=bar`` directive. See the 15``quirks/README.md`` file in the libinput source repository for more details on 16their contents. 17 18.. warning:: Model quirks are internal API and may change at any time. No 19 backwards-compatibility is guaranteed. 20 21For example, a quirks file may have this content to label all keyboards on 22the serial bus (PS/2) as internal keyboards: :: 23 24 [Serial Keyboards] 25 MatchUdevType=keyboard 26 MatchBus=serial 27 AttrKeyboardIntegration=internal 28 29 30The model quirks are part of the source distribution and should never be 31modified locally. Updates to libinput may overwrite modifications or even 32stop parsing any property. For temporary local workarounds, see 33:ref:`device-quirks-local`. 34 35Device quirks are parsed on libinput initialization. A parsing error in the 36device quirks disables **all** device quirks and may negatively impact 37device behavior on the host. If the quirks cannot be loaded, an error 38message 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------------------------------------------------------------------------------ 44Installing temporary local device quirks 45------------------------------------------------------------------------------ 46 47The model quirks are part of the source distribution and should never be 48modified. For temporary local workarounds, libinput reads the 49``/etc/libinput/local-overrides.quirks`` file. Users may add a sections to 50this file to add a device quirk for a local device but beware that **any 51modification 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 57The ``local-overrides.quirks`` file usually needs to be created by the user. 58Once 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------------------------------------------------------------------------------ 64Debugging device quirks 65------------------------------------------------------------------------------ 66 67libinput provides the ``libinput quirks`` tool to debug the quirks database. 68This 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 70devices. :: 71 72 $ libinput quirks list /dev/input/event19 73 $ libinput quirks list /dev/input/event0 74 AttrLidSwitchReliability=reliable 75 76The device `event19` does not have any quirks assigned. 77 78When called with the ``--verbose`` argument, ``libinput quirks list`` prints 79information 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 108Note that this is an example only, the output may change over time. The tool 109uses the same parser as libinput and any parsing errors will show up in the 110output. 111 112.. _device-quirks-list: 113 114------------------------------------------------------------------------------ 115List of supported device quirks 116------------------------------------------------------------------------------ 117 118This list is a guide for developers to ease the process of submitting 119patches upstream. This section shows device quirks supported 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 126In the documentation below, the letters N, M, O, P refer to arbitrary integer 127values. 128 129Quirks starting with **Model*** triggers implementation-defined behaviour 130for this device not needed for any other device. Only the more 131general-purpose **Model*** flags are listed here. 132 133ModelALPSTouchpad, ModelAppleTouchpad, ModelWacomTouchpad, ModelChromebook 134 Reserved for touchpads made by the respective vendors 135ModelTouchpadVisibleMarker 136 Indicates the touchpad has a drawn-on visible marker between the software 137 buttons. 138ModelTabletModeNoSuspend 139 Indicates that the device does not need to be 140 suspended in :ref:`switches_tablet_mode`. 141ModelTabletModeSwitchUnreliable 142 Indicates that this tablet mode switch's state cannot be relied upon. 143ModelTrackball 144 Reserved for trackballs 145ModelBouncingKeys 146 Indicates that the device may send fake bouncing key events and 147 timestamps can not be relied upon. 148ModelSynapticsSerialTouchpad 149 Reserved for touchpads made by Synaptics on the serial bus 150AttrSizeHint=NxM, AttrResolutionHint=N 151 Hints at the width x height of the device in mm, or the resolution 152 of the x/y axis in units/mm. These may only be used where they apply to 153 a large proportion of matching devices. They should not be used for any 154 specific device, override ``EVDEV_ABS_*`` instead, see 155 :ref:`absolute_coordinate_ranges_fix`. 156AttrTouchSizeRange=N:M, AttrPalmSizeThreshold=O 157 Specifies the touch size required to trigger a press (N) and to trigger 158 a release (M). O > N > M. See :ref:`touchpad_touch_size_hwdb` for more 159 details. 160AttrPressureRange=N:M, AttrPalmPressureThreshold=O, AttrThumbPressureThreshold=P 161 Specifies the touch pressure required to trigger a press (N) and to 162 trigger a release (M), when a palm touch is triggered (O) and when a 163 thumb touch is triggered (P). O > P > N > M. See 164 :ref:`touchpad_pressure_hwdb` for more details. 165AttrLidSwitchReliability=reliable|write_open 166 Indicates the reliability of the lid switch. This is a string enum. Do not 167 use "reliable" for any specific device. Very few devices need this, if in 168 doubt do not set. See :ref:`switches_lid` for details. 169AttrKeyboardIntegration=internal|external 170 Indicates the integration of the keyboard. This is a string enum. 171 Generally only needed for USB keyboards. 172AttrTPKComboLayout=below 173 Indicates the position of the touchpad on an external touchpad+keyboard 174 combination device. This is a string enum. Don't specify it unless the 175 touchpad is below. 176AttrEventCodeDisable=EV_ABS;BTN_STYLUS;EV_KEY:0x123; 177 Disables the evdev event type/code tuples on the device. Entries may be 178 a named event type, or a named event code, or a named event type with a 179 hexadecimal event code, separated by a single colon. 180AttrEventCodeEnable=EV_ABS;BTN_STYLUS;EV_KEY:0x123; 181 Enables the evdev event type/code tuples on the device. Entries may be 182 a named event type, or a named event code, or a named event type with a 183 hexadecimal event code, separated by a single colon. 184AttrInputPropDisable=INPUT_PROP_BUTTONPAD;INPUT_PROP_POINTER; 185 Disables the evdev input property on the device. Entries may be 186 a named input property or the hexadecimal value of that property. 187AttrInputPropEnable=INPUT_PROP_BUTTONPAD;INPUT_PROP_POINTER; 188 Enables the evdev input property on the device. Entries may be 189 a named input property or the hexadecimal value of that property. 190AttrPointingStickIntegration=internal|external 191 Indicates the integration of the pointing stick. This is a string enum. 192 Only needed for external pointing sticks. These are rare. 193AttrTabletSmoothing=1|0 194 Enables (1) or disables (0) input smoothing for tablet devices. Smoothing is enabled 195 by default, except on AES devices. 196