Handbook - kernelconfig: Global review

Changes:

* Make the first paragraph a note
* AsciiDoc tweaks
* Remove stale architectures
* Remove editors paragraph
* Add link to config(5)
* Remove pssection
* Restore PORTS_MODULE variable

Reviewed by:            fernape@, karels@, mhorne@
Differential Revision:  https://reviews.freebsd.org/D39836

1 files changed, 84 insertions, 63 deletions

diff --git a/documentation/content/en/books/handbook/kernelconfig/_index.adoc b/documentation/content/en/books/handbook/kernelconfig/_index.adoc
index 2bc4c8a19a..9b5c761547 100644
--- a/documentation/content/en/books/handbook/kernelconfig/_index.adoc
+++ b/documentation/content/en/books/handbook/kernelconfig/_index.adoc
@@ -64,7 +64,10 @@ After reading this chapter, you will know:
 * How to install the new kernel.
 * How to troubleshoot if things go wrong.
 
+[NOTE]
+====
 All of the commands listed in the examples in this chapter should be executed as `root`.
+====
 
 [[kernelconfig-custom-kernel]]
 == Why Build a Custom Kernel?
@@ -82,29 +85,35 @@ Some security environments prevent the loading and unloading of kernel modules a
 
 Building a custom kernel is often a rite of passage for advanced BSD users.
 This process, while time consuming, can provide benefits to the FreeBSD system.
-Unlike the [.filename]#GENERIC# 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.
+Unlike the `GENERIC` 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:
 
 * Faster boot time. Since the kernel will only probe the hardware on the system, the time it takes the system to boot can decrease.
-* Lower memory usage. A custom kernel often uses less memory than the [.filename]#GENERIC# kernel by omitting unused features and device drivers. This is 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 useful on a system with a small amount of RAM.
-* Additional hardware support. A custom kernel can add support for devices which are not present in the [.filename]#GENERIC# kernel.
+* Lower memory usage. A custom kernel often uses less memory than the `GENERIC` kernel by omitting unused features and device drivers. This is 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 useful on a system with a small amount of RAM.
+* Additional hardware support. A custom kernel can add support for devices which are not present in the `GENERIC` kernel.
 
+[NOTE]
+====
 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 [.filename]#/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 network driver has the following information in its manual page:
 
