This patch does the following:
- comments author names - incorporates "9.4. Kernel Drivers, Subsystems, and Modules" into "9.2. Why Build a Custom Kernel?" - fixes reference to 9.4 in bsdinstall chapter - puts the configuration file section before the building the kernel section - makes it clearer how to get src and cp the needed config file - general wordsmithing to make the first half of this chapter less confusing Approved by: gjb (mentor)
This commit is contained in:
Dru Lavigne
parent
0211200603
commit
c41442ae34
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=42827
2 changed files with 261 additions and 357 deletions
|
|
@ -936,7 +936,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen>
|
|||
<para>Check the probe results carefully to make sure that &os;
|
||||
found all the devices you expected. If a device was not
|
||||
found, then it will not be listed. <link
|
||||
linkend="kernelconfig-modules">Kernel modules</link> allows
|
||||
linkend="kernelconfig-custom-kernel">Kernel modules</link> allows
|
||||
you to add in support for devices which are not in the
|
||||
<filename>GENERIC</filename> kernel.</para>
|
||||
|
||||
|
|
|
|||
|
|
@ -7,22 +7,20 @@
|
|||
|
||||
<chapter id="kernelconfig">
|
||||
<chapterinfo>
|
||||
<authorgroup>
|
||||
<!-- <authorgroup>
|
||||
<author>
|
||||
<firstname>Jim</firstname>
|
||||
<surname>Mock</surname>
|
||||
<contrib>Updated and restructured by </contrib>
|
||||
<!-- Mar 2000 -->
|
||||
<contrib>Updated and restructured in Mar 2000 by </contrib>
|
||||
</author>
|
||||
</authorgroup>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Jake</firstname>
|
||||
<surname>Hamby</surname>
|
||||
<contrib>Originally contributed by </contrib>
|
||||
<!-- 6 Oct 1995 -->
|
||||
<contrib>Originally contributed 6 Oct 1995 by </contrib>
|
||||
</author>
|
||||
</authorgroup>
|
||||
</authorgroup>-->
|
||||
</chapterinfo>
|
||||
|
||||
<title>Configuring the FreeBSD Kernel</title>
|
||||
|
|
@ -48,6 +46,10 @@
|
|||
<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>
|
||||
|
|
@ -73,10 +75,10 @@
|
|||
<sect1 id="kernelconfig-custom-kernel">
|
||||
<title>Why Build a Custom Kernel?</title>
|
||||
|
||||
<para>Traditionally, &os; used a <quote>monolithic</quote> kernel.
|
||||
<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 a new kernel, and then reboot into the new
|
||||
to compile and then reboot into a new
|
||||
kernel.</para>
|
||||
|
||||
<para>Today, most of the functionality in the &os; kernel is
|
||||
|
|
@ -87,10 +89,10 @@
|
|||
a modular kernel.</para>
|
||||
|
||||
<para>Occasionally, it is still necessary to perform static kernel
|
||||
configuration. This may be because the functionality is so tied
|
||||
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
|
||||
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
|
||||
|
|
@ -120,99 +122,11 @@
|
|||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Additional hardware support. A custom kernel can add in
|
||||
<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>
|
||||
</sect1>
|
||||
|
||||
<sect1 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 venturing into kernel configuration, it would be
|
||||
wise to get an inventory of the machine's hardware. In cases
|
||||
where &os; is not the primary operating system, the inventory
|
||||
list can be created by viewing the current operating system
|
||||
configuration. 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 will display a
|
||||
screen where <application>Device Manager</application> may
|
||||
be accessed.</para>
|
||||
</note>
|
||||
|
||||
<para>If another operating system does not exist on the machine,
|
||||
the administrator must find this information out manually. One
|
||||
method is using &man.dmesg.8; and &man.man.1;. Most device
|
||||
drivers on &os; have a manual page, listing supported hardware.
|
||||
During the boot probe, found hardware will be listed. For
|
||||
example, the following lines indicate that the &man.psm.4;
|
||||
driver found a mouse:</para>
|
||||
|
||||
<programlisting>psm0: <PS/2 Mouse> irq 12 on atkbdc0
|
||||
psm0: [GIANT-LOCKED]
|
||||
psm0: [ITHREAD]
|
||||
psm0: model Generic PS/2 mouse, device ID 0</programlisting>
|
||||
|
||||
<para>This driver will need to be included in the custom kernel
|
||||
configuration file or loaded using &man.loader.conf.5;.</para>
|
||||
|
||||
<para>On occasion, the data from <command>dmesg</command> will
|
||||
only show system messages instead of the boot probe output. In
|
||||
these situations, the output may be obtained by reading
|
||||
<filename>/var/run/dmesg.boot</filename>.</para>
|
||||
|
||||
<para>Another method for finding hardware is to use
|
||||
&man.pciconf.8; which provides more verbose output. For
|
||||
example:</para>
|
||||
|
||||
<programlisting>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</programlisting>
|
||||
|
||||
<para>This output, obtained by using
|
||||
<command>pciconf <option>-lv</option></command>, shows that the
|
||||
<devicename>ath</devicename> driver located a wireless Ethernet
|
||||
device. Type <command>man
|
||||
<replaceable>ath</replaceable></command> to read
|
||||
&man.ath.4;.</para>
|
||||
|
||||
<para>The <option>-k</option> flag, when passed to &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; man -k <replaceable>Atheros</replaceable></screen>
|
||||
|
||||
<programlisting>ath(4) - Atheros IEEE 802.11 wireless network driver
|
||||
ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
|
||||
|
||||
<para>Armed with a hardware inventory list, the process of
|
||||
building a custom kernel should appear less daunting.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kernelconfig-modules">
|
||||
<title>Kernel Drivers, Subsystems, and Modules</title>
|
||||
|
||||
<indexterm>
|
||||
<primary>kernel</primary>
|
||||
<secondary>drivers / modules / subsystems</secondary>
|
||||
</indexterm>
|
||||
|
||||
<para>Before building a custom kernel, consider the reason for
|
||||
doing so. If there is a need for specific hardware support,
|
||||
|
|
@ -221,7 +135,7 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
|
|||
<para>Kernel modules exist in <filename
|
||||
class="directory">/boot/kernel</filename> and may be
|
||||
dynamically loaded into the running kernel using
|
||||
&man.kldload.8;. Most, if not all kernel drivers have a
|
||||
&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>
|
||||
|
|
@ -232,223 +146,164 @@ following line in &man.loader.conf.5;:
|
|||
if_ath_load="YES"</programlisting>
|
||||
|
||||
<para>Adding <literal>if_ath_load="YES"</literal> to
|
||||
<filename>/boot/loader.conf</filename> will enable loading this
|
||||
<filename>/boot/loader.conf</filename> will load this
|
||||
module dynamically at boot time.</para>
|
||||
|
||||
<para>In some cases, there is no associated module. This is
|
||||
mostly true for certain subsystems. One way to tell if a driver
|
||||
is available is to check for the module itself.</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 some cases, there is no associated module in <filename
|
||||
class="directory">/boot/kernel</filename>. This is
|
||||
mostly true for certain subsystems.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kernelconfig-building">
|
||||
<title>Building and Installing a Custom Kernel</title>
|
||||
<sect1 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>
|
||||
|
||||
<indexterm>
|
||||
<primary>kernel</primary>
|
||||
<secondary>building / installing</secondary>
|
||||
</indexterm>
|
||||
<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>It is required to have the full &os; source tree installed
|
||||
to build the kernel.</para>
|
||||
<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>The kernel build is located at <filename
|
||||
class="directory">/usr/src/sys</filename>. It contains a
|
||||
number of subdirectories representing different parts of the
|
||||
kernel. These include <filename
|
||||
class="directory"><replaceable>arch</replaceable>/conf</filename>,
|
||||
which contains the kernel configuration file, and
|
||||
<filename class="directory">compile</filename>, which is the
|
||||
staging area where the kernel will be built.
|
||||
<replaceable>arch</replaceable> contains subdirectories for each
|
||||
supported architecture: <filename
|
||||
class="directory">i386</filename>, <filename
|
||||
class="directory">amd64</filename>, <filename
|
||||
class="directory">ia64</filename>, <filename
|
||||
class="directory">powerpc</filename>, <filename
|
||||
class="directory">sparc64</filename>, and <filename
|
||||
class="directory">pc98</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. Notice the logical organization of the
|
||||
directory structure, with each supported device, file system,
|
||||
and option in its own subdirectory.</para>
|
||||
<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>
|
||||
|
||||
<para>The examples in this chapter assume the i386 architecture.
|
||||
If the system has a different architecture, change the path
|
||||
names accordingly.</para>
|
||||
<programlisting>psm0: <PS/2 Mouse> irq 12 on atkbdc0
|
||||
psm0: [GIANT-LOCKED]
|
||||
psm0: [ITHREAD]
|
||||
psm0: model Generic PS/2 mouse, device ID 0</programlisting>
|
||||
|
||||
<note>
|
||||
<para>If <filename class="directory">/usr/src/</filename> does
|
||||
not exist or it is empty, source has not been installed. The
|
||||
easiest way to install source is to use
|
||||
<application>svn</application> as described in <xref
|
||||
linkend="svn"/>. One should also create a symlink to
|
||||
<filename class="directory">/usr/src/sys/</filename>:</para>
|
||||
<para>Since this hardware exists, this driver should not be removed from a custom kernel
|
||||
configuration file.</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput></screen>
|
||||
</note>
|
||||
<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>Next, <application>cd</application> to <filename
|
||||
class="directory"><replaceable>arch</replaceable>/conf</filename>
|
||||
and copy the <filename>GENERIC</filename> configuration file to
|
||||
the name of the custom kernel. For example:</para>
|
||||
<para>Another tool for finding hardware is
|
||||
&man.pciconf.8;, which provides more verbose output. For
|
||||
example:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
|
||||
&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen>
|
||||
<programlisting><command>pciconf <option>-lv</option></command>
|
||||
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</programlisting>
|
||||
|
||||
<para>Traditionally, this name is in 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 uses
|
||||
<filename><replaceable>MYKERNEL</replaceable></filename>.</para>
|
||||
<para>This output shows that the
|
||||
<devicename>ath</devicename> driver located a wireless Ethernet
|
||||
device.</para>
|
||||
|
||||
<tip>
|
||||
<para>When finished customizing the kernel configuration file,
|
||||
save a backup copy to a location outside of <filename
|
||||
class="directory">/usr/src</filename>. Do not edit
|
||||
<filename>GENERIC</filename> directly.</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>
|
||||
|
||||
<para>Alternately, keep the kernel configuration file elsewhere
|
||||
and create a symbolic link to the file in <filename
|
||||
class="directory"><replaceable>i386</replaceable></filename>.</para>
|
||||
<screen>&prompt.root; man -k <replaceable>Atheros</replaceable></screen>
|
||||
|
||||
<para>For example:</para>
|
||||
<programlisting>ath(4) - Atheros IEEE 802.11 wireless network driver
|
||||
ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
|
||||
&prompt.root; <userinput>mkdir /root/kernels</userinput>
|
||||
&prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput>
|
||||
&prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
|
||||
</tip>
|
||||
|
||||
<para>Edit
|
||||
<filename><replaceable>MYKERNEL</replaceable></filename>
|
||||
with a text editor. The default editor is
|
||||
<application>vi</application>, whose usage is covered well in
|
||||
many books in the <link
|
||||
linkend="bibliography">bibliography</link>. An easier editor
|
||||
for beginners, called <application>ee</application>, is also
|
||||
available. Feel free to change the comment lines at the top to
|
||||
reflect the configuration or the changes made to differentiate
|
||||
it from <filename>GENERIC</filename>.</para>
|
||||
|
||||
<para>If the <filename>GENERIC</filename> configuration file seems
|
||||
overwhelming, follow the descriptions in the <link
|
||||
linkend="kernelconfig-config">Configuration File</link>
|
||||
section slowly and carefully.</para>
|
||||
|
||||
<note>
|
||||
<para>After <link linkend="svn">syncing the source tree</link>
|
||||
with the latest sources, <emphasis>always</emphasis> read
|
||||
<filename class="directory">/usr/src/UPDATING</filename>
|
||||
before performing any update steps. This file describes any
|
||||
important issues or areas requiring special attention within
|
||||
the updated source code.
|
||||
<filename>/usr/src/UPDATING</filename> always matches
|
||||
the version of the &os; source and contains more up-to-date
|
||||
information than this Handbook.</para>
|
||||
</note>
|
||||
|
||||
<para>After saving the edits, compile the source code for the
|
||||
kernel.</para>
|
||||
|
||||
<procedure>
|
||||
<title>Building a Kernel</title>
|
||||
|
||||
<note>
|
||||
<para>It is required to have the full &os; source tree
|
||||
installed to build the kernel.</para>
|
||||
</note>
|
||||
|
||||
<step>
|
||||
<para><command>cd</command> to <filename
|
||||
class="directory">/usr/src</filename>:</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:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
|
||||
</step>
|
||||
</procedure>
|
||||
|
||||
<tip>
|
||||
<para>By default, when a custom kernel is compiled,
|
||||
<emphasis>all</emphasis> kernel modules are rebuilt as well.
|
||||
To update a kernel faster or to build only custom modules,
|
||||
edit <filename>/etc/make.conf</filename> before starting to
|
||||
build the kernel:</para>
|
||||
|
||||
<programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting>
|
||||
|
||||
<para>This variable specifies the list of modules to build
|
||||
instead the default of building of all of them.</para>
|
||||
|
||||
<programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>
|
||||
|
||||
<para>This variable sets up a list of top level modules to
|
||||
exclude from the build process. For other available
|
||||
variables, refer to &man.make.conf.5;.</para>
|
||||
</tip>
|
||||
|
||||
<indexterm>
|
||||
<primary><filename
|
||||
class="directory">/boot/kernel.old</filename></primary>
|
||||
</indexterm>
|
||||
|
||||
<para>The new kernel will be copied to <filename
|
||||
class="directory">/boot/kernel</filename> as
|
||||
<filename>/boot/kernel/kernel</filename> and the old kernel
|
||||
will be moved to <filename>/boot/kernel.old/kernel</filename>.
|
||||
Now, shutdown the system and reboot into the new kernel.
|
||||
If something goes wrong, refer to the <link
|
||||
linkend="kernelconfig-trouble">troubleshooting</link>
|
||||
instructions and the section which explains how to
|
||||
recover when the new kernel <link
|
||||
linkend="kernelconfig-noboot">does not boot</link>.</para>
|
||||
|
||||
<note>
|
||||
<para>Other files relating to the boot process, such as the boot
|
||||
&man.loader.8; and configuration, are stored in <filename
|
||||
class="directory">/boot</filename>. Third party or
|
||||
custom modules can be placed in <filename
|
||||
class="directory">/boot/kernel</filename>, although users
|
||||
should be aware that keeping modules in sync with the compiled
|
||||
kernel is very important. Modules not intended to run with
|
||||
the compiled kernel may result in instability.</para>
|
||||
</note>
|
||||
<para>Once the hardware inventory list is created, refer to it
|
||||
to ensure that installed hardware is not removed as you edit the custom
|
||||
kernel configuration file.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kernelconfig-config">
|
||||
<sect1info>
|
||||
<authorgroup>
|
||||
<!-- <authorgroup>
|
||||
<author>
|
||||
<firstname>Joel</firstname>
|
||||
<surname>Dahl</surname>
|
||||
<contrib>Updated by </contrib>
|
||||
</author>
|
||||
</authorgroup>
|
||||
</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 class="directory">/usr/src/</filename> does
|
||||
not exist or it is empty, source has not been installed.
|
||||
Source can be installed using
|
||||
<application>svn</application>, which is described in <xref
|
||||
linkend="svn"/>, or by installing the
|
||||
<literal>src</literal> distribution using &man.sysinstall.8;. This
|
||||
distribution can be selected by navigating to the
|
||||
<literal>Configuration</literal> and then to the
|
||||
<literal>Distributions</literal> menu within &man.sysinstall.8;.</para>
|
||||
|
||||
<para>Once source is installed, review the contents of <filename
|
||||
class="directory">/usr/src/sys</filename>. This directory contains a
|
||||
number of subdirectories, including those which represent the following
|
||||
supported architectures: <filename
|
||||
class="directory">amd64</filename>, <filename
|
||||
class="directory">i386</filename>, <filename
|
||||
class="directory">ia64</filename>, <filename
|
||||
class="directory">pc98</filename>, <filename
|
||||
class="directory">powerpc</filename>, and <filename
|
||||
class="directory">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
|
||||
class="directory">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 custom 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>
|
||||
|
||||
<tip>
|
||||
<para>When finished customizing the kernel configuration file,
|
||||
save a backup copy to a location outside of <filename
|
||||
class="directory">/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/<replaceable>amd64</replaceable>/conf</userinput>
|
||||
&prompt.root; <userinput>mkdir /root/kernels</userinput>
|
||||
&prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput>
|
||||
&prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
|
||||
</tip>
|
||||
|
||||
<para>The configuration file
|
||||
<filename><replaceable>MYKERNEL</replaceable></filename> can now be customized
|
||||
with any ASCII 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>
|
||||
|
|
@ -459,14 +314,18 @@ following line in &man.loader.conf.5;:
|
|||
<secondary>configuration file</secondary>
|
||||
</indexterm>
|
||||
|
||||
<para>The general format of a configuration file is quite simple.
|
||||
Each line contains a keyword and one or more arguments. For
|
||||
simplicity, most lines only contain one argument. Anything
|
||||
following a <literal>#</literal> is considered a comment and
|
||||
ignored. The following sections describe each keyword, in
|
||||
the order they are listed in <filename>GENERIC</filename>.
|
||||
For an exhaustive list of architecture dependent options and
|
||||
devices, refer to <filename>NOTES</filename> in the same
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
|
@ -490,60 +349,18 @@ 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 be also be added to the local
|
||||
<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>
|
||||
|
||||
<para>The remainder of this chapter addresses the contents of a
|
||||
typical configuration file and the role various options and
|
||||
devices play.</para>
|
||||
|
||||
<note>
|
||||
<para>To build a file which contains all available options,
|
||||
run the following command as <username>root</username>:</para>
|
||||
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf && make LINT</userinput></screen>
|
||||
</note>
|
||||
|
||||
<indexterm>
|
||||
<primary>kernel</primary>
|
||||
<secondary>configuration file</secondary>
|
||||
</indexterm>
|
||||
|
||||
<para>The following is an example of the
|
||||
<filename>GENERIC</filename> kernel configuration file with
|
||||
various additional comments where needed for clarity. This
|
||||
example should match the copy in
|
||||
<filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/GENERIC</filename>
|
||||
fairly closely.</para>
|
||||
|
||||
<indexterm>
|
||||
<primary>kernel options</primary>
|
||||
<secondary>machine</secondary>
|
||||
</indexterm>
|
||||
|
||||
<programlisting>machine i386</programlisting>
|
||||
|
||||
<para>This is the machine architecture. It must be either
|
||||
<literal>amd64</literal>, <literal>i386</literal>,
|
||||
<literal>ia64</literal>, <literal>pc98</literal>,
|
||||
<literal>powerpc</literal>, or
|
||||
<literal>sparc64</literal>.</para>
|
||||
|
||||
<indexterm>
|
||||
<primary>kernel options</primary>
|
||||
<secondary>cpu</secondary>
|
||||
</indexterm>
|
||||
<programlisting>cpu I486_CPU
|
||||
cpu I586_CPU
|
||||
cpu I686_CPU</programlisting>
|
||||
|
||||
<para>This option specifies the type of CPU. It is fine to have
|
||||
multiple instances of the CPU entries, but for a custom kernel
|
||||
it is best to specify the CPU. To determine the CPU type,
|
||||
review the boot messages in
|
||||
<filename>/var/run/dmesg.boot</filename>.</para>
|
||||
|
||||
<indexterm>
|
||||
<primary>kernel options</primary>
|
||||
|
|
@ -558,19 +375,6 @@ cpu I686_CPU</programlisting>
|
|||
The value in the <literal>ident</literal> string will
|
||||
print when the kernel boots.</para>
|
||||
|
||||
<programlisting>#To statically compile in device wiring instead of /boot/device.hints
|
||||
#hints "GENERIC.hints" # Default places to look for devices.</programlisting>
|
||||
|
||||
<para>&man.device.hints.5; is used to configure options for device
|
||||
drivers. The default location is
|
||||
<filename>/boot/device.hints</filename>. The
|
||||
<literal>hints</literal> option compiles these hints statically
|
||||
into the kernel so that there is no need to create
|
||||
<filename>/boot/device.hints</filename>.</para>
|
||||
|
||||
<!-- XXX: Add a comment here that explains when compiling hints into
|
||||
the kernel is a good idea and why. -->
|
||||
|
||||
<programlisting>makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols</programlisting>
|
||||
|
||||
<para>This option enables debugging information when passed to
|
||||
|
|
@ -580,12 +384,6 @@ cpu I686_CPU</programlisting>
|
|||
|
||||
<para>The default system scheduler for &os;. Keep this.</para>
|
||||
|
||||
<programlisting>options PREEMPTION # Enable kernel thread preemption</programlisting>
|
||||
|
||||
<para>Allows kernel threads to be preempted by higher priority
|
||||
threads. This helps with interactivity and allows interrupt
|
||||
threads to run sooner rather than waiting.</para>
|
||||
|
||||
<programlisting>options INET # InterNETworking</programlisting>
|
||||
|
||||
<para>Networking support. This is mandatory as most programs
|
||||
|
|
@ -1370,6 +1168,112 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
|
|||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kernelconfig-building">
|
||||
<title>Building and Installing a Custom Kernel</title>
|
||||
|
||||
<para>After saving the edits, compile the source code for the
|
||||
kernel.</para>
|
||||
|
||||
<note>
|
||||
<para>After <link linkend="svn">syncing the source tree</link>
|
||||
with the latest sources, <emphasis>always</emphasis> read
|
||||
<filename class="directory">/usr/src/UPDATING</filename>
|
||||
before performing any update steps. This file describes any
|
||||
important issues or areas requiring special attention within
|
||||
the updated source code.
|
||||
<filename>/usr/src/UPDATING</filename> always matches
|
||||
the version of the &os; source and contains more up-to-date
|
||||
information than this Handbook.</para>
|
||||
</note>
|
||||
|
||||
<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>
|
||||
|
||||
<procedure>
|
||||
<title>Building a Kernel</title>
|
||||
<indexterm>
|
||||
<primary>kernel</primary>
|
||||
<secondary>building / installing</secondary>
|
||||
</indexterm>
|
||||
|
||||
<note>
|
||||
<para>It is required to have the full &os; source tree
|
||||
installed to build the kernel.</para>
|
||||
</note>
|
||||
|
||||
<step>
|
||||
<para><command>cd</command> to <filename
|
||||
class="directory">/usr/src</filename>:</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:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
|
||||
</step>
|
||||
</procedure>
|
||||
|
||||
<tip>
|
||||
<para>By default, when a custom kernel is compiled,
|
||||
<emphasis>all</emphasis> kernel modules are rebuilt as well.
|
||||
To update a kernel faster or to build only custom modules,
|
||||
edit <filename>/etc/make.conf</filename> before starting to
|
||||
build the kernel:</para>
|
||||
|
||||
<programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting>
|
||||
|
||||
<para>This variable specifies the list of modules to build
|
||||
instead the default of building of all of them.</para>
|
||||
|
||||
<programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>
|
||||
|
||||
<para>This variable sets up a list of top level modules to
|
||||
exclude from the build process. For other available
|
||||
variables, refer to &man.make.conf.5;.</para>
|
||||
</tip>
|
||||
|
||||
<indexterm>
|
||||
<primary><filename
|
||||
class="directory">/boot/kernel.old</filename></primary>
|
||||
</indexterm>
|
||||
|
||||
<para>The new kernel will be copied to <filename
|
||||
class="directory">/boot/kernel</filename> as
|
||||
<filename>/boot/kernel/kernel</filename> and the old kernel
|
||||
will be moved to <filename>/boot/kernel.old/kernel</filename>.
|
||||
Now, shutdown the system and reboot into the new kernel.
|
||||
If something goes wrong, refer to the <link
|
||||
linkend="kernelconfig-trouble">troubleshooting</link>
|
||||
instructions and the section which explains how to
|
||||
recover when the new kernel <link
|
||||
linkend="kernelconfig-noboot">does not boot</link>.</para>
|
||||
|
||||
<note>
|
||||
<para>Other files relating to the boot process, such as the boot
|
||||
&man.loader.8; and configuration, are stored in <filename
|
||||
class="directory">/boot</filename>. Third party or
|
||||
custom modules can be placed in <filename
|
||||
class="directory">/boot/kernel</filename>, although users
|
||||
should be aware that keeping modules in sync with the compiled
|
||||
kernel is very important. Modules not intended to run with
|
||||
the compiled kernel may result in instability.</para>
|
||||
</note>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kernelconfig-trouble">
|
||||
<title>If Something Goes Wrong</title>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue