bsp-guide: Minor introduction rewrite and formatting BSP workflow.

(From yocto-docs rev: 697d8ce39a122a33faebf1ab66b6bb16bfab5986)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 149 insertions, 122 deletions

diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index f452c6eaec..dacd077f2d 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -714,34 +714,25 @@
             <title>Developing a Board Support Package (BSP)</title>
 
             <para>
-                A BSP is a collection of recipes that, when applied during a build, results in
-                an image that you can run on a particular board.
-                Thus, the package when compiled into the new image, supports the operation of the board.
-            </para>
-
-            <note>
-                For a brief list of terms used when describing the development process in the Yocto Project,
-                see the
-                "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-terms'>Yocto Project Terms</ulink>" section.
-            </note>
-
-            <para>
-                The remainder of this section presents the basic
-                steps used to create a BSP using the Yocto Project's
+                This section contains the high-level procedure you can follow
+                to create a BSP using the Yocto Project's
                 <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
                 Although not required for BSP creation, the
                 <filename>meta-intel</filename> repository, which contains
-                many BSPs supported by the Yocto Project, is part of the example.
+                many BSPs supported by the Yocto Project, is part of the
+                example.
             </para>
 
             <para>
-                For an example that shows how to create a new layer using the tools, see the
+                For an example that shows how to create a new layer using
+                the tools, see the
                 "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>"
                  section.
             </para>
 
             <para>
-                The following illustration and list summarize the BSP creation general workflow.
+                The following illustration and list summarize the BSP
+                creation general workflow.
             </para>
 
             <para>
@@ -750,149 +741,185 @@
 
             <para>
                 <orderedlist>
-                    <listitem><para><emphasis>Set up your host development system to support
-                        development using the Yocto Project</emphasis>:  See the
+                    <listitem><para>
+                        <emphasis>Set Up Your Host Development System to Support
+                        Development Using the Yocto Project:</emphasis>
+                        See the
                         "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>"
                         and the
-                        "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" sections both
-                        in the Yocto Project Quick Start for requirements.</para></listitem>
-                    <listitem><para><emphasis>Establish a local copy of the project files on your
-                        system</emphasis>:  You need this
+                        "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
+                        sections both in the Yocto Project Quick Start for
+                        build host requirements.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Establish a Local Copy of the Project Files on
+                        Your System:</emphasis>
+                        You need this
                         <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
                         available on your host system.
-                        Having these files on your system gives you access to the build
-                        process and to the tools you need.
+                        Having these files on your system gives you access to the
+                        build process and to the tools you need.
                         For information on how to set up the Source Directory,
                         see the
                         "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
                         section in the Yocto Project Development Manual.
                         </para></listitem>
-                    <listitem><para><emphasis>Establish the <filename>meta-intel</filename>
-                        repository on your system</emphasis>:  Having local copies
-                        of these supported BSP layers on your system gives you
-                        access to layers you might be able to build on or modify
-                        to create your BSP.
+                    <listitem><para>
+                        <emphasis>Establish the <filename>meta-intel</filename>
+                        Repository on Your System:</emphasis>
+                        Having local copies of these supported BSP layers on
+                        your system gives you access to layers you might be able
+                        to build on or modify to create your BSP.
                         For information on how to get these files, see the
                         "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-bsp-layers'>Setting Up BSP Layers</ulink>"
                         section in the Yocto Project Development Manual.
                         </para></listitem>
-                    <listitem><para><emphasis>Create your own BSP layer using the
-                        <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></link> script</emphasis>:
-                        Layers are ideal for
-                        isolating and storing work for a given piece of hardware.
-                        A layer is really just a location or area in which you place
-                        the recipes and configurations for your BSP.
+                    <listitem><para>
+                        <emphasis>Create Your Own BSP Layer Using the
+                        <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></link>
+                        script:</emphasis>
+                        Layers are ideal for isolating and storing work for a
+                        given piece of hardware.
+                        A layer is really just a location or area in which you
+                        place the recipes and configurations for your BSP.
                         In fact, a BSP is, in itself, a special type of layer.
-                        The simplest way to create a new BSP layer that is compliant with the
-                        Yocto Project is to use the <filename>yocto-bsp</filename> script.
+                        The simplest way to create a new BSP layer that is
+                        compliant with the Yocto Project is to use the
+                        <filename>yocto-bsp</filename> script.
                         For information about that script, see the
                         "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>"
