.\"	$OpenBSD: files.conf.5,v 1.4 2003/03/04 21:32:22 david Exp $
.\"
.\" Copyright (c) 2002 Miodrag Vallat.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistribution of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\"
.Dd October 8, 2002
.Dt FILES.CONF 5
.Os
.Sh NAME
.Nm files.conf
.Nd rules base for the config utility
.Sh DESCRIPTION
The various
.Pa files.*
files located in the kernel source tree
contain all the necessary information needed by
.Xr config 8
to parse a kernel configuration file and determine the list of files to
compile.
.Sh SYNTAX
The
.Pa files.*
rules base are simple, human-readable, text files.
Empty lines, as well as text prefixed by the
.Dq \&#
character, are ignored.
.\"
.Ss Device tree concept
.\"
The
.Ox
kernel
.Dq sees
the various devices as a hierarchical tree, where the various devices
.Dq attach
to parent entities, which can either be physical devices themselves
.Pq 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
.Dq mainbus ,
which is itself reported as attached to a fictitious
.Dq root
node.
There is no restriction on the
.Dq children
a device node may have ;
some device drivers can attach themselves to different kinds of parent devices.
For example, the logical
.Xr scsibus 4
device can either attach at an
.Tn SCSI
controller device, or at the logical
.Xr atapiscsi 4
bus.
.\"
.Ss Locators
.\"
Some device attachments need to provide attachment information.
For example, an
.Xr isa 4
device will use a range of io ports, one or more DMA channels, and one
interrupt vector.
This attachment information is known as the
.Dq locators
for the device.
Most of the busses support default values for unspecified locators, for devices
that either do not require them
.Po
such as
.Xr isa 4
cards not using interrupts
.Pc ,
or which can autoconfigure themselves
.Po 
such as
.Xr pci 4
devices
.Pc .
.Pp
Attachment lines in the kernel configuration file must match the locators of
the device they are attaching to.
For example, given
.Bl -item -offset indent -compact
.It
.Em define pci {[dev = -1], [function = -1]}
.El
in the rules files, the following kernel configuration lines are valid:
.Bl -item -offset indent -compact
.It
.Cd "pciknob0 at pci? dev 2 function 42 # use fixed values"
.It
.Cd "pciknob* at pci? dev ? function ?  # use default values"
.It
.Cd "pciknob* at pci?                   # use default locators"
.El
.Pp
but the following are not:
.Bl -item -offset indent -compact
.It
.Cd "pciknob* at pci? trick ? treat ?               # unknown locators"
.It
.Cd "pciknob* at pci? dev ? function ? usefulness ? # unknown locators"
.El
.\"
.Ss Attributes
.\"
The syntax
.Bl -item -offset indent -compact
.It
.Em define attribute
.El
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
.Bl -item -offset indent -compact
.It
.Em define attribute {}
.El
if no locators are necessary, or
.Bl -item -offset indent -compact
.It
.Em define attribute {[locator1 = default1], [locator2 = default2]}
.El
if locators are provided.
.\"
.Ss Devices
.\"
For simple device attachment, the syntax
.Bl -item -offset indent -compact
.It
.Em define device {}
.El
defines a simple device, with no locators.
If locators are necessary, they are specified as:
.Bl -item -offset indent -compact
.It
.Em define device {[locator1 = default1], [locator2 = default2]}
.El
A device can also reference an attribute with locators.
This is in fact a dependency rule.
For example,
.Pa sys/dev/conf/files
defines the following attribute for
.Tn SCSI
controllers:
.Bl -item -offset indent -compact
.It
.Em define scsi {}			# no locators
.El
and
.Tn SCSI
drivers can then be defined as
.Bl -item -offset indent -compact
.It
.Em define scsictrl: scsi
.El
A device may depend on as many attributes as necessary:
.Bl -item -offset indent -compact
.It
.Em define complexdev: simpledev, otherdev, specialattribute
.El
.\"
.Ss Pseudo devices
.\"
Pseudo device are defined as regular devices, except that they do not need
locators, and use a different keyword:
.Bl -item -offset indent -compact
.It
.Em pseudo-device loop: inet
.It
.Em pseudo-device ksyms
.El
define, respectively, the loopback network interface and the kernel symbols
pseudo-device.
.\"
.Ss Device attachment rules
.\"
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:
.Bl -item -offset indent -compact
.It
.Em attach device at parent, parent2, parent3
.El
which lists all the parent attributes a device may attach to.
For example, if a device is specified as:
.Bl -item -offset indent -compact
.It
.Em device smartknob: bells, whistles
.It
.Em attach smartknob at brainbus
.El
then a
.Bl -item -offset indent -compact
.It
.Cd smartknob* at brainbus?
.El
configuration file line is valid, while a
.Bl -item -offset indent -compact
.It
.Cd smartknob* at dumbbus?
.El
is not.
.Pp
If a device supports attachments to multiple parents, using different
.Dq glue
routines every time, the following syntax specifies the details:
.Bl -item -offset indent -compact
.It
.Em attach device at parent with device_parent_glue
.It
.Em attach device at parent2 with device_parent2_glue
.El
and will define more required attributes, depending on the kernel
configuration file's contents.
.\"
.Ss Rule file inclusion
.\"
It is possible to include other rules files anywhere in a file, using the
.Dq include
keyword:
.Bl -item -offset indent -compact
.It
.Em include "dev/pci/files.pci"
.El
will include the rules for machine-independent pci code.
.Pp
The files
.Pa sys/arch/machine/conf/files.machine ,
for every
.Dq machine
listed in the machine line in the kernel configuration file, as well as
.Pa sys/conf/files ,
are always processed, and do not need to be included.
.\"
.Ss Attribute requirements
.\"
The kernel configuration file description passed to
.Xr config 8
lists several compilation options, as well as several device definitions.
From this list,
.Xr config 8
will build a list of required attributes, which are
.Bl -bullet -offset XXX -compact
.It
the
.Dq option
lines, with the option name translated to lowercase (for example, an
.Dq option INET
line will produce the
.Dq inet
attribute).
.It
the device and pseudo-device names, except for
.Dq root .
.El
.\"
.Ss Kernel file list
.\"
Kernel source files are defined as:
.Bl -item -offset indent -compact
.It
.Em file somewhere/somefile.c	dependencies	need-rules
.El
If the
.Dq 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
.Dq \&|
and
.Dq \&&
operators.
For example, the line
.Bl -item -offset indent -compact
.It
.Em file netinet/ipsec_input.c	(inet | inet6) & ipsec
.El
teaches
.Xr config 8
to only add
.Pa sys/netinet/ipsec_input.c
to the filelist if the
.Dq ipsec
attribute, and at least one of the
.Dq inet
and
.Dq inet6
attributes, are required.
.Pp
The
.Dq need
rules can be empty, or one of the following keywords:
.Bl -tag -width "needs-count" -compact
.It Ar needs-flag
Create an attribute header file, defining whether or not this
attribute is compiled in.
.It Ar 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.
.El
.Pp
The
.Dq attribute header files
are simple C header files created in the kernel compilation directory,
with the name
.Pa attribute.h
and containing the following line:
.Bl -item -offset indent -compact
.It
#define NATTRIBUTE	0
.El
substituting the attribute name and its uppercase form, prefixed with
the letter
.Dq N ,
to
.Dq attribute
and
.Dq NATTRIBUTE ,
respectively.
For a
.Dq needs-flag
rule, the value on the
.Dq #define
line is either 1 if the attribute is required, or 0 if it is not required.
For a
.Dq needs-count
rule, the value is the number of device instances required, or 0
if the device is not required.
.Pp
Attribute files are created for every attribute listed with a
.Dq need
rule, even if it is never referenced from the kernel configuration file.
.\"
.Ss Miscellaneous items
.\"
.Pa sys/arch/machine/conf/files.machine
must also supply the following special commands:
.Bl -tag -width maxpartitions .\" -compact
.It Ar maxpartitions
Defines how many partitions are available on disk block devices, usually 16.
This value is used by
.Xr config 8
to setup various device information structures.
.It Ar maxusers
Defines the bounds, and the default value, for the
.Dq maxusers
parameter in the kernel configuration file.
The usual values are 2 8 64 ;
.Xr config 8
will report an error if the
.Dq maxusers parameter
in the kernel configuration file does not fit in the specified range.
.El
.\"
.Sh FILES
.Bl -tag -width XXX -compact .\" deliberately small width
.It Pa sys/arch/machine/conf/files.machine
Rules for architecture-dependent files, for the
.Dq machine
architecture.
.Pp
.It Pa sys/compat/emul/files.emul
Rules for the
.Dq emul
operating system or subsystem emulation.
.Pp
.It Pa sys/dev/class/files.class
Rules for the
.Dq class
class of devices.
.Pp
.It Pa sys/gnu/arch/i386/fpemul/files.fpemul
Rules for the i386 GPL floating-point emulator.
.Pp
.It Pa sys/scsi/files.scsi
Rules for the common
.Tn SCSI
subsystem.
.El
.Sh SEE ALSO
.Xr config 8