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