NAME
config
- the autoconfiguration framework
``device definition''
language
DESCRIPTION
In
NetBSD,
the
config(1)
program reads and verifies a machine description file (documented in
config(5))
that specifies the devices to include in the kernel.
A table is produced by
config(1)
which is used by the kernel during autoconfiguration (see
autoconf(9))
giving needed hints and details on matching hardware devices with
device drivers.
Each device in the machine description file has:
- 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.
- 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.
- 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.
- Attributes
-
An attribute describes the device's relationship with the code; it
then serves to constrain the device graph.
A
plain attribute
describes some attribute of a device.
An
interface attribute
describes a kind of
``software interface''
and declares the device's ability to support other devices that use
that interface.
In addition, an interface attribute usually identifies additional locators.
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.
However, there must be constraints on the parent/child pairings that
are possible.
These constraints are embedded in the
``device definition''
files.
The remainder of this page describes the
``device definition''
language and how to use this language to add new functionality to the
NetBSD
kernel.
DEVICE DEFINITION FILES
The device definition files are separated into machine-dependent and
machine-independent files.
The machine-dependent file is located in
sys/arch/<arch>/conf/files.<arch>
,
where <arch> is the name of
NetBSD
architecture.
The machine-independent file is located in
sys/conf/files
.
It in turn includes files for the machine-independent drivers located
in
sys/dev/<bus>/files.<bus>
,
where <bus> is the name of the machine-independent bus.
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.
Each device definition file consists of a list of statements,
typically one per line.
Comments may be inserted anywhere using the
``#''
character, and any line that begins with white space continues the
previous line.
Valid statements are:
- cinclude filename
-
Conditionally include contents of file
filename
to currently processed configuration.
If the specified
filename
doesn't exist, a warning is printed, but the error
ignored.
- defflag [filename] {options}
-
The space-separated list of pre-processor macros
options
are defined in file
filename.
This statement permits ``options FOO'' for FOO (i.e, without a value)
in the machine description file.
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
option
is case-sensitive.
- defparam [filename] {options}
-
The space-separated list of pre-processor macros
options
are defined in file
filename.
This statement permits ``options FOO=bar'' or ``option FOO="\"com\""''
in the machine description file.
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
option
is case-sensitive.
- defopt [filename] {options}
-
The space-separated list of pre-processor macros
options
are defined in file
filename.
This statement permits the syntax of either the defflag and defparam
statements and
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
option
is case-sensitive.
- deffs [filename] name
-
Define a filesystem
name.
- devclass name
-
Define a device class
name.
A device class is similar to an attribute.
- define name [{locators}]
-
The attribute
name
is defined and device definitions can then refer to it.
If the attribute is an interface attribute and defines optional
locators,
device attributes that refer to
name
are assumed to share the interface and require the same locators.
- device name [{locators}]: [attributes]
-
The device
name
is defined and requires the optional comma-separated list of locators
locators.
The optional
attributes
define attribute dependencies.
- attach name at interface [with ifname]: [attributes]
-
The device
name
is defined and supports the interface
interface.
If
ifname
is specified, it is used to specify the interface to the driver for
device
name
(see
driver(9)
for details).
The optional
attributes
define attribute dependencies.
- defpseudo name: [{locators}]
-
The pseudo-device
name
is defined.
The optional
locators
may be defined, but are largely pointless since no device can attach
to a pseudo-device.
- file pathname [attributes [flags]] [rule]
-
The file
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:
- 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.
- needs-flag
-
This flag performs the same operation as
needs-count
but only records if the number is nonzero.
Since the count is not exact,
needs-flag
does not prevent autoconfiguration cloning.
- device-major name char [block] [attributes]
-
The character device switch
name
associated with a character major device number is added to the list of
device switches used to build the kernel.
If
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.
- include filename
-
Include contents of file
filename
to currently processed configuration.
If the specified
filename
doesn't exist,
config(1)
exits with error.
- package filename
-
Changes prefix to directory of
filename,
processes contents of
filename,
and switches back to previous prefix.
This is syntactic sugar for:
- prefix dirname(filename)
-
- include basename(filename)
-
- prefix
-
- prefix[ dirname]
-
If
dirname
is specified, it is pushed on top of prefix stack.
Any further files specified via option
file
would have the prefix implicitly prepended before its
filename.
If
dirname
is not specified, pops (removes) a prefix from prefix stack.
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.
CODE REFERENCES
This section describes places within the
NetBSD
source tree where actual code implementing or using the
autoconfiguration framework can be found.
All pathnames are relative to
/usr/src
.
The device definition files are in
sys/conf/files
,
sys/arch/<arch>/conf/files.<arch>
,
and
sys/dev/<bus>/files.<bus>
.
The grammar for machine description files can be found in
config(1),
in
usr.bin/config/gram.y
.
SEE ALSO
config(1),
config(5),
autoconf(9),
driver(9)
HISTORY
Autoconfiguration first appeared in
4.1BSD.
The autoconfiguration framework was completely revised in
4.4BSD.
It has been modified within
NetBSD
to support bus-independent drivers and bus-dependent attachments.