CONFIG(9)              NetBSD Kernel Developer's Manual              CONFIG(9)

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 num-
             bers 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 inter-
             face.  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-inde-
     pendent bus.

     These files define all legal devices and pseudo-devices.  They also
     define all attributes and interfaces, establishing the rules that deter-
     mine 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 ``#'' charac-
     ter, 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 pro-
             cessed 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 exam-
             ple.  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-sepa-
             rated 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 speci-
             fied 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 par-
                     ticular 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 auto-
                     configuration 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 autoconfigura-
                     tion 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 configu-
             ration.  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 syntac-
             tic 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)

     Building 4.4 BSD Systems with Config.

     Chris Torek, Device Configuration in 4.4BSD, 1992.

HISTORY
     Autoconfiguration first appeared in 4.1BSD.  The autoconfiguration frame-
     work was completely revised in 4.4BSD.  It has been modified within
     NetBSD to support bus-independent drivers and bus-dependent attachments.

NetBSD 5.0_STABLE               August 19, 2003              NetBSD 5.0_STABLE
