1341 lines
55 KiB
XML
1341 lines
55 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!--
|
|
The FreeBSD Documentation Project
|
|
|
|
$FreeBSD$
|
|
-->
|
|
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
|
xml:id="kernelconfig">
|
|
<!--<chapterinfo>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Jim</firstname>
|
|
<surname>Mock</surname>
|
|
<contrib>Updated and restructured in Mar 2000 by </contrib>
|
|
</author>
|
|
</authorgroup>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Jake</firstname>
|
|
<surname>Hamby</surname>
|
|
<contrib>Originally contributed 6 Oct 1995 by </contrib>
|
|
</author>
|
|
</authorgroup>
|
|
</chapterinfo>
|
|
-->
|
|
|
|
<title>Configuring the FreeBSD Kernel</title>
|
|
|
|
<sect1 xml:id="kernelconfig-synopsis">
|
|
<title>Synopsis</title>
|
|
|
|
<indexterm>
|
|
<primary>kernel</primary>
|
|
<secondary>building a custom kernel</secondary>
|
|
</indexterm>
|
|
|
|
<para>The kernel is the core of the &os; operating system. It
|
|
is responsible for managing memory, enforcing security controls,
|
|
networking, disk access, and much more. While much of &os; is
|
|
dynamically configurable, it is still occasionally necessary to
|
|
configure and compile a custom kernel.</para>
|
|
|
|
<para>After reading this chapter, you will know:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>When to build a custom kernel.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>How to take a hardware inventory.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>How to customize a kernel configuration file.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>How to use the kernel configuration file to create and
|
|
build a new kernel.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>How to install the new kernel.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>How to troubleshoot if things go wrong.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>All of the commands listed in the examples in this chapter
|
|
should be executed as <systemitem
|
|
class="username">root</systemitem>.</para>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="kernelconfig-custom-kernel">
|
|
<title>Why Build a Custom Kernel?</title>
|
|
|
|
<para>Traditionally, &os; used a monolithic kernel. The kernel
|
|
was one large program, supported a fixed list of devices, and in
|
|
order to change the kernel's behavior, one had to compile and
|
|
then reboot into a new kernel.</para>
|
|
|
|
<para>Today, most of the functionality in the &os; kernel is
|
|
contained in modules which can be dynamically loaded and
|
|
unloaded from the kernel as necessary. This allows the running
|
|
kernel to adapt immediately to new hardware or for new
|
|
functionality to be brought into the kernel. This is known as
|
|
a modular kernel.</para>
|
|
|
|
<para>Occasionally, it is still necessary to perform static kernel
|
|
configuration. Sometimes the needed functionality is so tied
|
|
to the kernel that it can not be made dynamically loadable.
|
|
Some security environments prevent the loading and unloading of
|
|
kernel modules and require that only needed functionality is
|
|
statically compiled into the kernel.</para>
|
|
|
|
<para>Building a custom kernel is often a rite of passage for
|
|
advanced BSD users. This process, while time consuming, can
|
|
provide benefits to the &os; system. Unlike the
|
|
<filename>GENERIC</filename> kernel, which must support a wide
|
|
range of hardware, a custom kernel can be stripped down to only
|
|
provide support for that computer's hardware. This has a number
|
|
of benefits, such as:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Faster boot time. Since the kernel will only probe the
|
|
hardware on the system, the time it takes the system to boot
|
|
can decrease.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Lower memory usage. A custom kernel often uses less
|
|
memory than the <filename>GENERIC</filename> kernel by
|
|
omitting unused features and device drivers. This is
|
|
important because the kernel code remains resident in
|
|
physical memory at all times, preventing that memory from
|
|
being used by applications. For this reason, a custom
|
|
kernel is useful on a system with a small amount of
|
|
RAM.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Additional hardware support. A custom kernel can add
|
|
support for devices which are not present in the
|
|
<filename>GENERIC</filename> kernel.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Before building a custom kernel, consider the reason for
|
|
doing so. If there is a need for specific hardware support,
|
|
it may already exist as a module.</para>
|
|
|
|
<para>Kernel modules exist in <filename>/boot/kernel</filename>
|
|
and may be dynamically loaded into the running kernel using
|
|
&man.kldload.8;. Most kernel drivers have a loadable module and
|
|
manual page. For example, the &man.ath.4; wireless Ethernet
|
|
driver has the following information in its manual page:</para>
|
|
|
|
<screen>Alternatively, to load the driver as a module at boot time, place the
|
|
following line in &man.loader.conf.5;:
|
|
|
|
if_ath_load="YES"</screen>
|
|
|
|
<para>Adding <literal>if_ath_load="YES"</literal> to
|
|
<filename>/boot/loader.conf</filename> will load this module
|
|
dynamically at boot time.</para>
|
|
|
|
<para>In some cases, there is no associated module in
|
|
<filename>/boot/kernel</filename>. This is mostly true for
|
|
certain subsystems.</para>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="kernelconfig-devices">
|
|
<!--
|
|
<sect1info>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Tom</firstname>
|
|
<surname>Rhodes</surname>
|
|
<contrib>Written by </contrib>
|
|
</author>
|
|
</authorgroup>
|
|
</sect1info>
|
|
-->
|
|
<title>Finding the System Hardware</title>
|
|
|
|
<para>Before editing the kernel configuration file, it is
|
|
recommended to perform an inventory of the machine's hardware.
|
|
On a dual-boot system, the inventory can be created from the
|
|
other operating system. For example, µsoft;'s
|
|
<application>Device Manager</application> contains information
|
|
about installed devices.</para>
|
|
|
|
<note>
|
|
<para>Some versions of µsoft.windows; have a
|
|
<application>System</application> icon which can be used to
|
|
access <application>Device Manager</application>.</para>
|
|
</note>
|
|
|
|
<para>If &os; is the only installed operating system, use
|
|
&man.dmesg.8; to determine the hardware that was found and
|
|
listed during the boot probe. Most device drivers on &os; have
|
|
a manual page which lists the hardware supported by that driver.
|
|
For example, the following lines indicate that the &man.psm.4;
|
|
driver found a mouse:</para>
|
|
|
|
<screen>psm0: <PS/2 Mouse> irq 12 on atkbdc0
|
|
psm0: [GIANT-LOCKED]
|
|
psm0: [ITHREAD]
|
|
psm0: model Generic PS/2 mouse, device ID 0</screen>
|
|
|
|
<para>Since this hardware exists, this driver should not be
|
|
removed from a custom kernel configuration file.</para>
|
|
|
|
<para>If the output of <command>dmesg</command> does not display
|
|
the results of the boot probe output, instead read the contents
|
|
of <filename>/var/run/dmesg.boot</filename>.</para>
|
|
|
|
<para>Another tool for finding hardware is &man.pciconf.8;, which
|
|
provides more verbose output. For example:</para>
|
|
|
|
<screen>&prompt.user; <userinput>pciconf -lv</userinput>
|
|
ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00
|
|
vendor = 'Atheros Communications Inc.'
|
|
device = 'AR5212 Atheros AR5212 802.11abg wireless'
|
|
class = network
|
|
subclass = ethernet</screen>
|
|
|
|
<para>This output shows that the <filename>ath</filename> driver
|
|
located a wireless Ethernet device.</para>
|
|
|
|
<para>The <option>-k</option> flag of &man.man.1; can be used to
|
|
provide useful information. For example, to display a list of
|
|
manual pages which contain the specified word:</para>
|
|
|
|
<screen>&prompt.root; <userinput>man -k <replaceable>Atheros</replaceable></userinput></screen>
|
|
|
|
<programlisting>ath(4) - Atheros IEEE 802.11 wireless network driver
|
|
ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
|
|
|
|
<para>Once the hardware inventory list is created, refer to it
|
|
to ensure that drivers for installed hardware are not removed
|
|
as the custom kernel configuration is edited.</para>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="kernelconfig-config">
|
|
<!--
|
|
<sect1info>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Joel</firstname>
|
|
<surname>Dahl</surname>
|
|
<contrib>Updated by </contrib>
|
|
</author>
|
|
</authorgroup>
|
|
</sect1info>
|
|
-->
|
|
<title>The Configuration File</title>
|
|
|
|
<para>In order to create a custom kernel configuration file and
|
|
build a custom kernel, the full &os; source tree must first be
|
|
installed.</para>
|
|
|
|
<para>If <filename>/usr/src/</filename> does not exist or it is
|
|
empty, source has not been installed. Source can be installed
|
|
using <application>Subversion</application> and the instructions
|
|
in <xref linkend="svn"/>.</para>
|
|
|
|
<para>Once source is installed, review the contents of
|
|
<filename>/usr/src/sys</filename>. This directory contains a
|
|
number of subdirectories, including those which represent the
|
|
following supported architectures: <filename>amd64</filename>,
|
|
<filename>i386</filename>, <filename>ia64</filename>,
|
|
<filename>pc98</filename>, <filename>powerpc</filename>, and
|
|
<filename>sparc64</filename>. Everything inside a particular
|
|
architecture's directory deals with that architecture only and
|
|
the rest of the code is machine independent code common to all
|
|
platforms. Each supported architecture has a
|
|
<filename>conf</filename> subdirectory which contains the
|
|
<filename>GENERIC</filename> kernel configuration file for that
|
|
architecture.</para>
|
|
|
|
<para>Do not make edits to <filename>GENERIC</filename>. Instead,
|
|
copy the file to a different name and make edits to the copy.
|
|
The convention is to use a name with all capital letters. When
|
|
maintaining multiple &os; machines with different hardware, it
|
|
is a good idea to name it after the machine's hostname. This
|
|
example creates a copy, named <filename>MYKERNEL</filename>, of
|
|
the <filename>GENERIC</filename> configuration file for the
|
|
<literal>amd64</literal> architecture:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>amd64</replaceable>/conf</userinput>
|
|
&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen>
|
|
|
|
<para><filename><replaceable>MYKERNEL</replaceable></filename> can
|
|
now be customized with any <acronym>ASCII</acronym> text editor.
|
|
The default editor is <application>vi</application>, though an
|
|
easier editor for beginners, called
|
|
<application>ee</application>, is also installed with
|
|
&os;.</para>
|
|
|
|
<indexterm>
|
|
<primary>kernel</primary>
|
|
<secondary>NOTES</secondary>
|
|
</indexterm>
|
|
<indexterm><primary>NOTES</primary></indexterm>
|
|
<indexterm>
|
|
<primary>kernel</primary>
|
|
<secondary>configuration file</secondary>
|
|
</indexterm>
|
|
|
|
<para>The format of the kernel configuration file is simple.
|
|
Each line contains a keyword that represents a device or
|
|
subsystem, an argument, and a brief description. Any text
|
|
after a <literal>#</literal> is considered a comment and
|
|
ignored. To remove kernel support for a device or subsystem,
|
|
put a <literal>#</literal> at the beginning of the line
|
|
representing that device or subsystem. Do not add or remove a
|
|
<literal>#</literal> for any line that you do not
|
|
understand.</para>
|
|
|
|
<warning>
|
|
<para>It is easy to remove support for a device or option and
|
|
end up with a broken kernel. For example, if the &man.ata.4;
|
|
driver is removed from the kernel configuration file, a system
|
|
using <acronym>ATA</acronym> disk drivers may not boot. When
|
|
in doubt, just leave support in the kernel.</para>
|
|
</warning>
|
|
|
|
<para>In addition to the brief descriptions provided in this file,
|
|
additional descriptions are contained in
|
|
<filename>NOTES</filename>, which can be found in the same
|
|
directory as <filename>GENERIC</filename> for that architecture.
|
|
For architecture independent options, refer to
|
|
<filename>/usr/src/sys/conf/NOTES</filename>.</para>
|
|
|
|
<tip>
|
|
<para>When finished customizing the kernel configuration file,
|
|
save a backup copy to a location outside of
|
|
<filename>/usr/src</filename>.</para>
|
|
|
|
<para>Alternately, keep the kernel configuration file elsewhere
|
|
and create a symbolic link to the file:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd /usr/src/sys/amd64/conf</userinput>
|
|
&prompt.root; <userinput>mkdir /root/kernels</userinput>
|
|
&prompt.root; <userinput>cp GENERIC /root/kernels/MYKERNEL</userinput>
|
|
&prompt.root; <userinput>ln -s /root/kernels/MYKERNEL</userinput></screen>
|
|
</tip>
|
|
|
|
<para>An <literal>include</literal> directive is available for use
|
|
in configuration files. This allows another configuration file
|
|
to be included in the current one, making it easy to maintain
|
|
small changes relative to an existing file. If only a small
|
|
number of additional options or drivers are required, this
|
|
allows a delta to be maintained with respect to
|
|
<filename>GENERIC</filename>, as seen in this example:</para>
|
|
|
|
<programlisting>include GENERIC
|
|
ident MYKERNEL
|
|
|
|
options IPFIREWALL
|
|
options DUMMYNET
|
|
options IPFIREWALL_DEFAULT_TO_ACCEPT
|
|
options IPDIVERT</programlisting>
|
|
|
|
<para>Using this method, the local configuration file expresses
|
|
local differences from a <filename>GENERIC</filename> kernel.
|
|
As upgrades are performed, new features added to
|
|
<filename>GENERIC</filename> will also be added to the local
|
|
kernel unless they are specifically prevented using
|
|
<literal>nooptions</literal> or <literal>nodevice</literal>. A
|
|
comprehensive list of configuration directives and their
|
|
descriptions may be found in &man.config.5;.</para>
|
|
|
|
<note>
|
|
<para>To build a file which contains all available options,
|
|
run the following command as <systemitem
|
|
class="username">root</systemitem>:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>arch</replaceable>/conf && make LINT</userinput></screen>
|
|
</note>
|
|
|
|
<!--
|
|
<indexterm>
|
|
<primary>kernel options</primary>
|
|
<secondary>ident</secondary>
|
|
</indexterm>
|
|
|
|
This is outdated and specific to one architecture.
|
|
|
|
<programlisting>ident GENERIC</programlisting>
|
|
|
|
<para>This is the identification of the kernel. Change
|
|
this to the new kernel name, such as
|
|
<literal><replaceable>MYKERNEL</replaceable></literal>.
|
|
The value in the <literal>ident</literal> string will
|
|
print when the kernel boots.</para>
|
|
|
|
<programlisting>makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols</programlisting>
|
|
|
|
<para>This option enables debugging information when passed to
|
|
&man.gcc.1;.</para>
|
|
|
|
<programlisting>options SCHED_ULE # ULE scheduler</programlisting>
|
|
|
|
<para>The default system scheduler for &os;. Keep this.</para>
|
|
|
|
<programlisting>options INET # InterNETworking</programlisting>
|
|
|
|
<para>Networking support. This is mandatory as most programs
|
|
require at least loopback networking.</para>
|
|
|
|
<programlisting>options INET6 # IPv6 communications protocols</programlisting>
|
|
|
|
<para>This enables the IPv6 communication protocols.</para>
|
|
|
|
<programlisting>options FFS # Berkeley Fast Filesystem</programlisting>
|
|
|
|
<para>This is the basic hard drive file system. Leave it in if
|
|
the system boots from the hard disk.</para>
|
|
|
|
<programlisting>options SOFTUPDATES # Enable FFS Soft Updates support</programlisting>
|
|
|
|
<para>This option enables Soft Updates in the kernel which helps
|
|
to speed up write access on the disks. Even when this
|
|
functionality is provided by the kernel, it must be turned on
|
|
for specific disks. Review the output of &man.mount.8; to
|
|
determine if Soft Updates is enabled. If the
|
|
<literal>soft-updates</literal> option is not in the output, it
|
|
can be activated using &man.tunefs.8; for existing file systems
|
|
or &man.newfs.8; for new file systems.</para>
|
|
|
|
<programlisting>options UFS_ACL # Support for access control lists</programlisting>
|
|
|
|
<para>This option enables kernel support for access control lists
|
|
(<acronym>ACL</acronym>s). This relies on the use of extended
|
|
attributes and <acronym>UFS2</acronym>, and the feature is
|
|
described in detail in <xref linkend="fs-acl"/>.
|
|
<acronym>ACL</acronym>s are enabled by default and should not be
|
|
disabled in the kernel if they have been used previously on a
|
|
file system, as this will remove the ACLs, changing the way
|
|
files are protected in unpredictable ways.</para>
|
|
|
|
<programlisting>options UFS_DIRHASH # Improve performance on big directories</programlisting>
|
|
|
|
<para>This option includes functionality to speed up disk
|
|
operations on large directories, at the expense of using
|
|
additional memory. Keep this for a large server or interactive
|
|
workstation, and remove it from smaller systems where memory is
|
|
at a premium and disk access speed is less important, such as a
|
|
firewall.</para>
|
|
|
|
<programlisting>options MD_ROOT # MD is a potential root device</programlisting>
|
|
|
|
<para>This option enables support for a memory backed virtual disk
|
|
used as a root device.</para>
|
|
|
|
<indexterm>
|
|
<primary>kernel options</primary>
|
|
<secondary>NFS</secondary>
|
|
</indexterm>
|
|
<indexterm>
|
|
<primary>kernel options</primary>
|
|
<secondary>NFS_ROOT</secondary>
|
|
</indexterm>
|
|
<programlisting>options NFSCLIENT # Network Filesystem Client
|
|
options NFSSERVER # Network Filesystem Server
|
|
options NFS_ROOT # NFS usable as /, requires NFSCLIENT</programlisting>
|
|
|
|
<para>The network file system (<acronym>NFS</acronym>). These
|
|
lines can be commented unless the system needs to mount
|
|
partitions from a <acronym>NFS</acronym> file server over
|
|
TCP/IP.</para>
|
|
|
|
<indexterm>
|
|
<primary>kernel options</primary>
|
|
<secondary>MSDOSFS</secondary>
|
|
</indexterm>
|
|
<programlisting>options MSDOSFS # MSDOS Filesystem</programlisting>
|
|
|
|
<para>The &ms-dos; file system. Unless the system needs to mount
|
|
a DOS formatted hard drive partition at boot time, comment this
|
|
out. It will be automatically loaded the first time a DOS
|
|
partition is mounted. The <package>emulators/mtools</package>
|
|
package allows access to DOS floppies without having to mount
|
|
and unmount them and does not require
|
|
<literal>MSDOSFS</literal>.</para>
|
|
|
|
<programlisting>options CD9660 # ISO 9660 Filesystem</programlisting>
|
|
|
|
<para>The ISO 9660 file system for CDROMs. Comment it out if the
|
|
system does not have a CDROM drive or only mounts data CDs
|
|
occasionally since it will be dynamically loaded the first
|
|
time a data CD is mounted. Audio CDs do not need this file
|
|
system.</para>
|
|
|
|
<programlisting>options PROCFS # Process filesystem (requires PSEUDOFS)</programlisting>
|
|
|
|
<para>The process file system. This is a <quote>pretend</quote>
|
|
file system mounted on <filename>/proc</filename> which allows
|
|
some programs to provide more information on what processes are
|
|
running. Use of <literal>PROCFS</literal> is not required under
|
|
most circumstances, as most debugging and monitoring tools have
|
|
been adapted to run without <literal>PROCFS</literal>. The
|
|
default installation will not mount this file system by
|
|
default.</para>
|
|
|
|
<programlisting>options PSEUDOFS # Pseudo-filesystem framework</programlisting>
|
|
|
|
<para>Kernels making use of <literal>PROCFS</literal> must
|
|
also include support for <literal>PSEUDOFS</literal>.</para>
|
|
|
|
<programlisting>options GEOM_PART_GPT # GUID Partition Tables.</programlisting>
|
|
|
|
<para>Adds support for <link
|
|
xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
|
|
Partition Tables</link> (<acronym>GPT</acronym>). GPT
|
|
provides the ability to have a large number of partitions per
|
|
disk, 128 in the standard configuration.</para>
|
|
|
|
<programlisting>options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!]</programlisting>
|
|
|
|
<para>Compatibility with 4.3BSD. Leave this in as some programs
|
|
will act strangely if this is commented out.</para>
|
|
|
|
<programlisting>options COMPAT_FREEBSD4 # Compatible with &os;4</programlisting>
|
|
|
|
<para>This option is required to support applications compiled on
|
|
older versions of &os; that use older system call interfaces.
|
|
It is recommended that this option be used on all &i386; systems
|
|
that may run older applications. Platforms that gained support
|
|
after &os; 4.X, such as ia64 and &sparc64;, do not require
|
|
this option.</para>
|
|
|
|
<programlisting>options COMPAT_FREEBSD5 # Compatible with &os;5</programlisting>
|
|
|
|
<para>This option is required to support applications compiled on
|
|
&os; 5.X versions that use &os; 5.X system call
|
|
interfaces.</para>
|
|
|
|
<programlisting>options COMPAT_FREEBSD6 # Compatible with &os;6</programlisting>
|
|
|
|
<para>This option is required to support applications compiled on
|
|
&os; 6.X versions that use &os; 6.X system call
|
|
interfaces.</para>
|
|
|
|
<programlisting>options COMPAT_FREEBSD7 # Compatible with &os;7</programlisting>
|
|
|
|
<para>This option is required on &os; 8 and above to support
|
|
applications compiled on &os; 7.X versions that use
|
|
&os; 7.X system call interfaces.</para>
|
|
|
|
<programlisting>options SCSI_DELAY=5000 # Delay (in ms) before probing SCSI</programlisting>
|
|
|
|
<para>This causes the kernel to pause for 5 seconds before probing
|
|
each <acronym>SCSI</acronym> device in the system. If
|
|
<acronym>SCSI</acronym> drives are not recognized, increase the
|
|
number. If the system does not have any <acronym>SCSI</acronym>
|
|
drives, this value can be ignored or decreased to speed up
|
|
booting.</para>
|
|
|
|
<programlisting>options KTRACE # ktrace(1) support</programlisting>
|
|
|
|
<para>This enables kernel process tracing, which is useful in
|
|
debugging.</para>
|
|
|
|
<programlisting>options SYSVSHM # SYSV-style shared memory</programlisting>
|
|
|
|
<para>This option provides for System V shared memory. The
|
|
most common use of this is the XSHM extension in X, which many
|
|
graphics-intensive programs will automatically take advantage of
|
|
for extra speed. If <application>Xorg</application> is
|
|
installed, include this.</para>
|
|
|
|
<programlisting>options SYSVMSG # SYSV-style message queues</programlisting>
|
|
|
|
<para>Support for System V messages. This option only adds
|
|
a few hundred bytes to the kernel.</para>
|
|
|
|
<programlisting>options SYSVSEM # SYSV-style semaphores</programlisting>
|
|
|
|
<para>Support for System V semaphores. Less commonly used,
|
|
but only adds a few hundred bytes to the kernel.</para>
|
|
|
|
<note>
|
|
<para>Using <option>-p</option> with &man.ipcs.1; will list any
|
|
processes using each of these System V facilities.</para>
|
|
</note>
|
|
|
|
<programlisting>options _KPOSIX_PRIORITY_SCHEDULING # POSIX P1003_1B real-time extensions</programlisting>
|
|
|
|
<para>Real-time extensions added in the 1993 &posix;. Certain
|
|
applications in the Ports Collection use these.</para>
|
|
|
|
<programlisting>options KBD_INSTALL_CDEV # install a CDEV entry in /dev</programlisting>
|
|
|
|
<para>This option is required to allow the creation of keyboard
|
|
device nodes in <filename>/dev</filename>.</para>
|
|
|
|
<indexterm>
|
|
<primary>kernel options</primary>
|
|
<secondary>SMP</secondary>
|
|
</indexterm>
|
|
<programlisting>device apic # I/O APIC</programlisting>
|
|
|
|
<para>This device enables the use of the I/O APIC for interrupt
|
|
delivery. It can be used in both uni-processor and SMP kernels,
|
|
but is required for SMP kernels. Add <literal>options
|
|
SMP</literal> to include support for multiple
|
|
processors.</para>
|
|
|
|
<note>
|
|
<para>This device exists only on the &i386; architecture and
|
|
this configuration line should not be used on other
|
|
architectures.</para>
|
|
</note>
|
|
|
|
<programlisting>device eisa</programlisting>
|
|
|
|
<para>Include this for systems with an EISA motherboard. This
|
|
enables auto-detection and configuration support for all devices
|
|
on the EISA bus.</para>
|
|
|
|
<programlisting>device pci</programlisting>
|
|
|
|
<para>Include this for systems with a PCI motherboard. This
|
|
enables auto-detection of PCI cards and gatewaying from the PCI
|
|
to ISA bus.</para>
|
|
|
|
<programlisting># Floppy drives
|
|
device fdc</programlisting>
|
|
|
|
<para>This is the floppy drive controller.</para>
|
|
|
|
<programlisting># ATA and ATAPI devices
|
|
device ata</programlisting>
|
|
|
|
<para>This driver supports all ATA and ATAPI devices. Only
|
|
one <literal>device ata</literal> line is needed for the kernel
|
|
to detect all PCI ATA/ATAPI devices on modern machines.</para>
|
|
|
|
<programlisting>device atadisk # ATA disk drives</programlisting>
|
|
|
|
<para>This is needed along with <literal>device ata</literal> for
|
|
ATA disk drives.</para>
|
|
|
|
<programlisting>device ataraid # ATA RAID drives</programlisting>
|
|
|
|
<para>This is needed along with <literal>device ata</literal>
|
|
for ATA RAID drives.</para>
|
|
|
|
<programlisting><anchor xml:id="kernelconfig-atapi"/>
|
|
device atapicd # ATAPI CDROM drives</programlisting>
|
|
|
|
<para>This is needed along with <literal>device ata</literal>
|
|
for ATAPI CDROM drives.</para>
|
|
|
|
<programlisting>device atapifd # ATAPI floppy drives</programlisting>
|
|
|
|
<para>This is needed along with <literal>device ata</literal> for
|
|
ATAPI floppy drives.</para>
|
|
|
|
<programlisting>device atapist # ATAPI tape drives</programlisting>
|
|
|
|
<para>This is needed along with <literal>device ata</literal> for
|
|
ATAPI tape drives.</para>
|
|
|
|
<programlisting>options ATA_STATIC_ID # Static device numbering</programlisting>
|
|
|
|
<para>This makes the controller number static. Without this, the
|
|
device numbers are dynamically allocated.</para>
|
|
|
|
<programlisting># SCSI Controllers
|
|
device ahb # EISA AHA1742 family
|
|
device ahc # AHA2940 and onboard AIC7xxx devices
|
|
options AHC_REG_PRETTY_PRINT # Print register bitfields in debug
|
|
# output. Adds ~128k to driver.
|
|
device ahd # AHA39320/29320 and onboard AIC79xx devices
|
|
options AHD_REG_PRETTY_PRINT # Print register bitfields in debug
|
|
# output. Adds ~215k to driver.
|
|
device amd # AMD 53C974 (Teckram DC-390(T))
|
|
device isp # Qlogic family
|
|
#device ispfw # Firmware for QLogic HBAs- normally a module
|
|
device mpt # LSI-Logic MPT-Fusion
|
|
#device ncr # NCR/Symbios Logic
|
|
device sym # NCR/Symbios Logic (newer chipsets + those of `ncr')
|
|
device trm # Tekram DC395U/UW/F DC315U adapters
|
|
|
|
device adv # Advansys SCSI adapters
|
|
device adw # Advansys wide SCSI adapters
|
|
device aha # Adaptec 154x SCSI adapters
|
|
device aic # Adaptec 15[012]x SCSI adapters, AIC-6[23]60.
|
|
device bt # Buslogic/Mylex MultiMaster SCSI adapters
|
|
|
|
device ncv # NCR 53C500
|
|
device nsp # Workbit Ninja SCSI-3
|
|
device stg # TMC 18C30/18C50</programlisting>
|
|
|
|
<para>In this section, comment out any SCSI controllers not on
|
|
the system. For an IDE only system, these lines can be removed.
|
|
The <literal>*_REG_PRETTY_PRINT</literal> lines are
|
|
debugging options for their respective drivers.</para>
|
|
|
|
<programlisting># SCSI peripherals
|
|
device scbus # SCSI bus (required for SCSI)
|
|
device ch # SCSI media changers
|
|
device da # Direct Access (disks)
|
|
device sa # Sequential Access (tape etc)
|
|
device cd # CD
|
|
device pass # Passthrough device (direct SCSI access)
|
|
device ses # SCSI Environmental Services (and SAF-TE)</programlisting>
|
|
|
|
<para>Comment out any SCSI peripherals not on the system. If
|
|
the system only has IDE hardware, these lines can be removed
|
|
completely.</para>
|
|
|
|
<note>
|
|
<para>The USB &man.umass.4; driver and a few other drivers use
|
|
the SCSI subsystem even though they are not real SCSI devices.
|
|
Do not remove SCSI support if any such drivers are included in
|
|
the kernel configuration.</para>
|
|
</note>
|
|
|
|
<programlisting># RAID controllers interfaced to the SCSI subsystem
|
|
device amr # AMI MegaRAID
|
|
device arcmsr # Areca SATA II RAID
|
|
device asr # DPT SmartRAID V, VI and Adaptec SCSI RAID
|
|
device ciss # Compaq Smart RAID 5*
|
|
device dpt # DPT Smartcache III, IV - See NOTES for options
|
|
device hptmv # Highpoint RocketRAID 182x
|
|
device hptrr # Highpoint RocketRAID 17xx, 22xx, 23xx, 25xx
|
|
device iir # Intel Integrated RAID
|
|
device ips # IBM (Adaptec) ServeRAID
|
|
device mly # Mylex AcceleRAID/eXtremeRAID
|
|
device twa # 3ware 9000 series PATA/SATA RAID
|
|
|
|
# RAID controllers
|
|
device aac # Adaptec FSA RAID
|
|
device aacp # SCSI passthrough for aac (requires CAM)
|
|
device ida # Compaq Smart RAID
|
|
device mfi # LSI MegaRAID SAS
|
|
device mlx # Mylex DAC960 family
|
|
device pst # Promise Supertrak SX6000
|
|
device twe # 3ware ATA RAID</programlisting>
|
|
|
|
<para>Supported RAID controllers. If the system does not have any
|
|
of these, comment them out or remove them.</para>
|
|
|
|
<programlisting># atkbdc0 controls both the keyboard and the PS/2 mouse
|
|
device atkbdc # AT keyboard controller</programlisting>
|
|
|
|
<para>The <literal>atkbdc</literal> keyboard controller provides
|
|
I/O services for the AT keyboard and PS/2 style pointing
|
|
devices. This controller is required by &man.atkbd.4; and
|
|
&man.psm.4;.</para>
|
|
|
|
<programlisting>device atkbd # AT keyboard</programlisting>
|
|
|
|
<para>The &man.atkbd.4; driver, together with the &man.atkbdc.4;
|
|
controller, provides access to the AT 84 keyboard or the AT
|
|
enhanced keyboard which is connected to the AT keyboard
|
|
controller.</para>
|
|
|
|
<programlisting>device psm # PS/2 mouse</programlisting>
|
|
|
|
<para>Use this device if the mouse plugs into the PS/2 mouse
|
|
port.</para>
|
|
|
|
<programlisting>device kbdmux # keyboard multiplexer</programlisting>
|
|
|
|
<para>Basic support for keyboard multiplexing. If the system
|
|
does not use more than one keyboard, this line can be safely
|
|
removed.</para>
|
|
|
|
<programlisting>device vga # VGA video card driver</programlisting>
|
|
|
|
<para>The &man.vga.4; video card driver.</para>
|
|
|
|
<programlisting>device splash # Splash screen and screen saver support</programlisting>
|
|
|
|
<para>Required by the boot splash screen and screen savers.</para>
|
|
|
|
<programlisting># syscons is the default console driver, resembling a SCO console
|
|
device sc</programlisting>
|
|
|
|
<para>&man.sc.4; is the default console driver and resembles a SCO
|
|
console. Since most full-screen programs access the console
|
|
through a terminal database library like
|
|
<filename>termcap</filename>, it should not matter whether
|
|
this or <literal>vt</literal>, the
|
|
<literal>VT220</literal> compatible console driver, is used.
|
|
When a user logs in, the <envar>TERM</envar> variable can be set
|
|
to <literal>scoansi</literal> if full-screen programs have
|
|
trouble running under this console.</para>
|
|
|
|
<programlisting># Enable this for the pcvt (VT220 compatible) console driver
|
|
#device vt
|
|
#options XSERVER # support for X server on a vt console
|
|
#options FAT_CURSOR # start with block cursor</programlisting>
|
|
|
|
<para>This is a VT220-compatible console driver, backward
|
|
compatible to VT100/102. It works well on some laptops which
|
|
have hardware incompatibilities with <literal>sc</literal>.
|
|
Users may need to set <envar>TERM</envar> to
|
|
<literal>vt100</literal> or <literal>vt220</literal> after
|
|
login. This driver is useful when connecting to a large number
|
|
of different machines over the network, where
|
|
<filename>termcap</filename> or <filename>terminfo</filename>
|
|
entries for the <literal>sc</literal> device are not
|
|
available as <literal>vt100</literal> should be available
|
|
on virtually any platform.</para>
|
|
|
|
<programlisting>device agp</programlisting>
|
|
|
|
<para>Include this if the system has an AGP card. This will
|
|
enable support for AGP and AGP GART for boards which have these
|
|
features.</para>
|
|
|
|
<programlisting># Add suspend/resume support for the i8254.
|
|
device pmtimer</programlisting>
|
|
|
|
<para>Timer device driver for power management events, such as
|
|
APM and ACPI.</para>
|
|
|
|
<programlisting># PCCARD (PCMCIA) support
|
|
# PCMCIA and cardbus bridge support
|
|
device cbb # cardbus (yenta) bridge
|
|
device pccard # PC Card (16-bit) bus
|
|
device cardbus # CardBus (32-bit) bus</programlisting>
|
|
|
|
<para>PCMCIA support. Keep this on laptop systems.</para>
|
|
|
|
<programlisting># Serial (COM) ports
|
|
device sio # 8250, 16[45]50 based serial ports</programlisting>
|
|
|
|
<para>These are the serial ports referred to as
|
|
<filename>COM</filename> ports in &windows;.</para>
|
|
|
|
<note>
|
|
<para>If the system has an internal modem on
|
|
<filename>COM4</filename> and a serial port at
|
|
<filename>COM2</filename>, change the IRQ of the modem to
|
|
2. For a multiport serial card, refer to &man.sio.4; for more
|
|
information on the proper values to add to
|
|
<filename>/boot/device.hints</filename>. Some video cards,
|
|
notably those based on S3 chips, use I/O addresses in the
|
|
form of <literal>0x*2e8</literal>. Since many cheap serial
|
|
cards do not fully decode the 16-bit I/O address space, they
|
|
clash with these cards, making the
|
|
<filename>COM4</filename> port practically
|
|
unavailable.</para>
|
|
|
|
<para>Each serial port is required to have a unique IRQ and the
|
|
default IRQs for <filename>COM3</filename> and
|
|
<filename>COM4</filename> cannot be used. The exception
|
|
is multiport cards where shared interrupts are
|
|
supported.</para>
|
|
</note>
|
|
|
|
<programlisting># Parallel port
|
|
device ppc</programlisting>
|
|
|
|
<para>This is the ISA bus parallel port interface.</para>
|
|
|
|
<programlisting>device ppbus # Parallel port bus (required)</programlisting>
|
|
|
|
<para>Provides support for the parallel port bus.</para>
|
|
|
|
<programlisting>device lpt # Printer</programlisting>
|
|
|
|
<para>Adds support for parallel port printers.</para>
|
|
|
|
<note>
|
|
<para>All three of the above are required to enable parallel
|
|
printer support.</para>
|
|
</note>
|
|
|
|
<programlisting>device ppi # Parallel port interface device</programlisting>
|
|
|
|
<para>The general-purpose I/O (<quote>geek port</quote>) +
|
|
IEEE1284 I/O.</para>
|
|
|
|
<programlisting>#device vpo # Requires scbus and da</programlisting>
|
|
|
|
<indexterm><primary>zip drive</primary></indexterm>
|
|
<para>This is for an Iomega Zip drive. It requires
|
|
<literal>scbus</literal> and <literal>da</literal> support.
|
|
Best performance is achieved with ports in EPP 1.9 mode.</para>
|
|
|
|
<programlisting>#device puc</programlisting>
|
|
|
|
<para>Uncomment this device if the system has a
|
|
<quote>dumb</quote> serial or parallel PCI card that is
|
|
supported by the &man.puc.4; glue driver.</para>
|
|
|
|
<programlisting># PCI Ethernet NICs.
|
|
device de # DEC/Intel DC21x4x (<quote>Tulip</quote>)
|
|
device em # Intel PRO/1000 adapter Gigabit Ethernet Card
|
|
device ixgb # Intel PRO/10GbE Ethernet Card
|
|
device txp # 3Com 3cR990 (<quote>Typhoon</quote>)
|
|
device vx # 3Com 3c590, 3c595 (<quote>Vortex</quote>)</programlisting>
|
|
|
|
<para>Various PCI network card drivers. Comment out or remove
|
|
any of these which are not present in the system.</para>
|
|
|
|
<programlisting># PCI Ethernet NICs that use the common MII bus controller code.
|
|
# NOTE: Be sure to keep the 'device miibus' line in order to use these NICs!
|
|
device miibus # MII bus support</programlisting>
|
|
|
|
<para>MII bus support is required for some PCI 10/100 Ethernet
|
|
NICs, namely those which use MII-compliant transceivers or
|
|
implement transceiver control interfaces that operate like an
|
|
MII. Adding <literal>device miibus</literal> to the kernel
|
|
config pulls in support for the generic miibus API and all of
|
|
the PHY drivers, including a generic one for PHYs that are not
|
|
specifically handled by an individual driver.</para>
|
|
|
|
<programlisting>device bce # Broadcom BCM5706/BCM5708 Gigabit Ethernet
|
|
device bfe # Broadcom BCM440x 10/100 Ethernet
|
|
device bge # Broadcom BCM570xx Gigabit Ethernet
|
|
device dc # DEC/Intel 21143 and various workalikes
|
|
device fxp # Intel EtherExpress PRO/100B (82557, 82558)
|
|
device lge # Level 1 LXT1001 gigabit ethernet
|
|
device msk # Marvell/SysKonnect Yukon II Gigabit Ethernet
|
|
device nge # NatSemi DP83820 gigabit ethernet
|
|
device nve # nVidia nForce MCP on-board Ethernet Networking
|
|
device pcn # AMD Am79C97x PCI 10/100 (precedence over 'lnc')
|
|
device re # RealTek 8139C+/8169/8169S/8110S
|
|
device rl # RealTek 8129/8139
|
|
device sf # Adaptec AIC-6915 (<quote>Starfire</quote>)
|
|
device sis # Silicon Integrated Systems SiS 900/SiS 7016
|
|
device sk # SysKonnect SK-984x & SK-982x gigabit Ethernet
|
|
device ste # Sundance ST201 (D-Link DFE-550TX)
|
|
device stge # Sundance/Tamarack TC9021 gigabit Ethernet
|
|
device ti # Alteon Networks Tigon I/II gigabit Ethernet
|
|
device tl # Texas Instruments ThunderLAN
|
|
device tx # SMC EtherPower II (83c170 <quote>EPIC</quote>)
|
|
device vge # VIA VT612x gigabit ethernet
|
|
device vr # VIA Rhine, Rhine II
|
|
device wb # Winbond W89C840F
|
|
device xl # 3Com 3c90x (<quote>Boomerang</quote>, <quote>Cyclone</quote>)</programlisting>
|
|
|
|
<para>Drivers that use the MII bus controller code.</para>
|
|
|
|
<programlisting># ISA Ethernet NICs. pccard NICs included.
|
|
device cs # Crystal Semiconductor CS89x0 NIC
|
|
# 'device ed' requires 'device miibus'
|
|
device ed # NE[12]000, SMC Ultra, 3c503, DS8390 cards
|
|
device ex # Intel EtherExpress Pro/10 and Pro/10+
|
|
device ep # Etherlink III based cards
|
|
device fe # Fujitsu MB8696x based cards
|
|
device ie # EtherExpress 8/16, 3C507, StarLAN 10 etc.
|
|
device lnc # NE2100, NE32-VL Lance Ethernet cards
|
|
device sn # SMC's 9000 series of Ethernet chips
|
|
device xe # Xircom pccard Ethernet
|
|
|
|
# ISA devices that use the old ISA shims
|
|
#device le</programlisting>
|
|
|
|
<para>ISA Ethernet drivers. See
|
|
<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename>
|
|
for details of which cards are supported by which driver.</para>
|
|
|
|
<programlisting># Wireless NIC cards
|
|
device wlan # 802.11 support</programlisting>
|
|
|
|
<para>Generic 802.11 support. This line is required for wireless
|
|
networking.</para>
|
|
|
|
<programlisting>device wlan_wep # 802.11 WEP support
|
|
device wlan_ccmp # 802.11 CCMP support
|
|
device wlan_tkip # 802.11 TKIP support</programlisting>
|
|
|
|
<para>Crypto support for 802.11 devices. These lines are needed
|
|
on systems which use encryption and 802.11i security
|
|
protocols.</para>
|
|
|
|
<programlisting>device an # Aironet 4500/4800 802.11 wireless NICs.
|
|
device ath # Atheros pci/cardbus NIC's
|
|
device ath_hal # Atheros HAL (Hardware Access Layer)
|
|
device ath_rate_sample # SampleRate tx rate control for ath
|
|
device awi # BayStack 660 and others
|
|
device ral # Ralink Technology RT2500 wireless NICs.
|
|
device wi # WaveLAN/Intersil/Symbol 802.11 wireless NICs.
|
|
#device wl # Older non 802.11 Wavelan wireless NIC.</programlisting>
|
|
|
|
<para>Support for various wireless cards.</para>
|
|
|
|
<programlisting># Pseudo devices
|
|
device loop # Network loopback</programlisting>
|
|
|
|
<para>This is the generic loopback device for TCP/IP. This is
|
|
<emphasis>mandatory</emphasis>.</para>
|
|
|
|
<programlisting>device random # Entropy device</programlisting>
|
|
|
|
<para>Cryptographically secure random number generator.</para>
|
|
|
|
<programlisting>device ether # Ethernet support</programlisting>
|
|
|
|
<para><literal>ether</literal> is only needed if the system has
|
|
an Ethernet card. It includes generic Ethernet protocol
|
|
code.</para>
|
|
|
|
<programlisting>device sl # Kernel SLIP</programlisting>
|
|
|
|
<para><literal>sl</literal> provides SLIP support. This has been
|
|
almost entirely supplanted by PPP, which is easier to set up,
|
|
better suited for modem-to-modem connection, and more
|
|
powerful.</para>
|
|
|
|
<programlisting>device ppp # Kernel PPP</programlisting>
|
|
|
|
<para>This is for kernel PPP support for dial-up connections.
|
|
There is also a version of PPP implemented as a userland
|
|
application that uses <literal>tun</literal> and offers more
|
|
flexibility and features such as demand dialing.</para>
|
|
|
|
<programlisting>device tun # Packet tunnel.</programlisting>
|
|
|
|
<para>This is used by the userland PPP software. See the <link
|
|
linkend="userppp">PPP</link> section of the Handbook for more
|
|
information.</para>
|
|
|
|
<programlisting><anchor xml:id="kernelconfig-ptys"/>
|
|
device pty # Pseudo-ttys (telnet etc)</programlisting>
|
|
|
|
<para>This is a <quote>pseudo-terminal</quote> or simulated
|
|
login port. It is used by incoming <command>telnet</command>
|
|
and <command>rlogin</command> sessions,
|
|
<application>xterm</application>, and some other applications
|
|
such as <application>Emacs</application>.</para>
|
|
|
|
<programlisting>device md # Memory <quote>disks</quote></programlisting>
|
|
|
|
<para>Memory disk pseudo-devices.</para>
|
|
|
|
<programlisting>device gif # IPv6 and IPv4 tunneling</programlisting>
|
|
|
|
<para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6
|
|
tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6
|
|
tunneling. The <literal>gif</literal> device is
|
|
<quote>auto-cloning</quote>, and will create device nodes as
|
|
needed.</para>
|
|
|
|
<programlisting>device faith # IPv6-to-IPv4 relaying (translation)</programlisting>
|
|
|
|
<para>This pseudo-device captures packets that are sent to it and
|
|
diverts them to the IPv4/IPv6 translation daemon.</para>
|
|
|
|
<programlisting># The `bpf' device enables the Berkeley Packet Filter.
|
|
# Be aware of the administrative consequences of enabling this!
|
|
# Note that 'bpf' is required for DHCP.
|
|
device bpf # Berkeley packet filter</programlisting>
|
|
|
|
<para>The Berkeley Packet Filter pseudo-device allows network
|
|
interfaces to be placed in promiscuous mode, capturing every
|
|
packet on a broadcast network such as an Ethernet network.
|
|
These packets can be captured to disk and or examined using
|
|
&man.tcpdump.1;.</para>
|
|
|
|
<note>
|
|
<para>The &man.bpf.4; device is also used by &man.dhclient.8;.
|
|
If DHCP is used, leave this uncommented.</para>
|
|
</note>
|
|
|
|
<programlisting># USB support
|
|
device uhci # UHCI PCI->USB interface
|
|
device ohci # OHCI PCI->USB interface
|
|
device ehci # EHCI PCI->USB interface (USB 2.0)
|
|
device usb # USB Bus (required)
|
|
#device udbp # USB Double Bulk Pipe devices
|
|
device ugen # Generic
|
|
device uhid # <quote>Human Interface Devices</quote>
|
|
device ukbd # Keyboard
|
|
device ulpt # Printer
|
|
device umass # Disks/Mass storage - Requires scbus and da
|
|
device ums # Mouse
|
|
device ural # Ralink Technology RT2500USB wireless NICs
|
|
device urio # Diamond Rio 500 MP3 player
|
|
device uscanner # Scanners
|
|
# USB Ethernet, requires mii
|
|
device aue # ADMtek USB Ethernet
|
|
device axe # ASIX Electronics USB Ethernet
|
|
device cdce # Generic USB over Ethernet
|
|
device cue # CATC USB Ethernet
|
|
device kue # Kawasaki LSI USB Ethernet
|
|
device rue # RealTek RTL8150 USB Ethernet</programlisting>
|
|
|
|
<para>Support for various USB devices.</para>
|
|
|
|
<programlisting># FireWire support
|
|
device firewire # FireWire bus code
|
|
device sbp # SCSI over FireWire (Requires scbus and da)
|
|
device fwe # Ethernet over FireWire (non-standard!)</programlisting>
|
|
|
|
<para>Support for various Firewire devices.</para>
|
|
|
|
<para>For more information and additional devices supported by
|
|
&os;, see
|
|
<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename>.</para>
|
|
-->
|
|
|
|
<!--
|
|
This section refers to ancient hardware.
|
|
<sect2>
|
|
<title>Large Memory Configurations
|
|
(<acronym>PAE</acronym>)</title>
|
|
|
|
<indexterm>
|
|
<primary>Physical Address Extensions
|
|
(<acronym>PAE</acronym>)</primary>
|
|
<secondary>large memory</secondary>
|
|
</indexterm>
|
|
|
|
<para>Large memory configuration machines require access to
|
|
more than the 4 gigabyte limit on User+Kernel Virtual
|
|
Address (<acronym>KVA</acronym>) space. Due to this
|
|
limitation, Intel added support for 36-bit physical address
|
|
space access in the &pentium; Pro and later line of
|
|
CPUs.</para>
|
|
|
|
<para>The Physical Address Extension (<acronym>PAE</acronym>)
|
|
capability of the &intel; &pentium; Pro and later CPUs allows
|
|
memory configurations of up to 64 gigabytes. &os; provides
|
|
support for this capability via the <option>PAE</option>
|
|
kernel configuration option, available in all current release
|
|
versions of &os;. Due to the limitations of the Intel memory
|
|
architecture, no distinction is made for memory above or below
|
|
4 gigabytes. Memory allocated above 4 gigabytes is simply
|
|
added to the pool of available memory.</para>
|
|
|
|
<para>To enable <acronym>PAE</acronym> support in the kernel,
|
|
add the following line to the kernel configuration
|
|
file:</para>
|
|
|
|
<programlisting>options PAE</programlisting>
|
|
|
|
<note>
|
|
<para>The <acronym>PAE</acronym> support in &os; is only
|
|
available for &intel; IA-32 processors. It should also be
|
|
noted that the <acronym>PAE</acronym> support in &os; has
|
|
not received wide testing, and should be considered beta
|
|
quality compared to other stable features of &os;.</para>
|
|
</note>
|
|
|
|
<para><acronym>PAE</acronym> support in &os; has a few
|
|
limitations:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A process is not able to access more than 4
|
|
gigabytes of virtual memory space.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Device drivers that do not use the &man.bus.dma.9;
|
|
interface will cause data corruption in a
|
|
<acronym>PAE</acronym> enabled kernel and are not
|
|
recommended for use. For this reason, a
|
|
<filename>PAE</filename> kernel configuration file is
|
|
provided in &os; which excludes all drivers not known to
|
|
work in a <acronym>PAE</acronym> enabled kernel.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Some system tunables determine memory resource usage
|
|
by the amount of available physical memory. Such
|
|
tunables can unnecessarily over-allocate due to the
|
|
large memory nature of a <acronym>PAE</acronym> system.
|
|
One such example is the
|
|
<varname>kern.maxvnodes</varname> sysctl, which controls
|
|
the maximum number of vnodes allowed in the kernel. It
|
|
is advised to adjust this and other such tunables to a
|
|
reasonable value.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>It might be necessary to increase the kernel virtual
|
|
address (<acronym>KVA</acronym>) space or to reduce the
|
|
amount of specific kernel resource that is heavily used
|
|
in order to avoid <acronym>KVA</acronym> exhaustion.
|
|
The <option>KVA_PAGES</option> kernel option can be used
|
|
for increasing the <acronym>KVA</acronym> space.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>For performance and stability concerns, it is advised to
|
|
consult &man.tuning.7;. &man.pae.4; contains up-to-date
|
|
information on &os;'s <acronym>PAE</acronym> support.</para>
|
|
</sect2>
|
|
-->
|
|
</sect1>
|
|
|
|
<sect1 xml:id="kernelconfig-building">
|
|
<title>Building and Installing a Custom Kernel</title>
|
|
|
|
<para>Once the edits to the custom configuration file have been
|
|
saved, the source code for the kernel can be compiled using the
|
|
following steps:</para>
|
|
|
|
<procedure>
|
|
<title>Building a Kernel</title>
|
|
|
|
<indexterm>
|
|
<primary>kernel</primary>
|
|
<secondary>building / installing</secondary>
|
|
</indexterm>
|
|
|
|
<step>
|
|
<para>Change to this directory:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Compile the new kernel by specifying the name of the
|
|
custom kernel configuration file:</para>
|
|
|
|
<screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Install the new kernel associated with the specified
|
|
kernel configuration file. This command will copy the new
|
|
kernel to <filename>/boot/kernel/kernel</filename> and save
|
|
the old kernel to
|
|
<filename>/boot/kernel.old/kernel</filename>:</para>
|
|
|
|
<screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Shutdown the system and reboot into the new kernel.
|
|
If something goes wrong, refer to <xref
|
|
linkend="kernelconfig-noboot"/>.</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<para>By default, when a custom kernel is compiled, all kernel
|
|
modules are rebuilt. To update a kernel faster or to build
|
|
only custom modules, edit <filename>/etc/make.conf</filename>
|
|
before starting to build the kernel.</para>
|
|
|
|
<para>For example, this variable specifies the list of modules to
|
|
build instead of using the default of building all
|
|
modules:</para>
|
|
|
|
<programlisting>MODULES_OVERRIDE = linux acpi</programlisting>
|
|
|
|
<para>Alternately, this variable lists which modules to exclude
|
|
from the build process:</para>
|
|
|
|
<programlisting>WITHOUT_MODULES = linux acpi sound</programlisting>
|
|
|
|
<para>Additional variables are available. Refer to
|
|
&man.make.conf.5; for details.</para>
|
|
|
|
<indexterm>
|
|
<primary><filename>/boot/kernel.old</filename></primary>
|
|
</indexterm>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="kernelconfig-trouble">
|
|
<title>If Something Goes Wrong</title>
|
|
|
|
<para>There are four categories of trouble that can occur when
|
|
building a custom kernel:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><command>config</command> fails</term>
|
|
|
|
<listitem>
|
|
<para>If <command>config</command> fails, it will print the
|
|
line number that is incorrect. As an example, for the
|
|
following message, make sure that line 17 is typed
|
|
correctly by comparing it to <filename>GENERIC</filename>
|
|
or <filename>NOTES</filename>:</para>
|
|
|
|
<screen>config: line 17: syntax error</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>make</command> fails</term>
|
|
|
|
<listitem>
|
|
<para>If <command>make</command> fails, it is usually due to
|
|
an error in the kernel configuration file which is not
|
|
severe enough for <command>config</command> to catch.
|
|
Review the configuration, and if the problem is not
|
|
apparent, send an email to the &a.questions; which
|
|
contains the kernel configuration file.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="kernelconfig-noboot">
|
|
<term>The kernel does not boot</term>
|
|
|
|
<listitem>
|
|
<para>If the new kernel does not boot or fails to recognize
|
|
devices, do not panic! Fortunately, &os; has an excellent
|
|
mechanism for recovering from incompatible kernels.
|
|
Simply choose the kernel to boot from at the &os; boot
|
|
loader. This can be accessed when the system boot menu
|
|
appears by selecting the <quote>Escape to a loader
|
|
prompt</quote> option. At the prompt, type
|
|
<command>boot
|
|
<replaceable>kernel.old</replaceable></command>, or the
|
|
name of any other kernel that is known to boot
|
|
properly.</para>
|
|
|
|
<para>After booting with a good kernel, check over the
|
|
configuration file and try to build it again. One helpful
|
|
resource is <filename>/var/log/messages</filename> which
|
|
records the kernel messages from every successful boot.
|
|
Also, &man.dmesg.8; will print the kernel messages from
|
|
the current boot.</para>
|
|
|
|
<note>
|
|
<para>When troubleshooting a kernel, make sure to keep
|
|
a copy of <filename>GENERIC</filename>, or some other
|
|
kernel that is known to work, as a different name that
|
|
will not get erased on the next build. This is
|
|
important because every time a new kernel is installed,
|
|
<filename>kernel.old</filename> is overwritten with the
|
|
last installed kernel, which may or may not be bootable.
|
|
As soon as possible, move the working kernel by renaming
|
|
the directory containing the good kernel:</para>
|
|
|
|
<screen>&prompt.root; <userinput>mv /boot/kernel <replaceable>/boot/kernel.bad</replaceable></userinput>
|
|
&prompt.root; <userinput>mv /boot/<replaceable>kernel.good</replaceable> /boot/kernel</userinput></screen>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>The kernel works, but &man.ps.1; does not</term>
|
|
|
|
<listitem>
|
|
<para>If the kernel version differs from the one that the
|
|
system utilities have been built with, for example, a
|
|
kernel built from -CURRENT sources is installed on a
|
|
-RELEASE system, many system status commands like
|
|
&man.ps.1; and &man.vmstat.8; will not work. To fix this,
|
|
<link linkend="makeworld">recompile and install a
|
|
world</link> built with the same version of the source
|
|
tree as the kernel. It is never a good idea to use a
|
|
different version of the kernel than the rest of the
|
|
operating system.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
</chapter>
|