From 57e780f91551a858f51b9c5667fe9aa8e1ce968e Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 20 Oct 2011 10:38:05 -0700 Subject: documentation/dev-manual: Bruce Ashfield's dev-manual comments added. I was not able to get to Bruce's comments he submitted to me for the "Model" chapter of the development manual. His comments consisted of various tweaks to terminology I used and the inclusion of some additional technical information. This commit addresses all his comments for the review. (From yocto-docs rev: 206a22e1ccf077360974f18295b6df455cd50545) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-model.xml | 46 +++++++++++++-------- .../dev-manual/figures/kernel-dev-flow.png | Bin 61779 -> 61916 bytes 2 files changed, 28 insertions(+), 18 deletions(-) (limited to 'documentation') diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index d95382617a..93406eb600 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -191,7 +191,7 @@ Kernel modification involves changing the Linux Yocto kernel, which could involve changing - configuration variables as well as adding new kernel recipes. + configuration options as well as adding new kernel recipes. Configuration changes can be added in the form of configuration fragments, while recipe modification comes through the kernel's recipes-kernel area in a kernel layer you create. @@ -212,8 +212,8 @@ Kernel Overview - When one thinks of the source files for a kernel they usually think of a fixed structure - of files that contain kernel patches. + Traditionally, when one thinks of a patched kernel, they think of a base kernel + source tree and a fixed structure that conains kernel patches. The Yocto Project, however, employs mechanisims, that in a sense, result in a kernel source generator. By the end of this section, this analogy will become clearer. @@ -239,8 +239,8 @@ - The kernels are maintained using the Git application that, in a sense, structures - them in a "tree" complete with branches and leaves. + The kernels are maintained using the Git revision control system + that structures them using the familiar "tree", "branch", and "leaf" scheme. 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 @@ -253,7 +253,7 @@ Within the figure, the "Kernel.org Branch Point" represents the point in the tree - where a supported base kernel diverges from the Linux kernel. + where a supported base kernel is modified 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 @@ -267,7 +267,7 @@ 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. + Yocto Project kernel types 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. @@ -390,7 +390,10 @@ Project files Git repository. For information on how to get these files, see the bulleted item "The poky-extras Git Repository" - earlier in this manual. + earlier in this manual. + While it is certainly possible to modify the kernel without involving + a local Git repository, the suggested workflow for kernel modification + using the Yocto Project does use a Git repository. Establish a local copy of the Linux Yocto kernel files on your system: In order to make modifications to the kernel you need two things: a bare clone of the Linux Yocto kernel you are modifying and @@ -412,7 +415,7 @@ Once the changes are made, you need to use Git commands to commit the changes and then push them to the bare clone. Make kernel configuration changes - to your local kernel layer if applicable: + if applicable: If your situation calls for changing the kernel's configuration, you can use menuconfig to enable and disable kernel configurations. @@ -420,11 +423,18 @@ configuration changes you are making to the kernel. When saved, changes using menuconfig update the kernel's .config. - As an alternative method to changing the kernel's configuration, you can simply - edit the .config found in the Yocto Project build - directory at tmp/sysroots/<machine-name>/kernel - directly. - Add new kernel recipes if applicable: The standard + Try to resist the temptation of directly editing the .config + file found in the Yocto Project build directory at + tmp/sysroots/<machine-name>/kernel. + Doing so, can produce unexpected results when the Yocto Project build system + regenerates the configuration file. + Once you are satisfied with the configuration changes made using + menuconfig, you can directly examine the + .config file against a saved original and gather those + changes into a config fragment to be placed inside a + .bbappend + Add or extend kernel recipes if applicable: + The standard layer structure organizes recipe files inside the meta-kernel-dev layer that is within the poky-extras Git repository. @@ -465,10 +475,10 @@ which allows you to distribute the layer. If applicable, share your in-tree changes: If the changes you made - are suited for all Linux Yocto users, you might want to push the changes to a - contribution area for the Linux Yocto Git repository. - Once the changes are pushed, you can request that they - be pulled into the master branch of the kernel tree. + are suited for all Linux Yocto users, you might want to send them on for inclusion + into the Linux Yocto Git repository. + If the changes are accepted, the Yocto Project Maintainer pulls them into + the master branch of the kernel tree. Doing so makes them available to everyone using the kernel. diff --git a/documentation/dev-manual/figures/kernel-dev-flow.png b/documentation/dev-manual/figures/kernel-dev-flow.png index 11fdda5eaa..f200af6338 100644 Binary files a/documentation/dev-manual/figures/kernel-dev-flow.png and b/documentation/dev-manual/figures/kernel-dev-flow.png differ -- cgit v1.2.3-54-g00ecf