1 DRIVER.CONF(4) File Formats and Configurations DRIVER.CONF(4)
2
3
4
5 NAME
6 driver.conf - driver configuration files
7
8 SYNOPSIS
9 driver.conf
10
11
12 DESCRIPTION
13 Driver configuration files provide values for device properties. The
14 values override values provided by the devices themselves. Most modern
15 devices provide enough property values to make a driver configuration
16 file unnecessary.
17
18
19 The system associates a driver with its configuration file by name. For
20 example, a driver in /usr/kernel/drv called wombat has the driver
21 configuration file wombat.conf, also stored in /usr/kernel/drv,
22 associated with it. On systems that support 64-bit drivers, the driver
23 configuration file should be placed in the directory in which the
24 32-bit driver is (or would be) located, even if only a 64-bit version
25 is provided. For example, a 64-bit driver stored in
26 /usr/kernel/drv/sparcv9 stores its driver configuration file in
27 /usr/kernel/drv.
28
29
30 The value of the name property is the node name. In a driver.conf file,
31 where the generic node name and compatible property associated with a
32 self-identifying devices are typically not used, the node name must be
33 a binding name. The binding name is the name chosen by the system to
34 bind a driver to the device. The binding name is either an alias
35 associated with the driver established by add_drv(1M) or the driver
36 name itself.
37
38
39 The syntax of a single entry in a driver configuration file takes one
40 of three forms:
41
42 name="node name" parent="parent name" [property-name=value ...];
43
44
45
46 In this form, the parent name can be either the binding name of the
47 parent nexus driver or a specific full pathname, beginning with a slash
48 (/) character, identifying a specific instance of a parent bus. If a
49 binding name is used then all parent nodes bound to that driver match.
50 A generic name (for example, pci) is not a valid binding name even
51 though it can appear in the full pathname of all intended parents.
52
53
54 Alternatively, the parent can be specified by the type of interface it
55 presents to its children.
56
57 name="node name" class="class name" [property-name=value ...];
58
59
60
61 For example, the driver for the SCSI host adapter can have different
62 names on different platforms, but the target drivers can use class scsi
63 to insulate themselves from these differences.
64
65
66 Entries of either form above correspond to a device information
67 (devinfo) node in the kernel device tree. Each node has a name which is
68 usually the name of the driver, and a parent name which is the name of
69 the parent devinfo node to which it will be connected. Any number of
70 name-value pairs can be specified to create properties on the prototype
71 devinfo node. These properties can be retrieved using the DDI property
72 interfaces (for example, ddi_prop_get_int(9F) and ddi_prop_lookup(9F)).
73 The prototype devinfo node specification must be terminated with a
74 semicolon (;).
75
76
77 The third form of an entry is simply a list of properties.
78
79 [property-name=value ...];
80
81
82
83
84 A property created in this way is treated as global to the driver. It
85 can be overridden by a property with the same name on a particular
86 devinfo node, either by creating one explicitly on the prototype node
87 in the driver.conf file or by the driver.
88
89
90 Items are separated by any number of newlines, SPACE or TAB characters.
91
92
93 The configuration file can contain several entries to specify different
94 device configurations and parent nodes. The system can call the driver
95 for each possible prototype devinfo node, and it is generally the
96 responsibility of the drivers probe(9E) routine to determine if the
97 hardware described by the prototype devinfo node is really present.
98
99
100 Property names must not violate the naming conventions for Open Boot
101 PROM properties or for IEEE 1275 names. In particular, property names
102 should contain only printable characters, and should not contain at-
103 sign (@), slash (/), backslash (\), colon (:), or square brackets ([]).
104 Property values can be decimal integers or strings delimited by double
105 quotes ("). Hexadecimal integers can be constructed by prefixing the
106 digits with 0x.
107
108
109 A comma separated list of integers can be used to construct properties
110 whose value is an integer array. The value of such properties can be
111 retrieved inside the driver using ddi_prop_lookup_int_array(9F).
112
113
114 Comments are specified by placing a # character at the beginning of the
115 comment string, the comment string extends for the rest of the line.
116
117 EXAMPLES
118 Example 1 Configuration File for a PCI Bus Frame Buffer
119
120
121 The following is an example of a configuration file called
122 ACME,simple.conf for a PCI bus frame buffer called ACME,simple.
123
124
125 #
126 # Copyright (c) 1993, by ACME Fictitious Devices, Inc.
127 #
128 #ident "@(#)ACME,simple.conf 1.3 1999/09/09"
129
130 name="ACME,simple" class="pci" unit-address="3,1"
131 debug-mode=12;
132
133
134
135 This example creates a prototype devinfo node called ACME,simple under
136 all parent nodes of class pci. The node has device and function numbers
137 of 3 and 1, respectively; the property debug-mode is provided for all
138 instances of the driver.
139
140
141 Example 2 Configuration File for a Pseudo Device Driver
142
143
144 The following is an example of a configuration file called
145 ACME,example.conf for a pseudo device driver called ACME,example.
146
147
148 #
149 # Copyright (c) 1993, ACME Fictitious Devices, Inc.
150 #
151 #ident "@(#)ACME,example.conf 1.2 93/09/09"
152 name="ACME,example" parent="pseudo" instance=0
153 debug-level=1;
154
155 name="ACME,example" parent="pseudo" instance=1;
156
157 whizzy-mode="on";
158 debug-level=3;
159
160
161
162 This creates two devinfo nodes called ACME,example which attaches below
163 the pseudo node in the kernel device tree. The instance property is
164 only interpreted by the pseudo node, see pseudo(4) for further details.
165 A property called debug-level is created on the first devinfo node
166 which has the value 1. The example driver is able to fetch the value of
167 this property using ddi_prop_get_int(9F).
168
169
170
171 Two global driver properties are created, whizzy-mode (which has the
172 string value "on") and debug-level (which has the value 3). If the
173 driver looks up the property whizzy-mode on either node, it retrieves
174 the value of the global whizzy-mode property ("on"). If the driver
175 looks up the debug-level property on the first node, it retrieves the
176 value of the debug-level property on that node (1). Looking up the same
177 property on the second node retrieves the value of the global debug-
178 level property (3).
179
180
181 SEE ALSO
182 add_drv(1M), pci(4), pseudo(4), sbus(4), scsi(4), probe(9E),
183 ddi_getlongprop(9F), ddi_getprop(9F), ddi_getproplen(9F),
184 ddi_prop_get_int(9F), ddi_prop_lookup(9F), ddi_prop_op(9F)
185
186
187 Writing Device Drivers
188
189 WARNINGS
190 To avoid namespace collisions between multiple driver vendors, it is
191 strongly recommended that the name property of the driver should begin
192 with a vendor-unique string. A reasonably compact and unique choice is
193 the vendor over-the-counter stock symbol.
194
195 NOTES
196 The update_drv(1M) command should be used to prompt the kernel to
197 reread driver.conf files.
198
199
200
201 September 16, 2018 DRIVER.CONF(4)