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 name [[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
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)
Building 4.4 BSD Systems with
Config.
Chris Torek, Device
Configuration in 4.4BSD, 1992.
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.