308 lines
10 KiB
Groff
308 lines
10 KiB
Groff
.\" $NetBSD: config.9,v 1.4 2001/12/26 00:16:30 wiz 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
|
|
.Xr config 8 ,
|
|
.Xr autoconf 9 ,
|
|
.Xr driver 9
|
|
.Rs
|
|
.%T "Building 4.4 BSD Systems with Config"
|
|
.Re
|
|
.Rs
|
|
.%A Chris Torek
|
|
.%T "Device Configuration in 4.4BSD"
|
|
.%D 1992
|
|
.Re
|
|
.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.
|