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.
118 The kernel will augment this compiled-in environment with the environment
119 prepared for it at boot time by
121 Environment variables specified in the
123 environment will take precedence over environment variables specified in
125 and environment variables specified in the dynamic environment take precedence
128 .Va loader_env.disabled=1
129 may be specified in the static environment to disable the
134 should be done with caution and due consideration for whether or not it supplies
135 environment variables needed for properly booting the system.
137 .Va static_env.disabled=1
138 may be specified in the
140 environment to disable use of the static environment.
141 This option has no effect if specified in any environment after the
143 environment is processed.
144 This option is not usable in conjunction with
145 .Va loader_env.disabled .
147 This directive is useful for setting kernel tunables in
148 embedded environments that do not start from
155 directives will be processed and added to the static environment in reversed
156 order of appearance so that later specified variables properly override earlier
160 the first appearance of a given variable will be the first one seen by the
161 kernel, effectively shadowing any later appearances of the same variable within
163 .\" -------- ENVVAR --------
165 .It Ic envvar Ar setting
166 Specifies an individual environment setting to be added to the kernel's
167 compiled-in environment.
171 Optional quotes are supported in both name and value.
177 directives will be processed and added to the static environment in reversed
178 order of appearance so that later specified variables properly override earlier
180 .\" -------- FILES --------
182 .It Ic files Ar filename
183 Specifies a file containing a list of files specific to that kernel
184 configuration file (a la
185 .Pa files. Ns Aq Ar arch ) .
186 .\" -------- HINTS --------
188 .It Ic hints Ar filename
189 Specifies a file to load a static device configuration specification
193 onwards, the kernel reads the system's device configuration at boot
195 .Xr device.hints 5 ) .
196 This directive configures the kernel to use the static device configuration
200 Hints provided in this static device configuration will be overwritten in the
201 order in which they're encountered.
202 Hints in the compiled-in environment takes precedence over compiled-in hints,
203 and hints in the environment prepared for the kernel by
205 takes precedence over hints in the compiled-in environment.
207 Once the dynamic environment becomes available, all compiled-in hints will be
208 added to the dynamic environment if they do not already have an override in
209 the dynamic environment.
210 The dynamic environment will then be used for all searches of hints.
212 .Va static_hints.disabled=1
213 may be specified in either a compiled-in environment or the
215 environment to disable use of these hints files.
216 This option has no effect if specified in any environment after the
218 environment is processed.
222 must conform to the syntax specified by
224 Multiple hints lines are allowed.
225 The resulting hints will be the files concatenated in reverse order of
226 appearance so that hints in later files properly override hints in earlier
228 .\" -------- IDENT --------
231 Set the kernel name to
235 directive is required.
236 .\" -------- INCLUDE --------
238 .It Ic include Ar filename
239 Read subsequent text from file
241 and return to the current file after
243 is successfully processed.
244 .\" -------- MACHINE --------
246 .It Ic machine Ar arch Op Ar cpuarch
247 Specifies the architecture of the machine the kernel is being
253 .Bl -tag -width ".Cm powerpc" -compact
255 The DEC Alpha architecture.
257 The ARM architecture.
259 The AMD x86-64 architecture.
261 The Intel x86 based PC architecture.
263 The MIPS architecture.
265 The PC98 architecture.
267 The IBM PowerPC architecture.
269 The Sun Sparc64 architecture.
274 is specified, it points
276 to the cpu architecture of the machine.
279 architecture requires its cpu architecture
284 is not specified, it is assumed to be the same as
287 corresponds to MACHINE.
289 corresponds to MACHINE_ARCH.
291 A kernel configuration file may have only one
294 .\" -------- MAKEOPTION --------
296 .It Ic makeoption Ar options
297 .It Ic makeoptions Ar options
300 to the generated makefile.
304 argument is a comma separated list of one or more option
306 Each option specification has the form
308 .D1 Ar MakeVariableName Ns Op = Ns Ar Value
309 .D1 Ar MakeVariableName Ns += Ns Ar Value
311 and results in the appropriate
313 variable definition being inserted into the generated makefile.
314 If only the name of the
316 variable is specified,
318 is assumed to be the empty string.
321 .Bd -literal -offset indent -compact
322 makeoptions MYMAKEOPTION="foo"
323 makeoptions MYMAKEOPTION+="bar"
324 makeoptions MYNULLMAKEOPTION
326 .\" -------- MAXUSERS --------
328 .It Ic maxusers Ar number
329 This optional directive is used to configure the size
330 of some kernel data structures.
333 can be 0 (the default) or an integer greater than or equal to 2.
334 A value of 0 indicates that the kernel should configure
335 its data structures according to the size of available
337 If auto configuration is requested, the kernel will set
338 this tunable to a value between 32 and 384.
342 this tunable can also be set at boot time using
344 .\" -------- NOCPU --------
346 .It Ic nocpu Ar cputype
347 Remove the specified CPU
348 from the list of previously selected CPUs.
349 This directive can be used to cancel the effect of
351 directives in files included using
353 .\" -------- NODEVICE --------
355 .It Ic nodevice Ar name Op , Ar name Op ...
356 .It Ic nodevices Ar name Op , Ar name Op ...
357 Remove the specified devices
358 from the list of previously selected devices.
359 This directive can be used to cancel the effects of
363 directives in files included using
365 .\" -------- NOMAKEOPTION --------
367 .It Ic nomakeoption Ar name
368 .It Ic nomakeoptions Ar name
369 Removes previously defined
373 from the kernel build.
374 This directive can be used to cancel the effects of
376 directives in files included using
378 .\" -------- NOOPTION --------
380 .It Ic nooption Ar name Op , Ar name Op ...
381 .It Ic nooptions Ar name Op , Ar name Op ...
382 Remove the specified kernel options
383 from the list of previously defined options.
384 This directive can be used to cancel the effects of
388 directives in files included using
390 .\" -------- OPTIONS --------
392 .It Ic option Ar optionspec Op , Ar optionspec Op ...
393 .It Ic options Ar optionspec Op , Ar optionspec Op ...
394 Add compile time kernel options to the kernel build.
395 Each option specification has the form
397 .D1 Ar name Ns Op = Ns Ar value
401 is not specified, it is assumed to be
403 Options common to all architectures are specified in
405 .Pa sys/conf/options .
406 Options specific to architecture
408 are specified in the file
409 .Pa sys/conf/options. Ns Aq Ar arch .
410 .\" -------- PROFILE --------
412 .It Ic profile Ar number
413 Enables kernel profiling if
418 is 2 or greater, the kernel is configured for
419 high-resolution profiling.
420 Kernels can also be built for profiling using the
425 .Ss Obsolete Directives
426 The following kernel configuration directives are obsolete.
427 .Bl -tag -width indent
428 .\" -------- CONFIG --------
430 This directive was used to specify the device to be used for the root
434 onwards, this information is passed to a booting kernel by
438 .Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact
439 .It Pa sys/compile/ Ns Ar NAME
440 Compile directory created from a kernel configuration.
441 .It Pa sys/conf/Makefile. Ns Ar arch
443 fragments for architecture
445 .It Pa sys/conf/files
446 Devices common to all architectures.
447 .It Pa sys/conf/files. Ns Ar arch
448 Devices for architecture
450 .It Pa sys/conf/options
451 Options common to all architectures.
452 .It Pa sys/conf/options. Ns Ar arch
453 Options for architecture
465 .%T "Building 4.4BSD Kernels with Config"
466 .%A "Samuel J. Leffler"
467 .%A "Michael J. Karels"
472 utility first appeared in
474 and was subsequently revised in
477 The kernel configuration mechanism changed further in
481 moving toward an architecture supporting dynamic kernel