svn commit: r40999 - head/en_US.ISO8859-1/books/handbook/kernelconfig

Dru Lavigne dru at FreeBSD.org
Sun Feb 17 17:41:06 UTC 2013


Author: dru
Date: Sun Feb 17 17:41:05 2013
New Revision: 40999
URL: http://svnweb.freebsd.org/changeset/doc/40999

Log:
  Initial content fix. This patch addresses the following:
  
  - fixes you
  
  - fixes xref and directory tags
  
  - general tightening
  
  - csup changed to svn
  
  Approved by: gjb (mentor)

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	Sun Feb 17 17:28:26 2013	(r40998)
+++ head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml	Sun Feb 17 17:41:05 2013	(r40999)
@@ -37,21 +37,19 @@
 
     <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 more and more
-      of &os; becomes dynamically configurable it is still
-      occasionally necessary to reconfigure and recompile your
-      kernel.</para>
+      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>Why you might need to build a custom kernel.</para>
+	<para>When to build a custom kernel.</para>
       </listitem>
 
       <listitem>
-	<para>How to write a kernel configuration file, or alter an
-	  existing configuration file.</para>
+	<para>How to customize a kernel configuration file.</para>
       </listitem>
 
       <listitem>
@@ -68,50 +66,46 @@
       </listitem>
     </itemizedlist>
 
-    <para>All of the commands listed within this chapter by way of
-      example should be executed as <username>root</username> in
-      order to succeed.</para>
+    <para>All of the commands listed in the examples in this chapter
+      should be executed as <username>root</username>.</para>
   </sect1>
 
   <sect1 id="kernelconfig-custom-kernel">
     <title>Why Build a Custom Kernel?</title>
 
-    <para>Traditionally, &os; has had what is called a
-      <quote>monolithic</quote> kernel.  This means that the kernel
-      was one large program, supported a fixed list of devices, and
-      if you wanted to change the kernel's behavior then you had to
-      compile a new kernel, and then reboot your computer with the
-      new kernel.</para>
-
-    <para>Today, &os; is rapidly moving to a model where much of the
-      kernel's functionality is contained in modules which can be
-      dynamically loaded and unloaded from the kernel as necessary.
-      This allows the kernel to adapt to new hardware suddenly
-      becoming available (such as PCMCIA cards in a laptop), or for
-      new functionality to be brought into the kernel that was not
-      necessary when the kernel was originally compiled.  This is
-      known as a modular kernel.</para>
-
-    <para>Despite this, it is still necessary to carry out some
-      static kernel configuration.  In some cases this is because
-      the functionality is so tied to the kernel that it can not be
-      made dynamically loadable.  In others it may simply be because
-      no one has yet taken the time to write a dynamic loadable kernel
-      module for that functionality.</para>
-
-    <para>Building a custom kernel is one of the most important rites
-      of passage for advanced BSD users.  This process, while
-      time consuming, will provide many benefits to your &os; system.
-      Unlike the <filename>GENERIC</filename> kernel, which must
-      support a wide range of hardware, a custom kernel only contains
-      support for <emphasis>your</emphasis> PC's hardware.  This has
-      a number of benefits, such as:</para>
+    <para>Traditionally, &os; used a <quote>monolithic</quote> 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
+      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.  This may be because the 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 you have on your system, the time it takes
-	  your system to boot can decrease dramatically.</para>
+	<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>
@@ -121,15 +115,14 @@
 	  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 especially useful on a system with a small amount
-	  of RAM.</para>
+	  kernel is useful on a system with a small amount of
+	  RAM.</para>
       </listitem>
 
       <listitem>
-	<para>Additional hardware support.  A custom kernel allows
-	  you to add in support for devices which are not present
-	  in the <filename>GENERIC</filename> kernel, such as
-	  sound cards.</para>
+	<para>Additional hardware support.  A custom kernel can add in
+	  support for devices which are not present in the
+	  <filename>GENERIC</filename> kernel.</para>
       </listitem>
     </itemizedlist>
   </sect1>
@@ -149,12 +142,10 @@
     <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 may easily be created by viewing the current operating
