BSP Guide and BSP Chapter: Sync'ed these two files

After moving BSP Guide into its own folder for documentation I discovered
a consequence of that.  There are two separate bsp.xml files now:  one
in the poky-ref-manual folder and one in the bsp folder.  I had done some
good cleanup work in the version in the poky-ref-manual folder.  This
commit reflects a 'meld' operation where I re-sync'ed the bsp.xml
file in the bsp-guide folder to be the same (almost) as the one in the
poky-ref-manual folder.  There is still one slight difference between the
two files due to one's context as a stand-alone manual and the other as
a section in a larger book.

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>

1 files changed, 81 insertions, 71 deletions

diff --git a/documentation/poky-ref-manual/bsp.xml b/documentation/poky-ref-manual/bsp.xml
index 7cd18b61e3..e8809555c4 100644
--- a/documentation/poky-ref-manual/bsp.xml
+++ b/documentation/poky-ref-manual/bsp.xml
@@ -16,7 +16,8 @@
         </para>
 
         <para>
-            The intent of this document is to define a structure for these components
+            This section (or document if you are reading the BSP Developer's Guide) defines
+            a structure for these components
             so that BSPs follow a commonly understood layout.
             Providing a common form allows end-users to understand and become familiar 
             with the layout.  
@@ -28,21 +29,21 @@
             The proposed format does have elements that are specific to the Poky and 
             OpenEmbedded build systems. 
             It is intended that this information can be 
-            used by other systems besides Poky and OpenEmbedded and thatspecified it will be simple
+            used by other systems besides Poky and OpenEmbedded and that it will be simple
             to extract information and convert it to other formats if required.
-            Poky, through its standard slyers mechanism, can directly accept The format 
+            Poky, through its standard layers mechanism, can directly accept The format 
             described as a layer.
             The BSP captures all 
-            the hardware specific details in one place in a standard format, which is 
+            the hardware-specific details in one place in a standard format, which is 
             useful for any person wishing to use the hardware platform regardless of 
-            the build system being used.
+            the build system they are using.
         </para>
 
         <para>
             The BSP specification does not include a build system or other tools -
             it is concerned with the hardware-specific components only. 
             At the end 
-            distribution point you can shipt the BSP combined with a build system
+            distribution point you can ship the BSP combined with a build system
             and other tools. 
             However, it is important to maintain the distinction that these
             are separate components that happen to be combined in certain end products.
@@ -73,7 +74,6 @@ meta-bsp/packages/modem/modem-driver_0.1.bb
 meta-bsp/packages/modem/modem-daemon_0.1.bb
 meta-bsp/packages/image-creator/image-creator-native_0.1.bb
 meta-bsp/prebuilds/
-
                 </programlisting>
             </para>
 
@@ -92,8 +92,9 @@ meta-bsp/prebuilds/
                 Users could use these to get a system 
                 running and quickly get started on development tasks. 
                 The exact types of binaries
-                present will be highly hardware-dependent but a README file should be present 
-                explaining how to use them with the target hardware. 
+                present are highly hardware-dependent.
+                However, a README file should be present 
+                that explains how to use them with the target hardware. 
                 If prebuilt binaries are 
                 present, source code to meet licensing requirements must also be provided in 
                 some form.
@@ -105,8 +106,8 @@ meta-bsp/prebuilds/
             <title>Layer Configuration (meta-bsp/conf/layer.conf)</title>
 
             <para>
-                This file identifies the structure as a Poky layer by identifying the  
-                contents of the layer and containing information about how Poky should use 
+                This file identifies the structure as a Poky layer, identifies the  
+                contents of the layer and contains information about how Poky should use 
                 it. 
                 Generally, a standard boilerplate file consisting of the following works.
             </para>
@@ -193,9 +194,9 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
             <para>
                 These files make up the definition of a kernel to use with this
                 hardware. 
-                In this case it is a complete self-contained kernel with its own
-                configuration and patches but kernels can be shared between many
-                machines as well.
+                In this case, it is a complete self-contained kernel with its own
+                configuration and patches.
+                However, kernels can be shared between many machines as well.
                 Following is an example:
                <programlisting>
 meta-bsp/packages/linux/linux-bsp_2.6.50.bb
@@ -216,8 +217,8 @@ linux-bsp-2.6.50/*.patch
                </programlisting>
             </para>
             <para>
-                The above example file contains patches you can apply against the base kernel, wherever
-                they may have been obtained from.
+                The above example file contains patches you can apply against the base kernel, from wherever
+                they may have been obtained.
             </para>
             <para>
                <programlisting>
@@ -225,11 +226,11 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
                </programlisting>
             </para>
             <para>
-                Finally, this last example file contains configuration information to use to configure the kernel.
+                Finally, this last example file contains kernel configuration information.
             </para>
             <para>
                 Examples of kernel recipes are available in Poky itself. 
-                These files are optional since a kernel from Poky itself could be selected, although it
+                These files are optional since a kernel from Poky could be selected, although it
                 would be unusual not to have a kernel configuration.
             </para>
         </section>
@@ -240,8 +241,8 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
             <para>
                 This section describes other pieces of software that the hardware might need for best
                 operation. 
-                These are examples of the kinds of things that you could encounter.  
-                The examples used in this section are standard <filename>.bb</filename> file recipes in the 
+                This section shows examples of the kinds of things that you could encounter.  
+                The examples are standard <filename>.bb</filename> file recipes in the 
                 usual Poky format.  
                 You can include the source directly by referring to it in the source control system or 
                 the released tarballs of external software projects.
@@ -250,7 +251,7 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
             <para>
                 The following file is a bootloader recipe that can be used to generate a new
                 bootloader binary. 
-                Sometimes these files are included in the final image format and are needed to reflash hardware.
+                Sometimes these files are included in the final image format and are needed to re-flash hardware.
             </para>
             <para>
                <programlisting>
@@ -270,7 +271,7 @@ meta-bsp/packages/modem/modem-daemon_0.1.bb
             </para>
             <para>
                 Sometimes the device needs an image in a very specific format so that the update
-                mechanism can accept and reflash it. 
+                mechanism can accept and re-flash it. 
                 Recipes to build the tools needed to do this can be included with the BSP.
                 Following is an example.
             </para>
@@ -285,15 +286,15 @@ meta-bsp/packages/image-creator/image-creator-native_0.1.bb
             <title>Append BSP-Specific Information to Existing Recipes</title>
             <para>
                 Suppose you have a recipe such as 'pointercal' that requires machine-specific information.
-                At the same time, you have your new BSP code nicely partitioned into a layer, which is where 
+                At the same time, you have your new BSP code nicely partitioned into a layer through which  
                 you would also like to specify any machine-specific information associated with your new machine. 
                 Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole
-                pointercal recipe and files into your layer, and then add the single file for your machine.
+                pointercal recipe and files into your layer and then add the single file for your machine.
             </para>
             <para>
                 With the <filename>.bbappend</filename> extension, however, your work becomes much easier.
-                It allows you to easily merge BSP-specific information with the original recipe.
-                Whenever bitbake finds any <filename>.bbappend</filename> files, they will be
+                This extension allows you to easily merge BSP-specific information with the original recipe.
+                Whenever bitbake finds any <filename>.bbappend</filename> files they will be
                 included after bitbake loads the associated <filename>.bb</filename> but before any finalize 
                 or anonymous methods run.
                 This allows the BSP layer to do whatever it might want to do to customize the original recipe.
@@ -326,59 +327,65 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
         <section id='bsp-click-through-licensing'>
             <title>BSP 'Click-Through' Licensing Procedure</title>
 
-            <note><para> This section is here as a description of how
-                click-through licensing is expected to work, and is
-                not yet not impemented.
+            <note><para> This section describes how
+                click-through licensing is expected to work.
+                Currently, this functionality is not yet implemented.
             </para></note>
 
             <para>
-              In some cases, a BSP may contain separately licensed IP
-              (Intellectual Property) for a component, which imposes
+              In some cases, a BSP contains separately licensed IP
+              (Intellectual Property) for a component that imposes
               upon the user a requirement to accept the terms of a
-              'click-through' license.  Once the license is accepted
-              (in whatever form that may be, see details below) the
+              'click-through' license.  
+              Once the license is accepted the
               Poky build system can then build and include the
-              corresponding component in the final BSP image.  Some
-              affected components may be essential to the normal
+              corresponding component in the final BSP image.  
+              Some affected components might be essential to the normal
               functioning of the system and have no 'free' replacement
-              i.e. the resulting system would be non-functional
-              without them.  Other components may be simply
+              (i.e. the resulting system would be non-functional
+              without them).
+              On the other hand, other components might be simply
               'good-to-have' or purely elective, or if essential
               nonetheless have a 'free' (possibly less-capable)
-              version which may substituted for in the BSP recipe.
+              version that could be used as a in the BSP recipe.
             </para>
 
             <para>
-              For the latter cases, where it is possible to do so from
-              a functionality perspective, the Poky website will make
+              For cases where you can substitute something and still maintain functionality, the Poky website will make
               available a 'de-featured' BSP completely free of
-              encumbered IP, which can be used directly and without
-              any further licensing requirements.  If present, this
+              the encumbered IP.
+              In that case you can use the substitution directly and without
+              any further licensing requirements.  
+              If present, this
               fully 'de-featured' BSP will be named meta-bsp (i.e. the
-              normal default naming convention).  This is the simplest
-              and therefore preferred option if available, assuming
-              the resulting functionality meets requirements.
+              normal default naming convention).  
+              If available, this is the simplest the most preferred option.
+              This, of course, assumes the resulting functionality meets requirements.
             </para>
 
             <para>
               If however, a non-encumbered version is unavailable or
               the 'free' version would provide unsuitable
               functionality or quality, an encumbered version can be
-              used.  Encumbered versions of a BSP are given names of
-              the form meta-bsp-nonfree.  There are several ways
-              within the Poky build system to satisfy the licensing
-              requirements for an encumbered BSP, in roughly the
-              following order of preference:
+              used.  
+              Encumbered versions of a BSP are given names of
+              the form meta-bsp-nonfree.
+            </para>
+
+            <para>  
+              Several methods exist within the Poky build system to satisfy the licensing
+              requirements for an encumbered BSP.
+              The following list describes them in preferential order:
             </para>
 
-            <itemizedlist>
+            <orderedlist>
               <listitem>
 
                 <para>
                   Get a license key (or keys) for the encumbered BSP
                   by visiting 
                   <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink>
-                  and give the web form there the name of the BSP and your e-mail address.
+                  and give the name of the BSP and your e-mail address in the web form.
                 </para>
 
                 <programlisting>
@@ -388,7 +395,7 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
                 <para>
                   After agreeing to any applicable license terms, the
                   BSP key(s) will be immediately sent to the address
-                  given and can be used by specifying BSPKEY_&lt;keydomain&gt;
+                  you gave and you can use them by specifying BSPKEY_&lt;keydomain&gt;
                   environment variables when building the image:
                 </para>
 
@@ -397,40 +404,42 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
                 </programlisting>
 
                 <para>
-                  This will allow the encumbered image to be built
+                  These steps allow the encumbered image to be built
                   with no change at all to the normal build process.
                 </para>
 
                 <para>
                   Equivalently and probably more conveniently, a line
                   for each key can instead be put into the user's
-                  local.conf file.
+                  <filename>local.conf</filename> file.
                 </para>
 
                 <para>
                   The &lt;keydomain&gt; component of the
                   BSPKEY_&lt;keydomain&gt; is required because there
-                  may be multiple licenses in effect for a give BSP; a
-                  given &lt;keydomain&gt; in such cases corresponds to
+                  might be multiple licenses in effect for a give BSP.
+                  In such cases, a given &lt;keydomain&gt; corresponds to
                   a particular license.  In order for an encumbered
-                  BSP encompassing multiple key domains to be built
+                  BSP that encompasses multiple key domains to be built
                   successfully, a &lt;keydomain&gt; entry for each
-                  applicable license must be present in local.conf or
+                  applicable license must be present in <filename>local.conf</filename> or
                   supplied on the command-line.
                 </para>
               </listitem>
               <listitem>
                 <para>
-                  Do nothing - build as you normally would, and follow
-                  any license prompts that originate from the
-                  encumbered BSP (the build will cleanly stop at this
-                  point).  These usually take the form of instructions
+                  Do nothing - build as you normally would.
+                  When a license is needed the build will stop and prompt you with instructions.
+                  Follow the license prompts that originate from the
+                  encumbered BSP.  
+                  These prompts usually take the form of instructions
                   needed to manually fetch the encumbered package(s)
-                  and md5 sums into e.g. the poky/build/downloads
-                  directory.  Once the manual package fetch has been
-                  completed, restarting the build will continue where
-                  it left off, this time without the prompt since the
-                  license requirements will have been satisfied.
+                  and md5 sums into the required directory (e.g. the poky/build/downloads)
+                  Once the manual package fetch has been
+                  completed, restart the build to continue where
+                  it left off.
+                  During the build the prompt will not appear again since you have satisfied the 
+                  requirement.
                 </para>
               </listitem>
               <listitem>
@@ -440,7 +449,7 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
                   <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
                   Accepting the license agreement(s) presented will
                   subsequently allow you to download a tarball
-                  containing a full-featured BSP legally cleared for
+                  containing a full-featured BSP that is legally cleared for
                   your use by the just-given license agreement(s).
                   This method will also allow the encumbered image to
                   be built with no change at all to the normal build
@@ -449,9 +458,10 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
               </listitem>
             </itemizedlist>
             <para>
-              Note that method 3 is also the only option available
+              Note that the third method is also the only option available
               when downloading pre-compiled images generated from
-              non-free BSPs.  Those images are likewise available at
+              non-free BSPs.  
+              Those images are likewise available at
               <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
             </para>
         </section>