NAME
config
- kernel configuration file syntax
DESCRIPTION
The kernel configuration file specifies the way the kernel should be compiled
by the rest of the toolchain.
It is processed by
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.
This manual page is intended to serve as a complete reference of all aspects
of the syntax used in the many files processed by
config(1).
The novice user will prefer looking at the examples given in
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.
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
machine
statement, usually found in the
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
conf/files
.
Thus, the kernel configuration file contains two parts:
the description of the compilation options, and the selection of those options.
However, it begins with a small preamble that controls a couple of options of
config(1),
and a few statements belong to any of the two sections.
The user controls the options selection part, which is located in a file
commonly referenced as the
main configuration file
or simply the
kernel configuration file.
The developer is responsible for describing the options in the relevant files
from the kernel source tree.
Statements are separated by new-line characters.
However, new-line characters can appear in the middle of a given statement,
with the value of a space character.
OBJECTS AND NAMES
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 objects are manipulated through the kernel configuration
file, therefore some definitions are needed.
Options and attributes
The basic objects driving the kernel compilation are
options,
and are called
attributes
in some contexts.
An
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.
There is a special class of attribute, named
interface attribute,
which represents a hook that allows a device to attach to (i.e., be a child of)
another device.
An
interface attribute
has a (possibly empty) list of
locators
to match the actual location of a device.
For example, on a PCI bus, devices are located by a
device number
that is fixed by the wiring of the motherboard.
Additionally, each of those devices can appear through several interfaces named
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
pci(4)
device are
dev
(for device), and
function.
A
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
``?''
in the options selection section of the configuration file.
A single
locator
definition can take one of the following forms:
-
locator
-
locator
=
value
-
locatorlength[.blm Pp]
-
locatorlength[.blm Pp = {value, ...}]
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.
In the options selection section, the locators are specified when declaring an
instance as a space-separated list of
``locator<.blm Pp value<.blm Pp > >''
where value can be the
``?''
wildcard if the locator allows it.
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
interface attributes,
but not everything can attach to anything.
Furthermore, the user has the ability to define precise instances for the
devices.
An
instance
is simply the reality of a device when it is probed and attached by the kernel.
Each driver has a name for its devices.
It is called the base device name and is found as
base
in this documentation.
An
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
``*''
or a
``?'')
in order to match all the possible instances of a device.
The usual
``*''
becomes a
``?''
when the instance name is used as an
attachment name.
In the options selection part of the kernel configuration files, an
attachment
is an
interface attribute
concatenated with a number or the wildcard
``?''.
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
tun(4)
and
tap(4).
They are integrated in the kernel as pseudo-devices, and can have several
instances and even children, just like normal devices.
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
config(1)
objects.
In this documentation, the syntax for
dependencies
is a comma-separated list of
options
and
attributes.
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
ether
attribute.
Conditions
Finally, source file selection is possible through the help of
conditionals, referred to as
condition
later in this documentation.
The syntax for those conditions uses well-known operators (
``&'',
``|''
and
``!'')
to combine
options
and
attributes.
CONTEXT NEUTRAL STATEMENTS
- version yyyymmdd
-
Indicates the syntax version used by the rest of the file, or until the next
version
statement.
The argument is an ISO date.
A given
config(1)
binary might only be compatible with a limited range of version numbers.
- include path
-
Includes a file.
The path is relative to the top of the kernel source tree, or the inner-most
defined
prefix.
- cinclude path
-
Conditionally includes a file.
Contrary to
include,
it will not produce an error if the file does not exist.
The argument obeys the same rules as for
include.
- prefix[ path]
-
If
path
is given, it pushes a new prefix for
include
and
cinclude.
prefix
statements act like a stack, and an empty
path
argument has the latest prefix popped out.
The
path
argument is either absolute or relative to the current defined prefix, which
defaults to the top of ther kernel source tree.
- ifdef attribute
-
- ifndef attribute
-
- elifdef attribute
-
- elifndef attribute
-
- else
-
- endif
-
Conditionally interprets portions of the current file.
Those statements depend on whether or not the given
attribute
has been previously defined, through
define
or any other statement that implicitely defines attributes such as
device.
PREAMBLE
In addition to
include, cinclude,
and
prefix,
the preamble may contain the following optional statements:
- build path
-
Defines the build directory for the compilation of the kernel.
It replaces the default of
../compile/<config-file>
and is superseded by the
-b
parameter of
config(1).
- source path
-
Defines the directory in which the source of the kernel lives.
It replaces the default of
../../../..
and is superseded by the
-s
parameter of
config(1).
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
NetBSD
kernel will have to be added to the user-edited configuration file.
- devclass class
-
Defines a special attribute, named
device class.
A given device cannot belong to more than one device class.
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.
- defflag file[.blm Pp option option ...[[.blm Pp[: dependencies]
- ]]]
Defines a boolean option, that can either be selected or be un-selected by the
user with the
options
statement.
The optional
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
opt_<option>.h.
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.
- defparam file[.blm Pp option = value[.blm Pp := lint-value[.blm Pp option ...[[.blm Pp[: dependencies]
- ]]]]]
Behaves like
defflag,
except the defined option must have a value.
Such options are not typed:
they can have either a numeric or a string value.
If a
value
is specified, it is treated as a default, and the option is
always defined in the corresponding header file.
If a
lint-value
is specified,
config(1)
will use it as a value when generating a lint configuration with
-L,
and ignore it in all other cases.
- deffs file[.blm Pp name[ name[ ...]]
- ]
Defines a file-system name.
It is no more than a regular option, as defined by
defflag,
but it allows the user to select the
file-systems to be compiled in the kernel with the
file-system
statement instead of the
options
statement, and
config(1)
will enforce the rule that the user must select at least one file-system.
- obsolete defflag file[.blm Pp option[ option[ ...]]
- ]
- obsolete defparam file[.blm Pp option[ option[ ...]]
- ]
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,
config(1)
will emit a warning and ignore the option.
The optional
file
argument should match the original definition of the option.
- define attribute locators[{.blm Pp :dependencies[.blm Pp
- }]]
Defines an
attribute.
The
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
interface attribute,
on which devices can attach.
- maxpartitions 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
std.${ARCH}
file.
- maxusers min default max
-
Indicates the range of values that will later be accepted by
config(1)
for the
maxusers
statement in the options selection part of the configuration file.
In case the user doesn't include a
maxusers
statement in the configuration file, the value
default
is used instead.
- device base locators[{.blm Pp :dependencies[.blm Pp
- }]]
Declares a device of name
base.
The optional list of
locators,
which can also be empty, indicates the device can have children attached
directly to it.
Internally, that means
base
becomes an
interface attribute.
For every device the user selects,
config(1)
will add the matching
CFDRIVER_DECL(
)
statement to
ioconf.c
.
However, it is the responsibility of the developer to add the relevant
CFATTACH_DECL(
)
line to the source of the device's driver.
- attach base at attr ,attr ,...[[.blm Pp with name[.blm Pp :dependencies[.blm Pp
- ]]]]
All devices must have at least one declared attachment.
Otherwise, they will never be found in the
autoconf(9)
process.
The attributes on which an instance of device
base
can attach must be
interface attributes,
or
root
in case the device is at the top-level, which is usually the case of e.g.,
mainbus(4).
The instances of device
base
will later attach to one interface attribute from the specified list.
Different
attach
definitions must use different names using the
with
option.
It is then possible to use the associated
name
as a conditional element in a
file
statement.
- defpseudo base :dependencies[.blm Pp
- ]
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.
- defpseudodev base locators[{.blm Pp :dependencies[.blm Pp
- }]]
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.
This declaration should be used if the pseudodevice uses
autoconf(9)
functions to manage its instances or attach children.
As for normal devices, an optional list of
locators
can be defined, which implies an interface attribute named
base,
allowing the pseudo-device to have children.
Interface attributes can also be defined in the
dependencies
list.
- file path condition[.blm Pp needs-count[.blm Pp needs-flag[.blm Pp[ compile with rule]
- ]]]
Adds a source file to the list of files to be compiled into the kernel, if the
conditions
are met.
The
needs-count
option indicates that the source file requires the number of all the countable
objects it depends on (through the
conditions)
to be defined.
It is usually used for
pseudo-devices
whose number can be specified by the user in the
pseudo-device
statement.
Countable objects are devices and pseudo-devices.
For the former, the count is the number of declared instances.
For the latter, it is the number specified by the user, defaulting to 1.
The
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.
needs-count
and
needs-flag
both produce a header file for each of the considered attributes.
The name of that file is
<attribute>.h
.
It contains one pre-processor definition of
NATTRIBUTE
set to 0 if the attribute was not selected by the user, or to the number of
instances of the device in the
needs-count
case, or to 1 in all the other cases.
The
rule
argument specifies the
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
file
statement, but not from the same configuration source file, and all later
statements can only specify a
rule
argument, and no
conditions
or flags.
This is useful when a file needs special consideration from one particular
architecture.
- object path[ condition]
-
Adds an object file to the list of objects to be linked into the kernel, if the
conditions
are met.
This is most useful for third parties providing binary-only components.
- device-major base char number[.blm Pp block number[.blm Pp[ condition]
- ]]
Associates a major device number with the device
base.
A device can be a character device, a block device, or both, and can have
different numbers for each.
The
condition
indicates when the relevant line should be added to
ioconf.c
,
and works just like the
file
statement.
- makeoptions condition name+=value[, condition name+=value]
-
Appends to a definition in the generated
Makefile
.
OPTIONS SELECTION
- machine machine[ arch[ subarch[ ...]]]
-
The
machine
statement should appear first in the kernel configuration file, with the
exception of context-neutral statements.
It makes
config(1)
include, in that order, the following files:
-
conf/files
-
arch/${ARCH}/conf/files.${ARCH}
if defined
-
arch/${SUBARCH}/conf/files.${SUBARCH}
for each defined sub-architecture
-
arch/${MACHINE}/conf/files.${MACHINE}
It also defines an attribute for the
machine,
the
arch
and each of the
subarch.
- package path
-
Simpler version of:
-
prefix PATH
include FILE
prefix
- ident 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.
- maxusers 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 accommodate with more
users, and the
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.
- options name = value[.blm Pp[, name = value[.blm Pp, ...]
- ]]
Selects the option
name,
affecting it a
value
if the options requires it (see the
defflag
and
defparam
statements).
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.
- no options name[, name[, ...]]
-
Un-selects the option
name.
If option
name
has not been previously selected, the statement produces an error.
- no[.blm Pp file-system name[, name[, ...]]
- ]
Adds or removes support for all the listed file-systems.
A kernel must have support for at least one file-system.
- config name root on device type fs[.blm Pp[ dumps on device]
- ]
Adds
name
to the list of kernel binaries to compile from the configuration file, using
the specified root and dump devices information.
Any of the
device
and
fs
parameters can be wildcarded with
``?''
to let the kernel automatically discover those values.
At least one
config
statement must appear in the configuration file.
- no config name
-
Removes
name
from the list of kernel binaries to compile from the configuration file.
- instance at attachment[ locator specification]
-
Configures an instance of a device attaching at a specific location in the
device tree.
All parameters can be wildcarded, with a
``*''
for
instance,
and a
``?''
for
attachment
and the locators.
- no instance[ at 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
attachment
is specified, all matching instances are removed.
If
instance
is a bare device name, all the previously defined instances of that device,
regardless of the numbers or wildcard, are removed.
- no device at attachment
-
Removes all previously configured instances that attach to the specified
attachment.
If
attachment
ends with a
``*'',
all instances attaching to all the variants of
attachment
are removed.
- pseudo-device device[ number]
-
Adds support for the specified pseudo-device.
The parameter
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.
- no pseudo-device name
-
Removes support for the specified pseudo-device.
- makeoptions name=value[, name+=value[, ...]]
-
Adds or appends to a definition in the generated
Makefile
.
A definition cannot be overriden, it must be removed before it can be added
again.
- no makeoptions name[, name[, ...]]
-
Removes one or more definitions from the generated
Makefile
.
FILES
The files are relative to the kernel source top directory (e.g.,
/usr/src/sys
).
arch/${MACHINE}/conf/std.${MACHINE}
-
Standard configuration for the given architecture.
This file should always be included.
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.
conf/files
-
Main options description file.
EXAMPLES
config.samples(5)
uses several examples to cover all the practical aspects of writing or
modifying a kernel configuration file.
SEE ALSO
config(1),
options(4),
config.samples(5),
config(9)