From: Peter Hutterer Date: Tue, 2 Feb 2021 01:54:14 +0000 (+1000) Subject: quirks: improve the README X-Git-Tag: 1.16.902~33 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=14bec5b64e2454535484b47d61e39090d3b00c10;p=platform%2Fupstream%2Flibinput.git quirks: improve the README Make the headers valid markdown and reword/reformat a few other things to make it clearer and easier to read. Signed-off-by: Peter Hutterer --- diff --git a/quirks/README.md b/quirks/README.md index 55b9056f..4ff3e81b 100644 --- a/quirks/README.md +++ b/quirks/README.md @@ -1,4 +1,5 @@ -= libinput data file format = +libinput quirks file format +=========================== This directory contains hardware quirks used by libinput to work around bugs in the hardware, device behavior and to supply information not obtained @@ -6,28 +7,36 @@ through the kernel device. **THIS IS NOT STABLE API** -The data format may change at any time. If your data file is not part of the -libinput git tree, do not expect it to work after an update. Absolutely no -guarantees are made for backwards-compatibility. +The data format may change at any time. If your quirks file is not part of +the libinput git tree, do not expect it to work after an update. Absolutely +no guarantees are made for backwards-compatibility. **THIS IS NOT A CONFIGURATION API** Use the `libinput_device_config_foo()` functions for device configuration. -The quirks are hardware quirks only. +Quirks here are hardware quirks only. -== Data file naming == +Data file naming +---------------- Data files are read in versionsort order, read order determines how values -override each other. A values read later override previously values. The -current structure is 10-generic-foo.quirks for generic settings, -30-vendor-foo.quirks for vendor-specific settings and 50-system-foo.quirks -for system vendors. This is not a fixed naming scheme and may change at any -time. It's an approximation only because some vendors are also system -vendors, e.g. Microsoft makes devices and laptops. +override each other. Values read later override previously read values. The +current structure is: +- `10-generic-foo.quirks` for generic settings, +- `30-vendor-foo.quirks` for vendor-specific settings, and +- `50-system-foo.quirks` for system vendors. -Laptop-specific quirks should always go into the laptop vendor's file. +This is not a fixed naming scheme and may change at any time. It's an +approximation only because some vendors are also system vendors, e.g. +Microsoft makes devices and laptops. -== Sections, matches and values == +Laptop-specific quirks should always go into the laptop vendor's file even +where they apply to a component of a different vendor. For example, a quirk +for a Synaptics touchpad specific to a Dell laptop should go into the Dell +quirks file. + +Sections, matches and values +---------------------------- A data file must contain at least one section, each section must have at least one `Match` tag and at least one of either `Attr` or `Model`. Section @@ -54,24 +63,26 @@ All `Model` tags take a value of either `1` or `0`. All `Attr` tag values are specific to that attribute. -== Parser errors == +Parser errors +------------- The following will cause parser errors and are considered invalid data files: * Whitespace at the beginning of the line -* Sections without at least one `Match*` entry +* Sections without a `Match*` entry * Sections with the same `Match*` entry repeated * Sections without at least one of `Model*` or `Attr` entries * A `Model` tag with a value other than `1` or `0` * A string property with enclosing quotes -== Debugging == +Debugging +--------- When modifying a data file, use the `libinput list-quirks` tool to verify the changes. The tool can be pointed at the data directory to analyse, use `--verbose` to get more info. For example: ``` -libinput list-quirks --data-dir /path/to/git/repo/data/ --verbose /dev/input/event0 +libinput list-quirks --data-dir /path/to/git/repo/quirks/ --verbose /dev/input/event0 ```