config - the autoconfiguration framework ``device definition'' language
In NetBSD, the config(8) program reads and verifies a machine description
file specifying the devices to include in the kernel. A table is produced
by config(8) 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 (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.
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 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.
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
devices'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 [Toc] [Back] 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:
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(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 make(1). 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(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 make(1). The option is casesensitive.
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(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 make(1). 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 descripton 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.
major major-list
The devices listed in 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.
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.
This section describes places within the NetBSD source tree where actual
code implementing or utilising 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(8), in
usr.sbin/config/gram.y.
config(8), autoconf(9), driver(9)
Building 4.4 BSD Systems with Config.
Chris Torek, Device Configuration in 4.4BSD, 1992.
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.
BSD June 17, 2001 BSD
[ Back ] |
