kernel-dev: Updated kernel configuration section

A lot of rewriting here in this section to get it up to speed.
Also, moved that final section on determining hardware and
non-hardware features into an appendix where it belonged.

(From yocto-docs rev: 752e80d6ae8f81a0de7743b11b010d0ef36b314b)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 117 insertions, 0 deletions

diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index 4cacdd13ee..6d236855dd 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -479,6 +479,123 @@
             section for a detailed example that modifies the kernel.
         </para>
     </section>
+
+    <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'>
+        <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title>
+
+        <para>
+            This section describes part of the kernel configuration audit
+            phase that most developers can ignore.
+            For general information on kernel configuration including
+            <filename>menuconfig</filename>, <filename>defconfig</filename>
+            files, and configuration fragments, see the
+            "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>"
+            section.
+        </para>
+
+        <para>
+            During this part of the audit phase, the contents of the final
+            <filename>.config</filename> file are compared against the
+            fragments specified by the system.
+            These fragments can be system fragments, distro fragments,
+            or user-specified configuration elements.
+            Regardless of their origin, the OpenEmbedded build system
+            warns the user if a specific option is not included in the
+            final kernel configuration.
+        </para>
+
+        <para>
+            By default, in order to not overwhelm the user with
+            configuration warnings, the system only reports missing
+            "hardware" options as they could result in a boot
+            failure or indicate that important hardware is not available.
+        </para>
+
+        <para>
+            To determine whether or not a given option is "hardware" or
+            "non-hardware", the kernel Metadata contains files that
+            classify individual or groups of options as either hardware
+            or non-hardware.
+            To better show this, consider a situation where the
+            Yocto Project kernel cache contains the following files:
+            <literallayout class='monospaced'>
+     kernel-cache/features/drm-psb/hardware.cfg
+     kernel-cache/features/kgdb/hardware.cfg
+     kernel-cache/ktypes/base/hardware.cfg
+     kernel-cache/bsp/mti-malta32/hardware.cfg
+     kernel-cache/bsp/fsl-mpc8315e-rdb/hardware.cfg
+     kernel-cache/bsp/qemu-ppc32/hardware.cfg
+     kernel-cache/bsp/qemuarma9/hardware.cfg
+     kernel-cache/bsp/mti-malta64/hardware.cfg
+     kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg
+     kernel-cache/bsp/common-pc/hardware.cfg
+     kernel-cache/bsp/common-pc-64/hardware.cfg
+     kernel-cache/features/rfkill/non-hardware.cfg
+     kernel-cache/ktypes/base/non-hardware.cfg
+     kernel-cache/features/aufs/non-hardware.kcf
+     kernel-cache/features/ocf/non-hardware.kcf
+     kernel-cache/ktypes/base/non-hardware.kcf
+     kernel-cache/ktypes/base/hardware.kcf
+     kernel-cache/bsp/qemu-ppc32/hardware.kcf
+            </literallayout>
+            The following list provides explanations for the various
+            files:
+            <itemizedlist>
+                <listitem><para>
+                    <filename>hardware.kcf</filename>:
+                    Specifies a list of kernel Kconfig files that contain
+                    hardware options only.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>non-hardware.kcf</filename>:
+                    Specifies a list of kernel Kconfig files that contain
+                    non-hardware options only.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>hardware.cfg</filename>:
+                    Specifies a list of kernel <filename>CONFIG_</filename>
+                    options that are hardware, regardless of whether or not
+                    they are within a Kconfig file specified by a hardware
+                    or non-hardware Kconfig file (i.e.
+                    <filename>hardware.kcf</filename> or
+                    <filename>non-hardware.kcf</filename>).
+                    </para></listitem>
+                <listitem><para>
+                    <filename>non-hardware.cfg</filename>:
+                    Specifies a list of kernel <filename>CONFIG_</filename>
+                    options that are not hardware, regardless of whether or
+                    not they are within a Kconfig file specified by a
+                    hardware or non-hardware Kconfig file (i.e.
+                    <filename>hardware.kcf</filename> or
+                    <filename>non-hardware.kcf</filename>).
+                    </para></listitem>
+            </itemizedlist>
+            Here is a specific example using the
+            <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>:
+            <literallayout class='monospaced'>
+     CONFIG_SERIAL_8250
+     CONFIG_SERIAL_8250_CONSOLE
+     CONFIG_SERIAL_8250_NR_UARTS
+     CONFIG_SERIAL_8250_PCI
+     CONFIG_SERIAL_CORE
+     CONFIG_SERIAL_CORE_CONSOLE
+     CONFIG_VGA_ARB
+            </literallayout>
+            The kernel configuration audit automatically detects these
+            files (hence the names must be exactly the ones discussed here),
+            and uses them as inputs when generating warnings about the
+            final <filename>.config</filename> file.
+        </para>
+
+        <para>
+            A user-specified kernel Metadata repository, or recipe space
+            feature, can use these same files to classify options that are
+            found within its <filename>.cfg</filename> files as hardware
+            or non-hardware, to prevent the OpenEmbedded build system from
+            producing an error or warning when an option is not in the
+            final <filename>.config</filename> file.
+        </para>
+    </section>
 </appendix>
 <!--
 vim: expandtab tw=80 ts=4