diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index 2dfc46e740..813c96eca8 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -172,9 +172,9 @@ You can view a video presentation on "Building Custom Embedded Images with Yocto" at Free Electrons. - You can also find supplemental information in the + You can also find supplemental information in - Board Support Package (BSP) Development Guide. + The Board Support Package (BSP) Development Guide. Finally, there is wiki page write up of the example located here you might find helpful. @@ -195,9 +195,9 @@ 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 - Yocto Project Kernel Architecture and Use Manual. + The Yocto Project Kernel Architecture and Use Manual. You can reference Kernel Modification Example for a detailed example that changes the configuration of a kernel. @@ -208,51 +208,17 @@ 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. - 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. - - - - 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. - - - - 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 - SRC_URI 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. - - - - You can find a web interface to the Yocto Project source repository at - . - 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). - - - - The Yocto Project supports four types of kernels in its source repositories at - : + You can find a web interface to the Linux Yocto kernel source repositories at + . + 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: linux-yocto-2.6.34 - The stable Linux Yocto kernel that is based on the Linux 2.6.34 release. @@ -262,17 +228,125 @@ Linux Yocto kernel that is based on the Linux 3.0 release. linux-yocto-dev - A development kernel based on the latest upstream release candidate available. - linux-2.6 - A kernel based on - minimal Linux mainline tracking. - You can find the .bbappend for this kernel in the - meta-kernel-dev Git repository. - 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: + + + + + + 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 linux-yocto-3.0 + kernel. + Thus, everything further to the right in the structure is based on the + linux-yocto-3.0 kernel. + Branch points to right in the figure represent where the + linux-yocto-3.0 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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 Linux Yocto Kernel item earlier + in this manual for an example of how to set up the kernel source directory + structure on your host system. + + + + This next figure illustrates how the kernel source files might be arranged on + your host system. + + + + + + + + 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 + Modifying the Kernel Source Code provides a detailed example. + + + + 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 + SRC_URI 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. + + 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. + + + + + + + + Again, for a complete discussion of the Yocto Project kernel's architcture and its + branching strategy, see the The Yocto Project Kernel Architecture and Use Manual. + Also, you can reference + Modifying the Kernel Source Code + for a detailed example that modifies the kernel.