-      system configuration.  For example, µsoft;'s
-      <application>Device Manager</application> normally contains
-      important information about installed devices.  The
-      <application>Device Manager</application> is located in the
-      control panel.</para>
+      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 &microsoft.windows; have a
@@ -165,12 +156,11 @@
 
     <para>If another operating system does not exist on the machine,
       the administrator must find this information out manually.  One
-      method is using the &man.dmesg.8; utility and the &man.man.1;
-      commands.  Most device drivers on &os; have a manual page,
-      listing supported hardware, and during the boot probe, found
-      hardware will be listed.  For example, the following lines
-      indicate that the <devicename>psm</devicename> driver found
-      a mouse:</para>
+      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]
@@ -182,12 +172,12 @@ psm0: model Generic PS/2 mouse, device I
 
     <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 viewing the
-      <filename>/var/run/dmesg.boot</filename> file.</para>
+      these situations, the output may be obtained by reading
+      <filename>/var/run/dmesg.boot</filename>.</para>
 
-    <para>Another method of finding hardware is by using the
-      &man.pciconf.8; utility which provides more verbose output.
-      For example:</para>
+    <para>Another method for finding hardware is to use
+      &man.pciconf.8; which provides more verbose output.  For
+      example:</para>
 
     <programlisting>ath0 at pci0:3:0:0:        class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00
     vendor     = 'Atheros Communications Inc.'
@@ -195,22 +185,20 @@ psm0: model Generic PS/2 mouse, device I
     class      = network
     subclass   = ethernet</programlisting>
 
-    <para>This bit of output, obtained using
-      <command>pciconf <option>-lv</option></command> shows that the
+    <para>This output, obtained by using
+      <command>pciconf <option>-lv</option></command>, shows that the
       <devicename>ath</devicename> driver located a wireless Ethernet
-      device.  Using
-      <command>man <replaceable>ath</replaceable></command> will
-      return the &man.ath.4; manual page.</para>
+      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 also be used to provide useful information.  From the
-      above, one can issue:</para>
+      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>
 
-    <para>To get a list of manual pages which contain that particular
-      word:</para>
-
     <programlisting>ath(4)                   - Atheros IEEE 802.11 wireless network driver
 ath_hal(4)               - Atheros Hardware Access Layer (HAL)</programlisting>
 
@@ -226,45 +214,37 @@ ath_hal(4)               - Atheros Hardw
       <secondary>drivers / modules / subsystems</secondary>
     </indexterm>
 
-    <para>Before building a custom kernel, consider the reasons for
+    <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 the
-      <filename class="directory">/boot/kernel</filename> directory
-      and may be dynamically loaded into the running kernel using
+    <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
-      specific module and manual page.  For example, the last section
-      noted the <devicename>ath</devicename> wireless Ethernet driver.
-      This device has the following information in its manual
-      page:</para>
+      loadable module and manual page.  For example, the &man.ath.4;
+      wireless Ethernet driver has the following information in its
+      manual page:</para>
 
     <programlisting>Alternatively, to load the driver as a module at boot time, place the
 following line in &man.loader.conf.5;:
 
     if_ath_load="YES"</programlisting>
 
-    <para>As instructed, adding the
-      <literal>if_ath_load="YES"</literal> line to the
-      <filename>/boot/loader.conf</filename> file will
-      enable loading this module dynamically at boot time.</para>
-
-    <para>In some cases; however, there is no associated module.
-      This is mostly true for certain subsystems and very important
-      drivers, for instance, the fast file system
-      (<acronym>FFS</acronym>) is a required option in the kernel.
-      As is network support (INET).  Unfortunately the only way to
-      tell if a driver is required is to check for the module
-      itself.</para>
+    <para>Adding <literal>if_ath_load="YES"</literal> to
+      <filename>/boot/loader.conf</filename> will enable loading 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 without the module added to
-	<filename>loader.conf</filename>.  When in doubt, check for
-	the module and then just leave support in the kernel.</para>
+      <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>
   </sect1>
 
@@ -281,78 +261,66 @@ following line in &man.loader.conf.5;:
 	to build the kernel.</para>
     </note>
 
