mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-09-13 00:49:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

kernel-dev: Re-write of the "Organizing Your Source" section.

Browse Source 
A serious pass through this system to reorganize it.

(From yocto-docs rev: f13abc59730d78e5ffa5bce3d38519f8fc4c127f)

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
2013-01-11 14:04:40 -08:00
committed by Richard Purdie
parent 5b1098dc0b
commit c9f796dbd7
1 changed files with 118 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -56,7 +56,7 @@ contain the highest level visible CONFIG options as presented by the Linux
kernel menuconfig system. This reduces your maintenance effort and allows you kernel menuconfig system. This reduces your maintenance effort and allows you
to further separate your configuration in ways that make sense for your project. to further separate your configuration in ways that make sense for your project.
A common split is policy and hardware. For example, all your kernels may support A common split is policy and hardware. For example, all your kernels may support
the proc and sys filesystems, but only specific boards will require sound, usb, the proc and sys filesystems, but only specific boards will require sound, USB,
or specific drivers. Specifying these individually allows you to aggregate them or specific drivers. Specifying these individually allows you to aggregate them
together as needed, but maintain them in only one place. Similar logic applies together as needed, but maintain them in only one place. Similar logic applies
to source changes. to source changes.
@@ -136,7 +136,7 @@ to source changes.
The linux-yocto recipes define "standard", "tiny", and "preempt-rt" The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
kernel types. kernel types.
See the <link linkend='kernel-types'>Kernel Types</link> section See the <link linkend='kernel-types'>Kernel Types</link> section
for more inforation on kernel types. for more information on kernel types.
</para> </para>
<para> <para>
@@ -237,7 +237,7 @@ Together with KMACHINE, this defines the search arguments used by the Yocto
Project Linux kernel tools to find the appropriate description within the Project Linux kernel tools to find the appropriate description within the
metadata with which to build out the sources and configuration. The linux-yocto metadata with which to build out the sources and configuration. The linux-yocto
recipes define "standard", "tiny", and "preempt-rt" kernel types. See 3.3.4 for recipes define "standard", "tiny", and "preempt-rt" kernel types. See 3.3.4 for
more inforation on kernel types. more information on kernel types.
During the build, the kern-tools will search for the BSP description file that During the build, the kern-tools will search for the BSP description file that
most closely matches the KMACHINE and LINUX_KERNEL_TYPE passed in from the most closely matches the KMACHINE and LINUX_KERNEL_TYPE passed in from the
@@ -332,7 +332,7 @@ or if you just don't want to maintain a Linux kernel git repository on your own.
If you are doing active kernel development and are already maintaining a Linux If you are doing active kernel development and are already maintaining a Linux
kernel git repository of your own, you may find it more convenient to work with kernel git repository of your own, you may find it more convenient to work with
the meta-data in the same repository as the Linux kernel sources. This can make the meta-data in the same repository as the Linux kernel sources. This can make
iterative development of the Linux kernel more efficient outside of the bitbake iterative development of the Linux kernel more efficient outside of the BitBake
environment. environment.
Regardless of where the meta-data is stored, the syntax as Regardless of where the meta-data is stored, the syntax as
@@ -406,10 +406,10 @@ meta/
`-- standard.cfg `-- standard.cfg
When the meta-data is stored in recipe-space, you must take steps to ensure When the meta-data is stored in recipe-space, you must take steps to ensure
bitbake has the necessary information to decide which files to fetch and when BitBake has the necessary information to decide which files to fetch and when
they need to be fetched again. they need to be fetched again.
It is only necessary to specify the .scc files on the SRC_URI; bitbake will It is only necessary to specify the .scc files on the SRC_URI; BitBake will
parse them and fetch any files referenced in the .scc files by the include, parse them and fetch any files referenced in the .scc files by the include,
patch, or kconf commands. Because of this, it is necessary to bump the recipe PR patch, or kconf commands. Because of this, it is necessary to bump the recipe PR
value when changing the content of files not explicitly listed in the SRC_URI. value when changing the content of files not explicitly listed in the SRC_URI.
@@ -1373,17 +1373,21 @@ the KTYPE has changed, now set to "tiny".
</section> </section>
</section> </section>
<section id='working-with-branches'> <section id='organizing-your-source'>
<title>Working with Branches</title> <title>Organizing Your Source</title>
<para> <para>
Many recipes based on the <filename>linux-yocto-custom.bb<filename> Many recipes based on the <filename>linux-yocto-custom.bb</filename>
use Linux kernel sources that have only the single branch - "master". recipe use Linux kernel sources that have only a single
branch - "master".
This type of repository structure is fine for linear development
supporting a single machine and architecture.
However, if you work with multiple boards and architectures, However, if you work with multiple boards and architectures,
you are likely to run into the situation where a series of patches a kernel source repository with multiple branches is more
are needed for one board to boot. efficient.
For example, suppose you need a series of patches for one board to boot.
Sometimes, these patches are works-in-progress or fundamentally wrong, Sometimes, these patches are works-in-progress or fundamentally wrong,
yet still necessary for specific boards. yet they are still necessary for specific boards.
In these situations, you most likely do not want to include these In these situations, you most likely do not want to include these
patches in every kernel you build (i.e. have the patches as part of patches in every kernel you build (i.e. have the patches as part of
the lone "master" branch). the lone "master" branch).
@@ -1392,28 +1396,79 @@ the KTYPE has changed, now set to "tiny".
</para> </para>
<para> <para>
If you are supporting multiple boards and architectures, you have Repository organization strategies exist that maximize source reuse,
some options as to how you want to isolate your changes: remove redundancy, and logically order your changes.
This section presents strategies for the following cases:
<itemizedlist> <itemizedlist>
<listitem><para><emphasis>Include feature patches in the BSP:</emphasis> <listitem><para>Encapsulating patches in a feature description
Encapsulate patches in a feature description and only include and only including the patches in the BSP descriptions of
the patches in the BSP descriptions of the applicable boards. the applicable boards.</para></listitem>
For more information, see the <listitem><para>Creating a machine branch in your
"<link linkend='patches'>Patches</link>" and kernel source repository and applying the patches on that
"<link linkend='bsp-descriptions'>BSP Descriptions</link>" branch only.</para></listitem>
sections.</para></listitem> <listitem><para>Creating a feature branch in your
<listitem><para><emphasis>Create a machine branch:</emphasis> kernel source repository and merging that branch into your
You can create a machine branch in your Linux kernel sources BSP when needed.</para></listitem>
and apply the patches there. </itemizedlist>
You can then specify this new branch as the </para>
<filename>KBRANCH</filename> to use for this board.
You can do this in the recipe with the <para>
<filename>KBRANCH</filename> variable: The approach you take is entirely up to you
<literallayout class='monospaced'> and depends on what works best for your development model.
</para>
<section id='encapsulating-patches'>
<title>Encapsulating Patches</title>
<para>
if you are reusing patches from an external tree and are not
working on the patches, you might find the encapsulated feature
to be appropriate.
Given this scenario, you don't need to create any branches in the
source repository.
Rather, you just take the static patches you need and encapsulate
them within a feature description.
Once you have the feature description, you simply include that into
the BSP description as described in the
"<link linkend='bsp-descriptions'>BSP Descriptions</link>"
section.
</para>
<para>
You can find information on how to create patches and BSP
descriptions in the "<link linkend='patches'>Patches</link>" and
"<link linkend='bsp-descriptions'>BSP Descriptions</link>"
sections.
</para>
</section>
<section id='machine-branches'>
<title>Machine Branches</title>
<para>
When you have multiple machines and architectures to support,
or you are actively working on board support, it is more
efficient to create branches in the repository based on
individual machines.
Having machine branches allows common source to remain in the
"master" branch with any features specific to a machine stored
in the appropriate machine branch.
This organization method frees you from continually reintegrating
your patches into a feature.
</para>
<para>
Once you have a new branch, you can set up your kernel Metadata
to use the branch a couple different ways.
In the recipe, you can specify the new branch as the
<filename>KBRANCH</filename> to use for the board as
follows:
<literallayout class='monospaced'>
KBRANCH = "mynewbranch" KBRANCH = "mynewbranch"
</literallayout> </literallayout>
or in the BSP description using the "branch" command: Another method is to use the <filename>branch</filename> command
<literallayout class='monospaced'> in the BSP description:
<literallayout class='monospaced'>
mybsp.scc: mybsp.scc:
define KMACHINE mybsp define KMACHINE mybsp
define KTYPE standard define KTYPE standard
@@ -1423,44 +1478,23 @@ the KTYPE has changed, now set to "tiny".
branch mynewbranch branch mynewbranch
include mybsp-hw.scc include mybsp-hw.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>
<section id='machine-branches'>
<title>Machine Branches</title>
<para>
The "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel 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.
</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> </literallayout>
</para> </para>
<para> <para>
If you had two ktypes, standard and small for instance, and three If you find
machines, your Git tree might look like this: 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;kernel_type&gt;/&lt;machine&gt;
</literallayout>
</para>
<para>
If you had two kernel types, "standard" and "small" for
instance, and three machines, the branches in your
Git repository might look like this:
<literallayout class='monospaced'> <literallayout class='monospaced'>
common/base common/base
common/standard/base common/standard/base
@@ -1473,16 +1507,17 @@ the KTYPE has changed, now set to "tiny".
</para> </para>
<para> <para>
This organization can help clarify the relationship of the branches to This organization can help clarify the branch relationships.
each other. In this case, <filename>common/standard/machine_a</filename>
In this case, "common/standard/machine_a" would include everything in includes everything in <filename>common/base</filename> and
"common/base" and "common/standard/base". <filename>common/standard/base</filename>.
The "standard" and "small" branches add sources specific to those The "standard" and "small" branches add sources specific to those
kernel types that for whatever reason are not appropriate for the kernel types that for whatever reason are not appropriate for the
other branches. other branches.
<note>The "base" branches are an artifact of the way Git manages <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 its data internally on the filesystem: Git will not allow you
"common/standard" and "common/standard/machine_a" because it to use <filename>common/standard</filename> and
<filename>common/standard/machine_a</filename> because it
would have to create a file and a directory named "standard". would have to create a file and a directory named "standard".
</note> </note>
</para> </para>
@@ -1518,7 +1553,13 @@ mybsp.scc:
define KARCH i386 define KARCH i386
include standard.scc include standard.scc
branch mynewbranch branch mynewbranchIf 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
include mybsp.scc include mybsp.scc
@@ -1566,9 +1607,9 @@ Note: The "base" branches are an artifact of the way git manages its data
<title>Feature Branches</title> <title>Feature Branches</title>
<para> <para>
During active development a new feature, it can be more efficient When you are actively developing new features, it can be more
to work with that feature as a branch, rather than as a set of efficient to work with that feature as a branch, rather than
patches which have to be regularly updated. as a set of patches that have to be regularly updated.
The Yocto Project Linux kernel tools provide for this with The Yocto Project Linux kernel tools provide for this with
the <filename>git merge</filename> command. the <filename>git merge</filename> command.
</para> </para>