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