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.
This commit is contained in:
cube
parent
52514196f1
commit
8a5d15c785
|
|
@ -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
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue