Date: Sun, 17 Feb 2013 17:41:06 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r40999 - head/en_US.ISO8859-1/books/handbook/kernelconfig Message-ID: <201302171741.r1HHf6UX013972@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 µsoft.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@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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201302171741.r1HHf6UX013972>