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