CONFIG(5) | File Formats Manual | CONFIG(5) |
config
—
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.
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:
=
value[
locator=
value]
[
length]
[
length]={
value,
...}
[
locator[
length]={
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⟩
⟨value⟩” where value can be the
‘?
’ wildcard if the locator allows
it.
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 base 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
‘?
’.
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.
&
’,
‘|
’, and
‘!
’) to combine options and attributes .
version
yyyymmddversion
statement. The argument is an ISO
date. A given config(1)
binary might only be compatible with a limited range of version numbers.
include
pathprefix
.
cinclude
pathinclude
, it will not produce an error if the file
does not exist. The argument obeys the same rules as for
include
.
prefix
[path]file
, 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 the kernel source tree.
buildprefix
[path]file
. buildprefix
statements act like a stack, and an empty path
argument has the latest prefix popped out. The path
argument is relative to the current defined buildprefix, which defaults to
the top of the kernel build directory. When prefix is either absolute or
relative out of the kernel source tree (../),
buildprefix must be defined.
ifdef
attributeifndef
attributeelifdef
attributeelifndef
attributeelse
endif
define
or any
other statement that implicitly defines attributes such as
device
.include
,
cinclude
, and prefix
, the
preamble may contain the following optional statements:
build
path-b
parameter of
config(1).source
path-s
parameter of
config(1).devclass
classdefflag
[file] option
[option [...]]
[:
dependencies]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]
option[=
value]
[:=
lint-value]
[option [...]]
[:
dependencies]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
name ...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.
obsolete
defflag
[file] option
...obsolete
defparam
[file] option
...define
attribute [{
locators }
]
[:
dependencies]maxpartitions
numbermaxusers
min default maxmaxusers
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 }
]
[:
dependencies]CFDRIVER_DECL
() statement to
ioconf.c. However, it is the responsibility of the
developer to add the relevant CFATTACH_DECL_NEW
()
line to the source of the device's driver.
attach
base at
attr[,
attr[,
...]] [with
name] [: dependencies
]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]defpseudodev
base [{
locators }
]
[:
dependencies]file
path [condition]
[needs-count
] [needs-flag
]
[compile with
rule]needs-count
option indicates that the source file
requires the number of all the countable objects it depends on (through
the condition) 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.
Both needs-count
and
needs-flag
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
condition or flags. This is useful when a file
needs special consideration from one particular architecture.
The path is relative to the top of the kernel source tree, or
the inner-most defined prefix
.
object
path [condition]The path is relative to the top of the kernel source tree, or
the inner-most defined prefix
.
device-major
base [char
number] [block
number] [condition]file
statement.
makeoptions
condition
name+=
value[,
condition
name+=
value[,
...]]This variant of makeoptions
belongs to
the options description section. The condition is
mandatory and only +=
can be used. Not to be
confused with the confusingly similar variant of
makeoptions
used in the selections section.
machine
machine [arch
[subarch [...]]]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:
It also defines an attribute for the machine, the arch and each of the subarch.
package
pathprefix DIR include FILE prefix
ident
stringno
ident
maxusers
numbermaxusers
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][,
name[=
value][,
...]]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. If the option
has previously been selected, the statement produces a warning, and the
new options
statement replaces the original.
no
options
name[,
name[,
...]]file-system
name[,
name[,
...]]no
file-system
name[,
name[,
...]]config
name root on
device [type
fs] [dumps on
device]Any of the device and
fs parameters can be wildcarded with
‘?
’ to let the kernel
automatically discover those values. The device
can also be specified as a quoted specification string. The kernel
interprets this string like the console input when prompting for a root
device. E.g.,
“wedge:
NAME”
specifies a named disk wedge.
At least one config
statement must
appear in the configuration file.
no
config
nameat
attachment [locator-specifications
...]*
’ for
instance, and a
‘?
’ for
attachment and the locators.no
instance [at
attachment]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*
’, all instances attaching to all
the variants of attachment are removed.pseudo-device
device [number]no
pseudo-device
namemakeoptions
name=
value[,
name+=
value[,
...]]makeoptions_
⟨name⟩
is defined with defparam
, the
value is defined as an option too.
This variant of makeoptions
belongs to
the options selection section. Both =
and
+=
can be used. Not to be confused with the
confusingly similar variant of makeoptions
used
in the descriptions section.
no
makeoptions
name[,
name[,
...]]select
nameno
select
nameJuly 19, 2016 | NetBSD 10.1 |