kernel-dev: Formatting "Machine Branches" section.

(From yocto-docs rev: 30a0d3c1ef3d91221ce3f90a3fd2f4b93bff1c30)

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

1 files changed, 182 insertions, 0 deletions

diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index ee90df2..dbc3dfb 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -1308,6 +1308,188 @@ the KTYPE has changed, now set to "tiny".
     </section>
 </section>
 
+
+
+
+<section id='machine-branches'>
+    <title>Machine Branches</title>
+
+    <para>
+        The "<link linkend='using-metadata-in-a-recipe'>Using Metadata in a Recipe</link>"
+        section introduced the <filename>KBRANCH</filename> variable, which
+        defines the source branch to use from the Linux kernel Git repository
+        you are using.
+        Many linux-yocto-custom derived recipes will be using Linux kernel
+        sources with only a single branch: "master".
+        However, when you are working with multiple boards and architectures,
+        you are likely to run into the situation where a series of patches
+        are needed for one board to boot.
+        Sometimes, these patches are works-in-progress or fundamentally wrong,
+        yet still necessary for specific boards.
+        In these situations, you most likely do not want to include these
+        patches in every kernel you build.
+        You have a couple of options.
+    </para>
+
+    <para>
+        First, you could encapsulate these patches in a feature description
+        and only include them in the BSP description for the board(s) that
+        require them.
+        For more information, see the
+        "<link linkend='patches'>Patches</link>" and
+        "<link linkend='bsp-descriptions'>BSP Descriptions</link>" sections.
+    </para>
+
+    <para>
+        Alternatively, you can create a branch in your Linux kernel sources
+        and apply the patches there.
+        You can then specify this new branch as the
+        <filename>KBRANCH</filename> to use for this board.
+        You can do this in the recipe with the
+        <filename>KBRANCH</filename> variable:
+        <literallayout class='monospaced'>
+     KBRANCH = "mynewbranch"
+        </literallayout>
+        or in the BSP description using the "branch" command:
+        <literallayout class='monospaced'>
+     mybsp.scc:
+        define KMACHINE mybsp
+        define KTYPE standard
+        define KARCH i386
+        include standard.scc
+
+        branch mynewbranch
+
+        include mybsp.scc
+        </literallayout>
+    </para>
+
+    <para>
+        The approach you take, feature or branch, is entirely up to you
+        and depends on what works best for your development model.
+        If you are actively working on board support, you may find that
+        working within a branch is more practical than trying to continually
+        reintegrate your patches into a feature.
+        On the other hand, if you are simply reusing some patches from an
+        external tree and are not working on them, you may find the
+        encapsulated feature to be appropriate as it does not require the
+        additional complexity of branching in your Linux kernel sources.
+    </para>
+
+    <para>
+        If you are supporting multiple boards and architectures and find
+        yourself with numerous branches, you might consider using a
+        hierarchical branching system similar to what the linux-yocto Linux
+        kernel repositories use:
+        <literallayout class='monospaced'>
+     &lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt;
+        </literallayout>
+    </para>
+
+    <para>
+        If you had two ktypes, standard and small for instance, and three
+        machines, your Git tree might look like this:
+        <literallayout class='monospaced'>
+     common/base
+     common/standard/base
+     common/standard/machine_a
+     common/standard/machine_b
+     common/standard/machine_c
+     common/small/base
+     common/small/machine_a
+        </literallayout>
+    </para>
+
+    <para>
+        This organization can help clarify the relationship of the branches to
+        each other.
+        In this case, "common/standard/machine_a" would include everything in
+        "common/base" and "common/standard/base".
+        The "standard" and "small" branches add sources specific to those
+        kernel types that for whatever reason are not appropriate for the
+        other branches.
+        <note>The "base" branches are an artifact of the way Git manages
+            its data internally on the filesystem: it will not allow you to use
+            "common/standard" and "common/standard/machine_a" because it
+            would have to create a file and a directory named "standard".
+        </note>
+    </para>
+
+    <para>
+        Original text:
+        <literallayout class='monospaced'>
+Section 3.1 introduced the KBRANCH variable which defines the source branch to
+use from the Linux kernel git repository you are using. Many linux-yocto-custom
+derived recipes will be using Linux kernel sources with only a single branch:
+"master". However, when you are working with multiple boards and architectures,
+you are likely to run into the situation where a series of patches are needed
+for one board to boot. Sometimes these patches are works in progress or
+fundamentally wrong, yet still necessary for specific boards. In these
+situations, you most likely do not want to include these patches in every kernel
+you build. You have a couple of options.
+
+First, you could encapsulate these patches in a feature description and only
+include them in the BSP description for the board(s) that require them (see
+3.3.2 and 3.3.5).
+
+Alternatively, you can create a branch in your Linux kernel sources and apply
+the patches there. You can then specify this new branch as the KBRANCH to use
+for this board. You can do this in the recipe with the KBRANCH variable:
+	
+	KBRANCH = "mynewbranch"
+	
+or in the BSP description using the "branch" command:
+
+mybsp.scc:
+	define KMACHINE mybsp
+	define KTYPE standard
+	define KARCH i386
+	include standard.scc
+
+	branch mynewbranch
+
+	include mybsp.scc
+
+The decision of which approach to take, feature or branch, is entirely up to you
+and depends on what works best for your development model. If you are actively
+working on board support, you may find that working within a branch is more
+practical than trying to continually reintegrate your patches into a feature. On
+the other hand, if you are simply reusing some patches from an external tree and
+are not working on them, you may find the encapsulated feature to be appropriate
+as it does not require the additional complexity of branching in your Linux
+kernel sources.
+
+If you are supporting multiple boards and architectures and find yourself with
+numerous branches, you might consider using a hierarchical branching system
+similar to what the linux-yocto Linux kernel repositories use:
+
+	&lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt;
+
+If you had two ktypes, standard and small for instance, and three machines, your
+git tree might look like this:
+
+	common/base
+	common/standard/base
+	common/standard/machine_a
+	common/standard/machine_b
+	common/standard/machine_c
+	common/small/base
+	common/small/machine_a
+
+This organization can help clarify the relationship of the branches to
+each other. In this case, "common/standard/machine_a" would include everything in
+"common/base" and "common/standard/base". The "standard" and "small" branches
+add sources specific to those kernel types that for whatever reason are not
+appropriate for the other branches.
+
+Note: The "base" branches are an artifact of the way git manages its data
+      internally on the filesystem: it will not allow you to use
+      "common/standard" and "common/standard/machine_a" because it would have to
+      create a file and a directory named "standard".
+        </literallayout>
+    </para>
+</section>
+
 </chapter>
 <!--
 vim: expandtab tw=80 ts=4