New section 5 manual page detailing our kernel configuration file

format.

Reviewed by:	Ruslan Ermilov <ru@freebsd.org>, Jens
		Schweikhardt <schweikh@schweikhardt.net>

1 files changed, 343 insertions, 0 deletions

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.