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 October 28, 2021 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. 117.Pp 118The kernel will augment this compiled-in environment with the environment 119prepared for it at boot time by 120.Xr loader 8 . 121Environment variables specified in the 122.Xr loader 8 123environment will take precedence over environment variables specified in 124.Ar filename , 125and environment variables specified in the dynamic environment take precedence 126over both of these. 127.Pp 128.Va loader_env.disabled=1 129may be specified in the static environment to disable the 130.Xr loader 8 131environment. 132Disabling the 133.Xr loader 8 134should be done with caution and due consideration for whether or not it supplies 135environment variables needed for properly booting the system. 136.Pp 137.Va static_env.disabled=1 138may be specified in the 139.Xr loader 8 140environment to disable use of the static environment. 141This option has no effect if specified in any environment after the 142.Xr loader 8 143environment is processed. 144This option is not usable in conjunction with 145.Va loader_env.disabled . 146.Pp 147This directive is useful for setting kernel tunables in 148embedded environments that do not start from 149.Xr loader 8 . 150.Pp 151All 152.Ic env 153and 154.Ic envvar 155directives will be processed and added to the static environment in reversed 156order of appearance so that later specified variables properly override earlier 157specified variables. 158Note that within 159.Ar filename , 160the first appearance of a given variable will be the first one seen by the 161kernel, effectively shadowing any later appearances of the same variable within 162.Ar filename . 163.\" -------- ENVVAR -------- 164.Pp 165.It Ic envvar Ar setting 166Specifies an individual environment setting to be added to the kernel's 167compiled-in environment. 168.Ar setting 169must be of the form 170.Dq Va name=value . 171Optional quotes are supported in both name and value. 172.Pp 173All 174.Ic env 175and 176.Ic envvar 177directives will be processed and added to the static environment in reversed 178order of appearance so that later specified variables properly override earlier 179specified variables. 180.\" -------- FILES -------- 181.Pp 182.It Ic files Ar filename 183Specifies a file containing a list of files specific to that kernel 184configuration file (a la 185.Pa files . Ns Aq Ar arch ) . 186.\" -------- HINTS -------- 187.Pp 188.It Ic hints Ar filename 189Specifies a file to load a static device configuration specification 190from. 191From 192.Fx 5.0 193onwards, the kernel reads the system's device configuration at boot 194time (see 195.Xr device.hints 5 ) . 196This directive configures the kernel to use the static device configuration 197listed in 198.Ar filename . 199.Pp 200Hints provided in this static device configuration will be overwritten in the 201order in which they're encountered. 202Hints in the compiled-in environment takes precedence over compiled-in hints, 203and hints in the environment prepared for the kernel by 204.Xr loader 8 205takes precedence over hints in the compiled-in environment. 206.Pp 207Once the dynamic environment becomes available, all compiled-in hints will be 208added to the dynamic environment if they do not already have an override in 209the dynamic environment. 210The dynamic environment will then be used for all searches of hints. 211.Pp 212.Va static_hints.disabled=1 213may be specified in either a compiled-in environment or the 214.Xr loader 8 215environment to disable use of these hints files. 216This option has no effect if specified in any environment after the 217.Xr loader 8 218environment is processed. 219.Pp 220The file 221.Ar filename 222must conform to the syntax specified by 223.Xr device.hints 5 . 224Multiple hints lines are allowed. 225The resulting hints will be the files concatenated in reverse order of 226appearance so that hints in later files properly override hints in earlier 227files. 228.\" -------- IDENT -------- 229.Pp 230.It Ic ident Ar name 231Set the kernel name to 232.Ar name . 233At least one 234.Ic ident 235directive is required. 236.\" -------- INCLUDE -------- 237.Pp 238.It Ic include Ar filename 239Read subsequent text from file 240.Ar filename 241and return to the current file after 242.Ar filename 243is successfully processed. 244.\" -------- MACHINE -------- 245.Pp 246.It Ic machine Ar arch Op Ar cpuarch 247Specifies the architecture of the machine the kernel is being 248compiled for. 249Legal values for 250.Ar arch 251include: 252.Pp 253.Bl -tag -width ".Cm powerpc" -compact 254.It Cm arm64 255The 64-bit ARM application architecture. 256.It Cm arm 257The ARM architecture 258.It Cm amd64 259The AMD x86-64 architecture. 260.It Cm i386 261The Intel x86 based PC architecture. 262.It Cm mips 263The MIPS architecture. 264.It Cm powerpc 265The IBM PowerPC architecture. 266.It Cm riscv 267The RISC-V architecture. 268.El 269.Pp 270If argument 271.Ar cpuarch 272is specified, it points 273.Xr config 8 274to the cpu architecture of the machine. 275When 276.Ar cpuarch 277is not specified, it is assumed to be the same as 278.Ar arch . 279.Ar arch 280corresponds to MACHINE. 281.Ar cpuarch 282corresponds to MACHINE_ARCH. 283.Pp 284A kernel configuration file may have only one 285.Ic machine 286directive, unless the second one matches the 287machine argument in the first one exactly. 288.\" -------- MAKEOPTION -------- 289.Pp 290.It Ic makeoption Ar options 291.It Ic makeoptions Ar options 292Add 293.Ar options 294to the generated makefile. 295.Pp 296The 297.Ar options 298argument is a comma separated list of one or more option 299specifications. 300Each option specification has the form 301.Pp 302.D1 Ar MakeVariableName Ns Op = Ns Ar Value 303.D1 Ar MakeVariableName Ns += Ns Ar Value 304.Pp 305and results in the appropriate 306.Xr make 1 307variable definition being inserted into the generated makefile. 308If only the name of the 309.Xr make 1 310variable is specified, 311.Ar value 312is assumed to be the empty string. 313.Pp 314Example: 315.Bd -literal -offset indent -compact 316makeoptions MYMAKEOPTION="foo" 317makeoptions MYMAKEOPTION+="bar" 318makeoptions MYNULLMAKEOPTION 319.Ed 320.\" -------- MAXUSERS -------- 321.Pp 322.It Ic maxusers Ar number 323This optional directive is used to configure the size 324of some kernel data structures. 325The parameter 326.Ar number 327can be 0 (the default) or an integer greater than or equal to 2. 328A value of 0 indicates that the kernel should configure 329its data structures according to the size of available 330physical memory. 331If auto configuration is requested, the kernel will set 332this tunable to a value between 32 and 384 for 32-bit systems, 333or scale the value higher based on available memory for 64-bit 334systems. 335.Pp 336As explained in 337.Xr tuning 7 , 338this tunable can also be set at boot time using 339.Xr loader 8 . 340.\" -------- NOCPU -------- 341.Pp 342.It Ic nocpu Ar cputype 343Remove the specified CPU 344from the list of previously selected CPUs. 345This directive can be used to cancel the effect of 346.Ic cpu 347directives in files included using 348.Ic include . 349.\" -------- NODEVICE -------- 350.Pp 351.It Ic nodevice Ar name Op , Ar name Op ... 352.It Ic nodevices Ar name Op , Ar name Op ... 353Remove the specified devices 354from the list of previously selected devices. 355This directive can be used to cancel the effects of 356.Ic device 357or 358.Ic devices 359directives in files included using 360.Ic include . 361.\" -------- NOMAKEOPTION -------- 362.Pp 363.It Ic nomakeoption Ar name 364.It Ic nomakeoptions Ar name 365Removes previously defined 366.Xr make 1 367option 368.Ar name 369from the kernel build. 370This directive can be used to cancel the effects of 371.Ic makeoption 372directives in files included using 373.Ic include . 374.\" -------- NOOPTION -------- 375.Pp 376.It Ic nooption Ar name Op , Ar name Op ... 377.It Ic nooptions Ar name Op , Ar name Op ... 378Remove the specified kernel options 379from the list of previously defined options. 380This directive can be used to cancel the effects of 381.Ic option 382or 383.Ic options 384directives in files included using 385.Ic include . 386.\" -------- OPTIONS -------- 387.Pp 388.It Ic option Ar optionspec Op , Ar optionspec Op ... 389.It Ic options Ar optionspec Op , Ar optionspec Op ... 390Add compile time kernel options to the kernel build. 391Each option specification has the form 392.Pp 393.D1 Ar name Ns Op = Ns Ar value 394.Pp 395If 396.Ar value 397is not specified, it is assumed to be 398.Dv NULL . 399Options common to all architectures are specified in 400the file 401.Pa sys/conf/options . 402Options specific to architecture 403.Ar arch 404are specified in the file 405.Pa sys/conf/options . Ns Aq Ar arch . 406.El 407.Sh FILES 408.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact 409.It Pa sys/compile/ Ns Ar NAME 410Compile directory created from a kernel configuration. 411.It Pa sys/conf/Makefile . Ns Ar arch 412.Pa Makefile 413fragments for architecture 414.Ar arch . 415.It Pa sys/conf/files 416Devices common to all architectures. 417.It Pa sys/conf/files . Ns Ar arch 418Devices for architecture 419.Ar arch . 420.It Pa sys/conf/options 421Options common to all architectures. 422.It Pa sys/conf/options . Ns Ar arch 423Options for architecture 424.Ar arch . 425.El 426.Sh SEE ALSO 427.Xr kenv 1 , 428.Xr make 1 , 429.Xr device.hints 5 , 430.Xr loader.conf 5 , 431.Xr config 8 , 432.Xr kldload 8 , 433.Xr loader 8 434.Rs 435.%T "Building 4.4BSD Kernels with Config" 436.%A "Samuel J. Leffler" 437.%A "Michael J. Karels" 438.Re 439.Sh HISTORY 440The 441.Xr config 8 442utility first appeared in 443.Bx 4.1 , 444and was subsequently revised in 445.Bx 4.4 . 446.Pp 447The kernel configuration mechanism changed further in 448.Fx 4.0 449and 450.Fx 5.0 , 451moving toward an architecture supporting dynamic kernel 452configuration. 453