1.\" $NetBSD: config.9,v 1.1 2001/07/01 04:11:13 gmcgarry 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 17, 2001 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. A table is produced by 54.Xr config 8 55which is used by the kernel during autoconfiguration (see 56.Xr autoconf 9 ) 57giving needed hints and details on matching hardware devices with 58device drivers. 59.Pp 60Each device in the machine description file has: 61.Bl -tag -width xxxxxx 62.It A Name 63The name is simply an alphanumeric string that ends in a unit number 64(eg. "sd0", "sd1", and so forth). These unit numbers identify 65particular instances of a base device name; the base name in turn maps 66directly to a device driver. Device unit numbers are independent of 67hardware features. 68.It A Parent 69Every device must have a parent. The pairing is denoted by "child at 70parent". These pairings form the links in a directed graph. The root 71device is the only exception, as it does not have a parent. 72.It Locators 73Locators are used to augment the parent/child pairings the locate 74specific devices. Each locator value is simply an integer that 75represents some sort of device address on the parent bus or 76controller. This can be a memory address, and I/O port, a driver 77number, or any other value. Locators can sometimes be wildcarded on 78devices that support direct connection. 79.It Attributes 80An attribute describes the device's relationship with the code; it 81then serves to constrain the device graph. A 82.Em plain attribute 83describes some attribute of a device. An 84.Em interface attribute 85describes a kind of 86.Do 87software interface 88.Dc 89and declares the devices's ability to support other devices that use 90that interface. In addition, an interface attribute usually identifies 91additional 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 stating at 97this root node. 98.Pp 99However, there must be constraints on the parent/child pairings that 100are possible. These constraints are embedded in the 101.Do 102device definition 103.Dc 104files. The remainder of this page describes the 105.Do 106device definition 107.Dc 108language and how to use this language to add new functionality to the 109.Nx 110kernel. 111.Sh DEVICE DEFINITION FILES 112The device definition files are separated into machine-dependent and 113machine-independent files. The machine-dependent file is located in 114.Pa sys/arch/<arch>/conf/files.<arch> , 115where <arch> is the name of 116.Nx 117architecture. The machine-independent file is located in 118.Pa sys/conf/files . 119It in turn includes files for the machine-independent drivers located 120in 121.Pa sys/dev/<bus>/files.<bus> , 122where <bus> is the name of the machine-independent bus. 123.Pp 124These files define all legal device and pseuo-deives. They also 125define all attributes and interfaces, establishign the ule that 126determine allowable machine descriptions, and list the source files 127that make up the kernel. 128.Pp 129Each device definition file consists of a list of statements, 130typically one per line. Comments may be inserted anywhere using the 131.Do 132# 133.Dc 134character, and any line that begins with white space continues the 135previous line. Valid statements are: 136.Bl -tag -width xxxxxx 137.It defopt [filename] {options} 138The space-separated list of pre-processor macros 139.Em options 140are defined in file 141.Em filename . 142If the filename field is not specified, the options are defined on the 143commandline invocation of make. 144The 145.Em option 146is case-sensitive. 147.It deffs [filename] name 148Define a filesystem 149.Em name . 150.It devclass name 151Define a device class 152.Em name . 153A device class is similar to an attribute. 154.It define name [{locators}] 155The attribute 156.Em name 157is defined and device definitions can then refer to it. If the 158attribute is an interface attribute and defines optional 159.Em locators , 160device attributes that refer to 161.Em name 162are assumed to share the interface and require the same locators. 163.It device name [{locators}]: [attributes] 164The device 165.Em name 166is defined and requires the optional comma-separated list of locators 167.Em locators . 168The optional 169.Em attributes 170define attribute dependencies. 171.It attach name at interface [with ifname]: [attributes] 172The device 173.Em name 174is defined and supports the interface 175.Em interface . 176If 177.Em ifname 178is specified, it is used to specify the interface to the driver for 179device 180.Em name 181(see 182.Xr driver 9 183for details). 184The optional 185.Em attributes 186define attribute dependencies. 187.It defpseudo name: [{locators}] 188The pseudo-device 189.Em name 190is defined. The optional 191.Em locators 192may be defined, but are largely pointless since no device can attach 193to a pseudo-device. 194.It file pathname [attributes [flags]] [rule] 195The file 196.Em pathname 197is added to the list of files used to build the kernel. If no 198attributes are specific the file is always added to the kernel 199compilation. If any of the attributes are specified by other devices 200in the machine descripton file, then the file is included in 201compilation, otherwise it is omitted. Valid values for the optional 202flags are: 203.Bl -tag -width xxxxxx 204.It needs-count 205Specify that config should generate a file for each of the attributes 206notifying the driver how many of some particular device or set of 207devices are configured are configured in the kernel. This flags 208allows drivers to make calculations of driver used at compile time. 209This option prevents autoconfiguration cloning. 210.It needs-flag 211This flag performs the same operation and 212.Em needs-count 213but only records if the number is nonzero. Since the count is not 214extact, 215.Em needs-flag 216does not prevent autoconfiguration cloning. 217.El 218.It major major-list 219The devices listed in 220.Em major-list 221are associated with major device numbers, allowing them to be used for 222file system roots, swapping and crash dumps. Since major numbers are 223machine dependent, they should not appear in the machine-independent 224device definition files. 225.El 226.Pp 227To allow locators to be wildcarded in the machine description file, 228their default value must be defined in the attribute definition. To 229allow locators to be omitted entirely in the machine description file, 230enclose the locator in square brackets. This can be used when some 231locators do not make sense for some devices, but the software 232interface requires them. 233.Sh CODE REFERENCES 234This section describes places within the 235.Nx 236source tree where actual code implementing or utilising the 237autoconfiguration framework can be found. All pathnames are relative 238to 239.Pa /usr/src . 240.Pp 241The device definition files are in 242.Pa sys/conf/files , 243.Pa sys/arch/<arch>/conf/files.<arch> , 244and 245.Pa sys/dev/<bus>/files.<bus> . 246.Pp 247The grammar for machine description files can be found in 248.Xr config 8 , 249in 250.Pa usr.sbin/config/gram.y . 251.Sh SEE ALSO 252.Rs 253.%T "Building 4.4 BSD Systems with Config" 254.Re 255.Rs 256.%A Chris Torek 257.%T "Device Configuration in 4.4BSD" 258.%D 1992 259.Re 260.sp 261.Xr config 8 , 262.Xr autoconf 9 , 263.Xr driver 9 . 264.Sh HISTORY 265Autoconfiguration first appeared in 266.Bx 4.1 . 267The autoconfiguration framework was completely revised in 268.Bx 4.4 . 269It has been modified within 270.Nx 271to support bus-independent drivers and bus-dependent attachments. 272