1 .\" Copyright (c) 2003 Joseph Koshy
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
6 .\" 1. Redistributions of source code must retain the above copyright
7 .\" notice, this list of conditions and the following disclaimer.
8 .\" 2. Redistributions in binary form must reproduce the above copyright
9 .\" notice, this list of conditions and the following disclaimer in the
10 .\" documentation and/or other materials provided with the distribution.
12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .Nd kernel configuration file format
33 A kernel configuration file specifies the configuration of a
38 to create a build environment where a kernel may be built using
41 A kernel configuration file comprises a sequence of specification
44 A specification directive starts with a keyword at the beginning
45 of the line and is followed by additional parameters.
47 A specification directive may be terminated by a semicolon
50 Long input lines may be broken into shorter lines by starting the
51 second and subsequent lines with a white space character.
59 A double quote character
61 starts a quoted string.
62 All characters up to the next quote character form the value
66 character may be inserted into a quoted string by
70 Numbers are specified using
76 character starts a comment; all characters from the
78 character till the end of the current line are ignored.
80 Whitespace between tokens is ignored, except inside quoted strings.
81 Whitespace following a comment line is ignored.
82 .Ss Configuration Directives
83 Kernel configuration directives may appear in any order
84 in a kernel configuration file.
85 Directives are processed in order of appearance with subsequent
86 directive lines overriding the effect of prior ones.
88 The list of keywords and their meanings are as follows:
90 .Bl -tag -width indent -compact
91 .\" -------- CPU --------
93 Specify the CPU this kernel will run on.
94 There can be more than one
96 directive in a configuration file.
97 The allowed list of CPU names is architecture specific and is
99 .Pa sys/conf/options. Ns Aq Ar arch .
100 .\" -------- DEVICE --------
102 .It Ic device Ar name Op , Ar name Op ...
103 .It Ic devices Ar name Op , Ar name Op ...
104 Configures the specified devices
105 for inclusion into the kernel image.
106 Devices that are common to all architectures are
109 Devices that are specific to architecture
111 are defined in the file
112 .Pa sys/conf/files. Ns Aq Ar arch .
113 .\" -------- ENV --------
115 .It Ic env Ar filename
116 Specifies a filename containing a kernel environment definition.
117 The kernel normally uses an environment prepared for it at boot time
120 This directive makes the kernel ignore the boot environment and use
121 the compiled-in environment instead, unless the boot environment contains
122 .Va static_env.disabled=1 .
124 This directive is useful for setting kernel tunables in
125 embedded environments that do not start from
127 .\" -------- FILES --------
129 .It Ic files Ar filename
130 Specifies a file containing a list of files specific to that kernel
131 configuration file (a la
132 .Pa files. Ns Aq Ar arch ) .
133 .\" -------- HINTS --------
135 .It Ic hints Ar filename
136 Specifies a file to load a static device configuration specification
140 onwards, the kernel reads the system's device configuration at boot
142 .Xr device.hints 5 ) .
143 This directive configures the kernel to use the static device configuration
146 unless the boot environment contains
147 .Va static_hints.disabled=1 .
150 must conform to the syntax specified by
152 Multiple hints lines are allowed.
153 The resulting hints will be the files concatenated in the order of appearance.
154 .\" -------- IDENT --------
157 Set the kernel name to
161 directive is required.
162 .\" -------- INCLUDE --------
164 .It Ic include Ar filename
165 Read subsequent text from file
167 and return to the current file after
169 is successfully processed.
170 .\" -------- MACHINE --------
172 .It Ic machine Ar arch Op Ar cpuarch
173 Specifies the architecture of the machine the kernel is being
179 .Bl -tag -width ".Cm powerpc" -compact
181 The DEC Alpha architecture.
183 The ARM architecture.
185 The AMD x86-64 architecture.
187 The Intel x86 based PC architecture.
189 The MIPS architecture.
191 The PC98 architecture.
193 The IBM PowerPC architecture.
195 The Sun Sparc64 architecture.
200 is specified, it points
202 to the cpu architecture of the machine.
205 architecture requires its cpu architecture
210 is not specified, it is assumed to be the same as
213 corresponds to MACHINE.
215 corresponds to MACHINE_ARCH.
217 A kernel configuration file may have only one
220 .\" -------- MAKEOPTION --------
222 .It Ic makeoption Ar options
223 .It Ic makeoptions Ar options
226 to the generated makefile.
230 argument is a comma separated list of one or more option
232 Each option specification has the form
234 .D1 Ar MakeVariableName Ns Op = Ns Ar Value
235 .D1 Ar MakeVariableName Ns += Ns Ar Value
237 and results in the appropriate
239 variable definition being inserted into the generated makefile.
240 If only the name of the
242 variable is specified,
244 is assumed to be the empty string.
247 .Bd -literal -offset indent -compact
248 makeoptions MYMAKEOPTION="foo"
249 makeoptions MYMAKEOPTION+="bar"
250 makeoptions MYNULLMAKEOPTION
252 .\" -------- MAXUSERS --------
254 .It Ic maxusers Ar number
255 This optional directive is used to configure the size
256 of some kernel data structures.
259 can be 0 (the default) or an integer greater than or equal to 2.
260 A value of 0 indicates that the kernel should configure
261 its data structures according to the size of available
263 If auto configuration is requested, the kernel will set
264 this tunable to a value between 32 and 384.
268 this tunable can also be set at boot time using
270 .\" -------- NOCPU --------
272 .It Ic nocpu Ar cputype
273 Remove the specified CPU
274 from the list of previously selected CPUs.
275 This directive can be used to cancel the effect of
277 directives in files included using
279 .\" -------- NODEVICE --------
281 .It Ic nodevice Ar name Op , Ar name Op ...
282 .It Ic nodevices Ar name Op , Ar name Op ...
283 Remove the specified devices
284 from the list of previously selected devices.
285 This directive can be used to cancel the effects of
289 directives in files included using
291 .\" -------- NOMAKEOPTION --------
293 .It Ic nomakeoption Ar name
294 .It Ic nomakeoptions Ar name
295 Removes previously defined
299 from the kernel build.
300 This directive can be used to cancel the effects of
302 directives in files included using
304 .\" -------- NOOPTION --------
306 .It Ic nooption Ar name Op , Ar name Op ...
307 .It Ic nooptions Ar name Op , Ar name Op ...
308 Remove the specified kernel options
309 from the list of previously defined options.
310 This directive can be used to cancel the effects of
314 directives in files included using
316 .\" -------- OPTIONS --------
318 .It Ic option Ar optionspec Op , Ar optionspec Op ...
319 .It Ic options Ar optionspec Op , Ar optionspec Op ...
320 Add compile time kernel options to the kernel build.
321 Each option specification has the form
323 .D1 Ar name Ns Op = Ns Ar value
327 is not specified, it is assumed to be
329 Options common to all architectures are specified in
331 .Pa sys/conf/options .
332 Options specific to architecture
334 are specified in the file
335 .Pa sys/conf/options. Ns Aq Ar arch .
336 .\" -------- PROFILE --------
338 .It Ic profile Ar number
339 Enables kernel profiling if
344 is 2 or greater, the kernel is configured for
345 high-resolution profiling.
346 Kernels can also be built for profiling using the
351 .Ss Obsolete Directives
352 The following kernel configuration directives are obsolete.
353 .Bl -tag -width indent
354 .\" -------- CONFIG --------
356 This directive was used to specify the device to be used for the root
360 onwards, this information is passed to a booting kernel by
364 .Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact
365 .It Pa sys/compile/ Ns Ar NAME
366 Compile directory created from a kernel configuration.
367 .It Pa sys/conf/Makefile. Ns Ar arch
369 fragments for architecture
371 .It Pa sys/conf/files
372 Devices common to all architectures.
373 .It Pa sys/conf/files. Ns Ar arch
374 Devices for architecture
376 .It Pa sys/conf/options
377 Options common to all architectures.
378 .It Pa sys/conf/options. Ns Ar arch
379 Options for architecture
391 .%T "Building 4.4BSD Kernels with Config"
392 .%A "Samuel J. Leffler"
393 .%A "Michael J. Karels"
398 utility first appeared in
400 and was subsequently revised in
403 The kernel configuration mechanism changed further in
407 moving toward an architecture supporting dynamic kernel