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