Date: Wed, 19 Mar 2014 17:14:08 +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: r44289 - head/en_US.ISO8859-1/books/handbook/kernelconfig Message-ID: <201403191714.s2JHE8xn042632@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Wed Mar 19 17:14:08 2014 New Revision: 44289 URL: http://svnweb.freebsd.org/changeset/doc/44289 Log: White space fix only. Translators can ignore. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Wed Mar 19 16:52:25 2014 (r44288) +++ head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Wed Mar 19 17:14:08 2014 (r44289) @@ -69,17 +69,17 @@ </itemizedlist> <para>All of the commands listed in the examples in this chapter - should be executed as <systemitem class="username">root</systemitem>.</para> + should be executed as <systemitem + class="username">root</systemitem>.</para> </sect1> <sect1 xml:id="kernelconfig-custom-kernel"> <title>Why Build a Custom Kernel?</title> - <para>Traditionally, &os; used a monolithic kernel. - The kernel was one large program, supported a fixed list of - devices, and in order to change the kernel's behavior, one had - to compile and then reboot into a new - kernel.</para> + <para>Traditionally, &os; used a monolithic kernel. The kernel + was one large program, supported a fixed list of devices, and in + order to change the kernel's behavior, one had to compile and + then reboot into a new kernel.</para> <para>Today, most of the functionality in the &os; kernel is contained in modules which can be dynamically loaded and @@ -132,12 +132,11 @@ doing so. If there is a need for specific hardware support, it may already exist as a module.</para> - <para>Kernel modules exist in <filename>/boot/kernel</filename> and may be - dynamically loaded into the running kernel using - &man.kldload.8;. Most kernel drivers have a - loadable module and manual page. For example, the &man.ath.4; - wireless Ethernet driver has the following information in its - manual page:</para> + <para>Kernel modules exist in <filename>/boot/kernel</filename> + and may be dynamically loaded into the running kernel using + &man.kldload.8;. Most kernel drivers have a loadable module and + manual page. For example, the &man.ath.4; wireless Ethernet + driver has the following information in its manual page:</para> <screen>Alternatively, to load the driver as a module at boot time, place the following line in &man.loader.conf.5;: @@ -145,11 +144,12 @@ following line in &man.loader.conf.5;: if_ath_load="YES"</screen> <para>Adding <literal>if_ath_load="YES"</literal> to - <filename>/boot/loader.conf</filename> will load this - module dynamically at boot time.</para> + <filename>/boot/loader.conf</filename> will load this module + dynamically at boot time.</para> - <para>In some cases, there is no associated module in <filename>/boot/kernel</filename>. This is - mostly true for certain subsystems.</para> + <para>In some cases, there is no associated module in + <filename>/boot/kernel</filename>. This is mostly true for + certain subsystems.</para> </sect1> <sect1 xml:id="kernelconfig-devices"> @@ -166,11 +166,10 @@ following line in &man.loader.conf.5;: --> <title>Finding the System Hardware</title> - <para>Before editing the kernel configuration file, it is recommended - to perform an inventory of the machine's hardware. On a dual-boot - system, the inventory - can be created from the other operating system. - For example, µsoft;'s + <para>Before editing the kernel configuration file, it is + recommended to perform an inventory of the machine's hardware. + On a dual-boot system, the inventory can be created from the + other operating system. For example, µsoft;'s <application>Device Manager</application> contains information about installed devices.</para> @@ -180,12 +179,11 @@ following line in &man.loader.conf.5;: access <application>Device Manager</application>.</para> </note> - <para>If &os; is the only installed operating system, - use &man.dmesg.8; to determine the hardware that was found and - listed during the boot probe. Most device - drivers on &os; have a manual page which lists the hardware supported by that driver. - For - example, the following lines indicate that the &man.psm.4; + <para>If &os; is the only installed operating system, use + &man.dmesg.8; to determine the hardware that was found and + listed during the boot probe. Most device drivers on &os; have + a manual page which lists the hardware supported by that driver. + For example, the following lines indicate that the &man.psm.4; driver found a mouse:</para> <screen>psm0: <PS/2 Mouse> irq 12 on atkbdc0 @@ -197,12 +195,11 @@ psm0: model Generic PS/2 mouse, device I removed from a custom kernel configuration file.</para> <para>If the output of <command>dmesg</command> does not display - the results of the boot probe output, instead read the contents of - <filename>/var/run/dmesg.boot</filename>.</para> + the results of the boot probe output, instead read the contents + of <filename>/var/run/dmesg.boot</filename>.</para> - <para>Another tool for finding hardware is - &man.pciconf.8;, which provides more verbose output. For - example:</para> + <para>Another tool for finding hardware is &man.pciconf.8;, which + provides more verbose output. For example:</para> <screen>&prompt.user; <userinput>pciconf -lv</userinput> ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00 @@ -211,14 +208,12 @@ ath0@pci0:3:0:0: class=0x020000 c class = network subclass = ethernet</screen> - <para>This output shows that the - <filename>ath</filename> driver located a wireless Ethernet - device.</para> - - <para>The <option>-k</option> flag of &man.man.1; - can be used to provide useful information. For example, to - display a list of manual pages which contain the specified - word:</para> + <para>This output shows that the <filename>ath</filename> driver + located a wireless Ethernet device.</para> + + <para>The <option>-k</option> flag of &man.man.1; can be used to + provide useful information. For example, to display a list of + manual pages which contain the specified word:</para> <screen>&prompt.root; <userinput>man -k <replaceable>Atheros</replaceable></userinput></screen> @@ -252,36 +247,39 @@ ath_hal(4) - Atheros Hardw empty, source has not been installed. Source can be installed using <application>Subversion</application> and the instructions in <xref linkend="svn"/>.</para> - + <para>Once source is installed, review the contents of <filename>/usr/src/sys</filename>. This directory contains a - number of subdirectories, including those which represent the following - supported architectures: <filename>amd64</filename>, <filename>i386</filename>, <filename>ia64</filename>, <filename>pc98</filename>, <filename>powerpc</filename>, and <filename>sparc64</filename>. Everything inside a - particular architecture's directory deals with that architecture - only and the rest of the code is machine independent code common - to all platforms. Each supported architecture has a <filename>conf</filename> subdirectory - which contains the <filename>GENERIC</filename> kernel - configuration file for that architecture.</para> - + number of subdirectories, including those which represent the + following supported architectures: <filename>amd64</filename>, + <filename>i386</filename>, <filename>ia64</filename>, + <filename>pc98</filename>, <filename>powerpc</filename>, and + <filename>sparc64</filename>. Everything inside a particular + architecture's directory deals with that architecture only and + the rest of the code is machine independent code common to all + platforms. Each supported architecture has a + <filename>conf</filename> subdirectory which contains the + <filename>GENERIC</filename> kernel configuration file for that + architecture.</para> + <para>Do not make edits to <filename>GENERIC</filename>. Instead, copy the file to a different name and make edits to the copy. The convention is to use a name with all capital letters. When maintaining multiple &os; machines with different hardware, it is a good idea to name it after the machine's hostname. This - example creates a copy, named <filename>MYKERNEL</filename>, of the - <filename>GENERIC</filename> configuration file for the + example creates a copy, named <filename>MYKERNEL</filename>, of + the <filename>GENERIC</filename> configuration file for the <literal>amd64</literal> architecture:</para> <screen>&prompt.root; <userinput>cd /usr/src/sys/amd64/conf</userinput> &prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen> - <para>The configuration file - <filename>MYKERNEL</filename> can now be customized - with any ASCII text editor. The default editor is - <application>vi</application>, though an easier editor - for beginners, called <application>ee</application>, is also + <para>The configuration file <filename>MYKERNEL</filename> can now + be customized with any ASCII text editor. The default editor is + <application>vi</application>, though an easier editor for + beginners, called <application>ee</application>, is also installed with &os;.</para> - + <indexterm> <primary>kernel</primary> <secondary>NOTES</secondary> @@ -299,9 +297,10 @@ ath_hal(4) - Atheros Hardw ignored. To remove kernel support for a device or subsystem, put a <literal>#</literal> at the beginning of the line representing that device or subsystem. Do not add or remove a - <literal>#</literal> for any line that you do not understand.</para> + <literal>#</literal> for any line that you do not + understand.</para> - <warning> + <warning> <para>It is easy to remove support for a device or option and end up with a broken kernel. For example, if the &man.ata.4; driver is removed from the kernel configuration file, a system @@ -309,8 +308,8 @@ ath_hal(4) - Atheros Hardw in doubt, just leave support in the kernel.</para> </warning> - <para>In addition to the brief descriptions provided in this file, additional - descriptions are contained in + <para>In addition to the brief descriptions provided in this file, + additional descriptions are contained in <filename>NOTES</filename>, which can be found in the same directory as <filename>GENERIC</filename> for that architecture. For architecture independent options, refer to @@ -318,7 +317,8 @@ ath_hal(4) - Atheros Hardw <tip> <para>When finished customizing the kernel configuration file, - save a backup copy to a location outside of <filename>/usr/src</filename>.</para> + save a backup copy to a location outside of + <filename>/usr/src</filename>.</para> <para>Alternately, keep the kernel configuration file elsewhere and create a symbolic link to the file:</para> @@ -332,10 +332,10 @@ ath_hal(4) - Atheros Hardw <para>An <literal>include</literal> directive is available for use in configuration files. This allows another configuration file to be included in the current one, making it easy to maintain - small changes relative to an existing file. If - only a small number of additional options or drivers are - required, this allows a delta to be maintained with respect - to <filename>GENERIC</filename>, as seen in this example:</para> + small changes relative to an existing file. If only a small + number of additional options or drivers are required, this + allows a delta to be maintained with respect to + <filename>GENERIC</filename>, as seen in this example:</para> <programlisting>include GENERIC ident MYKERNEL @@ -346,17 +346,19 @@ options IPFIREWALL_DEFAULT_TO_AC options IPDIVERT</programlisting> <para>Using this method, the local configuration file expresses - local differences from a <filename>GENERIC</filename> - kernel. As upgrades are performed, new features added to + local differences from a <filename>GENERIC</filename> kernel. + As upgrades are performed, new features added to <filename>GENERIC</filename> will also be added to the local kernel unless they are specifically prevented using - <literal>nooptions</literal> or <literal>nodevice</literal>. - A comprehensive list of configuration directives and their + <literal>nooptions</literal> or <literal>nodevice</literal>. A + comprehensive list of configuration directives and their descriptions may be found in &man.config.5;.</para> <note> <para>To build a file which contains all available options, - run the following command as <systemitem class="username">root</systemitem>:</para> + run the following command as <systemitem + class="username">root</systemitem>:</para> + <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>arch</replaceable>/conf && make LINT</userinput></screen> </note> @@ -461,9 +463,10 @@ options NFS_ROOT # NFS <para>The &ms-dos; file system. Unless the system needs to mount a DOS formatted hard drive partition at boot time, comment this out. It will be automatically loaded the first time a DOS - partition is mounted. The <package>emulators/mtools</package> package allows - access to DOS floppies without having to mount and unmount - them and does not require <literal>MSDOSFS</literal>.</para> + partition is mounted. The <package>emulators/mtools</package> + package allows access to DOS floppies without having to mount + and unmount them and does not require + <literal>MSDOSFS</literal>.</para> <programlisting>options CD9660 # ISO 9660 Filesystem</programlisting> @@ -476,24 +479,26 @@ options NFS_ROOT # NFS <programlisting>options PROCFS # Process filesystem (requires PSEUDOFS)</programlisting> <para>The process file system. This is a <quote>pretend</quote> - file system mounted on <filename>/proc</filename> which allows some programs - to provide more information on what processes are running. Use - of <literal>PROCFS</literal> is not required under most - circumstances, as most debugging and monitoring tools have been - adapted to run without <literal>PROCFS</literal>. The default - installation will not mount this file system by default.</para> + file system mounted on <filename>/proc</filename> which allows + some programs to provide more information on what processes are + running. Use of <literal>PROCFS</literal> is not required under + most circumstances, as most debugging and monitoring tools have + been adapted to run without <literal>PROCFS</literal>. The + default installation will not mount this file system by + default.</para> <programlisting>options PSEUDOFS # Pseudo-filesystem framework</programlisting> - <para>Kernels making use of <literal>PROCFS</literal> must - also include support for <literal>PSEUDOFS</literal>.</para> + <para>Kernels making use of <literal>PROCFS</literal> must + also include support for <literal>PSEUDOFS</literal>.</para> <programlisting>options GEOM_PART_GPT # GUID Partition Tables.</programlisting> - <para>Adds support for <link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID - Partition Tables</link> (<acronym>GPT</acronym>). GPT - provides the ability to have a large number of partitions per - disk, 128 in the standard configuration.</para> + <para>Adds support for <link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID + Partition Tables</link> (<acronym>GPT</acronym>). GPT + provides the ability to have a large number of partitions per + disk, 128 in the standard configuration.</para> <programlisting>options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!]</programlisting> @@ -995,7 +1000,8 @@ device loop # Network loopbac <programlisting>device tun # Packet tunnel.</programlisting> - <para>This is used by the userland PPP software. See the <link linkend="userppp">PPP</link> section of the Handbook for more + <para>This is used by the userland PPP software. See the <link + linkend="userppp">PPP</link> section of the Handbook for more information.</para> <programlisting><anchor xml:id="kernelconfig-ptys"/> @@ -1076,7 +1082,7 @@ device fwe # Ethernet &os;, see <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename>.</para> --> - + <!-- This section refers to ancient hardware. <sect2> @@ -1166,21 +1172,22 @@ device fwe # Ethernet information on &os;'s <acronym>PAE</acronym> support.</para> </sect2> --> - </sect1> + </sect1> <sect1 xml:id="kernelconfig-building"> <title>Building and Installing a Custom Kernel</title> <para>Once the edits to the custom configuration file have been - saved, the source code for the - kernel can be compiled using the following steps:</para> + saved, the source code for the kernel can be compiled using the + following steps:</para> <procedure> <title>Building a Kernel</title> - <indexterm> - <primary>kernel</primary> - <secondary>building / installing</secondary> - </indexterm> + + <indexterm> + <primary>kernel</primary> + <secondary>building / installing</secondary> + </indexterm> <step> <para>Change to this directory:</para> @@ -1197,13 +1204,14 @@ device fwe # Ethernet <step> <para>Install the new kernel associated with the specified - kernel configuration file. This command will copy the new kernel to - <filename>/boot/kernel/kernel</filename> and save the old kernel - to <filename>/boot/kernel.old/kernel</filename>:</para> + kernel configuration file. This command will copy the new + kernel to <filename>/boot/kernel/kernel</filename> and save + the old kernel to + <filename>/boot/kernel.old/kernel</filename>:</para> <screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> </step> - + <step> <para>Shutdown the system and reboot into the new kernel. If something goes wrong, refer to <xref @@ -1211,46 +1219,46 @@ device fwe # Ethernet </step> </procedure> - <para>By default, when a custom kernel is compiled, - all kernel modules are rebuilt. - To update a kernel faster or to build only custom modules, - edit <filename>/etc/make.conf</filename> before starting to - build the kernel.</para> + <para>By default, when a custom kernel is compiled, all kernel + modules are rebuilt. To update a kernel faster or to build + only custom modules, edit <filename>/etc/make.conf</filename> + before starting to build the kernel.</para> - <para>For example, this variable specifies the list of modules to build - instead of using the default of building all modules:</para> + <para>For example, this variable specifies the list of modules to + build instead of using the default of building all + modules:</para> - <programlisting>MODULES_OVERRIDE = linux acpi ntfs</programlisting> + <programlisting>MODULES_OVERRIDE = linux acpi ntfs</programlisting> - <para>Alternately, this variable lists which modules to - exclude from the build process:</para> + <para>Alternately, this variable lists which modules to exclude + from the build process:</para> - <programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting> + <programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting> - <para>Additional variables are available. - Refer to &man.make.conf.5; for details.</para> + <para>Additional variables are available. Refer to + &man.make.conf.5; for details.</para> <indexterm> <primary><filename>/boot/kernel.old</filename></primary> </indexterm> </sect1> - <sect1 xml:id="kernelconfig-trouble"> - <title>If Something Goes Wrong</title> + <sect1 xml:id="kernelconfig-trouble"> + <title>If Something Goes Wrong</title> - <para>There are four categories of trouble that can occur when - building a custom kernel:</para> + <para>There are four categories of trouble that can occur when + building a custom kernel:</para> - <variablelist> - <varlistentry> - <term><command>config</command> fails</term> + <variablelist> + <varlistentry> + <term><command>config</command> fails</term> - <listitem> - <para>If <command>config</command> fails, it will print the line - number that is incorrect. As an example, for - the following message, make sure that line 17 is typed correctly by - comparing it to - <filename>GENERIC</filename> or <filename>NOTES</filename>:</para> + <listitem> + <para>If <command>config</command> fails, it will print the + line number that is incorrect. As an example, for the + following message, make sure that line 17 is typed + correctly by comparing it to <filename>GENERIC</filename> + or <filename>NOTES</filename>:</para> <screen>config: line 17: syntax error</screen> </listitem> @@ -1261,16 +1269,17 @@ device fwe # Ethernet <listitem> <para>If <command>make</command> fails, it is usually due to - an error in the kernel configuration file which is not severe - enough for <command>config</command> to catch. Review the - configuration, and if the problem is not apparent, - send an email to the &a.questions; which contains the - kernel configuration file.</para> + an error in the kernel configuration file which is not + severe enough for <command>config</command> to catch. + Review the configuration, and if the problem is not + apparent, send an email to the &a.questions; which + contains the kernel configuration file.</para> </listitem> </varlistentry> <varlistentry> - <term>The kernel does not boot<anchor xml:id="kernelconfig-noboot"/></term> + <term>The kernel does not boot<anchor + xml:id="kernelconfig-noboot"/></term> <listitem> <para>If the new kernel does not boot or fails to recognize @@ -1280,9 +1289,8 @@ device fwe # Ethernet loader. This can be accessed when the system boot menu appears by selecting the <quote>Escape to a loader prompt</quote> option. At the prompt, type - <command>boot - kernel.old</command>, or - the name of any other kernel that is known to boot properly.</para> + <command>boot kernel.old</command>, or the name of any + other kernel that is known to boot properly.</para> <para>After booting with a good kernel, check over the configuration file and try to build it again. One helpful @@ -1293,19 +1301,17 @@ device fwe # Ethernet <note> <para>When troubleshooting a kernel, make sure to keep - a copy of <filename>GENERIC</filename>, or some other kernel that - is known to work, as a different name that will - not get erased on the next build. This is important - because every time - a new kernel is installed, <filename>kernel.old</filename> is - overwritten with the last installed kernel, which may or - may not be bootable. As soon as possible, move the - working kernel by renaming the directory - containing the good kernel:</para> + a copy of <filename>GENERIC</filename>, or some other + kernel that is known to work, as a different name that + will not get erased on the next build. This is + important because every time a new kernel is installed, + <filename>kernel.old</filename> is overwritten with the + last installed kernel, which may or may not be bootable. + As soon as possible, move the working kernel by renaming + the directory containing the good kernel:</para> <screen>&prompt.root; <userinput>mv /boot/kernel /boot/kernel.bad</userinput> &prompt.root; <userinput>mv /boot/kernel.good /boot/kernel</userinput></screen> - </note> </listitem> </varlistentry> @@ -1316,13 +1322,14 @@ device fwe # Ethernet <listitem> <para>If the kernel version differs from the one that the system utilities have been built with, for example, a - kernel built from -CURRENT sources is installed on a -RELEASE system, many system status commands - like &man.ps.1; and &man.vmstat.8; will not work. To fix - this, <link linkend="makeworld">recompile and install a - world</link> built with the same version of the - source tree as the kernel. It is - never a good idea to use a different version of the kernel - than the rest of the operating system.</para> + kernel built from -CURRENT sources is installed on a + -RELEASE system, many system status commands like + &man.ps.1; and &man.vmstat.8; will not work. To fix this, + <link linkend="makeworld">recompile and install a + world</link> built with the same version of the source + tree as the kernel. It is never a good idea to use a + different version of the kernel than the rest of the + operating system.</para> </listitem> </varlistentry> </variablelist>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403191714.s2JHE8xn042632>