1.\" $NetBSD: config.5,v 1.21 2010/03/03 13:53:22 pooka Exp $ 2.\" 3.\" Copyright (c) 2006, 2007 The NetBSD Foundation. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd March 3, 2010 28.Dt CONFIG 5 29.Os 30.Sh NAME 31.Nm config 32.Nd kernel configuration file syntax 33.Sh DESCRIPTION 34The kernel configuration file specifies the way the kernel should be compiled 35by the rest of the toolchain. 36It is processed by 37.Xr config 1 38to produce a number of files that will allow the user to compile a possibly 39customised kernel. 40One compilation can issue several kernel binaries, with different root and 41dump devices configurations, or with full debugging information. 42.Pp 43This manual page is intended to serve as a complete reference of all aspects 44of the syntax used in the many files processed by 45.Xr config 1 . 46The novice user will prefer looking at the examples given in 47.Xr config.samples 5 48in order to understand better how the default configuration can be changed, 49and how all of its elements interact with each other. 50.Pp 51The kernel configuration file actually contains the description of all the 52options, drivers and source files involved in the kernel compilation, and the 53logic that binds them. 54The 55.Ic machine 56statement, usually found in the 57.Pa std.${MACHINE} 58file, hides this from the user by automatically including all the descriptive 59files spread all around the kernel source tree, the main one being 60.Pa conf/files . 61.Pp 62Thus, the kernel configuration file contains two parts: 63the description of the compilation options, and the selection of those options. 64However, it begins with a small preamble that controls a couple of options of 65.Xr config 1 , 66and a few statements belong to any of the two sections. 67.Pp 68The user controls the options selection part, which is located in a file 69commonly referenced as the 70.Em main configuration file 71or simply the 72.Em kernel configuration file . 73The developer is responsible for describing the options in the relevant files 74from the kernel source tree. 75.Pp 76Statements are separated by new-line characters. 77However, new-line characters can appear in the middle of a given statement, 78with the value of a space character. 79.Ss OBJECTS AND NAMES 80.Xr config 1 81is a rather complicated piece of software that tries to comply with any 82configuration the user might think of. 83Quite a few different objects are manipulated through the kernel configuration 84file, therefore some definitions are needed. 85.Ss Options and attributes 86The basic objects driving the kernel compilation are 87.Em options , 88and are called 89.Ar attributes 90in some contexts. 91An 92.Ar attribute 93usually refers to a feature a given piece of hardware might have. 94However, the scope of an attribute is rather wide and can just be a place 95holder to group some source files together. 96.Pp 97There is a special class of attribute, named 98.Em interface attribute , 99which represents a hook that allows a device to attach to (i.e., be a child of) 100another device. 101An 102.Em interface attribute 103has a (possibly empty) list of 104.Ar locators 105to match the actual location of a device. 106For example, on a PCI bus, devices are located by a 107.Em device number 108that is fixed by the wiring of the motherboard. 109Additionally, each of those devices can appear through several interfaces named 110.Em functions . 111A single PCI device entity is a unique function number of a given device from 112the considered PCI bus. 113Therefore, the locators for a 114.Xr pci 4 115device are 116.Ar dev 117(for device), and 118.Ar function . 119.Pp 120A 121.Ar locator 122can either be a single integer value, or an array of integer values. 123It can have a default value, in which case it can be wildcarded with a 124.Dq \&? 125in the options selection section of the configuration file. 126A single 127.Ar locator 128definition can take one of the following forms: 129.Bl -enum -offset indent -compact 130.It 131.Ar locator 132.It 133.Ar locator 134= 135.Ar value 136.It 137.Ar locator Ns Oo Ar length Oc 138.It 139.Ar locator Ns Oo Ar length Oc = Brq Ar value , ... 140.El 141The variants that specify a default value can be enclosed into square brackets, 142in which case the locator will not have to be specified later in the options 143selection section of the configuration file. 144.Pp 145In the options selection section, the locators are specified when declaring an 146instance as a space-separated list of 147.Dq Ao Ar locator Ac Ao Ar value Ac 148where value can be the 149.Dq \&? 150wildcard if the locator allows it. 151.Ss Devices, instances and attachments 152The main benefit of the kernel configuration file is to allow the user to avoid 153compiling some drivers, and wire down the configuration of some others. 154We have already seen that devices attach to each other through 155.Em interface attributes , 156but not everything can attach to anything. 157Furthermore, the user has the ability to define precise instances for the 158devices. 159An 160.Ar instance 161is simply the reality of a device when it is probed and attached by the kernel. 162.Pp 163Each driver has a name for its devices. 164It is called the base device name and is found as 165.Ar base 166in this documentation. 167An 168.Ar instance 169is the concatenation of a device name and a number. 170In the kernel configuration file, instances can sometimes be wildcarded 171(i.e., the number is replaced by a 172.Dq * 173or a 174.Dq \&? ) 175in order to match all the possible instances of a device. 176.Pp 177The usual 178.Dq * 179becomes a 180.Dq \&? 181when the instance name is used as an 182.Em attachment name . 183In the options selection part of the kernel configuration files, an 184.Em attachment 185is an 186.Em interface attribute 187concatenated with a number or the wildcard 188.Dq \&? . 189.Ss Pseudo-devices 190Some components of the kernel behave like a device although they don't have 191any actual reality in the hardware. 192For example, this is the case for special network devices, such as 193.Xr tun 4 194and 195.Xr tap 4 . 196They are integrated in the kernel as pseudo-devices, and can have several 197instances and even children, just like normal devices. 198.Ss Dependencies 199The options description part of the kernel configuration file contains all the 200logic that ties the source files together, and it is done first through writing 201down dependencies between 202.Xr config 1 203objects. 204.Pp 205In this documentation, the syntax for 206.Ar dependencies 207is a comma-separated list of 208.Ar options 209and 210.Ar attributes . 211.Pp 212For example, the use of an Ethernet network card requires the source files that 213handle the specificities of that protocol. 214Therefore, all Ethernet network card drivers depend on the 215.Ar ether 216attribute. 217.Ss Conditions 218Finally, source file selection is possible through the help of 219conditionals, referred to as 220.Ar condition 221later in this documentation. 222The syntax for those conditions uses well-known operators ( 223.Dq \*[Am] , 224.Dq | 225and 226.Dq \&! ) 227to combine 228.Ar options 229and 230.Ar attributes . 231.Ss CONTEXT NEUTRAL STATEMENTS 232.Bl -ohang 233.It Ic version Ar yyyymmdd 234Indicates the syntax version used by the rest of the file, or until the next 235.Ic version 236statement. 237The argument is an ISO date. 238A given 239.Xr config 1 240binary might only be compatible with a limited range of version numbers. 241.It Ic include Ar path 242Includes a file. 243The path is relative to the top of the kernel source tree, or the inner-most 244defined 245.Ic prefix . 246.It Ic cinclude Ar path 247Conditionally includes a file. 248Contrary to 249.Ic include , 250it will not produce an error if the file does not exist. 251The argument obeys the same rules as for 252.Ic include . 253.It Ic prefix Op Ar path 254If 255.Ar path 256is given, it pushes a new prefix for 257.Ic include 258and 259.Ic cinclude . 260.Ic prefix 261statements act like a stack, and an empty 262.Ar path 263argument has the latest prefix popped out. 264The 265.Ar path 266argument is either absolute or relative to the current defined prefix, which 267defaults to the top of ther kernel source tree. 268.It Ic ifdef Ar attribute 269.It Ic ifndef Ar attribute 270.It Ic elifdef Ar attribute 271.It Ic elifndef Ar attribute 272.It Ic else 273.It Ic endif 274Conditionally interprets portions of the current file. 275Those statements depend on whether or not the given 276.Ar attribute 277has been previously defined, through 278.Ic define 279or any other statement that implicitely defines attributes such as 280.Ic device . 281.El 282.Ss PREAMBLE 283In addition to 284.Ic include , cinclude , 285and 286.Ic prefix , 287the preamble may contain the following optional statements: 288.Bl -ohang 289.It Ic build Ar path 290Defines the build directory for the compilation of the kernel. 291It replaces the default of 292.Pa ../compile/\*[Lt]config-file\*[Gt] 293and is superseded by the 294.Fl b 295parameter of 296.Xr config 1 . 297.It Ic source Ar path 298Defines the directory in which the source of the kernel lives. 299It replaces the default of 300.Pa ../../../.. 301and is superseded by the 302.Fl s 303parameter of 304.Xr config 1 . 305.El 306.Ss OPTIONS DESCRIPTION 307The user will not usually have to use descriptive statements, as they are meant 308for the developer to tie a given piece of code to the rest of the kernel. 309However, third parties may provide sources to add to the kernel compilation, 310and the logic that binds them to the 311.Nx 312kernel will have to be added to the user-edited configuration file. 313.Bl -ohang 314.It Ic devclass Ar class 315Defines a special attribute, named 316.Em device class . 317A given device cannot belong to more than one device class. 318.Xr config 1 319translates that property by the rule that a device cannot depend on more than 320one device class, and will properly fill the configuration information file it 321generates according to that value. 322.It Ic defflag Oo Ar file Oc Ar option Oo Ar option Oo Ar ... Oc Oc \ 323 Op : Ar dependencies 324Defines a boolean option, that can either be selected or be un-selected by the 325user with the 326.Ic options 327statement. 328The optional 329.Ar file 330argument names a header file that will contain the C pre-processor definition 331for the option. 332If no file name is given, it will default to 333.Ar opt_\*[Lt]option\*[Gt].h . 334.Xr config 1 335will always create the header file, but if the user choose not to select the 336option, it will be empty. 337Several options can be combined in one header file, for convenience. 338The header file is created in the compilation directory, making them directly 339accessible by source files. 340.It Ic defparam Oo Ar file Oc Ar option Oo = Ar value Oc \ 341 Oo := Ar lint-value Oc Oo Ar option Oo Ar ... Oc Oc Op : Ar dependencies 342Behaves like 343.Ic defflag , 344except the defined option must have a value. 345Such options are not typed: 346they can have either a numeric or a string value. 347If a 348.Ar value 349is specified, it is treated as a default, and the option is 350always defined in the corresponding header file. 351If a 352.Ar lint-value 353is specified, 354.Xr config 1 355will use it as a value when generating a lint configuration with 356.Fl L , 357and ignore it in all other cases. 358.It Ic deffs Ar name Op Ar name Op Ar ... 359Defines a file-system name. 360It is no more than a regular option, as defined by 361.Ic defflag , 362but it allows the user to select the 363file-systems to be compiled in the kernel with the 364.Ic file-system 365statement instead of the 366.Ic options 367statement. 368.It Ic obsolete defflag Oo Ar file Oc Ar option Op Ar option Op Ar ... 369.It Ic obsolete defparam Oo Ar file Oc Ar option Op Ar option Op Ar ... 370Those two statements are identical and mark the listed option names as 371obsolete. 372If the user selects one of the listed options in the kernel configuration 373file, 374.Xr config 1 375will emit a warning and ignore the option. 376The optional 377.Ar file 378argument should match the original definition of the option. 379.It Ic define Ar attribute Oo Bro Ar locators Brc Oc Oo : Ar dependencies Oc 380Defines an 381.Ar attribute . 382The 383.Ar locators 384list is optional, and can be empty. 385If the pair of brackets are present, the locator list is defined and the 386declared attribute becomes an 387.Em interface attribute , 388on which devices can attach. 389.It Ic maxpartitions Ar number 390Defines the maximum number of partitions the disklabels for the considered 391architecture can hold. 392This statement cannot be repeated and should only appear in the 393.Pa std\&.$\&{ARCH\&} 394file. 395.It Ic maxusers Ar min default max 396Indicates the range of values that will later be accepted by 397.Xr config 1 398for the 399.Ic maxusers 400statement in the options selection part of the configuration file. 401In case the user doesn't include a 402.Ic maxusers 403statement in the configuration file, the value 404.Ar default 405is used instead. 406.It Ic device Ar base Oo Bro Ar locators Brc Oc Oo : dependencies Oc 407Declares a device of name 408.Ar base . 409The optional list of 410.Ar locators , 411which can also be empty, indicates the device can have children attached 412directly to it. 413Internally, that means 414.Ar base 415becomes an 416.Ar interface attribute . 417For every device the user selects, 418.Xr config 1 419will add the matching 420.Fn CFDRIVER_DECL 421statement to 422.Pa ioconf.c . 423However, it is the responsibility of the developer to add the relevant 424.Fn CFATTACH_DECL 425line to the source of the device's driver. 426.It Ic attach Ar base Ic at Ar attr Oo , Ar attr Oo , Ar ... Oc Oc Oo Ic with \ 427 Ar name Oc Oo : dependencies Oc 428All devices must have at least one declared attachment. 429Otherwise, they will never be found in the 430.Xr autoconf 9 431process. 432The attributes on which an instance of device 433.Ar base 434can attach must be 435.Ar interface attributes , 436or 437.Ic root 438in case the device is at the top-level, which is usually the case of e.g., 439.Xr mainbus 4 . 440The instances of device 441.Ar base 442will later attach to one interface attribute from the specified list. 443.Pp 444Different 445.Ic attach 446definitions must use different names using the 447.Ic with 448option. 449It is then possible to use the associated 450.Ar name 451as a conditional element in a 452.Ic file 453statement. 454.It Ic defpseudo Ar base Oo : dependencies Oc 455Declares a pseudo-device. 456Those devices don't need an attachment to be declared, they will always be 457attached if they were selected by the user. 458.It Ic defpseudodev Ar base Oo Bro Ar locators Brc Oc Oo : dependencies Oc 459Declares a pseudo-device. 460Those devices don't need an attachment to be declared, they will always be 461attached if they were selected by the user. 462This declaration should be used if the pseudodevice uses 463.Xr autoconf 9 464functions to manage its instances or attach children. 465As for normal devices, an optional list of 466.Ar locators 467can be defined, which implies an interface attribute named 468.Ar base , 469allowing the pseudo-device to have children. 470Interface attributes can also be defined in the 471.Ar dependencies 472list. 473.It Ic file Ar path Oo Ar condition Oc Oo Ic needs-count Oc \ 474 Oo Ic needs-flag Oc Op Ic compile with Ar rule 475Adds a source file to the list of files to be compiled into the kernel, if the 476.Ar conditions 477are met. 478The 479.Ic needs-count 480option indicates that the source file requires the number of all the countable 481objects it depends on (through the 482.Ar conditions ) 483to be defined. 484It is usually used for 485.Ar pseudo-devices 486whose number can be specified by the user in the 487.Ic pseudo-device 488statement. 489Countable objects are devices and pseudo-devices. 490For the former, the count is the number of declared instances. 491For the latter, it is the number specified by the user, defaulting to 1. 492The 493.Ic needs-flag 494options requires that a flag indicating the selection of an attribute to 495be created, but the precise number isn't needed. 496This is useful for source files that only partly depend on the attribute, 497and thus need to add pre-processor statements for it. 498.Pp 499.Ic needs-count 500and 501.Ic needs-flag 502both produce a header file for each of the considered attributes. 503The name of that file is 504.Pa \*[Lt]attribute\*[Gt].h . 505It contains one pre-processor definition of 506.Dv NATTRIBUTE 507set to 0 if the attribute was not selected by the user, or to the number of 508instances of the device in the 509.Ic needs-count 510case, or to 1 in all the other cases. 511.Pp 512The 513.Ar rule 514argument specifies the 515.Xr make 1 516rule that will be used to compile the source file. 517If it is not given, the default rule for the type of the file will be used. 518For a given file, there can be more than one 519.Ic file 520statement, but not from the same configuration source file, and all later 521statements can only specify a 522.Ar rule 523argument, and no 524.Ar conditions 525or flags. 526This is useful when a file needs special consideration from one particular 527architecture. 528.It Ic object Ar path Op Ar condition 529Adds an object file to the list of objects to be linked into the kernel, if the 530.Ar conditions 531are met. 532This is most useful for third parties providing binary-only components. 533.It Ic device-major Ar base Oo Ic char Ar number Oc Oo Ic block Ar number Oc \ 534 Op Ar condition 535Associates a major device number with the device 536.Ar base . 537A device can be a character device, a block device, or both, and can have 538different numbers for each. 539The 540.Ar condition 541indicates when the relevant line should be added to 542.Pa ioconf.c , 543and works just like the 544.Ic file 545statement. 546.It Ic makeoptions Ar condition name Ns += Ns Ar value Op , Ar condition \ 547 name Ns += Ns Ar value 548Appends to a definition in the generated 549.Pa Makefile . 550.El 551.Ss OPTIONS SELECTION 552.Bl -ohang 553.It Ic machine Ar machine Op Ar arch Op Ar subarch Op Ar ... 554The 555.Ic machine 556statement should appear first in the kernel configuration file, with the 557exception of context-neutral statements. 558It makes 559.Xr config 1 560include, in that order, the following files: 561.Bl -enum -offset indent -compact 562.It 563.Pa conf/files 564.It 565.Pa arch/${ARCH}/conf/files.${ARCH} 566if defined 567.It 568.Pa arch/${SUBARCH}/conf/files.${SUBARCH} 569for each defined sub-architecture 570.It 571.Pa arch/${MACHINE}/conf/files.${MACHINE} 572.El 573It also defines an attribute for the 574.Ar machine , 575the 576.Ar arch 577and each of the 578.Ar subarch . 579.It Ic package Ar path 580Simpler version of: 581.Bd -literal -offset indent 582prefix PATH 583include FILE 584prefix 585.Ed 586.It Ic ident Ar string 587Defines the indentification string of the kernel. 588This statement is optional, and the name of the main configuration file will be 589used as a default value. 590.It Ic maxusers Ar number 591Despite its name, this statement does not limit the maximum number of users on 592the system. 593There is no such limit, actually. 594However, some kernel structures need to be adjusted to accommodate with more 595users, and the 596.Ic maxusers 597parameter is used for example to compute the maximum number of opened files, 598and the maximum number of processes, which itself is used to adjust a few 599other parameters. 600.It Ic options Ar name Oo = Ar value Oc Op , Ar name Oo = Ar \ 601 value Oc , Ar ... 602Selects the option 603.Ar name , 604affecting it a 605.Ar value 606if the options requires it (see the 607.Ic defflag 608and 609.Ic defparam 610statements). 611.Pp 612If the option has not been declared in the options description part of the 613kernel configuration machinery, it will be added as a pre-processor definition 614when source files are compiled. 615.It Ic no options Ar name Op , Ar name Op , Ar ... 616Un-selects the option 617.Ar name . 618If option 619.Ar name 620has not been previously selected, the statement produces an error. 621.It Oo Ic no Oc Ic file-system Ar name Op , Ar name Op , Ar ... 622Adds or removes support for all the listed file-systems. 623.It Ic config Ar name Ic root on Ar device Oo Ic type Ar fs Oc Op Ic dumps on \ 624 Ar device 625Adds 626.Ar name 627to the list of kernel binaries to compile from the configuration file, using 628the specified root and dump devices information. 629.Pp 630Any of the 631.Ar device 632and 633.Ar fs 634parameters can be wildcarded with 635.Dq \&? 636to let the kernel automatically discover those values. 637.Pp 638At least one 639.Ic config 640statement must appear in the configuration file. 641.It Ic no config Ar name 642Removes 643.Ar name 644from the list of kernel binaries to compile from the configuration file. 645.It Ar instance Ic at Ar attachment Op Ar locator specification 646Configures an instance of a device attaching at a specific location in the 647device tree. 648All parameters can be wildcarded, with a 649.Dq * 650for 651.Ar instance , 652and a 653.Dq \&? 654for 655.Ar attachment 656and the locators. 657.It Ic no Ar instance Op Ic at Ar attachment 658Removes the previously configured instances of a device that exactly match the 659given specification. 660If two instances differ only by their locators, both are removed. 661If no 662.Ar attachment 663is specified, all matching instances are removed. 664.Pp 665If 666.Ar instance 667is a bare device name, all the previously defined instances of that device, 668regardless of the numbers or wildcard, are removed. 669.It Ic no device at Ar attachment 670Removes all previously configured instances that attach to the specified 671attachment. 672If 673.Ar attachment 674ends with a 675.Dq * , 676all instances attaching to all the variants of 677.Ar attachment 678are removed. 679.It Ic pseudo-device Ar device Op Ar number 680Adds support for the specified pseudo-device. 681The parameter 682.Ar number 683is passed to the initialisation function of the pseudo-device, usually to 684indicate how many instances should be created. 685It defaults to 1, and some pseudo-devices ignore that parameter. 686.It Ic no pseudo-device Ar name 687Removes support for the specified pseudo-device. 688.It Ic makeoptions Ar name Ns = Ns value Op , Ar name Ns += Ns value \ 689 Op , Ar ... 690Adds or appends to a definition in the generated 691.Pa Makefile . 692A definition cannot be overriden, it must be removed before it can be added 693again. 694.It Ic no makeoptions Ar name Op , Ar name Op , Ar ... 695Removes one or more definitions from the generated 696.Pa Makefile . 697.El 698.Sh FILES 699The files are relative to the kernel source top directory (e.g., 700.Pa /usr/src/sys ) . 701.Pp 702.Bl -tag -width arch/${MACHINE}/conf/std.${MACHINE} 703.It Pa arch/${MACHINE}/conf/std.${MACHINE} 704Standard configuration for the given architecture. 705This file should always be included. 706.It Pa arch/${MACHINE}/conf/GENERIC 707Standard options selection file for the given architecture. 708Users should always start changing their main kernel configuration file by 709editing a copy of this file. 710.It Pa conf/files 711Main options description file. 712.El 713.Sh EXAMPLES 714.Xr config.samples 5 715uses several examples to cover all the practical aspects of writing or 716modifying a kernel configuration file. 717.Sh SEE ALSO 718.Xr config 1 , 719.Xr options 4 , 720.Xr config.samples 5 , 721.Xr config 9 722