svn commit: r44289 - head/en_US.ISO8859-1/books/handbook/kernelconfig
Dru Lavigne
dru at FreeBSD.org
Wed Mar 19 17:14:09 UTC 2014
Author: dru
Date: Wed Mar 19 17:14:08 2014
New Revision: 44289
URL: http://svnweb.freebsd.org/changeset/doc/44289
Log:
White space fix only. Translators can ignore.
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Wed Mar 19 16:52:25 2014 (r44288)
+++ head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Wed Mar 19 17:14:08 2014 (r44289)
@@ -69,17 +69,17 @@
</itemizedlist>
<para>All of the commands listed in the examples in this chapter
- should be executed as <systemitem class="username">root</systemitem>.</para>
+ 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>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
@@ -132,12 +132,11 @@
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>
+ <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;:
@@ -145,11 +144,12 @@ 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>
+ <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>
+ <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">
@@ -166,11 +166,10 @@ following line in &man.loader.conf.5;:
-->
<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
+ <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>
@@ -180,12 +179,11 @@ following line in &man.loader.conf.5;:
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;
+ <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
@@ -197,12 +195,11 @@ psm0: model Generic PS/2 mouse, device I
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>
+ 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>
+ <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 at pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00
@@ -211,14 +208,12 @@ ath0 at pci0:3:0:0: class=0x020000 c
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>
+ <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>
@@ -252,36 +247,39 @@ ath_hal(4) - Atheros Hardw
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>
-
+ 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
+ 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/amd64/conf</userinput>
&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen>
- <para>The configuration file
- <filename>MYKERNEL</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
+ <para>The configuration file <filename>MYKERNEL</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>
@@ -299,9 +297,10 @@ ath_hal(4) - Atheros Hardw
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>
+ <literal>#</literal> for any line that you do not
+ understand.</para>
- <warning>
+ <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
@@ -309,8 +308,8 @@ ath_hal(4) - Atheros Hardw
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
+ <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
@@ -318,7 +317,8 @@ ath_hal(4) - Atheros Hardw
<tip>
<para>When finished customizing the kernel configuration file,
- save a backup copy to a location outside of <filename>/usr/src</filename>.</para>
+ 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>
@@ -332,10 +332,10 @@ ath_hal(4) - Atheros Hardw
<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>
+ 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
@@ -346,17 +346,19 @@ options IPFIREWALL_DEFAULT_TO_AC
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
+ 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
+ <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>
+ 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>
@@ -461,9 +463,10 @@ options NFS_ROOT # NFS
<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>
+ 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>
@@ -476,24 +479,26 @@ options NFS_ROOT # NFS
<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>
+ 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>
+ <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>
+ <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>
@@ -995,7 +1000,8 @@ device loop # Network loopbac
<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
+ <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"/>
@@ -1076,7 +1082,7 @@ device fwe # Ethernet
&os;, see
<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename>.</para>
-->
-
+
<!--
This section refers to ancient hardware.
<sect2>
@@ -1166,21 +1172,22 @@ device fwe # Ethernet
information on &os;'s <acronym>PAE</acronym> support.</para>
</sect2>
-->
- </sect1>
+ </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>
+ 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>
+
+ <indexterm>
+ <primary>kernel</primary>
+ <secondary>building / installing</secondary>
+ </indexterm>
<step>
<para>Change to this directory:</para>
@@ -1197,13 +1204,14 @@ device fwe # Ethernet
<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>
+ 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
@@ -1211,46 +1219,46 @@ device fwe # Ethernet
</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>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>
+ <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 ntfs</programlisting>
+ <programlisting>MODULES_OVERRIDE = linux acpi ntfs</programlisting>
- <para>Alternately, this variable lists which modules to
- exclude from the build process:</para>
+ <para>Alternately, this variable lists which modules to exclude
+ from the build process:</para>
- <programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>
+ <programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>
- <para>Additional variables are available.
- Refer to &man.make.conf.5; for details.</para>
+ <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>
+ <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>
+ <para>There are four categories of trouble that can occur when
+ building a custom kernel:</para>
- <variablelist>
- <varlistentry>
- <term><command>config</command> fails</term>
+ <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>
+ <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>
@@ -1261,16 +1269,17 @@ device fwe # Ethernet
<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>
+ 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>
- <term>The kernel does not boot<anchor xml:id="kernelconfig-noboot"/></term>
+ <term>The kernel does not boot<anchor
+ xml:id="kernelconfig-noboot"/></term>
<listitem>
<para>If the new kernel does not boot or fails to recognize
@@ -1280,9 +1289,8 @@ device fwe # Ethernet
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
- kernel.old</command>, or
- the name of any other kernel that is known to boot properly.</para>
+ <command>boot kernel.old</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
@@ -1293,19 +1301,17 @@ device fwe # Ethernet
<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>
+ 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 /boot/kernel.bad</userinput>
&prompt.root; <userinput>mv /boot/kernel.good /boot/kernel</userinput></screen>
-
</note>
</listitem>
</varlistentry>
@@ -1316,13 +1322,14 @@ device fwe # Ethernet
<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>
+ 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>
More information about the svn-doc-all
mailing list