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 December 3, 2005 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. 122.Pp 123This directive is useful for setting kernel tunables in 124embedded environments that do not start from 125.Xr loader 8 . 126.\" -------- FILES -------- 127.Pp 128.It Ic files Ar filename 129Specifies a file containing a list of files specific to that kernel 130configuration file (a la 131.Pa files. Ns Aq Ar arch ) . 132.\" -------- HINTS -------- 133.Pp 134.It Ic hints Ar filename 135Specifies a file to load a static device configuration specification 136from. 137From 138.Fx 5.0 139onwards, the kernel reads the system's device configuration at boot 140time (see 141.Xr device.hints 5 ) . 142This directive configures the kernel to use the static device configuration 143listed in 144.Ar filename . 145The file 146.Ar filename 147must conform to the syntax specified by 148.Xr device.hints 5 . 149Multiple hints lines are allowed. 150The resulting hints will be the files concatenated in the order of appearance. 151.\" -------- IDENT -------- 152.Pp 153.It Ic ident Ar name 154Set the kernel name to 155.Ar name . 156At least one 157.Ic ident 158directive is required. 159.\" -------- INCLUDE -------- 160.Pp 161.It Ic include Ar filename 162Read subsequent text from file 163.Ar filename 164and return to the current file after 165.Ar filename 166is successfully processed. 167.\" -------- MACHINE -------- 168.Pp 169.It Ic machine Ar arch Op Ar cpuarch 170Specifies the architecture of the machine the kernel is being 171compiled for. 172Legal values for 173.Ar arch 174include: 175.Pp 176.Bl -tag -width ".Cm powerpc" -compact 177.It Cm alpha 178The DEC Alpha architecture. 179.It Cm arm 180The ARM architecture. 181.It Cm amd64 182The AMD x86-64 architecture. 183.It Cm i386 184The Intel x86 based PC architecture. 185.It Cm ia64 186The Intel IA64 architecture. 187.It Cm mips 188The MIPS architecture. 189.It Cm pc98 190The PC98 architecture. 191.It Cm powerpc 192The IBM PowerPC architecture. 193.It Cm sparc64 194The Sun Sparc64 architecture. 195.El 196.Pp 197If argument 198.Ar cpuarch 199is specified, it points 200.Xr config 8 201to the cpu architecture of the machine. 202Currently the 203.Cm pc98 204architecture requires its cpu architecture 205to be set to 206.Cm i386 . 207When 208.Ar cpuarch 209is not specified, it is assumed to be the same as 210.Ar arch . 211.Ar arch 212corresponds to MACHINE. 213.Ar cpuarch 214corresponds to MACHINE_ARCH. 215.Pp 216A kernel configuration file may have only one 217.Ic machine 218directive. 219.\" -------- MAKEOPTION -------- 220.Pp 221.It Ic makeoption Ar options 222.It Ic makeoptions Ar options 223Add 224.Ar options 225to the generated makefile. 226.Pp 227The 228.Ar options 229argument is a comma separated list of one or more option 230specifications. 231Each option specification has the form 232.Pp 233.D1 Ar MakeVariableName Ns Op = Ns Ar Value 234.D1 Ar MakeVariableName Ns += Ns Ar Value 235.Pp 236and results in the appropriate 237.Xr make 1 238variable definition being inserted into the generated makefile. 239If only the name of the 240.Xr make 1 241variable is specified, 242.Ar value 243is assumed to be the empty string. 244.Pp 245Example: 246.Bd -literal -offset indent -compact 247makeoptions MYMAKEOPTION="foo" 248makeoptions MYMAKEOPTION+="bar" 249makeoptions MYNULLMAKEOPTION 250.Ed 251.\" -------- MAXUSERS -------- 252.Pp 253.It Ic maxusers Ar number 254This optional directive is used to configure the size 255of some kernel data structures. 256The parameter 257.Ar number 258can be 0 (the default) or an integer greater than or equal to 2. 259A value of 0 indicates that the kernel should configure 260its data structures according to the size of available 261physical memory. 262If auto configuration is requested, the kernel will set 263this tunable to a value between 32 and 384. 264.Pp 265As explained in 266.Xr tuning 7 , 267this tunable can also be set at boot time using 268.Xr loader 8 . 269.\" -------- NOCPU -------- 270.Pp 271.It Ic nocpu Ar cputype 272Remove the specified CPU 273from the list of previously selected CPUs. 274This directive can be used to cancel the effect of 275.Ic cpu 276directives in files included using 277.Ic include . 278.\" -------- NODEVICE -------- 279.Pp 280.It Ic nodevice Ar name Op , Ar name Op ... 281.It Ic nodevices Ar name Op , Ar name Op ... 282Remove the specified devices 283from the list of previously selected devices. 284This directive can be used to cancel the effects of 285.Ic device 286or 287.Ic devices 288directives in files included using 289.Ic include . 290.\" -------- NOMAKEOPTION -------- 291.Pp 292.It Ic nomakeoption Ar name 293.It Ic nomakeoptions Ar name 294Removes previously defined 295.Xr make 1 296option 297.Ar name 298from the kernel build. 299This directive can be used to cancel the effects of 300.Ic makeoption 301directives in files included using 302.Ic include . 303.\" -------- NOOPTION -------- 304.Pp 305.It Ic nooption Ar name Op , Ar name Op ... 306.It Ic nooptions Ar name Op , Ar name Op ... 307Remove the specified kernel options 308from the list of previously defined options. 309This directive can be used to cancel the effects of 310.Ic option 311or 312.Ic options 313directives in files included using 314.Ic include . 315.\" -------- OPTIONS -------- 316.Pp 317.It Ic option Ar optionspec Op , Ar optionspec Op ... 318.It Ic options Ar optionspec Op , Ar optionspec Op ... 319Add compile time kernel options to the kernel build. 320Each option specification has the form 321.Pp 322.D1 Ar name Ns Op = Ns Ar value 323.Pp 324If 325.Ar value 326is not specified, it is assumed to be 327.Dv NULL . 328Options common to all architectures are specified in 329the file 330.Pa sys/conf/options . 331Options specific to architecture 332.Ar arch 333are specified in the file 334.Pa sys/conf/options. Ns Aq Ar arch . 335.\" -------- PROFILE -------- 336.Pp 337.It Ic profile Ar number 338Enables kernel profiling if 339.Ar number 340is non-zero. 341If 342.Ar number 343is 2 or greater, the kernel is configured for 344high-resolution profiling. 345Kernels can also be built for profiling using the 346.Fl p 347option to 348.Xr config 8 . 349.El 350.Ss Obsolete Directives 351The following kernel configuration directives are obsolete. 352.Bl -tag -width indent 353.\" -------- CONFIG -------- 354.It Ic config 355This directive was used to specify the device to be used for the root 356file system. 357From 358.Fx 4.0 359onwards, this information is passed to a booting kernel by 360.Xr loader 8 . 361.El 362.Sh FILES 363.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact 364.It Pa sys/compile/ Ns Ar NAME 365Compile directory created from a kernel configuration. 366.It Pa sys/conf/Makefile. Ns Ar arch 367.Pa Makefile 368fragments for architecture 369.Ar arch . 370.It Pa sys/conf/files 371Devices common to all architectures. 372.It Pa sys/conf/files. Ns Ar arch 373Devices for architecture 374.Ar arch . 375.It Pa sys/conf/options 376Options common to all architectures. 377.It Pa sys/conf/options. Ns Ar arch 378Options for architecture 379.Ar arch . 380.El 381.Sh SEE ALSO 382.Xr kenv 1 , 383.Xr make 1 , 384.Xr device.hints 5 , 385.Xr loader.conf 5 , 386.Xr config 8 , 387.Xr kldload 8 , 388.Xr loader 8 389.Rs 390.%T "Building 4.4BSD Kernels with Config" 391.%A "Samuel J. Leffler" 392.%A "Michael J. Karels" 393.Re 394.Sh HISTORY 395The 396.Xr config 8 397utility first appeared in 398.Bx 4.1 , 399and was subsequently revised in 400.Bx 4.4 . 401.Pp 402The kernel configuration mechanism changed further in 403.Fx 4.0 404and 405.Fx 5.0 , 406moving toward an architecture supporting dynamic kernel 407configuration. 408