-    <para>First, let us take a quick tour of the kernel build
-      directory.  All directories mentioned will be relative to the
-      main <filename>/usr/src/sys</filename> directory, which is
-      also accessible through the path name <filename>/sys</filename>.
-      There are a number of subdirectories here representing different
-      parts of the kernel, but the most important for our purposes
-      are <filename><replaceable>arch</replaceable>/conf</filename>,
-      where you will edit your custom kernel configuration, and
-      <filename>compile</filename>, which is the staging area where
-      your kernel will be built.  <replaceable>arch</replaceable>
-      represents one of <filename>i386</filename>,
-      <filename>amd64</filename>, <filename>ia64</filename>,
-      <filename>powerpc</filename>, <filename>sparc64</filename>,
-      or <filename>pc98</filename> (an alternative development branch
-      of PC hardware, popular in Japan).  Everything inside a
+    <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; the rest of the code is machine independent code common
-      to all platforms to which &os; could potentially be ported.
-      Notice the logical organization of the directory structure,
-      with each supported device, file system, and option in its
-      own subdirectory.</para>
-
-    <para>The examples in this chapter assume that you are using
-      the i386 architecture.  If your system has a different
-      architecture you need to change the path names
-      accordingly.</para>
+      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>The examples in this chapter assume the i386 architecture.
+      If the system has a different architecture, change the path
+      names accordingly.</para>
 
     <note>
-      <para>If the directory <filename>/usr/src/</filename> does not
-	exist on your system (or if it is empty), then the sources
-	have not been installed.  The easiest way to install the full
-	source is to use &man.csup.1; as described in <xref
-	linkend="synching"/>.  You should also create a symlink to
+      <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 <link
+	  linkend="svn"></link>.  One should also create a symlink to
 	<filename class="directory">/usr/src/sys/</filename>:</para>
 
 	<screen>&prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput></screen>
     </note>
 
-    <para>Next, change to the
-      <filename><replaceable>arch</replaceable>/conf</filename>
-      directory and copy the <filename>GENERIC</filename>
-      configuration file to the name you want to give your kernel.
-      For example:</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>
 
     <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
 &prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen>
 
-    <para>Traditionally, this name is in all capital letters and,
-      if you are maintaining multiple &os; machines with different
-      hardware, it is a good idea to name it after your machine's
-      hostname.  We will call it
-      <filename><replaceable>MYKERNEL</replaceable></filename> for
-      the purpose of this example.</para>
+    <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>
 
     <tip>
-      <para>Storing your kernel configuration file directly under
-	<filename>/usr/src</filename> can be a bad idea.  If you are
-	experiencing problems it can be tempting to just delete
-	<filename>/usr/src</filename> and start again.  After doing
-	this, it usually only takes a few seconds for
-	you to realize that you have deleted your custom kernel
-	configuration file.  Also, do not edit
-	<filename>GENERIC</filename> directly, as it may get
-	overwritten the next time you
-	<link linkend="updating-upgrading">update your source
-	  tree</link>,
-	and your kernel modifications will be lost.</para>
-
-      <para>You might want to keep your kernel configuration file
-	elsewhere, and then create a symbolic link to the file in
-	the <filename><replaceable>i386</replaceable></filename>
-	directory.</para>
+      <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>Alternately, keep the kernel configuration file elsewhere
+	and create a symbolic link to the file in <filename
+	  class="directory"><replaceable>i386</replaceable></filename>.</para>
 
       <para>For example:</para>
 
@@ -362,43 +330,36 @@ following line in &man.loader.conf.5;:
 &prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
     </tip>
 
-    <para>Now, edit
+    <para>Edit
       <filename><replaceable>MYKERNEL</replaceable></filename>
-      with your favorite text editor.  If you are just starting out,
-      the only editor available will probably be
-      <application>vi</application>, which is too complex to explain
-      here, but is covered well in many books in the <link
-	linkend="bibliography">bibliography</link>.  However, &os;
-      does offer an easier editor called <application>ee</application>
-      which, if you are a beginner, should be your editor of choice.
-      Feel free to change the comment lines at the top to reflect
-      your configuration or the changes you have made to differentiate
+      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>
-    <indexterm><primary>SunOS</primary></indexterm>
 