-[source,shell,subs="macros"]
+[.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"
+      if_ath_load="YES"
+      if_ath_pci_load="YES"
 ....
 
-Adding `if_ath_load="YES"` to [.filename]#/boot/loader.conf# will load this module dynamically at boot time.
+Adding `if_ath_load="YES"` and `if_ath_pci_load="YES"` to [.filename]#/boot/loader.conf# will load these modules dynamically at boot time.
 
 In some cases, there is no associated module in [.filename]#/boot/kernel#.
 This is mostly true for certain subsystems.
@@ -116,16 +125,11 @@ Before editing the kernel configuration file, it is recommended to perform an in
 On a dual-boot system, the inventory can be created from the other operating system.
 For example, Microsoft(R)'s Device Manager contains information about installed devices.
 
-[NOTE]
-====
-Some versions of Microsoft(R) Windows(R) have a System icon which can be used to access Device Manager.
-====
-
 If FreeBSD 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 FreeBSD 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:
 
-[source,shell]
+[.programlisting]
 ....
 psm0: <PS/2 Mouse> irq 12 on atkbdc0
 psm0: [GIANT-LOCKED]
@@ -143,6 +147,12 @@ For example:
 [source,shell]
 ....
 % pciconf -lv
+....
+
+The output should be similar to the following:
+
+[.programlisting]
+....
 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'
@@ -150,7 +160,7 @@ ath0@pci0:3:0:0:        class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01
     subclass   = ethernet
 ....
 
-This output shows that the [.filename]#ath# driver located a wireless Ethernet device.
+This output shows that the `ath` driver located a wireless Ethernet device.
 
 The `-k` flag of man:man[1] can be used to provide useful information.
 For example, it can be used to display a list of manual pages which contain a particular device brand or name:
@@ -158,6 +168,12 @@ For example, it can be used to display a list of manual pages which contain a pa
 [source,shell]
 ....
 # man -k Atheros
+....
+
+The output should be similar to the following:
+
+[.programlisting]
+....
 ath(4)                   - Atheros IEEE 802.11 wireless network driver
 ath_hal(4)               - Atheros Hardware Access Layer (HAL)
 ....
@@ -173,7 +189,7 @@ If [.filename]#/usr/src/# does not exist or it is empty, source has not been ins
 Source can be installed with Git using the instructions in crossref:mirrors[git,“Using Git”]. 
 
 Once source is installed, review the contents of [.filename]#/usr/src/sys#.
-This directory contains a number of subdirectories, including those which represent the following supported architectures: [.filename]#amd64#, [.filename]#i386#, [.filename]#powerpc#, and [.filename]#sparc64#.
+This directory contains a number of subdirectories, including those which represent the FreeBSD supported architectures.
 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# subdirectory which contains the [.filename]#GENERIC# kernel configuration file for that architecture.
 
@@ -189,14 +205,14 @@ This example creates a copy, named [.filename]#MYKERNEL#, of the [.filename]#GEN
 # cp GENERIC MYKERNEL
 ....
 
-[.filename]#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 FreeBSD.
+The [.filename]#MYKERNEL# file can now be customized with any text editor.
 
 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.
+More information about the configuration kernel file can be found in man:config[5].
 
 [WARNING]
 ====
@@ -211,7 +227,6 @@ For architecture independent options, refer to [.filename]#/usr/src/sys/conf/NOT
 [TIP]
 ====
 When finished customizing the kernel configuration file, save a backup copy to a location outside of [.filename]#/usr/src#.
-
 Alternately, keep the kernel configuration file elsewhere and create a symbolic link to the file:
 
 [source,shell]
@@ -241,101 +256,113 @@ options         IPDIVERT
 
 Using this method, the local configuration file expresses local differences from a [.filename]#GENERIC# kernel.
 As upgrades are performed, new features added to [.filename]#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].
-
-[NOTE]
-====
-To build a file which contains all available options, run the following command as `root`:
-
-[source,shell]
-....
-# cd /usr/src/sys/arch/conf && make LINT
-....
 
-====
+A comprehensive list of configuration directives and their descriptions may be found in man:config[5].
 
 [[kernelconfig-building]]
 == 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:
 
-[.procedure]
-====
-*Procedure: Building a Kernel*
+Move to [.filename]#/usr/src#:
 
-. Change to this directory:
-+
 [source,shell]
 ....
 # cd /usr/src
 ....
-+
-. Compile the new kernel by specifying the name of the custom kernel configuration file:
-+
+
+Compile the new kernel by specifying the name of the custom kernel configuration file:
+
 [source,shell]
 ....
 # make buildkernel KERNCONF=MYKERNEL
 ....
-+
-. Install the new kernel associated with the specified kernel configuration file. This command will copy the new kernel to [.filename]#/boot/kernel/kernel# and save the old kernel to [.filename]#/boot/kernel.old/kernel#:
-+
+
+Install the new kernel associated with the specified kernel configuration file. This command will copy the new kernel to [.filename]#/boot/kernel/kernel# and save the old kernel to [.filename]#/boot/kernel.old/kernel#:
+
 [source,shell]
 ....
 # make installkernel KERNCONF=MYKERNEL
 ....
-+
-. Shutdown the system and reboot into the new kernel. If something goes wrong, refer to <<kernelconfig-noboot, The kernel does not boot>>.
-====
 
+Shutdown the system and reboot into the new kernel. If something goes wrong, refer to <<kernelconfig-noboot, The kernel does not boot>>.
+
+[TIP]
+====
 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# 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:
 
 [.programlisting]
 ....
-MODULES_OVERRIDE = linux acpi
+MODULES_OVERRIDE=	linux ipfw
 ....
 
 Alternately, this variable lists which modules to exclude from the build process:
 
 [.programlisting]
 ....
-WITHOUT_MODULES = linux acpi sound
+WITHOUT_MODULES=	linux acpi sound
+....
+
+This variable instructs the build to skip kernel modules and compile only the kernel itself:
+
+[.programlisting]
+....
+NO_MODULES=	yes
+....
+
+The Ports Framework includes drivers and other modules that depend on kernel interfaces, such as package:graphics/drm-kmod[] or package:emulators/virtualbox-ose-kmod[].
+With the `PORTS_MODULES` variable every time the kernel is built, the ports containing kernel modules are re-built against the updated sources.
+This ensures the kernel module stays in-sync with the kernel itself.
+The kernel and ports trees should be updated together for maximum compatibility.
+`PORTS_MODULES` can be added to [.filename]#/etc/make.conf# file to ensure all kernels you build rebuild this module.
+
+[.programlisting]
+....
+PORTS_MODULES=	drm-kmod virtualbox-ose-kmod
 ....
 
 Additional variables are available.
 Refer to man:make.conf[5] for details.
+====
 
 [[kernelconfig-trouble]]
 == If Something Goes Wrong
 
 There are four categories of trouble that can occur when building a custom kernel:
 
-`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 [.filename]#GENERIC# or [.filename]#NOTES#:
-+
+=== `config` fails
+
+If man:config[5] fails, it will print the line number that is incorrect.
+
+As an example, for the following message, make sure that line 32 is typed correctly by comparing it to [.filename]#GENERIC# or [.filename]#NOTES#:
+
 [source,shell]
 ....
-config: line 17: syntax error
+config: /usr/src/sys/amd64/conf/GENERIC:32: syntax error
 ....
 
-`make` fails::
-If `make` fails, it is usually due to an error in the kernel configuration file which is not severe enough for `config` to catch.
+=== `make` fails
+
+If man:make[1] 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 {freebsd-questions} which contains the kernel configuration file.
 
 [[kernelconfig-noboot]]
-The kernel does not boot::
+=== The kernel does not boot
+
 If the new kernel does not boot or fails to recognize devices, do not panic! Fortunately, FreeBSD has an excellent mechanism for recovering from incompatible kernels.
+
 Simply choose the kernel to boot from at the FreeBSD boot loader.
-This can be accessed when the system boot menu appears by selecting the "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.
-+
+This can be accessed when the system boot menu appears by selecting the "Kernel:" option, which initially displays "Kernel: default/kernel".
+Each time the option is selected, another choice appears, for example "kernel.old".
+When the desired kernel is listed, press return to boot.
+
 After booting with a good kernel, check over the configuration file and try to build it again.
 One helpful resource is [.filename]#/var/log/messages# which records the kernel messages from every successful boot.
 Also, man:dmesg[8] will print the kernel messages from the current boot.
-+
+
 [NOTE]
 ====
 When troubleshooting a kernel make sure to keep a copy of a kernel that is known to work, such as [.filename]#GENERIC#.
@@ -347,10 +374,4 @@ As soon as possible, move the working kernel by renaming the directory containin
 # mv /boot/kernel /boot/kernel.bad
 # mv /boot/kernel.good /boot/kernel
 ....
-
 ====
-
-The kernel works, but man:ps[1] does not::
-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, crossref:cutting-edge[makeworld,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.