From 45a1c42e7e1fd981027f0dcd9eae7a204a0d9f95 Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <scott.m.rifenbark@intel.com>
Date: Tue, 17 Jun 2014 10:09:06 +0300
Subject: kernel-dev: Edits to "Working with Out-of-Tree Modules"

Fixes [YOCTO #3729]

I made an editing pass through this section.  Found some minor
corrections.

(From yocto-docs rev: 314ec3a066de7328b6c6893ce33cc0e5faa8700a)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/kernel-dev/kernel-dev-common.xml | 64 +++++++++++++-------------
 1 file changed, 33 insertions(+), 31 deletions(-)

(limited to 'documentation/kernel-dev')

diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index 3ab21e7077..555c8d8903 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -261,7 +261,7 @@
 
 <!--
             <para>
-                <emphasis>AR - Darrren Hart:</emphasis>  This section
+                <emphasis>AR - Darren Hart:</emphasis>  This section
                 originated from the old Yocto Project Kernel Architecture
                 and Use Manual.
                 It was decided we need to put it in this section here.
@@ -635,9 +635,9 @@
         <title>Working with Out-of-Tree Modules</title>
 
         <para>
-            This section describes steps you need to take to be able
-            to build out-of-tree modules on your target and how to
-            incorporate out-of-tree modules in the build.
+            This section describes steps to build out-of-tree modules on
+            your target and describes how to incorporate out-of-tree modules
+            in the build.
         </para>
 
         <section id='building-out-of-tree-modules-on-the-target'>
@@ -646,7 +646,7 @@
             <para>
                 If you want to be able to build out-of-tree modules on
                 the target, there are some steps you need to take
-                on the target that has your SDK image running.
+                on the target that is running your SDK image.
                 Briefly, the <filename>kernel-dev</filename> package
                 is installed by default on all
                 <filename>*.sdk</filename> images.
@@ -657,15 +657,15 @@
 
             <para>
                 Prior to attempting to build the out-of-tree modules,
-                you need to be on the target as root and change to the
-                <filename>/usr/src/kernel</filename> directory and
-                then <filename>make</filename> the scripts:
+                you need to be on the target as root and you need to
+                change to the <filename>/usr/src/kernel</filename> directory.
+                Next, <filename>make</filename> the scripts:
                 <literallayout class='monospaced'>
      # cd /usr/src/kernel
      # make scripts
                 </literallayout>
                 Because all SDK image recipes include
-                <filename>dev-pkgs</filename> the
+                <filename>dev-pkgs</filename>, the
                 <filename>kernel-dev</filename> packages will be installed
                 as part of the SDK image.
                 The SDK uses the scripts when building out-of-tree
@@ -682,9 +682,9 @@
             <para>
                 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.
+                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>
@@ -700,12 +700,12 @@
             <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
+                In the same directory, create a new 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:
+                Finally, update the recipe as needed 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>
@@ -719,11 +719,11 @@
             </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:
+                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
 
@@ -742,27 +742,29 @@
                 The important point to note here is the
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
                 variable.
-                The class <filename>module.bbclass</filename> sets this variable,
-                as well as the
+                The
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-module'><filename>module</filename></ulink>
+                class sets this variable and the
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
                 variable to
                 <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
-                with the necessary Linux kernel build information to build modules.
+                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
                 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink>
                 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.
+                <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 configuration file:
+                the Yocto Project Reference Manual and set one of them
+                appropriately for your machine configuration file:
                 <itemizedlist>
                     <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
                         </para></listitem>
@@ -776,13 +778,13 @@
             </para>
 
             <para>
-                modules are often not required for boot and can be excluded from
+                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 value is derived by appending the module filename without
                 the <filename>.ko</filename> extension to the string
                 "kernel-module-".
             </para>
@@ -792,8 +794,8 @@
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
                 and not a
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
-                variable, the build will not fail if this module is not available
-                to include in the image.
+                variable, the build will not fail if this module is not
+                available to include in the image.
             </para>
         </section>
     </section>
-- 
cgit 1.2.3-korg