-    <para>If you have built a kernel under &sunos; or some other BSD
-      operating system, much of this file will be very familiar to
-      you.  If you are coming from some other operating system such
-      as DOS, on the other hand, the <filename>GENERIC</filename>
-      configuration file might seem overwhelming to you, so follow
-      the descriptions in the
-      <link linkend="kernelconfig-config">Configuration File</link>
+    <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>If you <link
-	  linkend="updating-upgrading">sync your source tree</link>
-	with the latest sources of the &os; project, be sure to always
-	check the file <filename>/usr/src/UPDATING</filename> before
-	you perform any update steps.  This file describes any
+      <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
-	your version of the &os; source, and is therefore more up
-	to date with new information than this handbook.</para>
+	the version of the &os; source and contains more up-to-date
+	information than this Handbook.</para>
     </note>
 
-    <para>You must now compile the source code for the kernel.</para>
+    <para>After saving the edits, compile the source code for the
+      kernel.</para>
 
     <procedure>
       <title>Building a Kernel</title>
@@ -409,14 +370,15 @@ following line in &man.loader.conf.5;:
       </note>
 
       <step>
-	<para>Change to the <filename
-	    class="directory">/usr/src</filename> directory:</para>
+	<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 kernel:</para>
+	<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>
@@ -429,52 +391,49 @@ following line in &man.loader.conf.5;:
     </procedure>
 
     <tip>
-      <para>By default, when you build a custom kernel,
-	<emphasis>all</emphasis> kernel modules will be rebuilt as
-	well.  If you want to update a kernel faster or to build only
-	custom modules, you should edit
-	<filename>/etc/make.conf</filename> before starting to build
-	the kernel:</para>
+      <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 sets up a list of modules to build instead
-	of all of them.</para>
+      <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 variables which
-	you may find useful in the process of building kernel, refer
-	to &man.make.conf.5; manual page.</para>
+	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>
+      <primary><filename
+	class="directory">/boot/kernel.old</filename></primary>
     </indexterm>
 
-    <para>The new kernel will be copied to the <filename
-	class="directory">/boot/kernel</filename> directory as
+    <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 to use your new kernel.
-      If something goes wrong, there are some <link
+      Now, shutdown the system and reboot into the new kernel.
+      If something goes wrong, refer to the <link
 	linkend="kernelconfig-trouble">troubleshooting</link>
-      instructions at the end of this chapter that you may find
-      useful.  Be sure to read the section which explains how to
-      recover in case your new kernel <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>/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 or incorrectness.</para>
+	&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>
 
@@ -506,22 +465,19 @@ following line in &man.loader.conf.5;:
       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>.
-      <anchor
-      id="kernelconfig-options"/> For an exhaustive list of
-      architecture dependent options and devices, see the
-      <filename>NOTES</filename> file in the same directory as the
-      <filename>GENERIC</filename> file.  For architecture independent
-      options, see
+      For an exhaustive list of architecture dependent options and
+      devices, refer to <filename>NOTES</filename> 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>
 
-    <para>An <literal>include</literal> directive is
-      available for use in configuration files.  This allows another
-      configuration file to be logically included in the current
-      one, making it easy to maintain small changes relative to an
-      existing file.  For example, if you require a
-      <filename>GENERIC</filename> kernel with only a small number
-      of additional options or drivers, this allows you to maintain
-      only a delta with respect to GENERIC:</para>
+    <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.  For example, if
+      only a small number of additional options or drivers are
+      required, this allows a delta to be maintained with respect
+      to GENERIC:</para>
 
     <programlisting>include GENERIC
 ident MYKERNEL
@@ -531,13 +487,11 @@ options         DUMMYNET
 options         IPFIREWALL_DEFAULT_TO_ACCEPT
 options         IPDIVERT</programlisting>
 
-    <para>Many administrators will find that this model offers
-      significant benefits over the historic writing of configuration
-      files from scratch: the local configuration file will express
-      only local differences from a <filename>GENERIC</filename>
-      kernel and as upgrades are performed, new features added to
-      <filename>GENERIC</filename> will be added to the local kernel
-      unless specifically prevented using
+    <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
+      kernel unless they are specifically prevented using
       <literal>nooptions</literal> or <literal>nodevice</literal>.
       The remainder of this chapter addresses the contents of a
       typical configuration file and the role various options and
