diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml index cd2038a24e..de9ce7223f 100644 --- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml @@ -69,17 +69,17 @@ All of the commands listed in the examples in this chapter - should be executed as root. + should be executed as root. Why Build a Custom Kernel? - 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. + 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. 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. - Kernel modules exist in /boot/kernel 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: + Kernel modules exist in /boot/kernel + 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: 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" Adding if_ath_load="YES" to - /boot/loader.conf will load this - module dynamically at boot time. + /boot/loader.conf will load this module + dynamically at boot time. - In some cases, there is no associated module in /boot/kernel. This is - mostly true for certain subsystems. + In some cases, there is no associated module in + /boot/kernel. This is mostly true for + certain subsystems. @@ -166,11 +166,10 @@ following line in &man.loader.conf.5;: --> Finding the System Hardware - 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 + 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 Device Manager contains information about installed devices. @@ -180,12 +179,11 @@ following line in &man.loader.conf.5;: access Device Manager. - 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; + 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: psm0: <PS/2 Mouse> irq 12 on atkbdc0 @@ -197,12 +195,11 @@ psm0: model Generic PS/2 mouse, device ID 0 removed from a custom kernel configuration file. If the output of dmesg does not display - the results of the boot probe output, instead read the contents of - /var/run/dmesg.boot. + the results of the boot probe output, instead read the contents + of /var/run/dmesg.boot. - Another tool for finding hardware is - &man.pciconf.8;, which provides more verbose output. For - example: + Another tool for finding hardware is &man.pciconf.8;, which + provides more verbose output. For example: &prompt.user; pciconf -lv 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 card=0x058a1014 chip=0x1014168c rev=0x01 class = network subclass = ethernet - This output shows that the - ath driver located a wireless Ethernet - device. + This output shows that the ath driver + located a wireless Ethernet device. - The 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: + The 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: &prompt.root; man -k Atheros @@ -252,36 +247,39 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL) empty, source has not been installed. Source can be installed using Subversion and the instructions in . - + Once source is installed, review the contents of /usr/src/sys. This directory contains a - number of subdirectories, including those which represent the following - supported architectures: amd64, i386, ia64, pc98, powerpc, and sparc64. 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 conf subdirectory - which contains the GENERIC kernel - configuration file for that architecture. - + number of subdirectories, including those which represent the + following supported architectures: amd64, + i386, ia64, + pc98, powerpc, and + sparc64. 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 + conf subdirectory which contains the + GENERIC kernel configuration file for that + architecture. + Do not make edits to GENERIC. 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 MYKERNEL, of the - GENERIC configuration file for the + example creates a copy, named MYKERNEL, of + the GENERIC configuration file for the amd64 architecture: &prompt.root; cd /usr/src/sys/amd64/conf &prompt.root; cp GENERIC MYKERNEL - The configuration file - MYKERNEL can now be customized - with any ASCII text editor. The default editor is - vi, though an easier editor - for beginners, called ee, is also + The configuration file MYKERNEL can now + be customized with any ASCII text editor. The default editor is + vi, though an easier editor for + beginners, called ee, is also installed with &os;. - + kernel NOTES @@ -299,9 +297,10 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL) ignored. To remove kernel support for a device or subsystem, put a # at the beginning of the line representing that device or subsystem. Do not add or remove a - # for any line that you do not understand. + # for any line that you do not + understand. - + 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 Hardware Access Layer (HAL) in doubt, just leave support in the kernel. - In addition to the brief descriptions provided in this file, additional - descriptions are contained in + In addition to the brief descriptions provided in this file, + additional descriptions are contained in NOTES, which can be found in the same directory as GENERIC for that architecture. For architecture independent options, refer to @@ -318,7 +317,8 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL) When finished customizing the kernel configuration file, - save a backup copy to a location outside of /usr/src. + save a backup copy to a location outside of + /usr/src. Alternately, keep the kernel configuration file elsewhere and create a symbolic link to the file: @@ -332,10 +332,10 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL) An include 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 GENERIC, as seen in this example: + 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 + GENERIC, as seen in this example: include GENERIC ident MYKERNEL @@ -346,17 +346,19 @@ options IPFIREWALL_DEFAULT_TO_ACCEPT options IPDIVERT Using this method, the local configuration file expresses - local differences from a GENERIC - kernel. As upgrades are performed, new features added to + local differences from a GENERIC kernel. + As upgrades are performed, new features added to GENERIC will also be added to the local kernel unless they are specifically prevented using - nooptions or nodevice. - A comprehensive list of configuration directives and their + nooptions or nodevice. A + comprehensive list of configuration directives and their descriptions may be found in &man.config.5;. To build a file which contains all available options, - run the following command as root: + run the following command as root: + &prompt.root; cd /usr/src/sys/arch/conf && make LINT @@ -461,9 +463,10 @@ options NFS_ROOT # NFS usable as /, requires NFSCLIENTThe &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 emulators/mtools package allows - access to DOS floppies without having to mount and unmount - them and does not require MSDOSFS. + partition is mounted. The emulators/mtools + package allows access to DOS floppies without having to mount + and unmount them and does not require + MSDOSFS. options CD9660 # ISO 9660 Filesystem @@ -476,24 +479,26 @@ options NFS_ROOT # NFS usable as /, requires NFSCLIENToptions PROCFS # Process filesystem (requires PSEUDOFS) The process file system. This is a pretend - file system mounted on /proc which allows some programs - to provide more information on what processes are running. Use - of PROCFS is not required under most - circumstances, as most debugging and monitoring tools have been - adapted to run without PROCFS. The default - installation will not mount this file system by default. + file system mounted on /proc which allows + some programs to provide more information on what processes are + running. Use of PROCFS is not required under + most circumstances, as most debugging and monitoring tools have + been adapted to run without PROCFS. The + default installation will not mount this file system by + default. options PSEUDOFS # Pseudo-filesystem framework - Kernels making use of PROCFS must - also include support for PSEUDOFS. + Kernels making use of PROCFS must + also include support for PSEUDOFS. options GEOM_PART_GPT # GUID Partition Tables. - Adds support for GUID - Partition Tables (GPT). GPT - provides the ability to have a large number of partitions per - disk, 128 in the standard configuration. + Adds support for GUID + Partition Tables (GPT). GPT + provides the ability to have a large number of partitions per + disk, 128 in the standard configuration. options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!] @@ -995,7 +1000,8 @@ device loop # Network loopback device tun # Packet tunnel. - This is used by the userland PPP software. See the PPP section of the Handbook for more + This is used by the userland PPP software. See the PPP section of the Handbook for more information. @@ -1076,7 +1082,7 @@ device fwe # Ethernet over FireWire (non-standard!)/usr/src/sys/arch/conf/NOTES. --> - + - + Building and Installing a Custom Kernel Once the edits to the custom configuration file have been - saved, the source code for the - kernel can be compiled using the following steps: + saved, the source code for the kernel can be compiled using the + following steps: Building a Kernel - - kernel - building / installing - + + + kernel + building / installing + Change to this directory: @@ -1197,13 +1204,14 @@ device fwe # Ethernet over FireWire (non-standard!) Install the new kernel associated with the specified - kernel configuration file. This command will copy the new kernel to - /boot/kernel/kernel and save the old kernel - to /boot/kernel.old/kernel: + kernel configuration file. This command will copy the new + kernel to /boot/kernel/kernel and save + the old kernel to + /boot/kernel.old/kernel: &prompt.root; make installkernel KERNCONF=MYKERNEL - + Shutdown the system and reboot into the new kernel. If something goes wrong, refer to - 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 /etc/make.conf before starting to - build the kernel. + 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 /etc/make.conf + before starting to build the kernel. - For example, this variable specifies the list of modules to build - instead of using the default of building all modules: + For example, this variable specifies the list of modules to + build instead of using the default of building all + modules: - MODULES_OVERRIDE = linux acpi ntfs + MODULES_OVERRIDE = linux acpi ntfs - Alternately, this variable lists which modules to - exclude from the build process: + Alternately, this variable lists which modules to exclude + from the build process: - WITHOUT_MODULES = linux acpi sound ntfs + WITHOUT_MODULES = linux acpi sound ntfs - Additional variables are available. - Refer to &man.make.conf.5; for details. + Additional variables are available. Refer to + &man.make.conf.5; for details. /boot/kernel.old - - If Something Goes Wrong + + If Something Goes Wrong - There are four categories of trouble that can occur when - building a custom kernel: + There are four categories of trouble that can occur when + building a custom kernel: - - - config fails + + + config fails - - If config 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 - GENERIC or NOTES: + + If config 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 GENERIC + or NOTES: config: line 17: syntax error @@ -1261,16 +1269,17 @@ device fwe # Ethernet over FireWire (non-standard!) If make fails, it is usually due to - an error in the kernel configuration file which is not severe - enough for config 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. + an error in the kernel configuration file which is not + severe enough for config 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. - The kernel does not boot + The kernel does not boot If the new kernel does not boot or fails to recognize @@ -1280,9 +1289,8 @@ device fwe # Ethernet over FireWire (non-standard!)Escape to a loader prompt option. At the prompt, type - boot - kernel.old, or - the name of any other kernel that is known to boot properly. + boot kernel.old, or the name of any + other kernel that is known to boot properly. 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 over FireWire (non-standard!) When troubleshooting a kernel, make sure to keep - a copy of GENERIC, 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, kernel.old 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: + a copy of GENERIC, 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, + kernel.old 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: &prompt.root; mv /boot/kernel /boot/kernel.bad &prompt.root; mv /boot/kernel.good /boot/kernel - @@ -1316,13 +1322,14 @@ device fwe # Ethernet over FireWire (non-standard!) 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, recompile and install a - world 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. + 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, + recompile and install a + world 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.