kernel-dev: Formatted the "BSP Descriptions" section.

(From yocto-docs rev: 9cfccb3372f47094479fb0a5ad095cf2b46f906e)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 147 insertions, 105 deletions

diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index e8587eee52..ee90df2732 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -1016,133 +1016,175 @@ Note: It is not strictly necessary to create a ktype scc file. The BSP file can
         <title>BSP Descriptions</title>
 
         <para>
-3.3.5 BSP Descriptions
-----------
-BSP descriptions combine kernel types (see 3.3.4) with hardware-specific
-features (see 3.3.3). The hardware specific portion is typically defined
-independently, and then aggregated with each supported kernel type. Consider a
-simple example:
-
-mybsp.scc:
-        define KMACHINE mybsp
-        define KTYPE standard
-        define KARCH i386
-
-        kconf mybsp.cfg
-
-Every BSP description should include the definition of the KMACHINE, KTYPE, and
-KARCH variables. These variables allow the build-system to identify this
-description as meeting the criteria set by the recipe being built. This
-particular description can be said to support the "mybsp" machine for the
-"standard" kernel type and the "i386" architecture. Note that there is no hard
-link between the KTYPE and a ktype description file. If you do not have kernel
-types defined in your meta-data, you only need to ensure that the recipe
-LINUX_KERNEL_TYPE and the KTYPE here match.
-
-NOTE: future versions of the tooling make the specification of KTYPE in the BSP
-      optional.
-
-If you did want to separate your kernel policy from your hardware configuration,
-you could do so by specifying a kernel type, such as "standard" (see 3.3.4) and
-including that description in the BSP description. You might also have multiple
-hardware configurations that you aggregate into a single hardware description
-file which you could include here, rather than referencing a single .cfg file.
-Consider the following:
+            BSP descriptions combine kernel types with hardware-specific
+            features.
+            The hardware specific portion is typically defined
+            independently, and then aggregated with each supported kernel
+            type.
+            Consider a simple example:
+            <literallayout class='monospaced'>
+     mybsp.scc:
+        define KMACHINE mybsp
+        define KTYPE standard
+        define KARCH i386
 
-mybsp.scc:
-        define KMACHINE mybsp
-        define KTYPE standard
-        define KARCH i386
+        kconf mybsp.cfg
+            </literallayout>
+            Every BSP description should include the definition of the
+            <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
+            and <filename>KARCH</filename> variables.
+            These variables allow the build-system to identify this
+            description as meeting the criteria set by the recipe being built.
+            This particular description can be said to support the "mybsp"
+            machine for the "standard" kernel type and the "i386" architecture.
+            Be aware that there is no hard link between the
+            <filename>KTYPE</filename> and a ktype description file.
+            If you do not have kernel types defined in your metadata, you
+            only need to ensure that the recipe
+            <filename>LINUX_KERNEL_TYPE</filename> and the
+            <filename>KTYPE</filename> here match.
+            <note>
+                Future versions of the tooling make the specification of
+                <filename>KTYPE</filename> in the BSP optional.
+            </note>
+        </para>
 
-        include standard.scc
-        include mybsp.scc
+        <para>
+            If you did want to separate your kernel policy from your
+            hardware configuration, you could do so by specifying a kernel
+            type, such as "standard" (see 3.3.4) and including that
+            description in the BSP description.
+            You might also have multiple hardware configurations that you
+            aggregate into a single hardware description file which you
+            could include here, rather than referencing a single
+            <filename>.cfg</filename> file.
+            Consider the following:
+            <literallayout class='monospaced'>
+     mybsp.scc:
+        define KMACHINE mybsp
+        define KTYPE standard
+        define KARCH i386
 
-In the above example standard.scc aggregates all the configuration fragments,
-patches, and features that make up your standard kernel policy whereas mybsp.scc
-aggregates all those necessary to support the hardware available on the mybsp
-machine. For information on how to break a complete .config into the various
-fragments, see 2.3.1.
+        include standard.scc
+        include mybsp.scc
+            </literallayout>
+        </para>
 
-Many real-world examples are more complex. Like any other scc file, BSP
-descriptions can aggregate features. Consider the Fish River Island II (fri2)
-BSP definitions from the linux-yocto-3.4 repository:
+        <para>
+            In the above example, <filename>standard.scc</filename>
+            aggregates all the configuration fragments, patches, and
+            features that make up your standard kernel policy whereas
+            <filename>mybsp.scc</filename> aggregates all those necessary
+            to support the hardware available on the <filename>mybsp</filename>
+            machine.
+            For information on how to break a complete <filename>.config</filename>
+            into the various, see the
+            "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
+            section.
+        </para>
 
-fri2.scc:
-        kconf hardware fri2.cfg
+        <para>
+            Many real-world examples are more complex.
+            Like any other <filename>scc</filename> file, BSP
+            descriptions can aggregate features.
+            Consider the Fish River Island II (fri2)
+            BSP definitions from the linux-yocto-3.4 repository:
+            <literallayout class='monospaced'>
+     fri2.scc:
+        kconf hardware fri2.cfg
         
