Performed general edits to this chapter.

many english corrections performed.

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

1 files changed, 127 insertions, 119 deletions

diff --git a/documentation/poky-ref-manual/bsp.xml b/documentation/poky-ref-manual/bsp.xml
index acb9f38e19..7cd18b61e3 100644
--- a/documentation/poky-ref-manual/bsp.xml
+++ b/documentation/poky-ref-manual/bsp.xml
@@ -1,53 +1,60 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<chapter id='bsp'>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="bsp">
 
         <title>Board Support Packages (BSP) - Developers Guide</title>
 
         <para>
-            A Board Support Package (BSP) is a collection of information which together
+            A Board Support Package (BSP) is a collection of information that
             defines how to support a particular hardware device, set of devices, or 
-            hardware platform. It will include information about the hardware features 
+            hardware platform. 
+            The BSP includes information about the hardware features 
             present on the device and kernel configuration information along with any 
-            additional hardware drivers required. It will also list any additional software 
+            additional hardware drivers required.
+            The BSP also lists any additional software 
             components required in addition to a generic Linux software stack for both 
             essential and optional platform features.
         </para>
 
         <para>
             The intent of this document is to define a structure for these components
-            so that BSPs follow a commonly understood layout, allowing them to be 
-            provided in a common form that everyone understands. It also allows end-users
-            to become familiar with one common format and encourages standardisation 
+            so that BSPs follow a commonly understood layout.
+            Providing a common form allows end-users to understand and become familiar 
+            with the layout.  
+            A common form also encourages standardization 
             of software support of hardware.
         </para>
 
         <para>
             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/OpenEmbedded and that it will be simple
-            to extract information and convert to other formats if required. The format 
-            described can be directly accepted as a layer by Poky using its standard 
-            layers mechanism, but it is important to recognise that the BSP captures all 
+            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
+            to extract information and convert it to other formats if required.
+            Poky, through its standard slyers 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 
             useful for any person wishing to use the hardware platform regardless of 
-            the build system in use.
+            the build system being used.
         </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 the BSP may be shipped combined with a build system
-            and other tools, but it is important to maintain the distinction that these
-            are separate components which may just be combined in certain end products.
+            it is concerned with the hardware-specific components only. 
+            At the end 
+            distribution point you can shipt 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.
         </para>
 
-        <section id='bsp-filelayout'>
+        <section id="bsp-filelayout">
             <title>Example Filesystem Layout</title>
 
             <para>
-                The BSP consists of a file structure inside a base directory, meta-bsp in this example, where "bsp" is a placeholder for the machine or platform name. Examples of some files that it could contain are:
+                The BSP consists of a file structure inside a base directory, meta-bsp in this example, 
+                where "bsp" is a placeholder for the machine or platform name. 
+                Examples of some files that it could contain are:
             </para>
 
             <para>
@@ -76,15 +83,18 @@ meta-bsp/prebuilds/
 
         </section>
 
