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