A new manual page to describe config(8)'s rules files. Will probably require

more details over time.

2 files changed, 406 insertions, 6 deletions

diff --git a/share/man/man5/Makefile b/share/man/man5/Makefile
index d98789adf06..6b6a746aff5 100644
--- a/share/man/man5/Makefile
+++ b/share/man/man5/Makefile
@@ -1,14 +1,15 @@
-#	$OpenBSD: Makefile,v 1.28 2002/08/26 22:12:11 avsm Exp $
+#	$OpenBSD: Makefile,v 1.29 2002/10/13 21:21:21 miod Exp $
 #	$NetBSD: Makefile,v 1.14 1995/05/11 23:13:15 cgd Exp $
 
 # missing: dump.5 plot.5
 
 MAN=	a.out.5 acct.5 bsd.port.mk.5 bsd.regress.mk.5 core.5 dir.5 disktab.5 \
-	ethers.5 fbtab.5 fs.5 fstab.5 group.5 hostname.if.5 hosts.equiv.5 \
-	hosts.5 intro.5 link.5 login.conf.5 moduli.5 motd.5 netgroup.5 \
-	networks.5 passwd.5 passwd.conf.5 pf.conf.5 phones.5 printcap.5 protocols.5 \
-	remote.5 resolv.conf.5 rpc.5 services.5 shells.5 stab.5 sysctl.conf.5 \
-	types.5 utmp.5 wsconsctl.conf.5 forward.5 genassym.cf.5
+	ethers.5 fbtab.5 files.conf.5 forward.5 fs.5 fstab.5 genassym.cf.5 \
+	group.5 hostname.if.5 hosts.equiv.5 hosts.5 intro.5 link.5 \
+	login.conf.5 moduli.5 motd.5 netgroup.5 networks.5 passwd.5 \
+	passwd.conf.5 pf.conf.5 phones.5 printcap.5 protocols.5 remote.5 \
+	resolv.conf.5 rpc.5 services.5 shells.5 stab.5 sysctl.conf.5 types.5 \
+	utmp.5 wsconsctl.conf.5
 MLINKS= dir.5 dirent.5 fs.5 inode.5 utmp.5 wtmp.5 utmp.5 lastlog.5
 MLINKS+= hosts.equiv.5 .rhosts.5
 MLINKS+= resolv.conf.5 resolver.5
diff --git a/share/man/man5/files.conf.5 b/share/man/man5/files.conf.5
new file mode 100644
index 00000000000..e0f66650c31
--- /dev/null
+++ b/share/man/man5/files.conf.5
@@ -0,0 +1,399 @@
+.\"	$OpenBSD: files.conf.5,v 1.1 2002/10/13 21:21:21 miod 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 fictious
+.Dq root
+node.
+There is no restriction on the
+.Dq childrens
+a device node may have ;
+some device drivers can attach themselves to different kind 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
+.Pq such as Xr pci 4 devices .
+.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
+define pci {[dev = -1], [function = -1]}
+.El
+in the rules files, the following kernel configuration lines are valid:
+.Bl -item -offset indent -compact
+.It
+pciknob0 at pci? dev 2 function 42 # use fixed values
+.It
+pciknob* at pci? dev ? function ?  # use default values
+.It
+pciknob* at pci?                   # use default locators
+.El
+but the following are not:
+.Bl -item -offset indent -compact
+.It
+pciknob* at pci? trick ? treat ?               # unknown locators
+.It
+pciknob* at pci? dev ? function ? usefulness ? # unknown locators
+.El
+.\"
+.Ss Attributes
+.\"
+The syntax
+.Bl -item -offset indent -compact
+.It
+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, as
+.Bl -item -offset indent -compact
+.It
+define attribute {}
+.El
+if no locators are necessary, or
+.Bl -item -offset indent -compact
+.It
+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
+define device {}
+.El
+defines a simple device, with no locators.
+If locators are necessary, they are specified as:
+.Bl -item -offset indent -compact
+.It
+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
+define scsi {}			# no locators
+.El
+and
+.Tn SCSI
+drivers can then be defined as
+.Bl -item -offset indent -compact
+.It
+define scsictrl: scsi
+.El
+A device may depend on as many attributes as necessary:
+.Bl -item -offset indent -compact
+.It
+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
+pseudo-device loop: inet
+.It
+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
+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
+device smartknob: bells, whistles
+.It
+attach smartknob at brainbus
+.El
+then a
+.Bl -item -offset indent -compact
+.It
+smartknob* at brainbus?
+.El
+configuration file line is valid, while a
+.Bl -item -offset indent -compact
+.It
+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
+attach device at parent with device_parent_glue
+.It
+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
+include "dev/pci/files.pci"
+.El
+will include the rules for machine-independant 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
+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
+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 needs-flag
+Create an attribute header file, defining whether or not this
+attribute is compiled in.
+.It 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
+.\"
+The
+.Pa sys/arch/machine/conf/files.machine
+must also supply the following special commands:
+.Bl -tag -width maxpartitions .\" -compact
+.It 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 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.
+.It Pa sys/compat/emul/files.emul
+Rules for the
+.Dq emul
+operating system or subsystem emulation
+.It Pa sys/dev/class/files.class
+Rules for the
+.Dq class
+class of devices.
+.It Pa sys/gnu/arch/i386/fpemul/files.fpemul
+Rules for the i386 GPL floating-point emulator.
+.It Pa sys/scsi/files.scsi
+Rules for the common
+.Tn SCSI
+subsystem.
+.El
+.Sh SEE ALSO
+.Xr config 8