| blob | df18e02ecee2922e58fbf7f05a4e21ac84fe9865 |
1 .\" $NetBSD: config.9,v 1.25 2008/04/30 13:10:58 martin Exp $
2 .\"
3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Gregory McGarry.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd August 19, 2003
31 .Dt CONFIG 9
32 .Os
33 .Sh NAME
34 .Nm config
35 .Nd the autoconfiguration framework
36 .Do
37 device definition
38 .Dc
39 language
40 .Sh DESCRIPTION
41 In
42 .Nx ,
43 the
44 .Xr config 1
45 program reads and verifies a machine description file (documented in
46 .Xr config 5 )
47 that specifies the devices to include in the kernel.
48 A table is produced by
49 .Xr config 1
50 which is used by the kernel during autoconfiguration (see
51 .Xr autoconf 9 )
52 giving needed hints and details on matching hardware devices with
53 device drivers.
54 .Pp
55 Each device in the machine description file has:
56 .Bl -tag -width xxxxxx
57 .It A Name
58 The name is simply an alphanumeric string that ends in a unit number
59 (e.g., "sd0", "sd1", and so forth).
60 These unit numbers identify particular instances of a base device name;
61 the base name in turn maps directly to a device driver.
62 Device unit numbers are independent of hardware features.
63 .It A Parent
64 Every device must have a parent.
65 The pairing is denoted by "child at parent".
66 These pairings form the links in a directed graph.
67 The root device is the only exception, as it does not have a parent.
68 .It Locators
69 Locators are used to augment the parent/child pairings that locate
70 specific devices.
71 Each locator value is simply an integer that represents some sort of
72 device address on the parent bus or controller.
73 This can be a memory address, an I/O port, a driver number, or any
74 other value.
75 Locators can sometimes be wildcarded on devices that support direct
76 connection.
77 .It Attributes
78 An attribute describes the device's relationship with the code; it
79 then serves to constrain the device graph.
80 A
81 .Em plain attribute
82 describes some attribute of a device.
83 An
84 .Em interface attribute
85 describes a kind of
86 .Do
87 software interface
88 .Dc
89 and declares the device's ability to support other devices that use
90 that interface.
91 In addition, an interface attribute usually identifies additional locators.
92 .El
93 .Pp
94 During autoconfiguration, the directed graph is turned into a tree by
95 nominating one device as the root node and matching drivers with
96 devices by doing a depth-first traversal through the graph starting at
97 this root node.
98 .Pp
99 However, there must be constraints on the parent/child pairings that
100 are possible.
101 These constraints are embedded in the
102 .Do
103 device definition
104 .Dc
105 files.
106 The remainder of this page describes the
107 .Do
108 device definition
109 .Dc
110 language and how to use this language to add new functionality to the
111 .Nx
112 kernel.
113 .Sh DEVICE DEFINITION FILES
114 The device definition files are separated into machine-dependent and
115 machine-independent files.
116 The machine-dependent file is located in
117 .Pa sys/arch/\*[Lt]arch\*[Gt]/conf/files.\*[Lt]arch\*[Gt] ,
118 where \*[Lt]arch\*[Gt] is the name of
119 .Nx
120 architecture.
121 The machine-independent file is located in
122 .Pa sys/conf/files .
123 It in turn includes files for the machine-independent drivers located
124 in
125 .Pa sys/dev/\*[Lt]bus\*[Gt]/files.\*[Lt]bus\*[Gt] ,
126 where \*[Lt]bus\*[Gt] is the name of the machine-independent bus.
127 .Pp
128 These files define all legal devices and pseudo-devices.
129 They also define all attributes and interfaces, establishing the rules that
130 determine allowable machine descriptions, and list the source files
131 that make up the kernel.
132 .Pp
133 Each device definition file consists of a list of statements,
134 typically one per line.
135 Comments may be inserted anywhere using the
136 .Do
137 #
138 .Dc
139 character, and any line that begins with white space continues the
140 previous line.
141 Valid statements are:
142 .Bl -tag -width xxxxxx
143 .It cinclude filename
144 Conditionally include contents of file
145 .Ar filename
146 to currently processed configuration.
147 If the specified
148 .Ar filename
149 doesn't exist, a warning is printed, but the error
150 ignored.
151 .It defflag [filename] {options}
152 The space-separated list of pre-processor macros
153 .Em options
154 are defined in file
155 .Em filename .
156 This statement permits ``options FOO'' for FOO (i.e, without a value)
157 in the machine description file.
158 .Xr config 1
159 will generate an error if a value is given.
160 If the filename field is not specified, it will be constructed based upon
161 the lower-case of the option name, ``opt_foo.h'' for example.
162 The
163 .Em option
164 is case-sensitive.
165 .It defparam [filename] {options}
166 The space-separated list of pre-processor macros
167 .Em options
168 are defined in file
169 .Em filename .
170 This statement permits ``options FOO=bar'' or ``option FOO="\\"com\\""''
171 in the machine description file.
172 .Xr config 1
173 will generate an error if a value is not given.
174 If the filename field is not specified, it will be constructed based upon
175 the lower-case of the option name, ``opt_foo.h'' for example.
176 The
177 .Em option
178 is case-sensitive.
179 .It defopt [filename] {options}
180 The space-separated list of pre-processor macros
181 .Em options
182 are defined in file
183 .Em filename .
184 This statement permits the syntax of either the defflag and defparam
185 statements and
186 .Xr config 1
187 does not perform any checking of whether ``options FOO'' takes a
188 value.
189 Therefore, the use of the defopt statement is deprecated in
190 favour of the defflag and defparam statements.
191 If the filename field is not specified, it will be constructed based upon
192 the lower-case of the option name, ``opt_foo.h'' for example.
193 The
194 .Em option
195 is case-sensitive.
196 .It deffs [filename] name
197 Define a filesystem
198 .Em name .
199 .It devclass name
200 Define a device class
201 .Em name .
202 A device class is similar to an attribute.
203 .It define name [{locators}]
204 The attribute
205 .Em name
206 is defined and device definitions can then refer to it.
207 If the attribute is an interface attribute and defines optional
208 .Em locators ,
209 device attributes that refer to
210 .Em name
211 are assumed to share the interface and require the same locators.
212 .It device name [{locators}]: [attributes]
213 The device
214 .Em name
215 is defined and requires the optional comma-separated list of locators
216 .Em locators .
217 The optional
218 .Em attributes
219 define attribute dependencies.
220 .It attach name at interface [with ifname]: [attributes]
221 The device
222 .Em name
223 is defined and supports the interface
224 .Em interface .
225 If
226 .Em ifname
227 is specified, it is used to specify the interface to the driver for
228 device
229 .Em name
230 (see
231 .Xr driver 9
232 for details).
233 The optional
234 .Em attributes
235 define attribute dependencies.
236 .It defpseudo name: [{locators}]
237 The pseudo-device
238 .Em name
239 is defined.
240 The optional
241 .Em locators
242 may be defined, but are largely pointless since no device can attach
243 to a pseudo-device.
244 .It file pathname [attributes [flags]] [rule]
245 The file
246 .Em pathname
247 is added to the list of files used to build the kernel.
248 If no attributes are specified, the file is always added to the kernel
249 compilation.
250 If any of the attributes are specified by other devices in the machine
251 description file, then the file is included in compilation, otherwise it
252 is omitted.
253 Valid values for the optional flags are:
254 .Bl -tag -width xxxxxx
255 .It needs-count
256 Specify that config should generate a file for each of the attributes
257 notifying the driver how many of some particular device or set of
258 devices are configured in the kernel.
259 This flag allows drivers to make calculations of driver used at compile time.
260 This option prevents autoconfiguration cloning.
261 .It needs-flag
262 This flag performs the same operation as
263 .Em needs-count
264 but only records if the number is nonzero.
265 Since the count is not exact,
266 .Em needs-flag
267 does not prevent autoconfiguration cloning.
268 .El
269 .It device-major name char [block] [attributes]
270 The character device switch
271 .Em name
272 associated with a character major device number is added to the list of
273 device switches used to build the kernel.
274 If
275 .Em block
276 is specified, the block device switch associated with a block major device
277 number is also added.
278 If all of attributes are specified by devices in the machine description
279 files, then device switches are added into the device switches' table of
280 the kernel in compilation, otherwise they are omitted.
281 .It include Ar filename
282 Include contents of file
283 .Ar filename
284 to currently processed configuration.
285 If the specified
286 .Ar filename
287 doesn't exist,
288 .Xr config 1
289 exits with error.
290 .It package Ar filename
291 Changes prefix to directory of
292 .Ar filename ,
293 processes contents of
294 .Ar filename ,
295 and switches back to previous prefix.
296 This is syntactic sugar for:
297 .Bd -literal -compact -offset indent
298 .Li prefix Ar dirname(filename)
299 .Li include Ar basename(filename)
300 .Li prefix
301 .Ed
302 .It prefix Op Ar dirname
303 If
304 .Ar dirname
305 is specified, it is pushed on top of prefix stack.
306 Any further files specified via option
307 .Ar file
308 would have the prefix implicitly prepended before its
309 .Ar filename .
310 If
311 .Ar dirname
312 is not specified, pops (removes) a prefix from prefix stack.
313 .El
314 .Pp
315 To allow locators to be wildcarded in the machine description file,
316 their default value must be defined in the attribute definition.
317 To allow locators to be omitted entirely in the machine description file,
318 enclose the locator in square brackets.
319 This can be used when some locators do not make sense for some devices,
320 but the software interface requires them.
321 .Sh CODE REFERENCES
322 This section describes places within the
323 .Nx
324 source tree where actual code implementing or using the
325 autoconfiguration framework can be found.
326 All pathnames are relative to
327 .Pa /usr/src .
328 .Pp
329 The device definition files are in
330 .Pa sys/conf/files ,
331 .Pa sys/arch/\*[Lt]arch\*[Gt]/conf/files.\*[Lt]arch\*[Gt] ,
332 and
333 .Pa sys/dev/\*[Lt]bus\*[Gt]/files.\*[Lt]bus\*[Gt] .
334 .Pp
335 The grammar for machine description files can be found in
336 .Xr config 1 ,
337 in
338 .Pa usr.bin/config/gram.y .
339 .Sh SEE ALSO
340 .Xr config 1 ,
341 .Xr config 5 ,
342 .Xr autoconf 9 ,
343 .Xr driver 9
344 .Rs
345 .%T "Building 4.4 BSD Systems with Config"
346 .Re
347 .Rs
348 .%A Chris Torek
349 .%T "Device Configuration in 4.4BSD"
350 .%D 1992
351 .Re
352 .Sh HISTORY
353 Autoconfiguration first appeared in
354 .Bx 4.1 .
355 The autoconfiguration framework was completely revised in
356 .Bx 4.4 .
357 It has been modified within
358 .Nx
359 to support bus-independent drivers and bus-dependent attachments.