-        <section id='bsp-filelayout-binary'>
+        <section id="bsp-filelayout-binary">
             <title>Prebuilt User Binaries (meta-bsp/binary/*)</title>
 
             <para>
                 This optional area contains useful prebuilt kernels and userspace filesystem 
-                images appropriate to the target system. Users could use these to get a system 
-                running and quickly get started on development tasks. The exact types of binaries
+                images appropriate to the target system. 
+                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. If prebuilt binaries are 
+                explaining 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.
             </para>
@@ -95,9 +105,10 @@ meta-bsp/prebuilds/
             <title>Layer Configuration (meta-bsp/conf/layer.conf)</title>
 
             <para>
-                This file identifies the structure as a Poky layer. This file identifies the 
-                contents of the layer and contains information about how Poky should use 
-                it. In general it will most likely be a standard boilerplate file consisting of:
+                This file identifies the structure as a Poky layer by identifying the  
+                contents of the layer and containing information about how Poky should use 
+                it. 
+                Generally, a standard boilerplate file consisting of the following works.
             </para>
 
             <para>
@@ -106,7 +117,7 @@ meta-bsp/prebuilds/
 BBPATH := "${BBPATH}${LAYERDIR}"
 
 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
-BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb ${LAYERDIR}/recipes/*/*.bbappend"
+BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ ${LAYERDIR}/recipes/*/*.bbappend"
 
 BBFILE_COLLECTIONS += "bsp"
 BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
@@ -115,47 +126,45 @@ BBFILE_PRIORITY_bsp = "5"
             </para>
 
             <para>
-                which simply makes bitbake aware of the recipes and conf directories.
-            </para>
-
-            <para>
-                This file is required for recognition of the BSP by Poky.
+                This file simply makes bitbake aware of the recipes and conf directories and is required 
+                for recognition of the BSP by Poky.
             </para>
 
         </section>
 
-        <section id='bsp-filelayout-machine'>
+        <section id="bsp-filelayout-machine">
             <title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title>
 
             <para>
                 The machine files bind together all the information contained elsewhere
-                in the BSP into a format that Poky/OpenEmbedded can understand. If
-                the BSP supports multiple machines, multiple machine configuration files
-                can be present. These filenames correspond to the values users set the
-                MACHINE variable to.
+                in the BSP into a format that Poky/OpenEmbedded can understand. 
+                If the BSP supports multiple machines, multiple machine configuration files
+                can be present. 
+                These filenames correspond to the values to which users have set the MACHINE variable.
             </para>
 
             <para>
-                These files would define things like which kernel package to use
-                (PREFERRED_PROVIDER of virtual/kernel), which hardware drivers to
+                These files define things such as what kernel package to use
+                (PREFERRED_PROVIDER of virtual/kernel), what hardware drivers to
                 include in different types of images, any special software components
                 that are needed, any bootloader information, and also any special image
                 format requirements.
             </para>
 
             <para>
-                At least one machine file is required for a Poky BSP layer but more than one may be present.
+                At least one machine file is required for a Poky BSP layer.
+                However, you can supply more than one file.
             </para>
 
         </section>
 
-        <section id='bsp-filelayout-tune'>
-            <title>Hardware Optimisation Options (meta-bsp/conf/machine/include/tune-*.inc)</title>
+        <section id="bsp-filelayout-tune">
+            <title>Hardware Optimization Options (meta-bsp/conf/machine/include/tune-*.inc)</title>
 
             <para>
                 These are shared hardware "tuning" definitions and are commonly used to
-                pass specific optimisation flags to the compiler. An example is
-                tune-atom.inc:
+                pass specific optimization flags to the compiler. 
+                An example is tune-atom.inc:
             </para>
             <para>
                <programlisting>
@@ -164,40 +173,42 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
                </programlisting>
             </para>
             <para>
-                which defines a new package architecture called "core2" and uses the
-                optimization flags specified, which are carefully chosen to give best
-                performance on atom cpus.
+                This example defines a new package architecture called "core2" and uses the
+                specified optimization flags, which are carefully chosen to give best
+                performance on atom processors.
             </para>
             <para>
                 The tune file would be included by the machine definition and can be
-                contained in the BSP or reference one from the standard core set of
+                contained in the BSP or referenced from one of the standard core set of
                 files included with Poky itself.
             </para>
             <para>
-                These files are optional for a Poky BSP layer.
+                Both the base package architecuture file and the tune file are optional for a Poky BSP layer.
             </para>
         </section>
+
         <section id='bsp-filelayout-kernel'>
             <title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title>
 
             <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
+                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. Taking some specific example files:
-            </para>
-            <para>
+                machines as well.
+                Following is an example:
                <programlisting>
 meta-bsp/packages/linux/linux-bsp_2.6.50.bb
                </programlisting>
+                This example file is the core kernel recipe that details from where to get the kernel
+                source.
+                All standard source code locations are supported so this could 
+                be a release tarball, some git repository, or source included in
+                the directory within the BSP itself.
             </para>
             <para>
-                which is the core kernel recipe which firstly details where to get the kernel
-                source from. All standard source code locations are supported so this could 
-                be a release tarball, some git repository, or source included in
-                the directory within the BSP itself. It then contains information about which 
-                patches to apply and how to configure and build it. It can reuse the main
-                Poky kernel build class, so the definitions here can remain very simple.
+                The file then contains information about what patches to apply and how to configure and build them.
+                It can reuse the main Poky kernel build class, so the definitions here can remain very simple.   
             </para>
             <para>
                <programlisting>
@@ -205,7 +216,7 @@ linux-bsp-2.6.50/*.patch
                </programlisting>
             </para>
             <para>
-                which are patches which may be applied against the base kernel, wherever
+                The above example file contains patches you can apply against the base kernel, wherever
                 they may have been obtained from.
             </para>
             <para>
@@ -214,11 +225,11 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
                </programlisting>
             </para>
             <para>
-                which is the configuration information to use to configure the kernel.
+                Finally, this last example file contains configuration information to use to configure the kernel.
             </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
+                Examples of kernel recipes are available in Poky itself. 
+                These files are optional since a kernel from Poky itself could be selected, although it
                 would be unusual not to have a kernel configuration.
             </para>
         </section>
@@ -227,11 +238,19 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
             <title>Other Software (meta-bsp/packages/*)</title>
 
             <para>
-                This area includes other pieces of software which the hardware may need for best
-                operation. These are just examples of the kind of things that may be
-                encountered. These are standard .bb file recipes in the usual Poky format,
-                so for examples, see standard Poky recipes. The source can be included directly, 
-                referred to in source control systems or release tarballs of external software projects.
+                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 
+                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.
+                You only need to provide these types of files if the platform requires them.
+            </para>
+            <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.
             </para>
             <para>
                <programlisting>
@@ -239,9 +258,9 @@ meta-bsp/packages/bootloader/bootloader_0.1.bb
                </programlisting>
             </para>
             <para>
-                Some kind of bootloader recipe which may be used to generate a new
-                bootloader binary. Sometimes these are included in the final image
-                format and needed to reflash hardware.
+                These next two files are examples of a hardware driver and a hardware daemon that might need
+                to be included in images to make the hardware useful. 
+                Although the example uses "modem" there may be other components needed, such as firmware.
             </para>
             <para>
                <programlisting>
@@ -250,72 +269,62 @@ meta-bsp/packages/modem/modem-daemon_0.1.bb
                </programlisting>
             </para>
             <para>
-                These are examples of a hardware driver and also a hardware daemon which
-                may need to be included in images to make the hardware useful. "modem"
-                is one example but there may be other components needed like firmware.
+                Sometimes the device needs an image in a very specific format so that the update
+                mechanism can accept and reflash it. 
+                Recipes to build the tools needed to do this can be included with the BSP.
+                Following is an example.
             </para>
             <para>
                <programlisting>
 meta-bsp/packages/image-creator/image-creator-native_0.1.bb
                </programlisting>
             </para>
+        </section>
+
+        <section id='bs-filelayout-bbappend'>
+            <title>Append BSP-Specific Information to Existing Recipes</title>
             <para>
-                Sometimes the device will need an image in a very specific format for
-                its update mechanism to accept and reflash with it. Recipes to build the
-                tools needed to do this can be included with the BSP.
+                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 
+                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.
             </para>
             <para>
-                These files only need be provided if the platform requires them.
+                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
+                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.
             </para>
-        </section>
-
-        <section id='bs-filelayout-bbappend'>
-            <title>Append BSP specific information to existing recipes</title>
-
             <para>
-            Say you have a recipe like pointercal which has machine-specific information in it,
-            and then you have your new BSP code in a layer. Before the .bbappend extension was
-            introduced, you'd have to copy the whole pointercal recipe and files into your layer,
-            and then add the single file for your machine, which is ugly.
-
-            .bbappend makes the above work much easier, to allow BSP-specific information to be merged
-            with the original recipe easily. When bitbake finds any X.bbappend files, they will be
-            included after bitbake loads X.bb but before finalise or anonymous methods run.
-            This allows the BSP layer to poke around and do whatever it might want to customise
-            the original recipe.
-
-            If your recipe needs to reference extra files it can use the FILESEXTRAPATH variable
-            to specify their location. The example below shows extra files contained in a folder
-            called ${PN} (the package name).
+                If your recipe needs to reference extra files it can use the FILESEXTRAPATH variable
+                to specify their location. 
+                The example below shows extra files contained in a folder called ${PN} (the package name).
             </para>
-
             <programlisting>
 FILESEXTRAPATHS := "${THISDIR}/${PN}"
             </programlisting>
-
             <para>
-            Then the BSP could add machine-specific config files in layer directory, which will be
-            added by bitbake. You can look at meta-emenlow/packages/formfactor as an example.
+            This technique allows the BSP to add machine-specific configuration files to the layer directory, 
+            which will be picked up by bitbake. 
+            For an example see <filename>meta-emenlow/packages/formfactor</filename>.
             </para>
         </section>
 
-        <section id='bsp-filelayout-prebuilds'>
+        <section id="bsp-filelayout-prebuilds">
             <title>Prebuild Data (meta-bsp/prebuilds/*)</title>
-
-            <para>
-                The location can contain a precompiled representation of the source code 
-                contained elsewhere in the BSP layer. It can be processed and used by
-                Poky to provide much faster build times, assuming a compatible configuration is used.
-            </para>
-
             <para>
-                These files are optional.
+                This location can contain precompiled representations of the source code 
+                contained elsewhere in the BSP layer. 
+                Assuming a compatible configuration is used, Poky can process and use these optional precompiled 
+                representations to provide much faster build times.
             </para>
-
         </section>
 
         <section id='bsp-click-through-licensing'>
-            <title>BSP 'Click-through' Licensing Procedure</title>
+            <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
@@ -367,10 +376,9 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
 
                 <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.
+                  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.
                 </para>
 
                 <programlisting>