1.\" $NetBSD: config.9,v 1.14 2003/06/25 07:08:26 heas 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 June 25, 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 the 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, and 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 defflag [filename] {options} 150The space-separated list of pre-processor macros 151.Em options 152are defined in file 153.Em filename . 154This statement permits ``options FOO'' for FOO (i.e, without a value) 155in the machine description file. 156.Xr config 8 157will generate an error if a value is given. 158If the filename field is not specified, it will be constructed based upon 159the lower-case of the option name, ``opt_foo.h'' for example. 160The 161.Em option 162is case-sensitive. 163.It defparam [filename] {options} 164The space-separated list of pre-processor macros 165.Em options 166are defined in file 167.Em filename . 168This statement permits ``options FOO=bar'' or ``option FOO="\\"com\\""'' 169in the machine description file. 170.Xr config 8 171will generate an error if a value is not given. 172If the filename field is not specified, it will be constructed based upon 173the lower-case of the option name, ``opt_foo.h'' for example. 174The 175.Em option 176is case-sensitive. 177.It defopt [filename] {options} 178The space-separated list of pre-processor macros 179.Em options 180are defined in file 181.Em filename . 182This statement permits the syntax of either the defflag and defparam 183statements and 184.Xr config 8 185does not perform any checking of whether ``options FOO'' takes a 186value. 187Therefore, the use of the defopt statement is deprecated in 188favour of the defflag and defparam statements. 189If the filename field is not specified, it will be constructed based upon 190the lower-case of the option name, ``opt_foo.h'' for example. 191The 192.Em option 193is case-sensitive. 194.It deffs [filename] name 195Define a filesystem 196.Em name . 197.It devclass name 198Define a device class 199.Em name . 200A device class is similar to an attribute. 201.It define name [{locators}] 202The attribute 203.Em name 204is defined and device definitions can then refer to it. 205If the attribute is an interface attribute and defines optional 206.Em locators , 207device attributes that refer to 208.Em name 209are assumed to share the interface and require the same locators. 210.It device name [{locators}]: [attributes] 211The device 212.Em name 213is defined and requires the optional comma-separated list of locators 214.Em locators . 215The optional 216.Em attributes 217define attribute dependencies. 218.It attach name at interface [with ifname]: [attributes] 219The device 220.Em name 221is defined and supports the interface 222.Em interface . 223If 224.Em ifname 225is specified, it is used to specify the interface to the driver for 226device 227.Em name 228(see 229.Xr driver 9 230for details). 231The optional 232.Em attributes 233define attribute dependencies. 234.It defpseudo name: [{locators}] 235The pseudo-device 236.Em name 237is defined. 238The optional 239.Em locators 240may be defined, but are largely pointless since no device can attach 241to a pseudo-device. 242.It file pathname [attributes [flags]] [rule] 243The file 244.Em pathname 245is added to the list of files used to build the kernel. 246If no attributes are specified, the file is always added to the kernel 247compilation. 248If any of the attributes are specified by other devices in the machine 249description file, then the file is included in compilation, otherwise it 250is omitted. 251Valid values for the optional flags are: 252.Bl -tag -width xxxxxx 253.It needs-count 254Specify that config should generate a file for each of the attributes 255notifying the driver how many of some particular device or set of 256devices are configured in the kernel. 257This flag allows drivers to make calculations of driver used at compile time. 258This option prevents autoconfiguration cloning. 259.It needs-flag 260This flag performs the same operation as 261.Em needs-count 262but only records if the number is nonzero. 263Since the count is not exact, 264.Em needs-flag 265does not prevent autoconfiguration cloning. 266.El 267.It device-major name char [block] [attributes] 268The character device switch 269.Em name 270associated with a character major device number is added to the list of 271device switches used to build the kernel. 272If 273.Em block 274is specified, the block device switch associated with a block major device 275number is also added. 276If all of attributes are specified by devices in the machine description 277files, then device switches are added into the device switches' table of 278the kernel in compilation, otherwise they are omitted. 279.El 280.Pp 281To allow locators to be wildcarded in the machine description file, 282their default value must be defined in the attribute definition. 283To allow locators to be omitted entirely in the machine description file, 284enclose the locator in square brackets. 285This can be used when some locators do not make sense for some devices, 286but the software interface requires them. 287.Sh CODE REFERENCES 288This section describes places within the 289.Nx 290source tree where actual code implementing or using the 291autoconfiguration framework can be found. 292All pathnames are relative to 293.Pa /usr/src . 294.Pp 295The device definition files are in 296.Pa sys/conf/files , 297.Pa sys/arch/\*[Lt]arch\*[Gt]/conf/files.\*[Lt]arch\*[Gt] , 298and 299.Pa sys/dev/\*[Lt]bus\*[Gt]/files.\*[Lt]bus\*[Gt] . 300.Pp 301The grammar for machine description files can be found in 302.Xr config 8 , 303in 304.Pa usr.sbin/config/gram.y . 305.Sh SEE ALSO 306.Xr config 8 , 307.Xr autoconf 9 , 308.Xr driver 9 309.Rs 310.%T "Building 4.4 BSD Systems with Config" 311.Re 312.Rs 313.%A Chris Torek 314.%T "Device Configuration in 4.4BSD" 315.%D 1992 316.Re 317.Sh HISTORY 318Autoconfiguration first appeared in 319.Bx 4.1 . 320The autoconfiguration framework was completely revised in 321.Bx 4.4 . 322It has been modified within 323.Nx 324to support bus-independent drivers and bus-dependent attachments. 325