-        include cfg/x86.scc
-        include features/eg20t/eg20t.scc
-        include cfg/dmaengine.scc
-        include features/ericsson-3g/f5521gw.scc
-        include features/power/intel.scc
-        include cfg/efi.scc
-        include features/usb/ehci-hcd.scc
-        include features/usb/ohci-hcd.scc
-        include features/iwlwifi/iwlwifi.scc
-
-The fri2.scc description file includes a hardware configuration fragment
-(fri2.cfg) specific to the fri2 BSP as well as several more general
-configuration fragments and features enabling hardware found on the fri2. This
-description is then included in each of the three machine-ktype descriptions
-(standard, preempt-rt, and tiny). Consider the fri2 standard description:
+        include cfg/x86.scc
+        include features/eg20t/eg20t.scc
+        include cfg/dmaengine.scc
+        nclude features/ericsson-3g/f5521gw.scc
+        include features/power/intel.scc
+        include cfg/efi.scc
+        include features/usb/ehci-hcd.scc
+        include features/usb/ohci-hcd.scc
+        include features/iwlwifi/iwlwifi.scc
+            </literallayout>
+        </para>
 
-fri2-standard.scc:
-        define KMACHINE fri2
-        define KTYPE standard
-        define KARCH i386
+        <para>
+            The <filename>fri2.scc</filename> description file includes
+            a hardware configuration fragment
+            (<filename>fri2.cfg</filename>) specific to the fri2 BSP
+            as well as several more general configuration fragments and
+            features enabling hardware found on the fri2.
+            This description is then included in each of the three
+            machine-ktype descriptions (standard, preempt-rt, and tiny).
+            Consider the fri2 standard description:
+            <literallayout class='monospaced'>
+     fri2-standard.scc:
+        define KMACHINE fri2
+        define KTYPE standard
+        define KARCH i386
         
-        include ktypes/standard/standard.scc
-        branch fri2
+        include ktypes/standard/standard.scc
+        branch fri2
         
-        git merge emgd-1.14
+        git merge emgd-1.14
         
-        include fri2.scc
+        include fri2.scc
         
-        # Extra fri2 configs above the minimal defined in fri2.scc
-        include cfg/efi-ext.scc
-        include features/drm-emgd/drm-emgd.scc
-        include cfg/vesafb.scc
+        # Extra fri2 configs above the minimal defined in fri2.scc
+        include cfg/efi-ext.scc
+        include features/drm-emgd/drm-emgd.scc
+        include cfg/vesafb.scc
         
-        # default policy for standard kernels
-        include cfg/usb-mass-storage.scc
-
-Note the "include fri2.scc" line about midway through the file. By defining all
-hardware enablement common to the BSP for all kernel types, duplication is
-significantly reduced.
-
-This description introduces a few more variables and commands worthy of further
-discussion.  Note the "branch" command which is used to create a
-machine-specific branch into which source changes can be applied. With this
-branch set up, the "git merge" command uses the git SCM to merge in a feature
-branch "emgd-1.14".  This could also be handled with the patch command, but for
-commonly used features such as this, feature branches can be a convenient
-mechanism (see 3.5).
+        # default policy for standard kernels
+        include cfg/usb-mass-storage.scc
+            </literallayout>
+            The "include fri2.scc" line about midway through the file defines
+            all hardware enablement common to the BSP for all kernel types.
+            Including the statement significantly reduces duplication.
+        </para>
 
-Next consider the fri2 tiny description:
+        <para>
+            This description introduces a few more variables and commands
+            worthy of further discussion.
+            Notice the "branch" command, which is used to create a
+            machine-specific branch into which source changes can be applied.
+            With this branch set up, the <filename>git merge</filename> command
+            uses Git to merge in a feature branch "emgd-1.14".
+            This could also be handled with the patch command, but for
+            commonly used features such as this, feature branches can be a
+            convenient mechanism.
+            See the "<link linkend='feature-branches'>Feature Branches</link>"
+            section for more information.
+        </para>
 
-fri2-tiny.scc:
-        define KMACHINE fri2
-        define KTYPE tiny
-        define KARCH i386
+        <para>
+            Now consider the Fish River Island 2 tiny
+            (<filename>fri2-tiny</filename>) BSP description:
+            <literallayout class='monospaced'>
+     fri2-tiny.scc:
+        define KMACHINE fri2
+        define KTYPE tiny
+        define KARCH i386
         
-        include ktypes/tiny/tiny.scc
-        branch fri2
+        include ktypes/tiny/tiny.scc
+        branch fri2
         
-        include fri2.scc
+        include fri2.scc
+            </literallayout>
+            As you might expect, the tiny description includes quite a bit less.
+            In fact, it includes only the minimal policy defined by the
+            tiny ktype and the hardware-specific configuration required for
+            boot and the most basic functionality of the system as defined in
+            the base fri2 description file.
+        </para>
 
-As you might expect, the tiny description includes quite a bit less. In fact,
-it includes only the minimal policy defined by the tiny ktype and the
-hardware-specific configuration required for boot and the most basic
-functionality of the system as defined in the base fri2 description file. Note
-again the three critical variables: KMACHINE, KTYPE, and KARCH. Of these, only
-the KTYPE has changed, now set to "tiny".
+        <para>
+            Notice again the three critical variables: <filename>KMACHINE</filename>,
+            <filename>KTYPE</filename>, and <filename>KARCH</filename>.
+            Of these, only the <filename>KTYPE</filename> has changed.
+            It is now set to "tiny".
         </para>
 
         <para>
             Original text:
             <literallayout class='monospaced'>
-3.3.5 BSP Descriptions
-----------
 BSP descriptions combine kernel types (see 3.3.4) with hardware-specific
 features (see 3.3.3). The hardware specific portion is typically defined
 independently, and then aggregated with each supported kernel type. Consider a