kernel-dev: Re-write of "Incorporating Out-of-Tree Modules" section.

(From yocto-docs rev: 1abc8be7a2862d51165615f49c8c9cfab319564b)

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

1 files changed, 114 insertions, 1 deletions

diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index 506a45ee11..d76580dd02 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -783,7 +783,119 @@ details.
         <title>Incorporating Out-of-Tree Modules</title>
 
         <para>
-        While it is always preferable to work with sources integrated into the Linux
+            While it is always preferable to work with sources integrated
+            into the Linux kernel sources, if you need an external kernel
+            module, the <filename>hello-mod.bb</filename> recipe is available
+            as a template from which you can create your own out-of-tree
+            Linux kernel module recipe.
+        </para>
+
+        <para>
+            This template recipe is located in the
+            <filename>poky</filename> Git repository of the
+            Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
+            at:
+            <literallayout class="monospaced">
+     poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
+            </literallayout>
+        </para>
+
+        <para>
+            To get started, copy this recipe to your layer and give it a
+            meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
+            In the same directory, create a directory named
+            <filename>files</filename> where you can store any source files,
+            patches, or other files necessary for building
+            the module that do not come with the sources.
+            Finally, update the recipe as appropriate for the module.
+            Typically you will need to set the following variables:
+            <itemizedlist>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Depending on the build system used by the module sources, you might
+            need to make some adjustments.
+            For example, a typical module <filename>Makefile</filename> looks
+            much like the one provided with the <filename>hello-mod</filename>
+            template:
+            <literallayout class='monospaced'>
+     obj-m := hello.o
+
+     SRC := $(shell pwd)
+
+     all:
+         $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
+
+     modules_install:
+         $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
+     ...
+            </literallayout>
+        </para>
+
+        <para>
+            The important point to note here is the
+            <filename>KERNEL_SRC</filename> variable.
+            The module <filename>bbclass</filename> sets this variable,
+            as well as the <filename>KERNEL_PATH</filename> variable
+            to <filename>${STAGING_KERNEL_DIR}</filename> with the
+            necessary Linux kernel build information to build modules.
+            If your module <filename>Makefile</filename> uses a different
+            variable, you might want to override the
+            <filename>do_compile()</filename> step, or create a patch to
+            the <filename>Makefile</filename> to work with the more typical
+            <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename>
+            variables.
+        </para>
+
+        <para>
+            After you have prepared your recipe, you will likely want to
+            include the module in your images.
+            To do this, see the documentation for the following variables in
+            the Yocto Project Reference Manual and set one of them as
+            appropriate in your machine <filename>config</filename> file:
+            <itemizedlist>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            modules are often not required for boot and can be excluded from
+            certain build configurations.
+            The following allows for the most flexibility:
+            <literallayout class='monospaced'>
+     MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
+            </literallayout>
+            Where the value is derived by appending the module filename without
+            the <filename>.ko</filename> extension to the string
+            "kernel-module-".
+        </para>
+
+        <para>
+            Because the variable is <filename>RRECOMMENDS</filename> and not
+            a <filename>RDEPENDS</filename> variable, the build will not fail
+            if this module is not available to include in the image.
+        </para>
+
+        <para>
+            Original Text:
+            <literallayout class='monospaced'>
+While it is always preferable to work with sources integrated into the Linux
 kernel sources, if you have need of an external kernel module, the hello-mod
 recipe is available as a template to create your own out-of-tree Linux kernel
 module recipe. It is available in the poky repository at:
@@ -844,6 +956,7 @@ extension to the string "kernel-module-".
 
 As it is an RRECOMMENDS (and not an RDEPENDS) variable, the build will not fail
 if this module is not available to include in the image.
+            </literallayout>
         </para>
     </section>
 </chapter>