From ff07f3efa8e7c764e1d583fae680c5da4075c133 Mon Sep 17 00:00:00 2001 From: jkoshy Date: Sun, 6 Jul 2003 01:52:26 +0000 Subject: New section 5 manual page detailing our kernel configuration file format. Reviewed by: Ruslan Ermilov , Jens Schweikhardt --- share/man/man5/config.5 | 343 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 343 insertions(+) create mode 100644 share/man/man5/config.5 (limited to 'share') diff --git a/share/man/man5/config.5 b/share/man/man5/config.5 new file mode 100644 index 0000000..946e8ae --- /dev/null +++ b/share/man/man5/config.5 @@ -0,0 +1,343 @@ +.\" Copyright (c) 2003 Joseph Koshy +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 3, 2003 +.Dt CONFIG 5 +.Os +.Sh NAME +.Nm config +.Nd kernel configuration file format +.Sh DESCRIPTION +A kernel configuration file specifies the configuration of a +.Fx +kernel. +It is processed by +.Xr config 8 +to create a build environment where a kernel may be built using +.Xr make 1 . +.Ss Lexical Structure +A kernel configuration file comprises a sequence of specification +directives. +.Pp +A specification directive starts with a keyword at the beginning +of the line and is followed by additional parameters. +.Pp +A specification directive may be terminated by a semicolon +.Ql \&; +or by a newline. +Long input lines may be broken into shorter lines by starting the +second and subsequent lines with a white space character. +.Pp +Case is significant, +.Dq Li machine +and +.Dq Li MACHINE +are different tokens. +.Pp +A double quote character +.Ql \[dq] +starts a quoted string. +All characters up to the next quote character form the value +of the quoted string. +A +.Ql \[dq] +character may be inserted into a quoted string by +using the sequence +.Ql \e\[dq] . +.Pp +Numbers are specified using +.Tn C Ns -style +syntax. +.Pp +A +.Ql # +character starts a comment; all characters from the +.Ql # +character till the end of the current line are ignored. +.Pp +Whitespace between tokens is ignored, except inside quoted strings. +Whitespace following a comment line is ignored. +.Ss Configuration Directives +Kernel configuration directives may appear in any order +in a kernel configuration file. +Directives are processed in order of appearance with subsequent +directive lines overriding the effect of prior ones. +.Pp +The list of keywords and their meanings are as follows: +.Bl -tag -width indent +.\" -------- CPU -------- +.It Ic cpu Ar cputype +Specify the CPU this kernel will run on. +There can be more than one +.Ic cpu +directive in a configuration file. +The allowed list of CPU names is architecture specific and is +defined in the file +.Pa sys/conf/options. Ns Aq Ar arch . +.\" -------- DEVICE -------- +.It Ic device Ar name Op Ar count +Configures device +.Ar name +for inclusion into the kernel image. +If +.Ar count +is specified, the device is configured for +.Ar count +instances. +Devices that are common to all architectures are +defined in the file +.Pa sys/conf/files . +Devices that are specific to architecture +.Ar arch +are defined in the file +.Pa sys/conf/files. Ns Aq Ar arch . +.\" -------- ENV -------- +.It Ic env Ar filename +Specifies a filename containing a kernel environment definition. +The kernel normally uses an environment prepared for it at boot time +by +.Xr loader 8 . +This directive makes the kernel ignore the boot environment and use +the compiled-in environment instead. +.Pp +This directive is useful for setting kernel tunables in +embedded environments that do not start from +.Xr loader 8 . +.\" -------- HINTS -------- +.It Ic hints Ar filename +Specifies a file to load a static device configuration specification +from. +From +.Fx 5.0 +onwards, the kernel reads the system's device configuration at boot +time (see +.Xr device.hints 5 ) . +This directive configures the kernel to use the static device configuration +listed in +.Ar filename . +The file +.Ar filename +must conform to the syntax specified by +.Xr device.hints 5 . +.\" -------- IDENT -------- +.It Ic ident Ar name +Set the kernel name to +.Ar name . +At least one +.Ic ident +directive is required. +.\" -------- INCLUDE -------- +.It Ic include Ar filename +Read subsequent text from file +.Ar filename +and return to the current file after +.Ar filename +is successfully processed. +.\" -------- MACHINE -------- +.It Ic machine Ar arch +Specifies the architecture of the machine the kernel is being +compiled for. +Legal values for +.Ar arch +include: +.Pp +.Bl -tag -width ".Cm powerpc" -compact +.It Cm alpha +The DEC Alpha architecture. +.It Cm amd64 +The AMD x86-64 architecture. +.It Cm i386 +The Intel x86 based PC architecture. +.It Cm ia64 +The Intel IA64 architecture. +.It Cm pc98 +The PC98 architecture. +.It Cm powerpc +The IBM PowerPC architecture. +.It Cm sparc64 +The Sun Sparc64 architecture. +.El +.Pp +A kernel configuration file may have only one +.Ic machine +directive. +.\" -------- MAKEOPTION -------- +.It Ic makeoptions Ar options +Add +.Ar options +to the generated makefile. +.Pp +The +.Ar options +argument is a comma separated list of one or more option +specifications. +Each option specification has the form +.Pp +.D1 Ar MakeVariableName Ns Op = Ns Ar Value +.Pp +and results in the appropriate +.Xr make 1 +variable definition being inserted into the generated makefile. +If only the name of the +.Xr make 1 +variable is specified, +.Ar value +is assumed to be the empty string. +.Pp +Example: +.Bd -literal -offset indent -compact +makeoptions MYMAKEOPTION="foobar" +makeoptions MYNULLMAKEOPTION +.Ed +.\" -------- MAXUSERS -------- +.It Ic maxusers Ar number +This optional directive is used to configure the size +of some kernel data structures. +The parameter +.Ar number +can be 0 (the default) or an integer greater than or equal to 2. +A value of 0 indicates that the kernel should configure +its data structures according to the size of available +physical memory. +If autoconfiguration is requested, the kernel will set +this tunable to a value between 32 and 384. +.Pp +As explained in +.Xr tuning 7 , +this tunable can also be set at boot time using +.Xr loader 8 . +.\" -------- NOMAKEOPTION -------- +.It Ic nomakeoption Ar name +Removes previously defined +.Xr make 1 +option +.Ar name +from the kernel build. +This directive can be used to cancel the effects of +.Ic makeoption +directives in files included using +.Ic include . +.\" -------- NOOPTION -------- +.It Ic nooption Ar kerneloptionname +Remove kernel option +.Ar kerneloptionname +from the list of previously defined options. +This directive can be used to cancel the effects of +.Ic options +directives in files included using +.Ic include . +.\" -------- OPTIONS -------- +.It Ic options Ar optionspecs +Add compile time kernel options to the kernel build. +The argument +.Ar optionspecs +is a comma separated list of option specifications. +Each option specification has the form +.Pp +.D1 Ar KernelOptionName Ns Op = Ns Ar OptionValue +.Pp +If +.Ar OptionValue +is not specified, it is assumed to be +.Dv NULL . +Options common to all architectures are specified in +the file +.Pa sys/conf/options . +Options specific to architecture +.Ar arch +are specified in the file +.Pa sys/conf/options. Ns Aq Ar arch . +.\" -------- PROFILE -------- +.It Ic profile Ar number +Enables kernel profiling if +.Ar number +is non-zero. +If +.Ar number +is 2 or greater, the kernel is configured for +high-resolution profiling. +Kernels can also be built for profiling using the +.Fl p +option to +.Xr config 8 . +.El +.Ss Obsolete Directives +The following kernel configuration directives are obsolete. +.Bl -tag -width indent +.\" -------- CONFIG -------- +.It Ic config +This directive was used to specify the device to be used for the root +file system. +From +.Fx 4.0 +onwards, this information is passed to a booting kernel by +.Xr loader 8 . +.El +.Sh FILES +.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact +.It Pa sys/compile/ Ns Ar NAME +Compile directory created from a kernel configuration. +.It Pa sys/conf/Makefile. Ns Ar arch +.Pa Makefile +fragments for architecture +.Ar arch . +.It Pa sys/conf/files +Devices common to all architectures. +.It Pa sys/conf/files. Ns Ar arch +Devices for architecture +.Ar arch . +.It Pa sys/conf/options +Options common to all architectures. +.It Pa sys/conf/options. Ns Ar arch +Options for architecture +.Ar arch . +.El +.Sh SEE ALSO +.Xr kenv 1 , +.Xr make 1 , +.Xr device.hints 5 , +.Xr loader.conf 5 , +.Xr config 8 , +.Xr kldload 8 , +.Xr loader 8 +.Rs +.%T "Building 4.4BSD Kernels with Config" +.%A "Samuel J. Leffler" +.%A "Michael J. Karels" +.Re +.Sh HISTORY +The +.Xr config 8 +utility first appeared in +.Bx 4.1 , +and was subsequently revised in +.Bx 4.4 . +.Pp +The kernel configuration mechanism changed further in +.Fx 4.0 +and +.Fx 5.0 , +moving towards an architecture supporting dynamic kernel +configuration. -- cgit v1.1