diff options
Diffstat (limited to 'share/man/man5/files.conf.5')
-rw-r--r-- | share/man/man5/files.conf.5 | 399 |
1 files changed, 399 insertions, 0 deletions
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 |