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 May 13, 2004 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.Bl -tag -width indent 90.\" -------- CPU -------- 91.It Ic cpu Ar cputype 92Specify the CPU this kernel will run on. 93There can be more than one 94.Ic cpu 95directive in a configuration file. 96The allowed list of CPU names is architecture specific and is 97defined in the file 98.Pa sys/conf/options. Ns Aq Ar arch . 99.\" -------- DEVICE -------- 100.It Ic device Ar name Op Ar count 101Configures device 102.Ar name 103for inclusion into the kernel image. 104If 105.Ar count 106is specified, the device is configured for 107.Ar count 108instances. 109Devices that are common to all architectures are 110defined in the file 111.Pa sys/conf/files . 112Devices that are specific to architecture 113.Ar arch 114are defined in the file 115.Pa sys/conf/files. Ns Aq Ar arch . 116.\" -------- ENV -------- 117.It Ic env Ar filename 118Specifies a filename containing a kernel environment definition. 119The kernel normally uses an environment prepared for it at boot time 120by 121.Xr loader 8 . 122This directive makes the kernel ignore the boot environment and use 123the compiled-in environment instead. 124.Pp 125This directive is useful for setting kernel tunables in 126embedded environments that do not start from 127.Xr loader 8 . 128.\" -------- FILES -------- 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.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 . 149.\" -------- IDENT -------- 150.It Ic ident Ar name 151Set the kernel name to 152.Ar name . 153At least one 154.Ic ident 155directive is required. 156.\" -------- INCLUDE -------- 157.It Ic include Ar filename 158Read subsequent text from file 159.Ar filename 160and return to the current file after 161.Ar filename 162is successfully processed. 163.\" -------- MACHINE -------- 164.It Ic machine Ar arch 165Specifies the architecture of the machine the kernel is being 166compiled for. 167Legal values for 168.Ar arch 169include: 170.Pp 171.Bl -tag -width ".Cm powerpc" -compact 172.It Cm alpha 173The DEC Alpha architecture. 174.It Cm amd64 175The AMD x86-64 architecture. 176.It Cm i386 177The Intel x86 based PC architecture. 178.It Cm ia64 179The Intel IA64 architecture. 180.It Cm pc98 181The PC98 architecture. 182.It Cm powerpc 183The IBM PowerPC architecture. 184.It Cm sparc64 185The Sun Sparc64 architecture. 186.El 187.Pp 188A kernel configuration file may have only one 189.Ic machine 190directive. 191.\" -------- MAKEOPTION -------- 192.It Ic makeoptions Ar options 193Add 194.Ar options 195to the generated makefile. 196.Pp 197The 198.Ar options 199argument is a comma separated list of one or more option 200specifications. 201Each option specification has the form 202.Pp 203.D1 Ar MakeVariableName Ns Op = Ns Ar Value 204.Pp 205and results in the appropriate 206.Xr make 1 207variable definition being inserted into the generated makefile. 208If only the name of the 209.Xr make 1 210variable is specified, 211.Ar value 212is assumed to be the empty string. 213.Pp 214Example: 215.Bd -literal -offset indent -compact 216makeoptions MYMAKEOPTION="foobar" 217makeoptions MYNULLMAKEOPTION 218.Ed 219.\" -------- MAXUSERS -------- 220.It Ic maxusers Ar number 221This optional directive is used to configure the size 222of some kernel data structures. 223The parameter 224.Ar number 225can be 0 (the default) or an integer greater than or equal to 2. 226A value of 0 indicates that the kernel should configure 227its data structures according to the size of available 228physical memory. 229If auto configuration is requested, the kernel will set 230this tunable to a value between 32 and 384. 231.Pp 232As explained in 233.Xr tuning 7 , 234this tunable can also be set at boot time using 235.Xr loader 8 . 236.\" -------- NOMAKEOPTION -------- 237.It Ic nomakeoption Ar name 238Removes previously defined 239.Xr make 1 240option 241.Ar name 242from the kernel build. 243This directive can be used to cancel the effects of 244.Ic makeoption 245directives in files included using 246.Ic include . 247.\" -------- NOOPTION -------- 248.It Ic nooption Ar kerneloptionname 249Remove kernel option 250.Ar kerneloptionname 251from the list of previously defined options. 252This directive can be used to cancel the effects of 253.Ic options 254directives in files included using 255.Ic include . 256.\" -------- OPTIONS -------- 257.It Ic options Ar optionspecs 258Add compile time kernel options to the kernel build. 259The argument 260.Ar optionspecs 261is a comma separated list of option specifications. 262Each option specification has the form 263.Pp 264.D1 Ar KernelOptionName Ns Op = Ns Ar OptionValue 265.Pp 266If 267.Ar OptionValue 268is not specified, it is assumed to be 269.Dv NULL . 270Options common to all architectures are specified in 271the file 272.Pa sys/conf/options . 273Options specific to architecture 274.Ar arch 275are specified in the file 276.Pa sys/conf/options. Ns Aq Ar arch . 277.\" -------- PROFILE -------- 278.It Ic profile Ar number 279Enables kernel profiling if 280.Ar number 281is non-zero. 282If 283.Ar number 284is 2 or greater, the kernel is configured for 285high-resolution profiling. 286Kernels can also be built for profiling using the 287.Fl p 288option to 289.Xr config 8 . 290.El 291.Ss Obsolete Directives 292The following kernel configuration directives are obsolete. 293.Bl -tag -width indent 294.\" -------- CONFIG -------- 295.It Ic config 296This directive was used to specify the device to be used for the root 297file system. 298From 299.Fx 4.0 300onwards, this information is passed to a booting kernel by 301.Xr loader 8 . 302.El 303.Sh FILES 304.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact 305.It Pa sys/compile/ Ns Ar NAME 306Compile directory created from a kernel configuration. 307.It Pa sys/conf/Makefile. Ns Ar arch 308.Pa Makefile 309fragments for architecture 310.Ar arch . 311.It Pa sys/conf/files 312Devices common to all architectures. 313.It Pa sys/conf/files. Ns Ar arch 314Devices for architecture 315.Ar arch . 316.It Pa sys/conf/options 317Options common to all architectures. 318.It Pa sys/conf/options. Ns Ar arch 319Options for architecture 320.Ar arch . 321.El 322.Sh SEE ALSO 323.Xr kenv 1 , 324.Xr make 1 , 325.Xr device.hints 5 , 326.Xr loader.conf 5 , 327.Xr config 8 , 328.Xr kldload 8 , 329.Xr loader 8 330.Rs 331.%T "Building 4.4BSD Kernels with Config" 332.%A "Samuel J. Leffler" 333.%A "Michael J. Karels" 334.Re 335.Sh HISTORY 336The 337.Xr config 8 338utility first appeared in 339.Bx 4.1 , 340and was subsequently revised in 341.Bx 4.4 . 342.Pp 343The kernel configuration mechanism changed further in 344.Fx 4.0 345and 346.Fx 5.0 , 347moving toward an architecture supporting dynamic kernel 348configuration. 349