367 lines
12 KiB
Groff
367 lines
12 KiB
Groff
.\" $NetBSD: config.9,v 1.24 2006/06/04 21:58:21 perry 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 August 19, 2003
|
|
.Dt CONFIG 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm config
|
|
.Nd the autoconfiguration framework
|
|
.Do
|
|
device definition
|
|
.Dc
|
|
language
|
|
.Sh DESCRIPTION
|
|
In
|
|
.Nx ,
|
|
the
|
|
.Xr config 1
|
|
program reads and verifies a machine description file (documented in
|
|
.Xr config 5 )
|
|
that specifies the devices to include in the kernel.
|
|
A table is produced by
|
|
.Xr config 1
|
|
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
|
|
(e.g., "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 that 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, an 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 device'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 starting 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/\*[Lt]arch\*[Gt]/conf/files.\*[Lt]arch\*[Gt] ,
|
|
where \*[Lt]arch\*[Gt] 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/\*[Lt]bus\*[Gt]/files.\*[Lt]bus\*[Gt] ,
|
|
where \*[Lt]bus\*[Gt] is the name of the machine-independent bus.
|
|
.Pp
|
|
These files define all legal devices and pseudo-devices.
|
|
They also define all attributes and interfaces, establishing the rules 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 cinclude filename
|
|
Conditionally include contents of file
|
|
.Ar filename
|
|
to currently processed configuration.
|
|
If the specified
|
|
.Ar filename
|
|
doesn't exist, a warning is printed, but the error
|
|
ignored.
|
|
.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 1
|
|
will generate an error if a value is given.
|
|
If the filename field is not specified, it will be constructed based upon
|
|
the lower-case of the option name, ``opt_foo.h'' for example.
|
|
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 1
|
|
will generate an error if a value is not given.
|
|
If the filename field is not specified, it will be constructed based upon
|
|
the lower-case of the option name, ``opt_foo.h'' for example.
|
|
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 1
|
|
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, it will be constructed based upon
|
|
the lower-case of the option name, ``opt_foo.h'' for example.
|
|
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 specified, the file is always added to the kernel
|
|
compilation.
|
|
If any of the attributes are specified by other devices in the machine
|
|
description 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 in the kernel.
|
|
This flag 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 as
|
|
.Em needs-count
|
|
but only records if the number is nonzero.
|
|
Since the count is not exact,
|
|
.Em needs-flag
|
|
does not prevent autoconfiguration cloning.
|
|
.El
|
|
.It device-major name char [block] [attributes]
|
|
The character device switch
|
|
.Em name
|
|
associated with a character major device number is added to the list of
|
|
device switches used to build the kernel.
|
|
If
|
|
.Em block
|
|
is specified, the block device switch associated with a block major device
|
|
number is also added.
|
|
If all of attributes are specified by devices in the machine description
|
|
files, then device switches are added into the device switches' table of
|
|
the kernel in compilation, otherwise they are omitted.
|
|
.It include Ar filename
|
|
Include contents of file
|
|
.Ar filename
|
|
to currently processed configuration.
|
|
If the specified
|
|
.Ar filename
|
|
doesn't exist,
|
|
.Xr config 1
|
|
exits with error.
|
|
.It package Ar filename
|
|
Changes prefix to directory of
|
|
.Ar filename ,
|
|
processes contents of
|
|
.Ar filename ,
|
|
and switches back to previous prefix.
|
|
This is syntactic sugar for:
|
|
.Bl -tag -compact -offset indent
|
|
.It prefix Ar dirname(filename)
|
|
.It include Ar basename(filename)
|
|
.It prefix
|
|
.El
|
|
.It prefix Op Ar dirname
|
|
If
|
|
.Ar dirname
|
|
is specified, it is pushed on top of prefix stack.
|
|
Any further files specified via option
|
|
.Ar file
|
|
would have the prefix implicitly prepended before its
|
|
.Ar filename .
|
|
If
|
|
.Ar dirname
|
|
is not specified, pops (removes) a prefix from prefix stack.
|
|
.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 using 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/\*[Lt]arch\*[Gt]/conf/files.\*[Lt]arch\*[Gt] ,
|
|
and
|
|
.Pa sys/dev/\*[Lt]bus\*[Gt]/files.\*[Lt]bus\*[Gt] .
|
|
.Pp
|
|
The grammar for machine description files can be found in
|
|
.Xr config 1 ,
|
|
in
|
|
.Pa usr.bin/config/gram.y .
|
|
.Sh SEE ALSO
|
|
.Xr config 1 ,
|
|
.Xr config 5 ,
|
|
.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.
|