mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-02-05 16:28:43 +01:00
Code Issues Packages Projects Releases Wiki Activity

kernel-dev: Formatting "Machine Branches" section.

Browse Source 
(From yocto-docs rev: 30a0d3c1ef3d91221ce3f90a3fd2f4b93bff1c30)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2012-12-27 14:50:40 -06:00
committed by Richard Purdie
parent fe1b20f80a
commit 49166264bd
1 changed files with 182 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
documentation/kernel-dev/kernel-dev-advanced.xml
View File

@@ -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