From d36e4792e7e4061f65fda41af2a0c931f5596052 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 28 Jan 2013 12:09:38 -0600 Subject: kernel-dev: Added "Maintenance" appendix. New appendix required adding the kernel-dev-maint-appx.xml file. The contents are sections 3.2 and 3.3 from the old YP Kernel Architecture and Use Manual, which is "Tree Construction" and "Build Strategy." According to Darren Hart, this information should be retained for the few people on the planet that might ever need it. In addition to adding the new file, I had to add the bits to the kernel-dev.xml manual to support including the appendix when making the manual. (From yocto-docs rev: b25e40308080c59c6700e1dce8ebf6a9a2dafbcc) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/kernel-dev/kernel-dev-maint-appx.xml | 218 +++++++++++++++++++++ documentation/kernel-dev/kernel-dev.xml | 2 + 2 files changed, 220 insertions(+) create mode 100644 documentation/kernel-dev/kernel-dev-maint-appx.xml diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml new file mode 100644 index 0000000000..17a409e7ea --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-maint-appx.xml @@ -0,0 +1,218 @@ + %poky; ] > + + +Kernel Maintenance + +
+ Tree Construction + + This section describes construction of the Yocto Project kernel source repositories + as accomplished by the Yocto Project team to create kernel repositories. + These kernel repositories are found under the heading "Yocto Linux Kernel" at + &YOCTO_GIT_URL;/cgit.cgi + and can be shipped as part of a Yocto Project release. + The team creates these repositories by + compiling and executing the set of feature descriptions for every BSP/feature + in the product. + Those feature descriptions list all necessary patches, + configuration, branching, tagging and feature divisions found in a kernel. + Thus, the Yocto Project kernel repository (or tree) is built. + + + The existence of this tree allows you to access and clone a particular + Yocto Project kernel repository and use it to build images based on their configurations + and features. + + + You can find the files used to describe all the valid features and BSPs + in the Yocto Project kernel in any clone of the Yocto Project kernel source repository + Git tree. + For example, the following command clones the Yocto Project baseline kernel that + branched off of linux.org version 3.4: + + $ git clone git://git.yoctoproject.org/linux-yocto-3.4 + + For another example of how to set up a local Git repository of the Yocto Project + kernel files, see the + "Yocto Project Kernel" bulleted + item in the Yocto Project Development Manual. + + + Once you have cloned the kernel Git repository on your local machine, you can + switch to the meta branch within the repository. + Here is an example that assumes the local Git repository for the kernel is in + a top-level directory named linux-yocto-3.4: + + $ cd ~/linux-yocto-3.4 + $ git checkout -b meta origin/meta + + Once you have checked out and switched to the meta branch, + you can see a snapshot of all the kernel configuration and feature descriptions that are + used to build that particular kernel repository. + These descriptions are in the form of .scc files. + + + You should realize, however, that browsing your local kernel repository + for feature descriptions and patches is not an effective way to determine what is in a + particular kernel branch. + Instead, you should use Git directly to discover the changes in a branch. + Using Git is an efficient and flexible way to inspect changes to the kernel. + For examples showing how to use Git to inspect kernel commits, see the following sections + in this chapter. + + Ground up reconstruction of the complete kernel tree is an action only taken by the + Yocto Project team during an active development cycle. + When you create a clone of the kernel Git repository, you are simply making it + efficiently available for building and development. + + + + The following steps describe what happens when the Yocto Project Team constructs + the Yocto Project kernel source Git repository (or tree) found at + given the + introduction of a new top-level kernel feature or BSP. + These are the actions that effectively create the tree + that includes the new feature, patch or BSP: + + A top-level kernel feature is passed to the kernel build subsystem. + Normally, this feature is a BSP for a particular kernel type. + The file that describes the top-level feature is located by searching + these system directories: + + The in-tree kernel-cache directories, which are located + in meta/cfg/kernel-cache + Areas pointed to by SRC_URI statements + found in recipes + + For a typical build, the target of the search is a + feature description in an .scc file + whose name follows this format: + + <bsp_name>-<kernel_type>.scc + + + Once located, the feature description is either compiled into a simple script + of actions, or into an existing equivalent script that is already part of the + shipped kernel. + Extra features are appended to the top-level feature description. + These features can come from the + KERNEL_FEATURES + variable in recipes. + Each extra feature is located, compiled and appended to the script + as described in step three. + The script is executed to produce a series of meta-* + directories. + These directories are descriptions of all the branches, tags, patches and configurations that + need to be applied to the base Git repository to completely create the + source (build) branch for the new BSP or feature. + The base repository is cloned, and the actions + listed in the meta-* directories are applied to the + tree. + The Git repository is left with the desired branch checked out and any + required branching, patching and tagging has been performed. + + + + The kernel tree is now ready for developer consumption to be locally cloned, + configured, and built into a Yocto Project kernel specific to some target hardware. + The generated meta-* directories add to the kernel + as shipped with the Yocto Project release. + Any add-ons and configuration data are applied to the end of an existing branch. + The full repository generation that is found in the + official Yocto Project kernel repositories at + http://git.yoctoproject.org/cgit.cgi + is the combination of all supported boards and configurations. + The technique the Yocto Project team uses is flexible and allows for seamless + blending of an immutable history with additional patches specific to a + deployment. + Any additions to the kernel become an integrated part of the branches. + + +
+ +
+ Build Strategy + + + AR - Darrren Hart: Some parts of this section + need to be in the + "Using an Iterative Development Process" + section. + Darren needs to figure out which parts and identify them. + + + + Once a local Git repository of the Yocto Project kernel exists on a development system, + you can consider the compilation phase of kernel development - building a kernel image. + Some prerequisites exist that are validated by the build process before compilation + starts: + + + + The + SRC_URI points + to the kernel Git repository. + A BSP build branch exists. + This branch has the following form: + + <kernel_type>/<bsp_name> + + + + + The OpenEmbedded build system makes sure these conditions exist before attempting compilation. + Other means, however, do exist, such as as bootstrapping a BSP. + + + + Before building a kernel, the build process verifies the tree + and configures the kernel by processing all of the + configuration "fragments" specified by feature descriptions in the .scc + files. + As the features are compiled, associated kernel configuration fragments are noted + and recorded in the meta-* series of directories in their compilation order. + The fragments are migrated, pre-processed and passed to the Linux Kernel + Configuration subsystem (lkc) as raw input in the form + of a .config file. + The lkc uses its own internal dependency constraints to do the final + processing of that information and generates the final .config file + that is used during compilation. + + + + Using the board's architecture and other relevant values from the board's template, + kernel compilation is started and a kernel image is produced. + + + + The other thing that you notice once you configure a kernel is that + the build process generates a build tree that is separate from your kernel's local Git + source repository tree. + This build tree has a name that uses the following form, where + ${MACHINE} is the metadata name of the machine (BSP) and "kernel_type" is one + of the Yocto Project supported kernel types (e.g. "standard"): + + linux-${MACHINE}-<kernel_type>-build + + + + + The existing support in the kernel.org tree achieves this + default functionality. + + + + This behavior means that all the generated files for a particular machine or BSP are now in + the build tree directory. + The files include the final .config file, all the .o + files, the .a files, and so forth. + Since each machine or BSP has its own separate build directory in its own separate branch + of the Git repository, you can easily switch between different builds. + +
+ + diff --git a/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml index 1d2d55e3ac..9682d54006 100644 --- a/documentation/kernel-dev/kernel-dev.xml +++ b/documentation/kernel-dev/kernel-dev.xml @@ -65,6 +65,8 @@ + + -- cgit v1.2.3-54-g00ecf