config
—
the autoconfiguration framework “device
definition” language
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.
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.
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.
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.