]>
Commit | Line | Data |
---|---|---|
514094f9 | 1 | <?xml version='1.0'?> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
12b42c76 | 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
0307f791 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1+ --> |
f48f7543 | 5 | |
3715a071 | 6 | <refentry id="hwdb" conditional="ENABLE_HWDB"> |
65eb4378 TG |
7 | <refentryinfo> |
8 | <title>hwdb</title> | |
9 | <productname>systemd</productname> | |
65eb4378 TG |
10 | </refentryinfo> |
11 | ||
12 | <refmeta> | |
13 | <refentrytitle>hwdb</refentrytitle> | |
14 | <manvolnum>7</manvolnum> | |
15 | </refmeta> | |
16 | ||
17 | <refnamediv> | |
18 | <refname>hwdb</refname> | |
19 | <refpurpose>Hardware Database</refpurpose> | |
20 | </refnamediv> | |
21 | ||
22 | <refsect1><title>Description</title> | |
23 | <para>The hardware database is a key-value store for associating modalias-like keys to | |
a8eaaee7 | 24 | udev-property-like values. It is used primarily by udev to add the relevant properties |
65eb4378 TG |
25 | to matching devices, but it can also be queried directly.</para> |
26 | </refsect1> | |
27 | ||
28 | <refsect1><title>Hardware Database Files</title> | |
29 | <para>The hwdb files are read from the files located in the | |
12b42c76 TG |
30 | system hwdb directory <filename>/usr/lib/udev/hwdb.d</filename> and |
31 | the local administration directory <filename>/etc/udev/hwdb.d</filename>. | |
65eb4378 TG |
32 | All hwdb files are collectively sorted and processed in lexical order, |
33 | regardless of the directories in which they live. However, files with | |
34 | identical filenames replace each other. Files in <filename>/etc</filename> | |
12b42c76 TG |
35 | have the highest priority and take precedence over files with the same |
36 | name in <filename>/usr/lib</filename>. This can be used to override a | |
37 | system-supplied hwdb file with a local file if needed; | |
65eb4378 | 38 | a symlink in <filename>/etc</filename> with the same name as a hwdb file in |
12b42c76 | 39 | <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>, |
dc17ee3d | 40 | disables that hwdb file entirely. hwdb files must have the extension |
65eb4378 TG |
41 | <filename>.hwdb</filename>; other extensions are ignored.</para> |
42 | ||
dc17ee3d ZJS |
43 | <para>Each hwdb file contains data records consisting of matches and associated |
44 | key-value pairs. Every record in the hwdb starts with one or more match strings, | |
45 | specifying a shell glob to compare the lookup string against. Multiple match lines | |
46 | are specified in consecutive lines. Every match line is compared individually, and | |
47 | they are combined by OR. Every match line must start at the first character of the | |
48 | line.</para> | |
65eb4378 | 49 | |
dc17ee3d ZJS |
50 | <para>The match lines are followed by one or more key-value pair lines, which are |
51 | recognized by a leading space character. The key name and value are separated by | |
52 | <literal>=</literal>. An empty line signifies the end of a record. Lines beginning | |
53 | with <literal>#</literal> are ignored.</para> | |
54 | ||
55 | <para>In case multiple records match a given lookup string, the key-value pairs | |
56 | from all records are combined. If a key is specified multiple times, the value | |
57 | from the record with the highest priority is used (each key can have only a single | |
58 | value). The priority is higher when the record is in a file that sorts later | |
59 | lexicographically, and in case of records in the same file, later records have | |
60 | higher priority.</para> | |
65eb4378 TG |
61 | |
62 | <para>The content of all hwdb files is read by | |
63 | <citerefentry><refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
64 | and compiled to a binary database located at <filename>/etc/udev/hwdb.bin</filename>, | |
dc17ee3d ZJS |
65 | or alternatively <filename>/usr/lib/udev/hwdb.bin</filename> if you want ship the |
66 | compiled database in an immutable image. During runtime, only the binary database | |
67 | is used.</para> | |
68 | </refsect1> | |
69 | ||
70 | <refsect1> | |
71 | <title>Examples</title> | |
72 | ||
73 | <example> | |
74 | <title>General syntax of hwdb files</title> | |
75 | ||
76 | <programlisting># /usr/lib/udev/hwdb.d/example.hwdb | |
77 | # Comments can be placed before any records. This is a good spot | |
78 | # to describe what that file is used for, what kind of properties | |
79 | # it defines, and the ordering convention. | |
80 | ||
81 | # A record with three matches and one property | |
82 | mouse:*:name:*Trackball*: | |
83 | mouse:*:name:*trackball*: | |
84 | mouse:*:name:*TrackBall*: | |
85 | ID_INPUT_TRACKBALL=1 | |
86 | ||
87 | # A record with a single match and five properties | |
88 | mouse:usb:v046dp4041:name:Logitech MX Master: | |
89 | MOUSE_DPI=1000@166 | |
90 | MOUSE_WHEEL_CLICK_ANGLE=15 | |
91 | MOUSE_WHEEL_CLICK_ANGLE_HORIZONTAL=26 | |
92 | MOUSE_WHEEL_CLICK_COUNT=24 | |
93 | MOUSE_WHEEL_CLICK_COUNT_HORIZONTAL=14 | |
94 | </programlisting> | |
95 | </example> | |
96 | ||
97 | <example> | |
98 | <title>Overriding of properties</title> | |
99 | ||
100 | <programlisting># /usr/lib/udev/hwdb.d/60-keyboard.hwdb | |
101 | evdev:atkbd:dmi:bvn*:bvr*:bd*:svnAcer*:pn* | |
102 | KEYBOARD_KEY_a1=help | |
103 | KEYBOARD_KEY_a2=setup | |
104 | KEYBOARD_KEY_a3=battery | |
105 | ||
106 | evdev:atkbd:dmi:bvn*:bvr*:bd*:svnAcer*:pn123* | |
107 | KEYBOARD_KEY_a2=wlan | |
108 | ||
109 | # /etc/udev/hwdb.d/70-keyboard.hwdb | |
110 | # disable wlan key on all at keyboards | |
111 | evdev:atkbd:* | |
112 | KEYBOARD_KEY_a2=reserved</programlisting> | |
113 | ||
114 | <para>If the hwdb consists of those two files, a keyboard with the lookup string | |
115 | <literal>evdev:atkbd:dmi:bvnAcer:bdXXXXX:bd08/05/2010:svnAcer:pn123</literal> | |
116 | will match all three records, and end up with the following properties:</para> | |
117 | ||
118 | <programlisting>KEYBOARD_KEY_a1=help | |
119 | KEYBOARD_KEY_a2=reserved | |
120 | KEYBOARD_KEY_a3=battery</programlisting> | |
121 | </example> | |
65eb4378 TG |
122 | </refsect1> |
123 | ||
124 | <refsect1> | |
125 | <title>See Also</title> | |
126 | <para> | |
127 | <citerefentry> | |
128 | <refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum> | |
129 | </citerefentry> | |
130 | </para> | |
131 | </refsect1> | |
132 | </refentry> |