diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml index 7f3eac3d3b..d32ea20b34 100644 --- a/documentation/kernel-manual/kernel-how-to.xml +++ b/documentation/kernel-manual/kernel-how-to.xml @@ -17,15 +17,15 @@ Workflow examples - Source Code Manager (SCM) - + + guilt + scc file example "dirty" string - + Transition kernel layer --> @@ -33,90 +33,91 @@
Tree Construction -The Yocto Project kernel repository, as shipped with the product, is created 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 the kernel. - - -The files used to describe all the valid features and BSPs in the Yocto Project -kernel can be found in any clone of the kernel git tree. The directory -wrs/cfg/kernel-cache/ is a snapshot of all the kernel configuration and -feature descriptions (.scc) that were used to build the kernel repository. -It should however be noted, that browsing the snapshot of feature -descriptions and patches is not an effective way to determine what is in a -particular kernel branch. Using git directly to get insight into the changes -in a branch is more efficient and a more flexible way to inspect changes to -the kernel. Examples of using git to inspect kernel commits are in the -following sections. - - -As a reminder, it is envisioned that a ground up reconstruction of the -complete kernel tree is an action only taken by Yocto Project team during an -active development cycle. When an end user creates a project, it takes -advantage of this complete tree in order to efficiently place a git tree -within their project. - - -The general flow of the project specific kernel tree construction is as follows: - - a top level kernel feature is passed to the kernel build subsystem, - normally this is a BSP for a particular kernel type. + The Yocto Project kernel repository, as shipped with the product, is created 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 the kernel. + + + You can find the files used to describe all the valid features and BSPs in the Yocto Project + kernel in any clone of the kernel git tree. + The directory wrs/cfg/kernel-cache/ is a snapshot of all the kernel + configuration and feature descriptions (.scc) used to build the kernel repository. + You should realize, however, that browsing the snapshot of 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 a 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. + Creating a project takes advantage of this complete tree in order to + place efficiently a git tree within the project. + + + The general flow for constructing a project-specific kernel tree is as follows: + + A top-level kernel feature is passed to the kernel build subsystem. + Normally, this is a BSP for a particular kernel type. - the file that describes the top level feature is located by searching - system directories: - - - the kernel-cache under linux/wrs/cfg/kernel-cache + The file that describes the top-level feature is located by searching + these system directories: + + + The kernel-cache under + linux/wrs/cfg/kernel-cache - recipe SRC_URIs + Recipe SRC_URIs - + - In a typical build a feature description of the format: - <bsp name>-<kernel type>.scc is the target of the search. - + For a typical build a feature description of the format: + <bsp name>-<kernel type>.scc is the target of the search. + - once located, the feature description is compiled into a simple script - of actions, or an existing equivalent script which was part of the - shipped kernel is located. + Once located, the feature description is either compiled into a simple script + of actions, or an existing equivalent script that was part of the + shipped kernel is located. - extra features are appended to the top level feature description. Extra - features can come from the KERNEL_FEATURES variable in recipes. + 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 from - step #3 + Each extra feature is located, compiled and appended to the script from + step #3 - the script is executed, and a meta-series is produced. The meta-series - is a description of all the branches, tags, patches and configuration that - need to be applied to the base git repository to completely create the - "bsp_name-kernel_type". + The script is executed, and a meta-series is produced. + The meta-series is a description of all the branches, tags, patches and configuration that + needs to be applied to the base git repository to completely create the + "bsp_name-kernel_type". - the base repository is cloned, and the actions - listed in the meta-series are applied to the tree. + The base repository is cloned, and the actions + listed in the meta-series 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 git repository is left with the desired branch checked out and any + required branching, patching and tagging has been performed. + + - -The tree is now ready for configuration and compilation. Those two topics will -be covered below. - + + The tree is now ready for configuration and compilation. + -The end user generated meta-series adds 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 linux-2.6-windriver.git is the combination of all - supported boards and configurations. - - - -This technique is flexible and allows the seamless blending of an immutable -history with additional deployment specific patches. Any additions to the -kernel become an integrated part of the branches. - + The end-user generated meta-series adds 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 + linux-2.6-windriver.git is the combination of all + supported boards and configurations. + + This technique is flexible and allows the seamless blending of an immutable + history with additional deployment specific patches. + Any additions to the kernel become an integrated part of the branches. + - +
Build Strategy - -There are some prerequisites that must be met before starting the compilation -phase of the kernel build system: - - - There must be a kernel git repository indicated in the SRC_URI. - There must be a branch <bsp name>-<kernel type>. - + + There are some prerequisites that must be met before starting the compilation + phase of the kernel build system: + - -These are typically met by running tree construction/patching phase of the -build system, but can be achieved by other means. Examples of alternate work -flows such as bootstrapping a BSP are provided below. - - -Before building a kernel it is configured by processing all of the -configuration "fragments" specified by the scc feature descriptions. As the -features are compiled, associated kernel configuration fragments are noted -and recorded in the meta-series 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 that will -be used during compilation. - - -Kernel compilation is started, using the board's architecture and other -relevant values from the board template, and a kernel image is produced. - - -The other thing that you will first see once you configure a kernel is that -it will generate a build tree that is separate from your git source tree. -This build dir will be called "linux-<BSPname>-<kerntype>-build" where -kerntype is one of standard kernel types. This functionality is done by making -use of the existing support that is within the kernel.org tree by default. - - -What this means, is that all the generated files (that includes the final -".config" itself, all ".o" and ".a" etc) are now in this directory. Since -the git source tree can contain any number of BSPs, all on their own branch, -you now can easily switch between builds of BSPs as well, since each one also -has their own separate build directory. - + + There must be a kernel git repository indicated in the SRC_URI. + There must be a branch <bsp name>-<kernel type>. + + + + You can typically meet these prerequisites by running the tree construction/patching phase + of the build system. + However, other means do exist. + For examples of alternate workflows such as bootstrapping a BSP, see + the Workflow Examples section in this manual. + + + + Before building a kernel it is configured by processing all of the + configuration "fragments" specified by the scc feature descriptions. + As the features are compiled, associated kernel configuration fragments are noted + and recorded in the meta-series 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 + the Kernel compilation is started and a kernel image is produced. + + + The other thing that you will first see once you configure a kernel is that + it will generate a build tree that is separate from your git source tree. + This build tree has the name using the following form: + + linux-<BSPname>-<kerntype>-build + + "kerntype" is one of the standard kernel types. + + + + The existing support in the kernel.org tree achieves this default functionality. + + + + What this means, is that all the generated files for a particular BSP are now in this directory. + The files include the final .config, all the .o + files, the .a files, and so forth. + Since each BSP has its own separate build directory in its own separate branch + of the git tree you can easily switch between different BSP builds. +
- + +
- Export Internally Via git - -Committed changes can also be exported from a working directory by pushing -(or by making a pull request) the changes into a master repository. Those -same change can then be pulled into a new kernel build at a later time using this command form: - + Exporting Changes Internally by Using git + + + This section describes how you can export changes from a working directory + by pushing the changes into a master repository or by making a pull request. + Once you have pushed the changes in the master repository you can then + pull those same changes into a new kernel build at a later time. + + + + Use this command form to push the changes: + git push ssh://<master server>/<path to repo> <local branch>:<remote branch> - -For example: - + + + + + For example, the following command pushes the changes from your local branch + common_pc-standard to the remote branch with the same name + in the master repository //git.mycompany.com/pub/git/kernel-2.6.27. + > push ssh://git.mycompany.com/pub/git/kernel-2.6.27 common_pc-standard:common_pc-standard - -A pull request entails using "git request-pull" to compose an email to the -maintainer requesting that a branch be pulled into the master repository, see -http://github.com/guides/pull-requests for an example. - - -Other commands such as 'git stash' or branching can also be used to save -changes, but are not covered in this document. - - -See the section "importing from another SCM" for how a git push to the -default_kernel, can be used to automatically update the builds of all users -of a central git repository. - -
+ + + + + A pull request entails using "git request-pull" to compose an email to the + maintainer requesting that a branch be pulled into the master repository, see + for an example. + + + + Other commands such as 'git stash' or branching can also be used to save + changes, but are not covered in this document. + + + +
@@ -699,10 +796,10 @@ induced patch damage. An example of dumping patches for external submission follows: # dump the last 4 commits - > git format-patch ‐‐thread -n -o ~/rr/ HEAD^^^^ - > git send-email ‐‐compose ‐‐subject '[RFC 0/N] <patch series summary>' \ - ‐‐to foo@yoctoproject.org ‐‐to bar@yoctoproject.org \ - ‐‐cc list@yoctoproject.org ~/rr + > git format-patch --thread -n -o ~/rr/ HEAD^^^^ + > git send-email --compose --subject '[RFC 0/N] <patch series summary>' \ + --to foo@yoctoproject.org --to bar@yoctoproject.org \ + --cc list@yoctoproject.org ~/rr # the editor is invoked for the 0/N patch, and when complete the entire # series is sent via email for review @@ -934,7 +1031,7 @@ That's it. Configure and build. So first create a bare clone of the Yocto Project git repository, and then create a local clone of that: - $ git clone ‐‐bare git://git.pokylinux.org/linux-2.6-windriver.git + $ git clone --bare git://git.pokylinux.org/linux-2.6-windriver.git linux-2.6-windriver.git $ git clone linux-2.6-windriver.git linux-2.6-windriver