MirOS Manual: files.conf(5)

FILES.CONF(5)                BSD Reference Manual                FILES.CONF(5)

NAME

     files.conf - rules base for the config utility

DESCRIPTION

     The various files.* files located in the kernel source tree contain all
     the necessary information needed by config(8) to parse a kernel confi-
     guration file and determine the list of files to compile.

SYNTAX

     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

     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 enti-
     ties, designed to make the driver code simpler. Usually, the top-most
     devices are attached to the pseudo-device "mainbus", which is itself re-
     ported 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

     Some device attachments need to provide attachment information. For exam-
     ple, 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 autocon-
     figure 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

     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

     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/conf/files defines the following attri-
     bute for SCSI controllers:

           define scsi {}           # no locators

     and SCSI drivers can then be defined as

           device scsictrl: scsi

     A device may depend on as many attributes as necessary:

           device complexdev: simpledev, otherdev, specialattribute

Pseudo devices

     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 sym-
     bols pseudo-device.

Device attachment rules

     Due to the tree structure of the device nodes, every device but the pseu-
     do 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 exam-
     ple, 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 confi-
     guration file's contents.

Rule file inclusion

     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

     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

           •   the "option" lines, with the option name translated to lower-
               case (for example, an "option INET" line will produce the
               "inet" attribute).
           •   the device and pseudo-device names, except for "root".

Kernel file list

     Kernel source files are defined as:

           file somewhere/somefile.c       dependencies    need-rules

     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" at-
     tributes, 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

     sys/arch/machine/conf/files.machine must also supply the following spe-
     cial 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.

FILES

     sys/arch/machine/conf/files.machine
          Rules for architecture-dependent files, for the "machine" architec-
          ture.

     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.

SEE ALSO

     config(8)

MirOS BSD #10-current          October 8, 2002                               3

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.