.\"     $NetBSD: config.9,v 1.3 2001/12/13 19:26:50 gmcgarry Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Gregory McGarry.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd June 17, 2001
.Dt CONFIG 9
.Os
.Sh NAME
.Nm config
.Nd the autoconfiguration framework
.Do
device definition
.Dc
language
.Sh DESCRIPTION
In
.Nx ,
the
.Xr config 8
program reads and verifies a machine description file specifying the
devices to include in the kernel.  A table is produced by
.Xr config 8
which is used by the kernel during autoconfiguration (see
.Xr autoconf 9 )
giving needed hints and details on matching hardware devices with
device drivers.
.Pp
Each device in the machine description file has:
.Bl -tag -width xxxxxx
.It A Name
The name is simply an alphanumeric string that ends in a unit number
(eg. "sd0", "sd1", and so forth).  These unit numbers identify
particular instances of a base device name; the base name in turn maps
directly to a device driver.  Device unit numbers are independent of
hardware features.
.It A Parent
Every device must have a parent.  The pairing is denoted by "child at
parent".  These pairings form the links in a directed graph.  The root
device is the only exception, as it does not have a parent.
.It Locators
Locators are used to augment the parent/child pairings the locate
specific devices.  Each locator value is simply an integer that
represents some sort of device address on the parent bus or
controller.  This can be a memory address, and I/O port, a driver
number, or any other value.  Locators can sometimes be wildcarded on
devices that support direct connection.
.It Attributes
An attribute describes the device's relationship with the code; it
then serves to constrain the device graph.  A
.Em plain attribute
describes some attribute of a device.  An
.Em interface attribute
describes a kind of
.Do
software interface
.Dc
and declares the devices's ability to support other devices that use
that interface.  In addition, an interface attribute usually identifies
additional locators.
.El
.Pp
During autoconfiguration, the directed graph is turned into a tree by
nominating one device as the root node and matching drivers with
devices by doing a depth-first traversal through the graph stating at
this root node.
.Pp
However, there must be constraints on the parent/child pairings that
are possible.  These constraints are embedded in the
.Do
device definition
.Dc
files.  The remainder of this page describes the
.Do
device definition
.Dc
language and how to use this language to add new functionality to the
.Nx
kernel.
.Sh DEVICE DEFINITION FILES
The device definition files are separated into machine-dependent and
machine-independent files.  The machine-dependent file is located in
.Pa sys/arch/<arch>/conf/files.<arch> ,
where <arch> is the name of
.Nx
architecture.  The machine-independent file is located in
.Pa sys/conf/files .
It in turn includes files for the machine-independent drivers located
in
.Pa sys/dev/<bus>/files.<bus> ,
where <bus> is the name of the machine-independent bus.
.Pp
These files define all legal device and pseuo-deives.  They also
define all attributes and interfaces, establishign the ule that
determine allowable machine descriptions, and list the source files
that make up the kernel.
.Pp
Each device definition file consists of a list of statements,
typically one per line.  Comments may be inserted anywhere using the
.Do
#
.Dc
character, and any line that begins with white space continues the
previous line.  Valid statements are:
.Bl -tag -width xxxxxx
.It defflag [filename] {options}
The space-separated list of pre-processor macros
.Em options
are defined in file
.Em filename .
This statement permits ``options FOO'' for FOO (i.e, without a value)
in the machine description file.
.Xr config 8
will generate an error if a value is given.  If the filename field is
not specified, the options are defined on the commandline invocation
of
.Xr make 1 .
The
.Em option
is case-sensitive.
.It defparam [filename] {options}
The space-separated list of pre-processor macros
.Em options
are defined in file
.Em filename .
This statement permits ``options FOO=bar'' or ``option FOO="\\"com\\""''
in the machine description file.
.Xr config 8
will generate an error if a value is not given.  If the filename field
is not specified, the options are defined on the commandline
invocation of
.Xr make 1 .
The
.Em option
is case-sensitive.
.It defopt [filename] {options}
The space-separated list of pre-processor macros
.Em options
are defined in file
.Em filename .
This statement permits the syntax of either the defflag and defparam
statements and
.Xr config 8
does not perform any checking of whether ``options FOO'' takes a
value.  Therefore, the use of the defopt statement is deprecated in
favour of the defflag and defparam statements.  If the filename field
is not specified, the options are defined on the commandline
invocation of
.Xr make 1 .
The
.Em option
is case-sensitive.
.It deffs [filename] name
Define a filesystem
.Em name .
.It devclass name
Define a device class
.Em name .
A device class is similar to an attribute.
.It define name [{locators}]
The attribute
.Em name
is defined and device definitions can then refer to it.  If the
attribute is an interface attribute and defines optional
.Em locators ,
device attributes that refer to
.Em name
are assumed to share the interface and require the same locators.
.It device name [{locators}]: [attributes]
The device
.Em name
is defined and requires the optional comma-separated list of locators
.Em locators .
The optional
.Em attributes
define attribute dependencies.
.It attach name at interface [with ifname]: [attributes]
The device
.Em name
is defined and supports the interface
.Em interface .
If
.Em ifname
is specified, it is used to specify the interface to the driver for
device
.Em name
(see
.Xr driver 9
for details).
The optional
.Em attributes
define attribute dependencies.
.It defpseudo name: [{locators}]
The pseudo-device
.Em name
is defined.  The optional
.Em locators
may be defined, but are largely pointless since no device can attach
to a pseudo-device.
.It file pathname [attributes [flags]] [rule]
The file
.Em pathname
is added to the list of files used to build the kernel.  If no
attributes are specific the file is always added to the kernel
compilation.  If any of the attributes are specified by other devices
in the machine descripton file, then the file is included in
compilation, otherwise it is omitted.  Valid values for the optional
flags are:
.Bl -tag -width xxxxxx
.It needs-count
Specify that config should generate a file for each of the attributes
notifying the driver how many of some particular device or set of
devices are configured are configured in the kernel.  This flags
allows drivers to make calculations of driver used at compile time.
This option prevents autoconfiguration cloning.
.It needs-flag
This flag performs the same operation and
.Em needs-count
but only records if the number is nonzero.  Since the count is not
extact,
.Em needs-flag
does not prevent autoconfiguration cloning.
.El
.It major major-list
The devices listed in
.Em major-list
are associated with major device numbers, allowing them to be used for
file system roots, swapping and crash dumps.  Since major numbers are
machine dependent, they should not appear in the machine-independent
device definition files.
.El
.Pp
To allow locators to be wildcarded in the machine description file,
their default value must be defined in the attribute definition.  To
allow locators to be omitted entirely in the machine description file,
enclose the locator in square brackets.  This can be used when some
locators do not make sense for some devices, but the software
interface requires them.
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
autoconfiguration framework can be found.  All pathnames are relative
to
.Pa /usr/src .
.Pp
The device definition files are in
.Pa sys/conf/files ,
.Pa sys/arch/<arch>/conf/files.<arch> ,
and
.Pa sys/dev/<bus>/files.<bus> .
.Pp
The grammar for machine description files can be found in
.Xr config 8 ,
in
.Pa usr.sbin/config/gram.y .
.Sh SEE ALSO
.Rs
.%T "Building 4.4 BSD Systems with Config"
.Re
.Rs
.%A Chris Torek
.%T "Device Configuration in 4.4BSD"
.%D 1992
.Re
.sp
.Xr config 8 ,
.Xr autoconf 9 ,
.Xr driver 9
.Sh HISTORY
Autoconfiguration first appeared in
.Bx 4.1 .
The autoconfiguration framework was completely revised in
.Bx 4.4 .
It has been modified within
.Nx
to support bus-independent drivers and bus-dependent attachments.