kernel-dev: Added new "in-tree" defconfig file section.

I added the new section "Using an "In-Tree" defconfig File"
section.  This section addresses the ability to not use the
default location for defconfig files, which is usually in the
metadata layer.  The section describes how to use the
KBUILD_DEFCONFIG variable.

Fixes [YOCTO #7474]

(From yocto-docs rev: f514c8b96ef991f5893c73ae06392eb306c12a5e)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 59 insertions, 0 deletions

diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index c0acac8316..618d60cbaf 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -238,6 +238,65 @@
                 section in the Yocto Project Development Manual.
             </para>
         </section>
+
+        <section id='using-an-in-tree-defconfig-file'>
+            <title>Using an "In-Tree"&nbsp;&nbsp;<filename>defconfig</filename> File</title>
+
+            <para>
+                It might be desirable to have kernel configuration fragment
+                support through a <filename>defconfig</filename> file that
+                is pulled from the kernel source tree for the configured
+                machine.
+                By default, the OpenEmbedded build system looks for
+                <filename>defconfig</filename> files in the layer used for
+                Metadata, which is "out-of-tree", and then configures them
+                using the following:
+                <literallayout class='monospaced'>
+     SRC_URI += "file://defconfig"
+                </literallayout>
+                If you do not want to maintain copies of
+                <filename>defconfig</filename> files in your layer but would
+                rather allow users to use the default configuration from the
+                kernel tree and still be able to add configuration fragments
+                to the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                through, for example, append files, you can direct the
+                OpenEmbedded build system to use a
+                <filename>defconfig</filename> file that is "in-tree".
+            </para>
+
+            <para>
+                To specify an "in-tree" <filename>defconfig</filename> file,
+                edit the recipe that builds your kernel so that it has the
+                following command form:
+                <literallayout class='monospaced'>
+     KBUILD_DEFCONFIG_<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'>KMACHINE</ulink> ?= <replaceable>defconfig_file</replaceable>
+                </literallayout>
+                You need to append the variable with
+                <filename>KMACHINE</filename> and then supply the path to
+                your "in-tree" <filename>defconfig</filename> file.
+            </para>
+
+            <para>
+                Aside from modifying your kernel recipe and providing your own
+                <filename>defconfig</filename> file, you need to be sure no
+                files or statements set <filename>SRC_URI</filename> to use a
+                <filename>defconfig</filename> other than your "in-tree"
+                file (e.g. a kernel's <filename>linux-</filename><replaceable>machine</replaceable><filename>.inc</filename>
+                file).
+                In other words, if the build system detects a statement
+                that identifies an "out-of-tree"
+                <filename>defconfig</filename> file, that statement
+                will override your
+                <filename>KBUILD_DEFCONFIG</filename> variable.
+            </para>
+
+            <para>
+                See the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG'><filename>KBUILD_DEFCONFIG</filename></ulink>
+                variable description for more information.
+            </para>
+        </section>
     </section>
 
     <section id='using-an-iterative-development-process'>