summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorcube <cube@NetBSD.org>2006-06-04 19:41:26 +0000
committercube <cube@NetBSD.org>2006-06-04 19:41:26 +0000
commit8a5d15c7851f6fe776d1881f6edea4775e00a558 (patch)
tree03d119d324ef50ea5322c1b648d155b4a8e01fa0
parent52514196f137a49cdef592582ecd66d038fba70b (diff)
Everything you've always wanted to know about config(1) without daring
asking (with reason). You've entered the config(1) dungeon--More-- An option hits you. You die.
-rw-r--r--usr.bin/config/config.5642
-rw-r--r--usr.bin/config/config.samples.5258
2 files changed, 900 insertions, 0 deletions
diff --git a/usr.bin/config/config.5 b/usr.bin/config/config.5
new file mode 100644
index 00000000000..634a3e5da09
--- /dev/null
+++ b/usr.bin/config/config.5
@@ -0,0 +1,642 @@
+.\" $NetBSD: config.5,v 1.1 2006/06/04 19:41:26 cube Exp $
+.\"
+.\" Copyright (c) 2006 The NetBSD Foundation.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to the NetBSD Foundation
+.\" by Quentin Garnier.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions 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.
+.\" 3. Neither the name of The NetBSD Foundation nor the names of its
+.\" contributors may be used to endorse or promote products derived
+.\" from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``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 FOUNDATION OR CONTRIBUTORS
+.\" 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 January 8, 2006
+.Dt CONFIG 5
+.Os
+.Sh NAME
+.Nm config
+.Nd kernel configuration file syntax
+.Sh DESCRIPTION
+The kernel configuration file specifies the way the kernel should be compiled
+by the rest of the toolchain.
+It is processed by
+.Xr config 1
+to produce a number of files that will allow the user to compile a possibly
+customised kernel.
+One compilation can issue several kernel binaries, with different root and
+dump devices configurations, or with full debugging information.
+.Pp
+This manual page is intended to serve as a complete reference of all aspects
+of the syntax used in the many files processed by
+.Xr config 1 .
+The novice user will prefer looking at the examples given in
+.Xr config.samples 5
+in order to understand better how the default configuration can be changed,
+and how all of its elements interact with each other.
+.Pp
+The kernel configuration file actually contains the description of all the
+options, drivers and source files involved in the kernel compilation, and the
+logic that binds them.
+The
+.Ic setmachine
+statement, usually found in the
+.Pa std.${MACHINE}
+file, hides this from the user by automatically including all the descriptive
+files spread all around the kernel source tree, the main one being
+.Pa conf/files .
+.Pp
+Thus, the kernel configuration file contains two parts:
+the description of the compilation options, and the selection of those options.
+However, a few statements belong to any of the two sections.
+.Pp
+The user controls the options selection part, which is located in a file
+commonly referenced as the
+.Em main configuration file
+or simply the
+.Em kernel configuration file .
+The developer is responsible for describing the options in the relevant files
+from the kernel source tree.
+.Ss OBJECTS AND NAMES
+.Xr config 1
+is a rather complicated piece of software that tries to comply with any
+configuration the user might think of.
+Quite a few different objets are manipulated through the kernel configuration
+file, therefore some definitions are needed.
+.Ss Options and attributes
+The basic objects driving the kernel compilation are
+.Em options ,
+and are called
+.Ar attributes
+in some contexts.
+An
+.Ar attribute
+usually refers to a feature a given piece of hardware might have.
+However, the scope of an attribute is rather wide and can just be a place
+holder to group some source files together.
+.Pp
+There is a special class of attribute, named
+.Em interface attribute ,
+which represents a hook that allows a device to attach to (i.e., be a child of)
+another device.
+An
+.Em interface attribute
+has a (possibly empty) list of
+.Ar locators
+to match the actual location of a device.
+For example, on a PCI bus, devices are located by a
+.Em device number
+that is fixed by the wiring of the motherboard.
+Additionally, each of those devices can appear through several interfaces named
+.Em functions .
+A single PCI device entity is a unique function number of a given device from
+the considered PCI bus.
+Therefore, the locators for a
+.Xr pci 4
+device are
+.Ar dev
+(for device), and
+.Ar function .
+.Pp
+A
+.Ar locator
+can either be a single integer value, or an array of integer values.
+It can have a default value, in which case it can be wildcarded with a
+.Dq \&?
+in the options selection section of the configuration file.
+A single
+.Ar locator
+definition can take one of the following forms:
+.Bl -enum -offset indent -compact
+.It
+.Ar locator
+.It
+.Ar locator
+=
+.Ar value
+.It
+.Ar locator Ns Oo Ar length Oc
+.It
+.Ar locator Ns Oo Ar length Oc = Brq Ar value , ...
+.El
+The variants that specify a default value can be enclosed into square brackets,
+in which case the locator will not have to be specified later in the options
+selection section of the configuration file.
+.Pp
+In the options selection section, the locators are specified when declaring an
+instance as a space-separated list of
+.Dq Ao Ar locator Ac Ao Ar value Ac
+where value can be the
+.Dq \&?
+wildcard if the locator allows it.
+.Ss Devices, instances and attachments
+The main benefit of the kernel configuration file is to allow the user to avoid
+compiling some drivers, and wire down the configuration of some others.
+We have already seen that devices attach to each other through
+.Em interface attributes ,
+but not everything can attach to anything.
+Furthermore, the user has the ability to define precise instances for the
+devices.
+An
+.Ar instance
+is simply the reality of a device when it is probed and attached by the kernel.
+.Pp
+Each driver has a name for its devices.
+It is called the base device name and is found as
+.Ar base
+in this documentation.
+An
+.Ar instance
+is the concatenation of a device name and a number.
+In the kernel configuration file, instances can sometimes be wildcarded
+(i.e., the number is replaced by a
+.Dq *
+or a
+.Dq \&? )
+in order to match all the possible instances of a device.
+.Pp
+The usual
+.Dq *
+becomes a
+.Dq \&?
+when the instance name is used as an
+.Em attachment name .
+In the options selection part of the kernel configuration files, an
+.Em attachment
+is an
+.Em interface attribute
+concatenated with a number or the wildcard
+.Dq \&? .
+.Ss Pseudo-devices
+Some components of the kernel behave like a device although they don't have
+any actual reality in the hardware.
+For example, this is the case for special network devices, such as
+.Xr tun 4
+and
+.Xr tap 4 .
+They are integrated in the kernel as pseudo-devices, and can have several
+instances and even children, just like normal devices.
+.Ss Dependencies
+The options description part of the kernel configuration file contains all the
+logic that ties the source files together, and it is done first through writing
+down dependencies between
+.Xr config 1
+objects.
+.Pp
+In this documentation, the syntax for
+.Ar dependencies
+is a comma-separated list of
+.Ar options
+and
+.Ar attributes .
+.Pp
+For example, the use of an Ethernet network card requires the source files that
+handle the specificities of that protocol.
+Therefore, all Ethernet network card drivers depend on the
+.Ar ether
+attribute.
+.Ss Conditions
+Finally, source file selection is possible through the help of
+conditionals, referred to as
+.Ar condition
+later in this documentation.
+The syntax for those conditions uses well-known operators (
+.Dq \*[Am] ,
+.Dq |
+and
+.Dq \&! )
+to combine
+.Ar options
+and
+.Ar attributes .
+.Ss CONTEXT NEUTRAL STATEMENTS
+.Bl -ohang
+.It Ic version Ar yyyymmdd
+Indicates the syntax version used by the rest of the file, or until the next
+.Ic version
+statement.
+The argument is an ISO date.
+A given
+.Xr config 1
+binary might only be compatible with a limited range of version numbers.
+.It Ic include Ar path
+Includes a file.
+The path is relative to the top of the kernel source tree, or the inner-most
+defined
+.Ic prefix .
+.It Ic cinclude Ar path
+Conditionally includes a file.
+Contrary to
+.Ic include ,
+it will not produce an error if the file does not exist.
+The argument obeys the same rules as for
+.Ic include .
+.It Ic prefix Op Ar path
+If
+.Ar path
+is given, it pushes a new prefix for
+.Ic include
+and
+.Ic cinclude .
+.Ic prefix
+statements act like a stack, and an empty
+.Ar path
+argument has the latest prefix popped out.
+The
+.Ar path
+argument is either absolute or relative to the current defined prefix, which
+defaults to the top of ther kernel source tree.
+.It Ic package Ar path
+Simpler version of:
+.Bd -literal -offset indent
+prefix PATH
+include FILE
+prefix
+.Ed
+.El
+.Ss OPTIONS DESCRIPTION
+The user will not usually have to use descriptive statements, as they are meant
+for the developer to tie a given piece of code to the rest of the kernel.
+However, third parties may provide sources to add to the kernel compilation,
+and the logic that binds them to the
+.Nx
+kernel will have to be added to the user-edited configuration file.
+.Bl -ohang
+.It Ic devclass Ar class
+Defines a special attribute, named
+.Em device class .
+A given device cannot belong to more than one device class.
+.Xr config 1
+translates that property by the rule that a device cannot depend on more than
+one device class, and will properly fill the configuration information file it
+generates according to that value.
+.It Ic defflag Oo Ar file Oc Ar option Oo Ar option Oo Ar ... Oc Oc \
+ Op : Ar dependencies
+Defines a boolean option, that can either be selected or be un-selected by the
+user with the
+.Ic options
+statement.
+The optional
+.Ar file
+argument names a header file that will contain the C pre-processor definition
+for the option.
+If no file name is given, it will default to
+.Ar opt_\*[Lt]option\*[Gt].h .
+.Xr config 1
+will always create the header file, but if the user choose not to select the
+option, it will be empty.
+Several options can be combined in one header file, for convenience.
+The header file is created in the compilation directory, making them directly
+accessible by source files.
+.It Ic defparam Oo Ar file Oc Ar option Oo Ar option Oo Ar ... Oc Oc \
+ Op : Ar dependencies
+Behaves like
+.Ic defflag ,
+except the defined option must have a value.
+Such options are not typed:
+they can have either a numeric or a string value.
+.It Ic deffs Oo Ar file Oc Ar name Op Ar name Op Ar ...
+Defines a file-system name.
+It is no more than a regular option, as defined by
+.Ic defflag ,
+but it allows the user to select the
+file-systems to be compiled in the kernel with the
+.Ic file-system
+statement instead of the
+.Ic options
+statement, and
+.Xr config 1
+will enforce the rule that the user must select at least one file-system.
+.It Ic obsolete defflag Oo Ar file Oc Ar option Op Ar option Op Ar ...
+.It Ic obsolete defparam Oo Ar file Oc Ar option Op Ar option Op Ar ...
+Those two statements are identical and mark the listed option names as
+obsolete.
+If the user selects one of the listed options in the kernel configuration
+file,
+.Xr config 1
+will emit a warning and ignore the option.
+The optional
+.Ar file
+argument should match the original definition of the option.
+.It Ic define Ar attribute Oo Bro Ar locators Brc Oc Oo : Ar dependencies Oc
+Defines an
+.Ar attribute .
+The
+.Ar locators
+list is optional, and can be empty.
+If the pair of brackets are present, the locator list is defined and the
+declared attribute becomes an
+.Em interface attribute ,
+on which devices can attach.
+.It Ic maxpartitions Ar number
+Defines the maximum number of partitions the disklabels for the considered
+architecture can hold.
+This statement cannot be repeated and should only appear in the
+.Pa std\&.$\&{ARCH\&}
+file.
+.It Ic maxusers Ar min default max
+Indicates the range of values that will later be accepted by
+.Xr config 1
+for the
+.Ic maxusers
+statement in the options selection part of the configuration file.
+In case the user doesn't include a
+.Ic maxusers
+statement in the configuration file, the value
+.Ar default
+is used instead.
+.It Ic device Ar base Oo Bro Ar locators Brc Oc Oo : dependencies Oc
+Declares a device of name
+.Ar base .
+The optional list of
+.Ar locators ,
+which can also be empty, indicates the device can have children attached
+directly to it.
+Internally, that means
+.Ar base
+becomes an
+.Ar interface attribute .
+For every device the user selects,
+.Xr config 1
+will add the matching
+.Fn CFDRIVER_DECL
+statement to
+.Pa ioconf.c .
+However, it is the responsibility of the developer to add the relevant
+.Fn CFATTACH_DECL
+line to the source of the device's driver.
+.It Ic attach Ar base Ic at Ar attr Oo , Ar attr Oo , Ar ... Oc Oc Oo Ic with \
+ Ar name Oc Oo : dependencies Oc
+All devices must have at least one declared attachment.
+Otherwise, they will never be found in the
+.Xr autoconf 9
+process.
+The attributes on which an instance of device
+.Ar base
+can attach must be
+.Ar interface attributes ,
+or
+.Ic root
+in case the device is at the top-level, which is usually the case of e.g.,
+.Xr mainbus 4 .
+The instances of device
+.Ar base
+will later attach to one interface attribute from the specified list.
+.Pp
+Different
+.Ic attach
+definitions must use different names using the
+.Ic with
+option.
+It is then possible to use the associated
+.Ar name
+as a conditional element in a
+.Ic file
+statement.
+.It Ic defpseudo Ar base Oo Bro Ar locators Brc Oc Oo : dependencies Oc
+Declares a pseudo-device.
+Those devices don't need an attachment to be declared, they will always be
+attached if they were selected by the user.
+As normal devices, an optional list of
+.Ar locators
+can be defined, allowing the pseudo-device to have children.
+.It Ic file Ar path Oo Ar condition Oc Oo Ic needs-count Oc \
+ Oo Ic needs-flag Oc Op Ic compile with Ar rule
+Adds a source file to the list of files to be compiled into the kernel, if the
+.Ar conditions
+are met.
+The
+.Ic needs-count
+option indicates that the source file requires the number of all the countable
+objects it depends on (through the
+.Ar conditions )
+to be defined.
+It is usually used for
+.Ar pseudo-devices
+whose number can be specified by the user in the
+.Ic pseudo-device
+statement.
+The
+.Ic needs-flag
+options requires that a flag indicating the selection of an attribute to
+be created, but the precise number isn't needed.
+This is useful for source files that only partly depend on the attribute,
+and thus need to add pre-processor statements for it.
+.Pp
+The
+.Ar rule
+argument specifies the
+.Xr make 1
+rule that will be used to compile the source file.
+If it is not given, the default rule for the type of the file will be used.
+For a given file, there can be more than one
+.Ic file
+statement, but not from the same configuration source file, and all later
+statements can only specify a
+.Ar rule
+argument, and no
+.Ar conditions
+or flags.
+This is useful when a file needs special consideration from one particular
+architecture.
+.It Ic object Ar path Op Ar condition
+Adds an object file to the list of objects to be linked into the kernel, if the
+.Ar conditions
+are met.
+This is most useful for third parties providing binary-only components.
+.It Ic device-major Ar base Oo Ic char Ar number Oc Oo Ic block Ar number Oc \
+ Op Ar condition
+Associates a major device number with the device
+.Ar base .
+A device can be a character device, a block device, or both, and can have
+different numbers for each.
+The
+.Ar condition
+indicates when the relevant line should be added to
+.Pa ioconf.c ,
+and works just like the
+.Ic file
+statement.
+.It Ic makeoptions Ar condition name Ns += Ns Ar value Op , Ar condition \
+ name Ns += Ns Ar value
+Appends to a definition in the generated
+.Pa Makefile .
+.El
+.Ss OPTIONS SELECTION
+.Bl -ohang
+.It Ic setmachine Ar machine Op Ar arch Op Ar subarch Op Ar ...
+The
+.Ic setmachine
+statement should appear first in the kernel configuration file, with the
+exception of context-neutral statements.
+It makes
+.Xr config 1
+include, in that order, the following files:
+.Bl -enum -offset indent -compact
+.It
+.Pa conf/files
+.It
+.Pa arch/${ARCH}/conf/files.${ARCH}
+if defined
+.It
+.Pa arch/${SUBARCH}/conf/files.${SUBARCH}
+for each defined sub-architecture
+.It
+.Pa arch/${MACHINE}/conf/files.${MACHINE}
+.El
+.It Ic ident Ar string
+Defines the indentification string of the kernel.
+This statement is optional, and the name of the main configuration file will be
+used as a default value.
+.It Ic maxusers Ar number
+Despite its name, this statement does not limit the maximum number of users on
+the system.
+There is no such limit, actually.
+However, some kernel structures need to be adjusted to accomodate with more
+users, and the
+.Ic maxusers
+parameter is used for example to compute the maximum number of opened files,
+and the maximum number of processes, which itself is used to adjust a few
+other parameters.
+.It Ic options Ar name Oo = Ar value Oc Op , Ar name Oo = Ar \
+ value Oc , Ar ...
+Selects the option
+.Ar name ,
+affecting it a
+.Ar value
+if the options requires it (see the
+.Ic defflag
+and
+.Ic defparam
+statements).
+.Pp
+If the option has not been declared in the options description part of the
+kernel configuration machinery, it will be added as a pre-processor definition
+when source files are compiled.
+.It Ic no options Ar name Op , Ar name Op , Ar ...
+Un-selects the option
+.Ar name .
+If option
+.Ar name
+has not been previously selected, the statement produces an error.
+.It Oo Ic no Oc Ic file-system Ar name Op , Ar name Op , Ar ...
+Adds or removes support for all the listed file-systems.
+A kernel must have support for at least one file-system.
+.It Ic config Ar name Ic root on Ar device Oo Ic type Ar fs Oc Op Ic dumps on \
+ Ar device
+Adds
+.Ar name
+to the list of kernel binaries to compile from the configuration file, using
+the specified root and dump devices information.
+.Pp
+Any of the
+.Ar device
+and
+.Ar fs
+parameters can be wildcarded with
+.Dq \&?
+to let the kernel automatically discover those values.
+.Pp
+At least one
+.Ic config
+statement must appear in the configuration file.
+.It Ic no config Ar name
+Removes
+.Ar name
+from the list of kernel binaries to compile from the configuration file.
+.It Ar instance Ic at Ar attachment Op Ar locator specification
+Configures an instance of a device attaching at a specific location in the
+device tree.
+All parameters can be wildcarded, with a
+.Dq *
+for
+.Ar instance ,
+and a
+.Dq \&?
+for
+.Ar attachment
+and the locators.
+.It Ic no Ar instance Op Ic at Ar attachment
+Removes the previously configured instances of a device that exactly match the
+given specification.
+If two instances differ only by their locators, both are removed.
+If no
+.Ar attachment
+is specified, all matching instances are removed.
+.Pp
+If
+.Ar instance
+is a bare device name, all the previously defined instances of that device,
+regardless of the numbers or wildcard, are removed.
+.It Ic no device at Ar attachment
+Removes all previously configured instances that attach to the specified
+attachment.
+If
+.Ar attachment
+ends with a
+.Dq * ,
+all instances attaching to all the variants of
+.Ar attachment
+are removed.
+.It Ic pseudo-device Ar device Op Ar number
+Adds support for the specified pseudo-device.
+The parameter
+.Ar number
+is passed to the initialisation function of the pseudo-device, usually to
+indicate how many instances should be created.
+It defaults to 1, and some pseudo-devices ignore that parameter.
+.It Ic no pseudo-device Ar name
+Removes support for the specified pseudo-device.
+.It Ic makeoptions Ar name Ns = Ns value Op , Ar name Ns += Ns value \
+ Op , Ar ...
+Adds or appends to a definition in the generated
+.Pa Makefile .
+A definition cannot be overriden, it must be removed before it can be added
+again.
+.It Ic no makeoptions Ar name Op , Ar name Op , Ar ...
+Removes one or more definitions from the generated
+.Pa Makefile .
+.El
+.Sh FILES
+The files are relative to the kernel source top directory (e.g.,
+.Pa /usr/src/sys ) .
+.Pp
+.Bl -tag -width arch/${MACHINE}/conf/std.${MACHINE}
+.It Pa arch/${MACHINE}/conf/std.${MACHINE}
+Standard configuration for the given architecture.
+This file should always be included.
+.It Pa arch/${MACHINE}/conf/GENERIC
+Standard options selection file for the given architecture.
+Users should always start changing their main kernel configuration file by
+editing a copy of this file.
+.It Pa conf/files
+Main options description file.
+.El
+.Sh EXAMPLES
+.Xr config.samples 5
+uses several examples to cover all the practical aspects of writing or
+modifying a kernel configuration file.
+.Sh SEE ALSO
+.Xr config 1 ,
+.Xr options 4 ,
+.Xr config.samples 5 ,
+.Xr config 9
diff --git a/usr.bin/config/config.samples.5 b/usr.bin/config/config.samples.5
new file mode 100644
index 00000000000..08f177d10d6
--- /dev/null
+++ b/usr.bin/config/config.samples.5
@@ -0,0 +1,258 @@
+.\" $NetBSD: config.samples.5,v 1.1 2006/06/04 19:41:26 cube Exp $
+.\"
+.\" Copyright (c) 2006 The NetBSD Foundation.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to the NetBSD Foundation
+.\" by Quentin Garnier.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions 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.
+.\" 3. Neither the name of The NetBSD Foundation nor the names of its
+.\" contributors may be used to endorse or promote products derived
+.\" from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``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 FOUNDATION OR CONTRIBUTORS
+.\" 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 March 24, 2006
+.Dt CONFIG.SAMPLES 5
+.Os
+.Sh NAME
+.Nm config.samples
+.Nd kernel configuration file syntax examples
+.Sh DESCRIPTION
+.Ss Devices, drivers and instances
+For a given device, at most one driver will attach.
+In order for a driver to attach, the kernel configuration file must include a
+compatible instance of the driver for the location of the device.
+The following lines from the
+.Pa GENERIC
+kernel configuration file of
+.Nx Ns / Ns i386
+are examples of instances of drivers:
+.Bd -literal
+pchb* at pci? dev ? function ? # PCI-Host bridges
+pcib* at pci? dev ? function ? # PCI-ISA bridges
+ppb* at pci? dev ? function ? # PCI-PCI bridges
+
+siop* at pci? dev ? function ? # Symbios 53c8xx SCSI
+esiop* at pci? dev ? function ? # Symbios 53c875 SCSI and newer
+
+ix0 at isa? port 0x300 irq 10 # EtherExpress/16
+.Ed
+.Pp
+The first three instances allow three different drivers to attach to all the
+matching devices found on any PCI bus.
+This is the most generic case.
+.Pp
+The next two lines allow two distinct drivers to attach to any matching device
+found on any PCI bus, but those two drivers are special because they both
+support some of the same devices.
+Each of the driver has a matching function that returns their score for the
+device that is being considered.
+.Xr autoconf 9
+decides at run-time which driver will attach.
+Of course, it is deterministic so if the user wants to change the driver that
+attaches to the device, the instance of the other driver will have to be
+removed, e.g. by commenting it out.
+.Pp
+The last line configures an instance of an ISA device.
+Unlike the PCI bus, the ISA bus cannot discover the devices that are present on
+the bus.
+The driver has to try accessing the device in order to discover it.
+That implies locators must be specified to some extent: a driver would
+usually need the base address of the device, some need the IRQ line that the
+device is configured to use, thoug some others would just try a set of known
+values, at the risk of badly interacting with other devices on the bus.
+.Ss Hard-wiring kernel configuration
+This technique consists in specifying exactly the location of the devices on a
+given system.
+In the general case it has very little use, because it does not change the size
+of the kernel, and it will prevent it from finding devices in case the hardware
+changes, even slightly.
+.Pp
+Let's consider the following excerpt of
+.Xr dmesg 8
+output:
+.Bd -literal
+auich0 at pci0 dev 31 function 5: i82801DB/DBM (ICH4/ICH4M) AC-97 Audio
+.Ed
+.Pp
+The
+.Xr auich 4
+driver (which controls Intel's AC-97 audio chips) attached there because of the
+following instance of
+.Pa GENERIC :
+.Bd -literal
+auich* at pci? dev ? function ?
+.Ed
+.Pp
+Hard-wiring that instance means re-writing it to the following:
+.Bd -literal
+auich0 at pci0 dev 31 function 5
+.Ed
+.Pp
+and that way,
+.Ar auich0
+will attach to that specific location, or will not attach.
+.Ss Removing options and drivers
+When two kernel configurations differ by a very small number of changes, it is
+easier to manage them by having one include the other, and add or remove the
+differences.
+Removing options and drivers is also useful in the situation of a user who
+wants to follow the development of
+.Nx :
+drivers and options get added to the configuration files found in the source
+tree, such as
+.Pa GENERIC ,
+so one can include it and remove all options and drivers that are not relevant
+to the considered system.
+Additions to
+.Pa GENERIC
+will then automatically be followed and used in case they are relevant.
+.Pp
+While negating an options (with
+.Ic no options )
+is unambiguous, it is not as clear for devices instances.
+.Pp
+The
+.Ic no Ar instance definition
+statements of
+.Xr config 1
+syntax only apply on the current state of the configuration file, not on the
+resulting kernel binary.
+.Xr autoconf 9
+has no knowledge of instance negation, thus it is currently impossible to
+express the following in a kernel configuration file:
+.Bd -ragged -offset indent
+.Do I want support for
+.Xr ath 4
+attaching at
+.Xr pci 4 ,
+but I do not want any instance of
+.Xr ath 4
+attaching at
+.Ar pci3 .
+.Dc
+.Ed
+.Pp
+For a real-world use of
+.Ic no device at Ar instance
+consider the following, taken from
+.Nx Ns / Ns i386 :
+.Bd -literal -offset indent
+include "arch/i386/conf/GENERIC"
+
+acpi0 at mainbus?
+
+com* at acpi?
+[... more instances of legacy devices attaching at acpi? ...]
+
+no device at isa0
+.Ed
+.Pp
+One could actually live without the
+.Ar isa0
+instance, as all the legacy devices are attached at
+.Ar acpi0 .
+But unfortunately, dependencies on the
+.Ar isa
+attribute are not well registered all through the source tree, so an instance
+of the
+.Xr isa 4
+driver is required to compile a kernel.
+So while:
+.Bd -literal -offset indent
+no isa*
+.Ed
+.Pp
+is what is intended, the
+.Xr isa 4
+instance itself must be kept, and that is precisely the difference made by:
+.Bd -literal -offset indent
+no device at isa0
+.Ed
+.Ss Interface attributes
+.Em Interface attributes
+are a subtility of
+.Xr config 1
+and
+.Xr autoconf 9 ,
+which often confuses users and utilities that parse
+.Xr dmesg 8
+output to manipulate kernel configuration files.
+What they are is best shown by the following example.
+.Pp
+The
+.Xr dmesg 8
+output look like this:
+.Bd -literal -offset indent
+auvia0 at pci0 dev 17 function 5: VIA Technologies VT8235 AC'97 Audio (rev 0x50)
+audio0 at auvia0: full duplex, mmap, independent
+.Ed
+.Pp
+while the kernel configuration look like this:
+.Bd -literal
+auvia* at pci? dev ? function ?
+audio* at audiobus?
+.Ed
+.Pp
+It is not obvious from the kernel configuration file that an
+.Xr audio 4
+device can attach at an
+.Xr auvia 4
+device.
+.Ar audiobus
+is an
+.Em interface attribute ,
+exposed by
+.Ar auvia .
+.Pp
+Of course, it is possible to specify
+.Bd -literal -offset indent
+audio* at auvia?
+.Ed
+in the kernel configuration file, but then one instance per audio controler
+would be needed.
+.Em Interface attributes
+reflect the fact there is a standard way to attach a device to its parent, no
+matter what the latter is precisely.
+It also means lower maintainance of the kernel configuration files because
+drivers for audio controlers are added more easily.
+.Pp
+Most attachments are done through
+.Em interface attributes ,
+although only a few of them are specified that way in the configuration files
+found in the tree.
+Another example of such an attribute is
+.Ar ata :
+.Bd -literal -offset indent
+viaide0 at pci0 dev 17 function 1
+atabus0 at viaide0 channel 0
+
+viaide* at pci? dev ? function ?
+atabus* at ata?
+.Ed
+.\" Suggested section, maybe for later:
+.\" .Ss Using a third-party driver
+.Sh SEE ALSO
+.Xr config 1 ,
+.Xr options 4 ,
+.Xr config 5 ,
+.Xr dmesg 8