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