From owner-svn-doc-all@FreeBSD.ORG Fri Oct 4 17:29:34 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id C2F62D7D; Fri, 4 Oct 2013 17:29:34 +0000 (UTC) (envelope-from dru@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id AE64D2B0A; Fri, 4 Oct 2013 17:29:34 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r94HTYDc025325; Fri, 4 Oct 2013 17:29:34 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r94HTYYp025321; Fri, 4 Oct 2013 17:29:34 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201310041729.r94HTYYp025321@svn.freebsd.org> From: Dru Lavigne Date: Fri, 4 Oct 2013 17:29:34 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42827 - in head/en_US.ISO8859-1/books/handbook: bsdinstall kernelconfig X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 04 Oct 2013 17:29:34 -0000 Author: dru Date: Fri Oct 4 17:29:34 2013 New Revision: 42827 URL: http://svnweb.freebsd.org/changeset/doc/42827 Log: This patch does the following: - comments author names - incorporates "9.4. Kernel Drivers, Subsystems, and Modules" into "9.2. Why Build a Custom Kernel?" - fixes reference to 9.4 in bsdinstall chapter - puts the configuration file section before the building the kernel section - makes it clearer how to get src and cp the needed config file - general wordsmithing to make the first half of this chapter less confusing Approved by: gjb (mentor) Modified: head/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml Fri Oct 4 15:14:58 2013 (r42826) +++ head/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml Fri Oct 4 17:29:34 2013 (r42827) @@ -936,7 +936,7 @@ Trying to mount root from cd9660:/dev/is Check the probe results carefully to make sure that &os; found all the devices you expected. If a device was not found, then it will not be listed. Kernel modules allows + linkend="kernelconfig-custom-kernel">Kernel modules allows you to add in support for devices which are not in the GENERIC kernel. Modified: head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Fri Oct 4 15:14:58 2013 (r42826) +++ head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Fri Oct 4 17:29:34 2013 (r42827) @@ -7,22 +7,20 @@ - + + Updated and restructured in Mar 2000 by Jake Hamby - Originally contributed by - + Originally contributed 6 Oct 1995 by - + --> Configuring the FreeBSD Kernel @@ -49,6 +47,10 @@ + How to take a hardware inventory. + + + How to customize a kernel configuration file. @@ -73,10 +75,10 @@ Why Build a Custom Kernel? - Traditionally, &os; used a monolithic 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 a new kernel, and then reboot into the new + to compile and then reboot into a new kernel. Today, most of the functionality in the &os; kernel is @@ -87,10 +89,10 @@ a modular kernel. Occasionally, it is still necessary to perform static kernel - configuration. This may be because the functionality is so tied + configuration. Sometimes the needed 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 + kernel modules and require that only needed functionality is statically compiled into the kernel. Building a custom kernel is often a rite of passage for @@ -120,45 +122,69 @@ - Additional hardware support. A custom kernel can add in + Additional hardware support. A custom kernel can add support for devices which are not present in the GENERIC kernel. + + 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. + + 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;: + + if_ath_load="YES" + + Adding if_ath_load="YES" to + /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. - + Finding the System Hardware - 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 can be created by viewing the current operating system - configuration. 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. Some versions of µsoft.windows; have a - System icon which will display a - screen where Device Manager may - be accessed. + System icon which can be used to + access Device Manager. - If another operating system does not exist on the machine, - the administrator must find this information out manually. One - 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 + 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: @@ -167,32 +193,29 @@ psm0: [GIANT-LOCKED] psm0: [ITHREAD] psm0: model Generic PS/2 mouse, device ID 0 - This driver will need to be included in the custom kernel - configuration file or loaded using &man.loader.conf.5;. + Since this hardware exists, this driver should not be removed from a custom kernel + configuration file. - On occasion, the data from dmesg will - only show system messages instead of the boot probe output. In - these situations, the output may be obtained by reading + If the output of dmesg does not display + the results of the boot probe output, instead read the contents of /var/run/dmesg.boot. - Another method for finding hardware is to use - &man.pciconf.8; which provides more verbose output. For + Another tool for finding hardware is + &man.pciconf.8;, which provides more verbose output. For example: - ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00 + pciconf + ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00 vendor = 'Atheros Communications Inc.' device = 'AR5212 Atheros AR5212 802.11abg wireless' class = network subclass = ethernet - This output, obtained by using - pciconf , shows that the + This output shows that the ath driver located a wireless Ethernet - device. Type man - ath to read - &man.ath.4;. + device. - The flag, when passed to &man.man.1; + 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: @@ -202,253 +225,85 @@ psm0: model Generic PS/2 mouse, device I ath(4) - Atheros IEEE 802.11 wireless network driver ath_hal(4) - Atheros Hardware Access Layer (HAL) - Armed with a hardware inventory list, the process of - building a custom kernel should appear less daunting. + Once the hardware inventory list is created, refer to it + to ensure that installed hardware is not removed as you edit the custom + kernel configuration file. - - Kernel Drivers, Subsystems, and Modules - - - kernel - drivers / modules / subsystems - - - 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. - - Kernel modules exist in /boot/kernel and may be - dynamically loaded into the running kernel using - &man.kldload.8;. Most, if not all 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;: - - if_ath_load="YES" - - Adding if_ath_load="YES" to - /boot/loader.conf will enable loading this - module dynamically at boot time. - - 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. - - - 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 ATA disk drivers may not boot. When - in doubt, just leave support in the kernel. - - - - - Building and Installing a Custom Kernel - - - kernel - building / installing - + + + + + The Configuration File - - It is required to have the full &os; source tree installed - to build the kernel. - + In order to create a custom kernel configuration file and + build a custom kernel, the full &os; source tree must first be installed. - The kernel build is located at /usr/src/sys. It contains a - number of subdirectories representing different parts of the - kernel. These include arch/conf, - which contains the kernel configuration file, and - compile, which is the - staging area where the kernel will be built. - arch contains subdirectories for each - supported architecture: i386, If /usr/src/ does + not exist or it is empty, source has not been installed. + Source can be installed using + svn, which is described in , or by installing the + src distribution using &man.sysinstall.8;. This + distribution can be selected by navigating to the + Configuration and then to the + Distributions menu within &man.sysinstall.8;. + + 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, powerpc, sparc64, and pc98. Everything inside a + class="directory">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. Notice the logical organization of the - directory structure, with each supported device, file system, - and option in its own subdirectory. - - The examples in this chapter assume the i386 architecture. - If the system has a different architecture, change the path - names accordingly. - - - If /usr/src/ does - not exist or it is empty, source has not been installed. The - easiest way to install source is to use - svn as described in . One should also create a symlink to - /usr/src/sys/: - - &prompt.root; ln -s /usr/src/sys /sys - - - Next, cd to arch/conf - and copy the GENERIC configuration file to - the name of the custom kernel. For example: - - &prompt.root; cd /usr/src/sys/i386/conf -&prompt.root; cp GENERIC MYKERNEL - - Traditionally, this name is in all capital letters. When + 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 uses - MYKERNEL. + example creates a custom configuration file for the + amd64 architecture: + + &prompt.root; cd /usr/src/sys/amd64/conf +&prompt.root; cp GENERIC MYKERNEL When finished customizing the kernel configuration file, save a backup copy to a location outside of /usr/src. Do not edit - GENERIC directly. + class="directory">/usr/src. Alternately, keep the kernel configuration file elsewhere - and create a symbolic link to the file in i386. + and create a symbolic link to the file: - For example: - - &prompt.root; cd /usr/src/sys/i386/conf + &prompt.root; cd /usr/src/sys/amd64/conf &prompt.root; mkdir /root/kernels &prompt.root; cp GENERIC /root/kernels/MYKERNEL &prompt.root; ln -s /root/kernels/MYKERNEL - Edit - MYKERNEL - with a text editor. The default editor is - vi, whose usage is covered well in - many books in the bibliography. An easier editor + 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 - available. Feel free to change the comment lines at the top to - reflect the configuration or the changes made to differentiate - it from GENERIC. - - If the GENERIC configuration file seems - overwhelming, follow the descriptions in the Configuration File - section slowly and carefully. - - - After syncing the source tree - with the latest sources, always read - /usr/src/UPDATING - before performing any update steps. This file describes any - important issues or areas requiring special attention within - the updated source code. - /usr/src/UPDATING always matches - the version of the &os; source and contains more up-to-date - information than this Handbook. - - - After saving the edits, compile the source code for the - kernel. - - - Building a Kernel - - - It is required to have the full &os; source tree - installed to build the kernel. - - - - cd to /usr/src: - - &prompt.root; cd /usr/src - - - - Compile the new kernel by specifying the name of the - custom kernel configuration file: - - &prompt.root; make buildkernel KERNCONF=MYKERNEL - - - - Install the new kernel: - - &prompt.root; make installkernel KERNCONF=MYKERNEL - - - - - By default, when a custom kernel is compiled, - all kernel modules are rebuilt as well. - To update a kernel faster or to build only custom modules, - edit /etc/make.conf before starting to - build the kernel: - - MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs - - This variable specifies the list of modules to build - instead the default of building of all of them. - - WITHOUT_MODULES = linux acpi sound ntfs - - This variable sets up a list of top level modules to - exclude from the build process. For other available - variables, refer to &man.make.conf.5;. - - - - /boot/kernel.old - - - The new kernel will be copied to /boot/kernel as - /boot/kernel/kernel and the old kernel - will be moved to /boot/kernel.old/kernel. - Now, shutdown the system and reboot into the new kernel. - If something goes wrong, refer to the troubleshooting - instructions and the section which explains how to - recover when the new kernel does not boot. - - - Other files relating to the boot process, such as the boot - &man.loader.8; and configuration, are stored in /boot. Third party or - custom modules can be placed in /boot/kernel, 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. - - - - - - - - Joel - Dahl - Updated by - - - - The Configuration File - + installed with &os;. + kernel NOTES @@ -459,14 +314,18 @@ following line in &man.loader.conf.5;: configuration file - The general format of a configuration file is quite simple. - Each line contains a keyword and one or more arguments. For - simplicity, most lines only contain one argument. Anything - following a # is considered a comment and - ignored. The following sections describe each keyword, in - the order they are listed in GENERIC. - For an exhaustive list of architecture dependent options and - devices, refer to NOTES in the same + The format of the kernel configuration file is simple. + Each line contains a keyword that represents a device or + subsystem, an argument, and a brief description. Any text + after a # is considered a comment and + 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. + + 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 /usr/src/sys/conf/NOTES. @@ -490,60 +349,18 @@ options IPDIVERTUsing this method, the local configuration file expresses local differences from a GENERIC kernel. As upgrades are performed, new features added to - GENERIC will be also be added to the local + 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 descriptions may be found in &man.config.5;. - The remainder of this chapter addresses the contents of a - typical configuration file and the role various options and - devices play. - To build a file which contains all available options, run the following command as root: &prompt.root; cd /usr/src/sys/i386/conf && make LINT - - kernel - configuration file - - - The following is an example of the - GENERIC kernel configuration file with - various additional comments where needed for clarity. This - example should match the copy in - /usr/src/sys/i386/conf/GENERIC - fairly closely. - - - kernel options - machine - - - machine i386 - - This is the machine architecture. It must be either - amd64, i386, - ia64, pc98, - powerpc, or - sparc64. - - - kernel options - cpu - - cpu I486_CPU -cpu I586_CPU -cpu I686_CPU - - 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 - /var/run/dmesg.boot. kernel options @@ -558,19 +375,6 @@ cpu I686_CPU The value in the ident string will print when the kernel boots. - #To statically compile in device wiring instead of /boot/device.hints -#hints "GENERIC.hints" # Default places to look for devices. - - &man.device.hints.5; is used to configure options for device - drivers. The default location is - /boot/device.hints. The - hints option compiles these hints statically - into the kernel so that there is no need to create - /boot/device.hints. - - - makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols This option enables debugging information when passed to @@ -580,12 +384,6 @@ cpu I686_CPU The default system scheduler for &os;. Keep this. - options PREEMPTION # Enable kernel thread preemption - - Allows kernel threads to be preempted by higher priority - threads. This helps with interactivity and allows interrupt - threads to run sooner rather than waiting. - options INET # InterNETworking Networking support. This is mandatory as most programs @@ -1370,6 +1168,112 @@ device fwe # Ethernet + + Building and Installing a Custom Kernel + + After saving the edits, compile the source code for the + kernel. + + + After syncing the source tree + with the latest sources, always read + /usr/src/UPDATING + before performing any update steps. This file describes any + important issues or areas requiring special attention within + the updated source code. + /usr/src/UPDATING always matches + the version of the &os; source and contains more up-to-date + information than this Handbook. + + + + 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 ATA disk drivers may not boot. When + in doubt, just leave support in the kernel. + + + + Building a Kernel + + kernel + building / installing + + + + It is required to have the full &os; source tree + installed to build the kernel. + + + + cd to /usr/src: + + &prompt.root; cd /usr/src + + + + Compile the new kernel by specifying the name of the + custom kernel configuration file: + + &prompt.root; make buildkernel KERNCONF=MYKERNEL + + + + Install the new kernel: + + &prompt.root; make installkernel KERNCONF=MYKERNEL + + + + + By default, when a custom kernel is compiled, + all kernel modules are rebuilt as well. + To update a kernel faster or to build only custom modules, + edit /etc/make.conf before starting to + build the kernel: + + MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs + + This variable specifies the list of modules to build + instead the default of building of all of them. + + WITHOUT_MODULES = linux acpi sound ntfs + + This variable sets up a list of top level modules to + exclude from the build process. For other available + variables, refer to &man.make.conf.5;. + + + + /boot/kernel.old + + + The new kernel will be copied to /boot/kernel as + /boot/kernel/kernel and the old kernel + will be moved to /boot/kernel.old/kernel. + Now, shutdown the system and reboot into the new kernel. + If something goes wrong, refer to the troubleshooting + instructions and the section which explains how to + recover when the new kernel does not boot. + + + Other files relating to the boot process, such as the boot + &man.loader.8; and configuration, are stored in /boot. Third party or + custom modules can be placed in /boot/kernel, 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. + + + If Something Goes Wrong