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 7cd18b6..e880955 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>