+                        section.</para>
+
+                        <para>Another example that illustrates a layer
+                        is an application.
+                        Suppose you are creating an application that has
+                        library or other dependencies in order for it to
+                        compile and run.
+                        The layer, in this case, would be where all the
+                        recipes that define those dependencies are kept.
+                        The key point for a layer is that it is an isolated
+                        area that contains all the relevant information for
+                        the project that the OpenEmbedded build system knows
+                        about.
+                        For more information on layers, see the
+                        "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+                        section in the Yocto Project Development Manual.
+                        For more information on BSP layers, see the
+                        "<link linkend='bsp-layers'>BSP Layers</link>"
                         section.
-                        </para>
+                        <note><title>Notes</title>
+                            <para>Five BSPs exist that are part of the Yocto
+                            Project release:
+                            <filename>beaglebone</filename> (ARM),
+                            <filename>mpc8315e</filename> (PowerPC),
+                            and <filename>edgerouter</filename> (MIPS).
+                            The recipes and configurations for these five BSPs
+                            are located and dispersed within the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+                            </para>
 
-                        <para>
-                            Another example that illustrates a layer
-                            is an application.
-                            Suppose you are creating an application that has
-                            library or other dependencies in order for it to
-                            compile and run.
-                            The layer, in this case, would be where all the
-                            recipes that define those dependencies are kept.
-                            The key point for a layer is that it is an isolated
-                            area that contains all the relevant information for
-                            the project that the OpenEmbedded build system knows
-                            about.
-                            For more information on layers, see the
-                            "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
-                            section in the Yocto Project Development Manual.
-                            For more information on BSP layers, see the
-                            "<link linkend='bsp-layers'>BSP Layers</link>"
-                            section.
-                            <note>
-                                <para>
-                                    Five BSPs exist that are part of the Yocto Project release:
-                                    <filename>beaglebone</filename> (ARM),
-                                    <filename>mpc8315e</filename> (PowerPC),
-                                    and <filename>edgerouter</filename> (MIPS).
-                                    The recipes and configurations for these five BSPs
-                                    are located and dispersed within the
-                                    <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
-                                </para>
-
-                                <para>
-                                    Three core Intel BSPs exist as part of the Yocto
-                                    Project release in the
-                                    <filename>meta-intel</filename> layer:
-                                    <itemizedlist>
-                                        <listitem><para><filename>intel-core2-32</filename>,
-                                            which is a BSP optimized for the Core2 family of CPUs
-                                            as well as all CPUs prior to the Silvermont core.
-                                            </para></listitem>
-                                        <listitem><para><filename>intel-corei7-64</filename>,
-                                            which is a BSP optimized for Nehalem and later
-                                            Core and Xeon CPUs as well as Silvermont and later
-                                            Atom CPUs, such as the Baytrail SoCs.
-                                            </para></listitem>
-                                        <listitem><para><filename>intel-quark</filename>,
-                                            which is a BSP optimized for the Intel Galileo
-                                            gen1 &amp; gen2 development boards.
-                                            </para></listitem>
-                                    </itemizedlist>
-                                </para>
-                            </note>
-                        </para>
+                            <para>Three core Intel BSPs exist as part of the Yocto
+                            Project release in the
+                            <filename>meta-intel</filename> layer:
+                            <itemizedlist>
+                                <listitem><para>
+                                    <filename>intel-core2-32</filename>,
+                                    which is a BSP optimized for the Core2 family of CPUs
+                                    as well as all CPUs prior to the Silvermont core.
+                                    </para></listitem>
+                                <listitem><para>
+                                    <filename>intel-corei7-64</filename>,
+                                    which is a BSP optimized for Nehalem and later
+                                    Core and Xeon CPUs as well as Silvermont and later
+                                    Atom CPUs, such as the Baytrail SoCs.
+                                    </para></listitem>
+                                <listitem><para>
+                                    <filename>intel-quark</filename>,
+                                    which is a BSP optimized for the Intel Galileo
+                                    gen1 &amp; gen2 development boards.
+                                    </para></listitem>
+                            </itemizedlist></para>
+                        </note></para>
 
-                        <para>When you set up a layer for a new BSP, you should follow a standard layout.
+                        <para>When you set up a layer for a new BSP, you should
+                        follow a standard layout.
                         This layout is described in the
                         "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
                         section.
-                        In the standard layout, you will notice a suggested structure for recipes and
-                        configuration information.
+                        In the standard layout, you will notice a suggested
+                        structure for recipes and configuration information.
                         You can see the standard layout for a BSP by examining
