1.\" Copyright (c) 2003 Joseph Koshy 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 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. 11.\" 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 22.\" SUCH DAMAGE. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd February 21, 2016 27.Dt CONFIG 5 28.Os 29.Sh NAME 30.Nm config 31.Nd kernel configuration file format 32.Sh DESCRIPTION 33A kernel configuration file specifies the configuration of a 34.Fx 35kernel. 36It is processed by 37.Xr config 8 38to create a build environment where a kernel may be built using 39.Xr make 1 . 40.Ss Lexical Structure 41A kernel configuration file comprises a sequence of specification 42directives. 43.Pp 44A specification directive starts with a keyword at the beginning 45of the line and is followed by additional parameters. 46.Pp 47A specification directive may be terminated by a semicolon 48.Ql \&; 49or by a newline. 50Long input lines may be broken into shorter lines by starting the 51second and subsequent lines with a white space character. 52.Pp 53Case is significant, 54.Dq Li machine 55and 56.Dq Li MACHINE 57are different tokens. 58.Pp 59A double quote character 60.Ql \[dq] 61starts a quoted string. 62All characters up to the next quote character form the value 63of the quoted string. 64A 65.Ql \[dq] 66character may be inserted into a quoted string by 67using the sequence 68.Ql \e\[dq] . 69.Pp 70Numbers are specified using 71.Tn C Ns -style 72syntax. 73.Pp 74A 75.Ql # 76character starts a comment; all characters from the 77.Ql # 78character till the end of the current line are ignored. 79.Pp 80Whitespace between tokens is ignored, except inside quoted strings. 81Whitespace following a comment line is ignored. 82.Ss Configuration Directives 83Kernel configuration directives may appear in any order 84in a kernel configuration file. 85Directives are processed in order of appearance with subsequent 86directive lines overriding the effect of prior ones. 87.Pp 88The list of keywords and their meanings are as follows: 89.Pp 90.Bl -tag -width indent -compact 91.\" -------- CPU -------- 92.It Ic cpu Ar cputype 93Specify the CPU this kernel will run on. 94There can be more than one 95.Ic cpu 96directive in a configuration file. 97The allowed list of CPU names is architecture specific and is 98defined in the file 99.Pa sys/conf/options. Ns Aq Ar arch . 100.\" -------- DEVICE -------- 101.Pp 102.It Ic device Ar name Op , Ar name Op ... 103.It Ic devices Ar name Op , Ar name Op ... 104Configures the specified devices 105for inclusion into the kernel image. 106Devices that are common to all architectures are 107defined in the file 108.Pa sys/conf/files . 109Devices that are specific to architecture 110.Ar arch 111are defined in the file 112.Pa sys/conf/files. Ns Aq Ar arch . 113.\" -------- ENV -------- 114.Pp 115.It Ic env Ar filename 116Specifies a filename containing a kernel environment definition. 117The kernel normally uses an environment prepared for it at boot time 118by 119.Xr loader 8 . 120This directive makes the kernel ignore the boot environment and use 121the compiled-in environment instead, unless the boot environment contains 122.Va static_env.disabled=1 . 123.Pp 124This directive is useful for setting kernel tunables in 125embedded environments that do not start from 126.Xr loader 8 . 127.\" -------- FILES -------- 128.Pp 129.It Ic files Ar filename 130Specifies a file containing a list of files specific to that kernel 131configuration file (a la 132.Pa files. Ns Aq Ar arch ) . 133.\" -------- HINTS -------- 134.Pp 135.It Ic hints Ar filename 136Specifies a file to load a static device configuration specification 137from. 138From 139.Fx 5.0 140onwards, the kernel reads the system's device configuration at boot 141time (see 142.Xr device.hints 5 ) . 143This directive configures the kernel to use the static device configuration 144listed in 145.Ar filename , 146unless the boot environment contains 147.Va static_hints.disabled=1 . 148The file 149.Ar filename 150must conform to the syntax specified by 151.Xr device.hints 5 . 152Multiple hints lines are allowed. 153The resulting hints will be the files concatenated in the order of appearance. 154.\" -------- IDENT -------- 155.Pp 156.It Ic ident Ar name 157Set the kernel name to 158.Ar name . 159At least one 160.Ic ident 161directive is required. 162.\" -------- INCLUDE -------- 163.Pp 164.It Ic include Ar filename 165Read subsequent text from file 166.Ar filename 167and return to the current file after 168.Ar filename 169is successfully processed. 170.\" -------- MACHINE -------- 171.Pp 172.It Ic machine Ar arch Op Ar cpuarch 173Specifies the architecture of the machine the kernel is being 174compiled for. 175Legal values for 176.Ar arch 177include: 178.Pp 179.Bl -tag -width ".Cm powerpc" -compact 180.It Cm alpha 181The DEC Alpha architecture. 182.It Cm arm 183The ARM architecture. 184.It Cm amd64 185The AMD x86-64 architecture. 186.It Cm i386 187The Intel x86 based PC architecture. 188.It Cm mips 189The MIPS architecture. 190.It Cm pc98 191The PC98 architecture. 192.It Cm powerpc 193The IBM PowerPC architecture. 194.It Cm sparc64 195The Sun Sparc64 architecture. 196.El 197.Pp 198If argument 199.Ar cpuarch 200is specified, it points 201.Xr config 8 202to the cpu architecture of the machine. 203Currently the 204.Cm pc98 205architecture requires its cpu architecture 206to be set to 207.Cm i386 . 208When 209.Ar cpuarch 210is not specified, it is assumed to be the same as 211.Ar arch . 212.Ar arch 213corresponds to MACHINE. 214.Ar cpuarch 215corresponds to MACHINE_ARCH. 216.Pp 217A kernel configuration file may have only one 218.Ic machine 219directive. 220.\" -------- MAKEOPTION -------- 221.Pp 222.It Ic makeoption Ar options 223.It Ic makeoptions Ar options 224Add 225.Ar options 226to the generated makefile. 227.Pp 228The 229.Ar options 230argument is a comma separated list of one or more option 231specifications. 232Each option specification has the form 233.Pp 234.D1 Ar MakeVariableName Ns Op = Ns Ar Value 235.D1 Ar MakeVariableName Ns += Ns Ar Value 236.Pp 237and results in the appropriate 238.Xr make 1 239variable definition being inserted into the generated makefile. 240If only the name of the 241.Xr make 1 242variable is specified, 243.Ar value 244is assumed to be the empty string. 245.Pp 246Example: 247.Bd -literal -offset indent -compact 248makeoptions MYMAKEOPTION="foo" 249makeoptions MYMAKEOPTION+="bar" 250makeoptions MYNULLMAKEOPTION 251.Ed 252.\" -------- MAXUSERS -------- 253.Pp 254.It Ic maxusers Ar number 255This optional directive is used to configure the size 256of some kernel data structures. 257The parameter 258.Ar number 259can be 0 (the default) or an integer greater than or equal to 2. 260A value of 0 indicates that the kernel should configure 261its data structures according to the size of available 262physical memory. 263If auto configuration is requested, the kernel will set 264this tunable to a value between 32 and 384. 265.Pp 266As explained in 267.Xr tuning 7 , 268this tunable can also be set at boot time using 269.Xr loader 8 . 270.\" -------- NOCPU -------- 271.Pp 272.It Ic nocpu Ar cputype 273Remove the specified CPU 274from the list of previously selected CPUs. 275This directive can be used to cancel the effect of 276.Ic cpu 277directives in files included using 278.Ic include . 279.\" -------- NODEVICE -------- 280.Pp 281.It Ic nodevice Ar name Op , Ar name Op ... 282.It Ic nodevices Ar name Op , Ar name Op ... 283Remove the specified devices 284from the list of previously selected devices. 285This directive can be used to cancel the effects of 286.Ic device 287or 288.Ic devices 289directives in files included using 290.Ic include . 291.\" -------- NOMAKEOPTION -------- 292.Pp 293.It Ic nomakeoption Ar name 294.It Ic nomakeoptions Ar name 295Removes previously defined 296.Xr make 1 297option 298.Ar name 299from the kernel build. 300This directive can be used to cancel the effects of 301.Ic makeoption 302directives in files included using 303.Ic include . 304.\" -------- NOOPTION -------- 305.Pp 306.It Ic nooption Ar name Op , Ar name Op ... 307.It Ic nooptions Ar name Op , Ar name Op ... 308Remove the specified kernel options 309from the list of previously defined options. 310This directive can be used to cancel the effects of 311.Ic option 312or 313.Ic options 314directives in files included using 315.Ic include . 316.\" -------- OPTIONS -------- 317.Pp 318.It Ic option Ar optionspec Op , Ar optionspec Op ... 319.It Ic options Ar optionspec Op , Ar optionspec Op ... 320Add compile time kernel options to the kernel build. 321Each option specification has the form 322.Pp 323.D1 Ar name Ns Op = Ns Ar value 324.Pp 325If 326.Ar value 327is not specified, it is assumed to be 328.Dv NULL . 329Options common to all architectures are specified in 330the file 331.Pa sys/conf/options . 332Options specific to architecture 333.Ar arch 334are specified in the file 335.Pa sys/conf/options. Ns Aq Ar arch . 336.\" -------- PROFILE -------- 337.Pp 338.It Ic profile Ar number 339Enables kernel profiling if 340.Ar number 341is non-zero. 342If 343.Ar number 344is 2 or greater, the kernel is configured for 345high-resolution profiling. 346Kernels can also be built for profiling using the 347.Fl p 348option to 349.Xr config 8 . 350.El 351.Ss Obsolete Directives 352The following kernel configuration directives are obsolete. 353.Bl -tag -width indent 354.\" -------- CONFIG -------- 355.It Ic config 356This directive was used to specify the device to be used for the root 357file system. 358From 359.Fx 4.0 360onwards, this information is passed to a booting kernel by 361.Xr loader 8 . 362.El 363.Sh FILES 364.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact 365.It Pa sys/compile/ Ns Ar NAME 366Compile directory created from a kernel configuration. 367.It Pa sys/conf/Makefile. Ns Ar arch 368.Pa Makefile 369fragments for architecture 370.Ar arch . 371.It Pa sys/conf/files 372Devices common to all architectures. 373.It Pa sys/conf/files. Ns Ar arch 374Devices for architecture 375.Ar arch . 376.It Pa sys/conf/options 377Options common to all architectures. 378.It Pa sys/conf/options. Ns Ar arch 379Options for architecture 380.Ar arch . 381.El 382.Sh SEE ALSO 383.Xr kenv 1 , 384.Xr make 1 , 385.Xr device.hints 5 , 386.Xr loader.conf 5 , 387.Xr config 8 , 388.Xr kldload 8 , 389.Xr loader 8 390.Rs 391.%T "Building 4.4BSD Kernels with Config" 392.%A "Samuel J. Leffler" 393.%A "Michael J. Karels" 394.Re 395.Sh HISTORY 396The 397.Xr config 8 398utility first appeared in 399.Bx 4.1 , 400and was subsequently revised in 401.Bx 4.4 . 402.Pp 403The kernel configuration mechanism changed further in 404.Fx 4.0 405and 406.Fx 5.0 , 407moving toward an architecture supporting dynamic kernel 408configuration. 409