@@ -545,8 +499,7 @@ options         IPDIVERT</programlisting
 
     <note>
       <para>To build a file which contains all available options,
-	as normally done for testing purposes, run the following
-	command as <username>root</username>:</para>
+	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>
@@ -559,7 +512,7 @@ options         IPDIVERT</programlisting
     <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 your copy in
+      example should match the copy in
       <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/GENERIC</filename>
       fairly closely.</para>
 
@@ -571,9 +524,9 @@ options         IPDIVERT</programlisting
     <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>amd64</literal>, <literal>i386</literal>,
+      <literal>ia64</literal>, <literal>pc98</literal>,
+      <literal>powerpc</literal>, or
       <literal>sparc64</literal>.</para>
 
     <indexterm>
@@ -584,14 +537,11 @@ options         IPDIVERT</programlisting
 cpu          I586_CPU
 cpu          I686_CPU</programlisting>
 
-    <para>The above option specifies the type of CPU you have in your
-      system.  You may have multiple instances of the CPU line (if,
-      for example, you are not sure whether you should use
-      <literal>I586_CPU</literal> or <literal>I686_CPU</literal>),
-      but for a custom kernel it is best to specify only the CPU
-      you have.  If you are unsure of your CPU type, you can check
-      the <filename>/var/run/dmesg.boot</filename> file to view your
-      boot messages.</para>
+    <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>
@@ -600,37 +550,29 @@ cpu          I686_CPU</programlisting>
 
     <programlisting>ident          GENERIC</programlisting>
 
-    <para>This is the identification of the kernel.  You should change
-      this to whatever you named your kernel,
-      i.e., <literal><replaceable>MYKERNEL</replaceable></literal>
-      if you have followed the instructions of the previous examples.
-      The value you put in the <literal>ident</literal> string will
-      print when you boot up the kernel, so it is useful to give the
-      new kernel a different name if you want to keep it separate
-      from your usual kernel (e.g., you want to build an experimental
-      kernel).</para>
+    <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>#To statically compile in device wiring instead of /boot/device.hints
 #hints          "GENERIC.hints"         # Default places to look for devices.</programlisting>
 
-    <para>The &man.device.hints.5; is
-      used to configure options of the device drivers.  The default
-      location that &man.loader.8; will check at boot time is
-      <filename>/boot/device.hints</filename>.  Using the
-      <literal>hints</literal> option you can compile these hints
-      statically into your kernel.  Then there is no need to create a
-      <filename>device.hints</filename> file in
-      <filename>/boot</filename>.</para>
+    <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>The normal build process of &os; includes
-      debugging information when building the kernel with the
-      <option>-g</option> option, which enables debugging
-      information when passed to &man.gcc.1;.</para>
+    <para>This option enables debugging information when passed to
+      &man.gcc.1;.</para>
 
     <programlisting>options          SCHED_ULE         # ULE scheduler</programlisting>
 
@@ -638,17 +580,14 @@ cpu          I686_CPU</programlisting>
 
     <programlisting>options          PREEMPTION         # Enable kernel thread preemption</programlisting>
 
-    <para>Allows threads that are in the kernel to be preempted
-      by higher priority threads.  It helps with interactivity and
-      allows interrupt threads to run sooner rather than
-      waiting.</para>
+    <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.  Leave this in, even if you do not
-      plan to be connected to a network.  Most programs require at
-      least loopback networking (i.e., making network connections
-      within your PC), so this is essentially mandatory.</para>
+    <para>Networking support.  This is mandatory as most programs
+      require at least loopback networking.</para>
 
     <programlisting>options          INET6             # IPv6 communications protocols</programlisting>
 
@@ -657,40 +596,38 @@ cpu          I686_CPU</programlisting>
     <programlisting>options          FFS               # Berkeley Fast Filesystem</programlisting>
 
     <para>This is the basic hard drive file system.  Leave it in if
