1libinput quirks file format 2=========================== 3 4This directory contains hardware quirks used by libinput to work around bugs 5in the hardware, device behavior and to supply information not obtained 6through the kernel device. 7 8**THIS IS NOT STABLE API** 9 10The data format may change at any time. If your quirks file is not part of 11the libinput git tree, do not expect it to work after an update. Absolutely 12no guarantees are made for backwards-compatibility. 13 14**THIS IS NOT A CONFIGURATION API** 15 16Use the `libinput_device_config_foo()` functions for device configuration. 17Quirks here are hardware quirks only. 18 19Data file naming 20---------------- 21 22Data files are read in versionsort order, read order determines how values 23override each other. Values read later override previously read values. The 24current structure is: 25- `10-generic-foo.quirks` for generic settings, 26- `30-vendor-foo.quirks` for vendor-specific settings, and 27- `50-system-foo.quirks` for system vendors. 28 29This is not a fixed naming scheme and may change at any time. It's an 30approximation only because some vendors are also system vendors, e.g. 31Microsoft makes devices and laptops. 32 33Laptop-specific quirks should always go into the laptop vendor's file even 34where they apply to a component of a different vendor. For example, a quirk 35for a Synaptics touchpad specific to a Dell laptop should go into the Dell 36quirks file. 37 38Sections, matches and values 39---------------------------- 40 41A data file must contain at least one section, each section must have at 42least one `Match` tag and at least one of either `Attr` or `Model`. Section 43names are free-form and may contain spaces. 44 45``` 46# This is a comment 47[Some touchpad] 48MatchBus=usb 49# No quotes around strings 50MatchName=*Synaptics Touchpad* 51AttrSizeHint=50x50 52ModelSynapticsTouchpad=1 53 54[Apple touchpad] 55MatchVendor=0x5AC 56MatchProduct=0x123 57ModelAppleTouchpad=1 58``` 59 60Comments are lines starting with `#`. 61 62All `Model` tags take a value of either `1` or `0`. 63 64All `Attr` tag values are specific to that attribute. 65 66Parser errors 67------------- 68 69The following requirements must be met: 70 71* No whitespace is allowed at the beginning of the line 72* A Section must have at least one `Match*` entry 73* A Section must not repeat `Match*` entry 74* A Section must have at least one of `Model*` or `Attr*` entries 75* A `Model` tag may only have the value `1` or `0` 76* String properties must not be enclosed in quotes 77* Hex numbers must use uppercase letters (e.g. `0x12AB`) 78 79Failure to meet these requirements will cause a parser error and the quirks 80files will not be used. 81 82Debugging 83--------- 84 85When modifying a data file, use the `libinput list-quirks` tool to 86verify the changes. The tool can be pointed at the data directory to 87analyse, use `--verbose` to get more info. For example: 88 89``` 90libinput list-quirks --data-dir /path/to/git/repo/quirks/ --verbose /dev/input/event0 91``` 92