sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

documentation/dev-manual/dev-manual-model.xml: Edits to Modifying Kernel 

Complete re-write of this section based on feedback from Dave Stewart.
Dave's comments centered around not being able to understand the overall
concepts of the Git repositories, the source areas on the host, etc.
I have added several illustrations and written around them to try and
better explain the kernel storage system in Git used by YP and how
that tranlates into host-resident code that the developer ultimately
uses and the Poky build system uses for the build.

(From yocto-docs rev: 4e37f68f77261f6519426fb81ba407c456f8d1a1)

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 2011-08-31 06:46:23 -07:00 committed by Richard Purdie
parent 5da4d3eb2b
commit 837a46434f
1 changed files with 124 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
documentation/dev-manual/dev-manual-model.xml
View File

@ -172,9 +172,9 @@
<para>
You can view a video presentation on "Building Custom Embedded Images with Yocto"
at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>.
You can also find supplemental information in the
You can also find supplemental information in
<ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'>
Board Support Package (BSP) Development Guide</ulink>.
The Board Support Package (BSP) Development Guide</ulink>.
Finally, there is wiki page write up of the example located
<ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
here</ulink> you might find helpful.
@ -195,9 +195,9 @@
<para>
The remainder of this section presents a high-level overview of the Linux Yocto
kernel architecture and the steps to modify the Linux Yocto kernel.
For a complete discussion of the kernel, see the
For a complete discussion of the kernel, see
<ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'>
Yocto Project Kernel Architecture and Use Manual</ulink>.
The Yocto Project Kernel Architecture and Use Manual</ulink>.
You can reference <xref linkend='dev-manual-kernel-appendix'>Kernel Modification Example</xref>
for a detailed example that changes the configuration of a kernel.
</para>
@ -208,51 +208,17 @@
<para>
When one thinks of the source files for a kernel they usually think of a fixed structure
of files that contain kernel patches.
The Yocto Project, however, employs mechanisims that in a sense result in a kernel source
The Yocto Project, however, employs mechanisims, that in a sense, result in a kernel source
generator.
</para>
<para>
The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto
Project files.
Git employs branching strategies that effectively produce a tree-like structure whose
branches represent diversions from more general code.
For example, suppose two kernels are basically identical with the exception of a couple
different features in each.
In the Yocto Project source repositories managed by Git a main branch can contain the
common or shared
parts of the kernel source and two branches that diverge from that common branch can
each contain the features specific to the respective kernel.
The result is a managed tree whose "leaves" represent the end of a specific path that yields
a set of kernel source files necessary for a specific piece of hardware and its features.
</para>
<para>
A big advantage to this scheme is the sharing of common features by keeping them in
"larger" branches that are further up the tree.
This practice eliminates redundant storage of similar features shared among kernels.
</para>
<para>
When you build the kernel on your development system all files needed for the build
are taken from the Yocto Project source repositories pointed to by the
<filename>SRC_URI</filename> variable and gathered in a temporary work area
where they are subsequently used to create the unique kernel.
Thus, in a sense, the process constructs a local source tree specific to your
kernel to generate the new kernel image - a source generator if you will.
</para>
<para>
You can find a web interface to the Yocto Project source repository at
<ulink url='http://git.yoctoproject.org/'></ulink>.
Within the interface you will see groups of related source code, each of which can
be cloned using Git to result in a working Git repository on your local system
(referred to as the "local Yocto Project files" in this manual).
</para>
<para>
The Yocto Project supports four types of kernels in its source repositories at
<ulink url='http://git.yoctoproject.org/'></ulink>:
You can find a web interface to the Linux Yocto kernel source repositories at
<ulink url='http://git.yoctoproject.org/'></ulink>.
If you look at the interface, you will see to the left a grouping of
Git repositories titled "Yocto Linux Kernel."
Within this group, you will find the four different kernels supported by
the Yocto Project:
<itemizedlist>
<listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The
stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem>
@ -262,17 +228,125 @@
Linux Yocto kernel that is based on the Linux 3.0 release.</para></listitem>
<listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
kernel based on the latest upstream release candidate available.</para></listitem>
<listitem><para><emphasis><filename>linux-2.6</filename></emphasis> - A kernel based on
minimal Linux mainline tracking.
You can find the <filename>.bbappend</filename> for this kernel in the
<filename>meta-kernel-dev</filename> Git repository.</para></listitem>
</itemizedlist>
</para>
<para>
For a complete discussion of the Yocto Project kernel's architcture and its branching strategy,
The kernels are maintained using the Git application that, in a sense, structures
them in a "tree" complete with branches and leaves.
Branches represent diversions from general code to more specific code, while leaves
represent the end-points for a complete and unique kernel whose source files
when gathered from the root of the tree to the leaf accumulate to create the files
necessary for a specific piece of hardware and its features.
The following figure displays this concept:
<para>
<imagedata fileref="figures/kernel-overview-1.png"
width="6in" depth="6in" align="center" scale="100" />
</para>
<para>
Within the figure, the "Kernel.org Branch Point" represents the point in the tree
where a supported base kernel diverges from the Linux kernel.
For example, this could be the branch point for the <filename>linux-yocto-3.0</filename>
kernel.
Thus, everything further to the right in the structure is based on the
<filename>linux-yocto-3.0</filename> kernel.
Branch points to right in the figure represent where the
<filename>linux-yocto-3.0</filename> kernel is modified for specific hardware
or types of kernels, such as real-time kernels.
Each leaf thus represents the end-point for a kernel designed to run on a specific
targeted device.
</para>
<para>
The overall result is a Git-maintained repository from which all the supported
Yocto Project kernels can be derived for all the supported Yocto Project devices.
A big advantage to this scheme is the sharing of common features by keeping them in
"larger" branches within the tree.
This practice eliminates redundant storage of similar features shared among kernels.
</para>
<note>
Keep in mind the figure does not take into account all four supported Linux Yocto
kernel types, but rather shows a single generic kernel just for conceptual purposes.
Also keep in mind that this structure represents the Yocto Project source repositories
that are either pulled from during the build or established on the host development system
prior to the build by either cloning a particular kernel's Git repository or by
downloading and unpacking a tarball.
</note>
<para>
Storage of all the available kernel source code is one thing, while representing the
code on your host development system is another.
Conceptually, you can think of the Yocto Project kernel source repositories as all the
source files necessary for all the supported kernels.
As a developer, you are just interested in the source files for the kernel on
on which you are working.
And, furthermore, you need them available on your host system.
</para>
<para>
You make kernel source code available on your host development system by using
Git to create a bare clone of the Linux Yocto kernel Git repository
in which you are interested.
Then, you use Git again to clone a copy of that bare clone.
This copy represents the directory structure on your host system that is particular
to the kernel you want.
These are the files you actually modify to change the kernel.
See the <link linkend='local-kernel-files'>Linux Yocto Kernel</link> item earlier
in this manual for an example of how to set up the kernel source directory
structure on your host system.
</para>
<para>
This next figure illustrates how the kernel source files might be arranged on
your host system.
</para>
<para>
<imagedata fileref="figures/kernel-overview-3.png"
width="6in" depth="4in" align="center" scale="100" />
</para>
<para>
In the previous figure, the file structure on the left represents the bare clone
set up to track the Yocto Project kernel Git repository.
The structure on the right represents the copy of the bare clone.
When you make modifcations to the kernel source code, this is the area in which
you work.
Once you make corrections, you must use Git to push the committed changes to the
bare clone.
The example in <xref linkend='modifying-the-kernel-source-code'>
Modifying the Kernel Source Code</xref> provides a detailed example.
</para>
<para>
What happens during the build?
When you build the kernel on your development system all files needed for the build
are taken from the Yocto Project source repositories pointed to by the
<filename>SRC_URI</filename> variable and gathered in a temporary work area
where they are subsequently used to create the unique kernel.
Thus, in a sense, the process constructs a local source tree specific to your
kernel to generate the new kernel image - a source generator if you will.
</para>
The following figure shows the temporary file structure
created on your host system when the build occurs.
This build directory contains all the source files used during the build.
</para>
<para>
<imagedata fileref="figures/kernel-overview-2.png"
width="6in" depth="5in" align="center" scale="100" />
</para>
<para>
Again, for a complete discussion of the Yocto Project kernel's architcture and its
branching strategy,
see the <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'>
The Yocto Project Kernel Architecture and Use Manual</ulink>.
Also, you can reference
<xref linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source Code</xref>
for a detailed example that modifies the kernel.
</para>
</section>