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