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>

documentation/kernel-dev/kernel-dev-advanced.xml

@@ -1016,77 +1016,106 @@ 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 with hardware-specific
-----------
+            features.
-BSP descriptions combine kernel types (see 3.3.4) with hardware-specific
+            The hardware specific portion is typically defined
-features (see 3.3.3). The hardware specific portion is typically defined
+            independently, and then aggregated with each supported kernel
-independently, and then aggregated with each supported kernel type. Consider a
+            type.
-simple example:
+            Consider a simple example:
-
+            <literallayout class='monospaced'>
-mybsp.scc:
+     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>
 
-Every BSP description should include the definition of the KMACHINE, KTYPE, and
+        <para>
-KARCH variables. These variables allow the build-system to identify this
+            If you did want to separate your kernel policy from your
-description as meeting the criteria set by the recipe being built. This
+            hardware configuration, you could do so by specifying a kernel
-particular description can be said to support the "mybsp" machine for the
+            type, such as "standard" (see 3.3.4) and including that
-"standard" kernel type and the "i386" architecture. Note that there is no hard
+            description in the BSP description.
-link between the KTYPE and a ktype description file. If you do not have kernel
+            You might also have multiple hardware configurations that you
-types defined in your meta-data, you only need to ensure that the recipe
+            aggregate into a single hardware description file which you
-LINUX_KERNEL_TYPE and the KTYPE here match.
+            could include here, rather than referencing a single
-
+            <filename>.cfg</filename> file.
-NOTE: future versions of the tooling make the specification of KTYPE in the BSP
+            Consider the following:
-      optional.
+            <literallayout class='monospaced'>
-
+     mybsp.scc:
-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:
-
-mybsp.scc:
         define KMACHINE mybsp
         define KTYPE standard
         define KARCH i386
 
         include standard.scc
         include mybsp.scc
+            </literallayout>
+        </para>
 
-In the above example standard.scc aggregates all the configuration fragments,
+        <para>
-patches, and features that make up your standard kernel policy whereas mybsp.scc
+            In the above example, <filename>standard.scc</filename>
-aggregates all those necessary to support the hardware available on the mybsp
+            aggregates all the configuration fragments, patches, and
-machine. For information on how to break a complete .config into the various
+            features that make up your standard kernel policy whereas
-fragments, see 2.3.1.
+            <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>
 
-Many real-world examples are more complex. Like any other scc file, BSP
+        <para>
-descriptions can aggregate features. Consider the Fish River Island II (fri2)
+            Many real-world examples are more complex.
-BSP definitions from the linux-yocto-3.4 repository:
+            Like any other <filename>scc</filename> file, BSP
-
+            descriptions can aggregate features.
-fri2.scc:
+            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
+        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>
 
-The fri2.scc description file includes a hardware configuration fragment
+        <para>
-(fri2.cfg) specific to the fri2 BSP as well as several more general
+            The <filename>fri2.scc</filename> description file includes
-configuration fragments and features enabling hardware found on the fri2. This
+            a hardware configuration fragment
-description is then included in each of the three machine-ktype descriptions
+            (<filename>fri2.cfg</filename>) specific to the fri2 BSP
-(standard, preempt-rt, and tiny). Consider the fri2 standard description:
+            as well as several more general configuration fragments and
-
+            features enabling hardware found on the fri2.
-fri2-standard.scc:
+            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
@@ -1105,22 +1134,31 @@ fri2-standard.scc:
 	
         # 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>
 
-Note the "include fri2.scc" line about midway through the file. By defining all
+        <para>
-hardware enablement common to the BSP for all kernel types, duplication is
+            This description introduces a few more variables and commands
-significantly reduced.
+            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>
 
-This description introduces a few more variables and commands worthy of further
+        <para>
-discussion.  Note the "branch" command which is used to create a
+            Now consider the Fish River Island 2 tiny
-machine-specific branch into which source changes can be applied. With this
+            (<filename>fri2-tiny</filename>) BSP description:
-branch set up, the "git merge" command uses the git SCM to merge in a feature
+            <literallayout class='monospaced'>
-branch "emgd-1.14".  This could also be handled with the patch command, but for
+     fri2-tiny.scc:
-commonly used features such as this, feature branches can be a convenient
-mechanism (see 3.5).
-
-Next consider the fri2 tiny description:
-
-fri2-tiny.scc:
         define KMACHINE fri2
         define KTYPE tiny
         define KARCH i386
@@ -1129,20 +1167,24 @@ fri2-tiny.scc:
         branch fri2
 	
         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,
+        <para>
-it includes only the minimal policy defined by the tiny ktype and the
+            Notice again the three critical variables: <filename>KMACHINE</filename>,
-hardware-specific configuration required for boot and the most basic
+            <filename>KTYPE</filename>, and <filename>KARCH</filename>.
-functionality of the system as defined in the base fri2 description file. Note
+            Of these, only the <filename>KTYPE</filename> has changed.
-again the three critical variables: KMACHINE, KTYPE, and KARCH. Of these, only
+            It is now set to "tiny".
-the KTYPE has changed, 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