-                        any supported BSP found in the <filename>meta-intel</filename> layer inside
-                        the Source Directory.</para></listitem>
-                    <listitem><para><emphasis>Make configuration changes to your new BSP
-                        layer</emphasis>:  The standard BSP layer structure organizes the files you need
-                        to edit in <filename>conf</filename> and several <filename>recipes-*</filename>
+                        any supported BSP found in the
+                        <filename>meta-intel</filename> layer inside the Source
+                        Directory.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Make Configuration Changes to Your New BSP
+                        Layer:</emphasis>
+                        The standard BSP layer structure organizes the files
+                        you need to edit in <filename>conf</filename> and
+                        several <filename>recipes-*</filename>
                         directories within the BSP layer.
-                        Configuration changes identify where your new layer is on the local system
-                        and identify which kernel you are going to use.
-                        When you run the <filename>yocto-bsp</filename> script, you are able to interactively
-                        configure many things for the BSP (e.g. keyboard, touchscreen, and so forth).
+                        Configuration changes identify where your new layer
+                        is on the local system and identify which kernel you
+                        are going to use.
+                        When you run the <filename>yocto-bsp</filename> script,
+                        you are able to interactively configure many things for
+                        the BSP (e.g. keyboard, touchscreen, and so forth).
                         </para></listitem>
-                    <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>:  Recipe
-                        changes include altering recipes (<filename>.bb</filename> files), removing
-                        recipes you do not use, and adding new recipes or append files
-                        (<filename>.bbappend</filename>) that you need to support your hardware.
+                    <listitem><para>
+                        <emphasis>Make Recipe Changes to Your New BSP
+                        Layer:</emphasis>
+                        Recipe changes include altering recipes
+                        (<filename>.bb</filename> files), removing recipes you
+                        do not use, and adding new recipes or append files
+                        (<filename>.bbappend</filename>) that you need to
+                        support your hardware.
                         </para></listitem>
-                    <listitem><para><emphasis>Prepare for the build</emphasis>:  Once you have made all the
-                        changes to your BSP layer, there remains a few things
-                        you need to do for the OpenEmbedded build system in order for it to create your image.
-                        You need to get the build environment ready by sourcing an environment setup script
+                    <listitem><para>
+                        <emphasis>Prepare for the Build:</emphasis>
+                        Once you have made all the changes to your BSP layer,
+                        there remains a few things you need to do for the
+                        OpenEmbedded build system in order for it to create
+                        your image.
+                        You need to get the build environment ready by
+                        sourcing an environment setup script
                         (i.e. <filename>oe-init-build-env</filename> or
                         <filename>oe-init-build-env-memres</filename>)
-                        and you need to be sure two key configuration files are configured appropriately:
-                        the <filename>conf/local.conf</filename> and the
+                        and you need to be sure two key configuration
+                        files are configured appropriately: the
+                        <filename>conf/local.conf</filename> and the
                         <filename>conf/bblayers.conf</filename> file.
-                        You must make the OpenEmbedded build system aware of your new layer.
+                        You must make the OpenEmbedded build system aware
+                        of your new layer.
                         See the
                         "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
                         section in the Yocto Project Development Manual
-                        for information on how to let the build system know about your new layer.</para>
-                        <para>The entire process for building an image is overviewed in the section
+                        for information on how to let the build system
+                        know about your new layer.</para>
+
+                        <para>The entire process for building an image is
+                        overviewed in the section
                         "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" section
                         of the Yocto Project Quick Start.
-                        You might want to reference this information.</para></listitem>
-                    <listitem><para><emphasis>Build the image</emphasis>:  The OpenEmbedded build system
-                        uses the BitBake tool to build images based on the type of image you want to create.
+                        You might want to reference this information.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Build the Image:</emphasis>
+                        The OpenEmbedded build system uses the BitBake tool
+                        to build images based on the type of image you want to
+                        create.
                         You can find more information about BitBake in the
                         <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
                         </para>
-                        <para>The build process supports several types of images to satisfy different needs.
+
+                        <para>The build process supports several types of
+                        images to satisfy different needs.
                         See the
-                        "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
-                        in the Yocto Project Reference Manual for information on
-                        supported images.</para></listitem>
+                        "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+                        chapter in the Yocto Project Reference Manual for
+                        information on supported images.
+                        </para></listitem>
                 </orderedlist>
             </para>
         </section>