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