-      you boot from the hard disk.</para>
+      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, this will
-      help speed up write access on the disks.  Even when this
+    <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 from &man.mount.8; to
-      see if Soft Updates is enabled for your system disks.  If you
-      do not see the <literal>soft-updates</literal> option then you
-      will need to activate it using the &man.tunefs.8; (for existing
-      file systems) or &man.newfs.8; (for new file systems)
-      commands.</para>
+      for specific disks.  Review the output so &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.  This relies on the use of extended
+    <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 access control lists,
-      changing the way files are protected in unpredictable
-      ways.</para>
+      described in detail in <link linkend="fs-acl"></link>.
+      <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.  You would normally keep this for a large
-      server, or interactive workstation, and remove it if you are
-      using &os; on a smaller system where memory is at a premium and
-      disk access speed is less important, such as a firewall.</para>
+      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>
 
@@ -709,9 +646,10 @@ cpu          I686_CPU</programlisting>
 options          NFSSERVER         # Network Filesystem Server
 options          NFS_ROOT          # NFS usable as /, requires NFSCLIENT</programlisting>
 
-    <para>The network file system.  Unless you plan to mount
-      partitions from a &unix; file server over TCP/IP, you can
-      comment these out.</para>
+    <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>
@@ -719,34 +657,32 @@ options          NFS_ROOT          # NFS
     </indexterm>
     <programlisting>options          MSDOSFS           # MSDOS Filesystem</programlisting>
 
-    <para>The &ms-dos; file system.  Unless you plan to mount a DOS
-      formatted hard drive partition at boot time, you can safely
-      comment this out.  It will be automatically loaded the first
-      time you mount a DOS partition, as described above.  Also,
-      the excellent
-      <filename role="package">emulators/mtools</filename> software
-      allows you to access DOS floppies without having to mount and
-      unmount them (and does not require <literal>MSDOSFS</literal> at
-      all).</para>
+    <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 <filename
+	role="package">emulators/mtools</filename> 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
-      you do not have a CDROM drive or only mount data CDs
-      occasionally (since it will be dynamically loaded the first
-      time you mount a data CD).  Audio CDs do not need this file
+    <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
-      programs like &man.ps.1; to give you 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>: installs will not mount this file
-      system by default.</para>
+      file system mounted on <filename
+	class="directory">/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>
 
@@ -757,51 +693,49 @@ options          NFS_ROOT          # NFS
 
     <para>Adds support for <ulink
 	url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
-      Partition Tables</ulink>.  GPT provides the ability to have a
-      large number of partitions per disk, 128 in the standard
-      configuration.</para>
+	  Partition Tables</ulink> (<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; some programs
-      will act strangely if you comment this out.</para>
+    <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 only in
-      5.X, such as ia64 and &sparc64;, do not require this
-      option.</para>
+    <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>
+    <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>
+    <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>
+    <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 SCSI device in your system.  If you only have IDE hard
-      drives, you can ignore this, otherwise you can try to lower
-      this number, to speed up booting.  Of course, if you do this
-      and &os; has trouble recognizing your SCSI devices, you will
-      have to raise it again.</para>
+      each SCSI device in the system.  If the system only has IDE hard
+      drives, ignore this or lower the number to speed up booting.
+      However, if &os; has trouble recognizing the SCSI devices, the
+      number will have to be raised again.</para>
 
     <programlisting>options          KTRACE            # ktrace(1) support</programlisting>
 
@@ -810,11 +744,11 @@ options          NFS_ROOT          # NFS
 
     <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 you use X, you will definitely
-      want to include this.</para>
+    <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>
 
@@ -823,47 +757,44 @@ options          NFS_ROOT          # NFS
 
     <programlisting>options          SYSVSEM           # SYSV-style semaphores</programlisting>
 
-    <para>Support for System V semaphores.  Less commonly used
+    <para>Support for System V semaphores.  Less commonly used,
       but only adds a few hundred bytes to the kernel.</para>
 
     <note>
-      <para>The <option>-p</option> option of the &man.ipcs.1;
-	command will list any processes using each of these
-	System V facilities.</para>
+      <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
-      (such as <application>&staroffice;</application>).</para>
+      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>
+      device nodes in <filename
+	class="directory">/dev</filename>.</para>
 
     <programlisting>options          ADAPTIVE_GIANT    # Giant mutex is adaptive.</programlisting>
 
-    <para>Giant is the name of a mutual exclusion mechanism (a
-      sleep mutex)that protects a large set of kernel resources.
+    <para>Giant is the name of a mutual exclusion mechanism, a

*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***


More information about the svn-doc-all mailing list