files.conf - rules base for the config utility
The various files.* files located in the kernel source tree
contain all
the necessary information needed by config(8) to parse a
kernel configuration
file and determine the list of files to compile.
The files.* rules base are simple, human-readable, text
files. Empty
lines, as well as text prefixed by the ``#'' character, are
ignored.
Device tree concept [Toc] [Back]
The OpenBSD kernel ``sees'' the various devices as a hierarchical tree,
where the various devices ``attach'' to parent entities,
which can either
be physical devices themselves (such as a computer bus), or
logical entities,
designed to make the driver code simpler. Usually,
the top-most
devices are attached to the pseudo-device ``mainbus'', which
is itself
reported as attached to a fictitious ``root'' node. There
is no restriction
on the ``children'' a device node may have; some device
drivers can
attach themselves to different kinds of parent devices. For
example, the
logical scsibus(4) device can either attach at an SCSI controller device,
or at the logical atapiscsi(4) bus.
Locators [Toc] [Back]
Some device attachments need to provide attachment information. For example,
an isa(4) device will use a range of I/O ports, one
or more DMA
channels, and one interrupt vector. This attachment information is known
as the ``locators'' for the device. Most of the busses support default
values for unspecified locators, for devices that either do
not require
them (such as isa(4) cards not using interrupts), or which
can autoconfigure
themselves (such as pci(4) devices).
Attachment lines in the kernel configuration file must match
the locators
of the device they are attaching to. For example, given
define pci {[dev = -1], [function = -1]}
in the rules files, the following kernel configuration lines
are valid:
pciknob0 at pci? dev 2 function 42 # use fixed values
pciknob* at pci? dev ? function ? # use default values
pciknob* at pci? # use default locators
but the following are not:
pciknob* at pci? trick ? treat ? # unknown locators
pciknob* at pci? dev ? function ? usefulness ? # unknown locators
Attributes [Toc] [Back]
The syntax
define attribute
defines a simple attribute, which can be later used to factorize code dependencies.
An attachment-like attribute will also require
locators to
be specified, such as
define attribute {}
if no locators are necessary, or
define attribute {[locator1 = default1], [locator2 =
default2]}
if locators are provided.
Devices [Toc] [Back]
For simple device attachment, the syntax
define device {}
defines a simple device, with no locators. If locators are
necessary,
they are specified as:
define device {[locator1 = default1], [locator2 = default2]}
A device can also reference an attribute with locators.
This is in fact
a dependency rule. For example, sys/dev/conf/files defines
the following
attribute for SCSI controllers:
define scsi {} # no locators
and SCSI drivers can then be defined as
define scsictrl: scsi
A device may depend on as many attributes as necessary:
define complexdev: simpledev, otherdev, specialattribute
Pseudo devices [Toc] [Back]
Pseudo device are defined as regular devices, except that
they do not
need locators, and use a different keyword:
pseudo-device loop: inet
pseudo-device ksyms
define, respectively, the loopback network interface and the
kernel symbols
pseudo-device.
Device attachment rules [Toc] [Back]
Due to the tree structure of the device nodes, every device
but the pseudo
devices need to attach to some parent node. A device
driver has to
specify to which parents it can attach, with the following
syntax:
attach device at parent, parent2, parent3
which lists all the parent attributes a device may attach
to. For example,
if a device is specified as:
device smartknob: bells, whistles
attach smartknob at brainbus
then a
smartknob* at brainbus?
configuration file line is valid, while a
smartknob* at dumbbus?
is not.
If a device supports attachments to multiple parents, using
different
``glue'' routines every time, the following syntax specifies
the details:
attach device at parent with device_parent_glue
attach device at parent2 with device_parent2_glue
and will define more required attributes, depending on the
kernel configuration
file's contents.
Rule file inclusion [Toc] [Back]
It is possible to include other rules files anywhere in a
file, using the
``include'' keyword:
include "dev/pci/files.pci"
will include the rules for machine-independent PCI code.
The files sys/arch/machine/conf/files.machine, for every
``machine''
listed in the machine line in the kernel configuration file,
as well as
sys/conf/files, are always processed, and do not need to be
included.
Attribute requirements [Toc] [Back]
The kernel configuration file description passed to config(8) lists several
compilation options, as well as several device definitions. From
this list, config(8) will build a list of required attributes, which are
+o the ``option'' lines, with the option name translated to lowercase
(for example, an ``option INET'' line will
produce the
``inet'' attribute).
+o the device and pseudo-device names, except for
``root''.
Kernel file list [Toc] [Back]
Kernel source files are defined as:
file somewhere/somefile.c dependencies needrules
If the ``dependencies'' part is empty, the file will always
be compiled
in. This is the case for the core kernel files. Otherwise,
the file
will only be added to the list if the dependencies are met.
Dependencies
are based upon attributes and device names. Multiple dependencies can be
written using the ``|'' and ``&'' operators. For example,
the line
file netinet/ipsec_input.c (inet | inet6) & ipsec
teaches config(8) to only add sys/netinet/ipsec_input.c to
the filelist
if the ``ipsec'' attribute, and at least one of the ``inet''
and
``inet6'' attributes, are required.
The ``need'' rules can be empty, or one of the following
keywords:
needs-flag Create an attribute header file, defining
whether or not
this attribute is compiled in.
needs-count Create an attribute header file, defining how
many instances
of this attribute are to be compiled in. This
rule is mostly
used for pseudo-devices.
The ``attribute header files'' are simple C header files
created in the
kernel compilation directory, with the name attribute.h and
containing
the following line:
#define NATTRIBUTE 0
substituting the attribute name and its uppercase form, prefixed with the
letter ``N'', to ``attribute'' and ``NATTRIBUTE'', respectively. For a
``needs-flag'' rule, the value on the ``#define'' line is
either 1 if the
attribute is required, or 0 if it is not required. For a
``needs-count''
rule, the value is the number of device instances required,
or 0 if the
device is not required.
Attribute files are created for every attribute listed with
a ``need''
rule, even if it is never referenced from the kernel configuration file.
Miscellaneous items [Toc] [Back]
sys/arch/machine/conf/files.machine must also supply the
following special
commands:
maxpartitions Defines how many partitions are available on
disk block
devices, usually 16. This value is used by
config(8) to
set up various device information structures.
maxusers Defines the bounds, and the default value,
for the
``maxusers'' parameter in the kernel configuration file.
The usual values are 2 8 64 ; config(8) will
report an error
if the ``maxusers parameter'' in the kernel configuration
file does not fit in the specified
range.
sys/arch/machine/conf/files.machine
Rules for architecture-dependent files, for the ``machine'' architecture.
sys/compat/emul/files.emul
Rules for the ``emul'' operating system or subsystem
emulation.
sys/dev/class/files.class
Rules for the ``class'' class of devices.
sys/gnu/arch/i386/fpemul/files.fpemul
Rules for the i386 GPL floating-point emulator.
sys/scsi/files.scsi
Rules for the common SCSI subsystem.
config(8)
OpenBSD 3.6 October 8, 2002
[ Back ] |
