From 5cbeb840061fad16524e355c07c518defae62b6e Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 17 Dec 2012 17:17:14 -0600 Subject: [PATCH] kernel-dev: Created file structure for new kernel-dev manual. (From yocto-docs rev: 25be3ebb7713b875c4ec6e3723961b7dd860295d) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../kernel-dev/figures/kernel-dev-title.png | Bin 0 -> 27810 bytes .../kernel-dev/kernel-dev-advanced.xml | 918 ++++++++++++++++ .../kernel-dev/kernel-dev-common.xml | 392 +++++++ .../kernel-dev/kernel-dev-customization.xsl | 8 + .../kernel-dev/kernel-dev-examples.xml | 918 ++++++++++++++++ documentation/kernel-dev/kernel-dev-faq.xml | 918 ++++++++++++++++ documentation/kernel-dev/kernel-dev-intro.xml | 78 ++ documentation/kernel-dev/kernel-dev-style.css | 979 ++++++++++++++++++ documentation/kernel-dev/kernel-dev.xml | 104 ++ 9 files changed, 4315 insertions(+) create mode 100644 documentation/kernel-dev/figures/kernel-dev-title.png create mode 100644 documentation/kernel-dev/kernel-dev-advanced.xml create mode 100644 documentation/kernel-dev/kernel-dev-common.xml create mode 100644 documentation/kernel-dev/kernel-dev-customization.xsl create mode 100644 documentation/kernel-dev/kernel-dev-examples.xml create mode 100644 documentation/kernel-dev/kernel-dev-faq.xml create mode 100644 documentation/kernel-dev/kernel-dev-intro.xml create mode 100644 documentation/kernel-dev/kernel-dev-style.css create mode 100644 documentation/kernel-dev/kernel-dev.xml diff --git a/documentation/kernel-dev/figures/kernel-dev-title.png b/documentation/kernel-dev/figures/kernel-dev-title.png new file mode 100644 index 0000000000000000000000000000000000000000..1cb989f34a54892348f2bb704ac2d5e96f86aa16 GIT binary patch literal 27810 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 %poky; ] > + + + +Working with the Yocto Project Kernel + + +
+ Introduction + + This chapter describes how to accomplish tasks involving a kernel's tree structure. + The information is designed to help the developer that wants to modify the Yocto + Project kernel and contribute changes upstream to the Yocto Project. + The information covers the following: + + Tree construction + Build strategies + Workflow examples + + +
+ +
+ 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 + + 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, see + the "Workflow Examples". + + + + 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. + +
+ +
+ Workflow Examples + + + As previously noted, the Yocto Project kernel has built-in Git integration. + However, these utilities are not the only way to work with the kernel repository. + The Yocto Project has not made changes to Git or to other tools that + would invalidate alternate workflows. + Additionally, the way the kernel repository is constructed results in using + only core Git functionality, thus allowing any number of tools or front ends to use the + resulting tree. + + + + This section contains several workflow examples. + Many of the examples use Git commands. + You can find Git documentation at + . + You can find a simple overview of using Git with the Yocto Project in the + "Git" + section of the Yocto Project Development Manual. + + +
+ Change Inspection: Changes/Commits + + + A common question when working with a kernel is: + "What changes have been applied to this tree?" + + + + In projects that have a collection of directories that + contain patches to the kernel, it is possible to inspect or "grep" the contents + of the directories to get a general feel for the changes. + This sort of patch inspection is not an efficient way to determine what has been + done to the kernel. + The reason it is inefficient is because there are many optional patches that are + selected based on the kernel type and the feature description. + Additionally, patches could exist in directories that are not included in the search. + + + + A more efficient way to determine what has changed in the branch is to use + Git and inspect or search the kernel tree. + This method gives you a full view of not only the source code modifications, + but also provides the reasons for the changes. + + +
+ What Changed in a Kernel? + + + Following are a few examples that show how to use Git commands to examine changes. + Because Git repositories in the Yocto Project do not break existing Git + functionality, and because there exists many permutations of these types of + Git commands, many methods exist by which you can discover changes. + + In the following examples, unless you provide a commit range, + kernel.org history is blended with Yocto Project + kernel changes. + You can form ranges by using branch names from the kernel tree as the + upper and lower commit markers with the Git commands. + You can see the branch names through the web interface to the + Yocto Project source repositories at + . + For example, the branch names for the linux-yocto-3.4 + kernel repository can be seen at + . + + To see a full range of the changes, use the + git whatchanged command and specify a commit range + for the branch (<commit>..<commit>). + + + + Here is an example that looks at what has changed in the + emenlow branch of the + linux-yocto-3.4 kernel. + The lower commit range is the commit associated with the + standard/base branch, while + the upper commit range is the commit associated with the + standard/emenlow branch. + + $ git whatchanged origin/standard/base..origin/standard/emenlow + + + + + To see a summary of changes use the git log command. + Here is an example using the same branches: + + $ git log --oneline origin/standard/base..origin/standard/emenlow + + The git log output might be more useful than + the git whatchanged as you get + a short, one-line summary of each change and not the entire commit. + + + + If you want to see code differences associated with all the changes, use + the git diff command. + Here is an example: + + $ git diff origin/standard/base..origin/standard/emenlow + + + + + You can see the commit log messages and the text differences using the + git show command: + Here is an example: + + $ git show origin/standard/base..origin/standard/emenlow + + + + + You can create individual patches for each change by using the + git format-patch command. + Here is an example that that creates patch files for each commit and + places them in your Documents directory: + + $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow + + +
+ +
+ Show a Particular Feature or Branch Change + + + Developers use tags in the Yocto Project kernel tree to divide changes for significant + features or branches. + Once you know a particular tag, you can use Git commands + to show changes associated with the tag and find the branches that contain + the feature. + + Because BSP branch, kernel.org, and feature tags are all + present, there could be many tags. + + The git show <tag> command shows changes that are tagged by + a feature. + Here is an example that shows changes tagged by the systemtap + feature: + + $ git show systemtap + + You can use the git branch --contains <tag> command + to show the branches that contain a particular feature. + This command shows the branches that contain the systemtap + feature: + + $ git branch --contains systemtap + + + + + You can use many other comparisons to isolate BSP and kernel changes. + For example, you can compare against kernel.org tags + such as the v3.4 tag. + +
+
+ +
+ Development: Saving Kernel Modifications + + + Another common operation is to build a BSP supplied by the Yocto Project, make some + changes, rebuild, and then test. + Those local changes often need to be exported, shared or otherwise maintained. + + + + Since the Yocto Project kernel source tree is backed by Git, this activity is + much easier as compared to with previous releases. + Because Git tracks file modifications, additions and deletions, it is easy + to modify the code and later realize that you need to save the changes. + It is also easy to determine what has changed. + This method also provides many tools to commit, undo and export those modifications. + + + + This section and its sub-sections, describe general application of Git's + push and pull commands, which are used to + get your changes upstream or source your code from an upstream repository. + The Yocto Project provides scripts that help you work in a collaborative development + environment. + For information on these scripts, see the + "Using Scripts to Push a Change + Upstream and Request a Pull" and + "Using Email to Submit a Patch" + sections in the Yocto Project Development Manual. + + + + There are many ways to save kernel modifications. + The technique employed + depends on the destination for the patches: + + + Bulk storage + Internal sharing either through patches or by using Git + External submissions + Exporting for integration into another Source Code + Manager (SCM) + + + + + Because of the following list of issues, the destination of the patches also influences + the method for gathering them: + + + Bisectability + Commit headers + Division of subsystems for separate submission or review + + + +
+ Bulk Export + + + This section describes how you can "bulk" export changes that have not + been separated or divided. + This situation works well when you are simply storing patches outside of the kernel + source repository, either permanently or temporarily, and you are not committing + incremental changes during development. + + This technique is not appropriate for full integration of upstream submission + because changes are not properly divided and do not provide an avenue for per-change + commit messages. + Therefore, this example assumes that changes have not been committed incrementally + during development and that you simply must gather and export them. + + + # bulk export of ALL modifications without separation or division + # of the changes + + $ git add . + $ git commit -s -a -m <msg> + or + $ git commit -s -a # and interact with $EDITOR + + + + + The previous operations capture all the local changes in the project source + tree in a single Git commit. + And, that commit is also stored in the project's source tree. + + + + Once the changes are exported, you can restore them manually using a template + or through integration with the default_kernel. + + +
+ +
+ Incremental/Planned Sharing + + + This section describes how to save modifications when you are making incremental + commits or practicing planned sharing. + The examples in this section assume that you have incrementally committed + changes to the tree during development and now need to export them. + The sections that follow + describe how you can export your changes internally through either patches or by + using Git commands. + + + + During development, the following commands are of interest. + For full Git documentation, refer to the Git documentation at + . + + + # edit a file + $ vi <path>/file + # stage the change + $ git add <path>/file + # commit the change + $ git commit -s + # remove a file + $ git rm <path>/file + # commit the change + $ git commit -s + + ... etc. + + + + + Distributed development with Git is possible when you use a universally + agreed-upon unique commit identifier (set by the creator of the commit) that maps to a + specific change set with a specific parent. + This identifier is created for you when + you create a commit, and is re-created when you amend, alter or re-apply + a commit. + As an individual in isolation, this is of no interest. + However, if you + intend to share your tree with normal Git push and + pull operations for + distributed development, you should consider the ramifications of changing a + commit that you have already shared with others. + + + + Assuming that the changes have not been pushed upstream, or pulled into + another repository, you can update both the commit content and commit messages + associated with development by using the following commands: + + + $ Git add <path>/file + $ Git commit --amend + $ Git rebase or Git rebase -i + + + + + Again, assuming that the changes have not been pushed upstream, and that + no pending works-in-progress exist (use git status to check), then + you can revert (undo) commits by using the following commands: + + + # remove the commit, update working tree and remove all + # traces of the change + $ git reset --hard HEAD^ + # remove the commit, but leave the files changed and staged for re-commit + $ git reset --soft HEAD^ + # remove the commit, leave file change, but not staged for commit + $ git reset --mixed HEAD^ + + + + + You can create branches, "cherry-pick" changes, or perform any number of Git + operations until the commits are in good order for pushing upstream + or for pull requests. + After a push or pull command, + commits are normally considered + "permanent" and you should not modify them. + If the commits need to be changed, you can incrementally do so with new commits. + These practices follow standard Git workflow and the kernel.org best + practices, which is recommended. + + It is recommended to tag or branch before adding changes to a Yocto Project + BSP or before creating a new one. + The reason for this recommendation is because the branch or tag provides a + reference point to facilitate locating and exporting local changes. + + + +
+ Exporting Changes Internally by Using Patches + + + This section describes how you can extract committed changes from a working directory + by exporting them as patches. + Once the changes have been extracted, you can use the patches for upstream submission, + place them in a Yocto Project template for automatic kernel patching, + or apply them in many other common uses. + + + + This example shows how to create a directory with sequentially numbered patches. + Once the directory is created, you can apply it to a repository using the + git am command to reproduce the original commit and all + the related information such as author, date, commit log, and so forth. + + The new commit identifiers (ID) will be generated upon re-application. + This action reflects that the commit is now applied to an underlying commit + with a different ID. + + + # <first-commit> can be a tag if one was created before development + # began. It can also be the parent branch if a branch was created + # before development began. + + $ git format-patch -o <dir> <first commit>..<last commit> + + + + + In other words: + + # Identify commits of interest. + + # If the tree was tagged before development + $ git format-patch -o <save dir> <tag> + + # If no tags are available + $ git format-patch -o <save dir> HEAD^ # last commit + $ git format-patch -o <save dir> HEAD^^ # last 2 commits + $ git whatchanged # identify last commit + $ git format-patch -o <save dir> <commit id> + $ git format-patch -o <save dir> <rev-list> + + +
+ +
+ 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 to 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, the following command pushes the changes from your local branch + yocto/standard/common-pc/base to the remote branch with the same name + in the master repository //git.mycompany.com/pub/git/kernel-3.4. + + $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \ + yocto/standard/common-pc/base:yocto/standard/common-pc/base + + + + + A pull request entails using the git request-pull command 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. + + +
+
+ +
+ Exporting Changes for External (Upstream) Submission + + + This section describes how to export changes for external upstream submission. + If the patch series is large or the maintainer prefers to pull + changes, you can submit these changes by using a pull request. + However, it is common to send patches as an email series. + This method allows easy review and integration of the changes. + + Before sending patches for review be sure you understand the + community standards for submitting and documenting changes and follow their best practices. + For example, kernel patches should follow standards such as: + + + + Documentation/SubmittingPatches (in any linux + kernel source tree) + + + + + + The messages used to commit changes are a large part of these standards. + Consequently, be sure that the headers for each commit have the required information. + For information on how to follow the Yocto Project commit message standards, see the + "How to Submit a + Change" section in the Yocto Project Development Manual. + + + + If the initial commits were not properly documented or do not meet those standards, + you can re-base by using the git rebase -i command to + manipulate the commits and + get them into the required format. + Other techniques such as branching and cherry-picking commits are also viable options. + + + + Once you complete the commits, you can generate the email that sends the patches + to the maintainer(s) or lists that review and integrate changes. + The command git send-email is commonly used to ensure + that patches are properly + formatted for easy application and avoid mailer-induced patch damage. + + + + The following is an example of dumping patches for external submission: + + # 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 + # the editor is invoked for the 0/N patch, and when complete the entire + # series is sent via email for review + + +
+ +
+ Exporting Changes for Import into Another SCM + + + When you want to export changes for import into another + Source Code Manager (SCM), you can use any of the previously discussed + techniques. + However, if the patches are manually applied to a secondary tree and then + that tree is checked into the SCM, you can lose change information such as + commit logs. + This process is not recommended. + + + + Many SCMs can directly import Git commits, or can translate Git patches so that + information is not lost. + Those facilities are SCM-dependent and you should use them whenever possible. + +
+
+ +
+ Working with the Yocto Project Kernel in Another SCM + + + This section describes kernel development in an SCM other than Git, + which is not the same as exporting changes to another SCM described earlier. + For this scenario, you use the OpenEmbedded build system to + develop the kernel in a different SCM. + The following must be true for you to accomplish this: + + The delivered Yocto Project kernel must be exported into the second + SCM. + Development must be exported from that secondary SCM into a + format that can be used by the OpenEmbedded build system. + + + +
+ Exporting the Delivered Kernel to the SCM + + + Depending on the SCM, it might be possible to export the entire Yocto Project + kernel Git repository, branches and all, into a new environment. + This method is preferred because it has the most flexibility and potential to maintain + the meta data associated with each commit. + + + + When a direct import mechanism is not available, it is still possible to + export a branch (or series of branches) and check them into a new repository. + + + + The following commands illustrate some of the steps you could use to + import the yocto/standard/common-pc/base + kernel into a secondary SCM: + + $ git checkout yocto/standard/common-pc/base + $ cd .. ; echo linux/.git > .cvsignore + $ cvs import -m "initial import" linux MY_COMPANY start + + + + + You could now relocate the CVS repository and use it in a centralized manner. + + + + The following commands illustrate how you can condense and merge two BSPs into a + second SCM: + + $ git checkout yocto/standard/common-pc/base + $ git merge yocto/standard/common-pc-64/base + # resolve any conflicts and commit them + $ cd .. ; echo linux/.git > .cvsignore + $ cvs import -m "initial import" linux MY_COMPANY start + + +
+ +
+ Importing Changes for the Build + + + Once development has reached a suitable point in the second development + environment, you need to export the changes as patches. + To export them, place the changes in a recipe and + automatically apply them to the kernel during patching. + +
+
+ +
+ Creating a BSP Based on an Existing Similar BSP + + + This section overviews the process of creating a BSP based on an + existing similar BSP. + The information is introductory in nature and does not provide step-by-step examples. + For detailed information on how to create a new BSP, see + the "Creating a New BSP Layer Using the yocto-bsp Script" section in the + Yocto Project Board Support Package (BSP) Developer's Guide, or see the + Transcript:_creating_one_generic_Atom_BSP_from_another + wiki page. + + + + The basic steps you need to follow are: + + Make sure you have set up a local Source Directory: + You must create a local + Source Directory + by either creating a Git repository (recommended) or + extracting a Yocto Project release tarball. + Choose an existing BSP available with the Yocto Project: + Try to map your board features as closely to the features of a BSP that is + already supported and exists in the Yocto Project. + Starting with something as close as possible to your board makes developing + your BSP easier. + You can find all the BSPs that are supported and ship with the Yocto Project + on the Yocto Project's Download page at + . + Be sure you have the Base BSP: + You need to either have a local Git repository of the base BSP set up or + have downloaded and extracted the files from a release BSP tarball. + Either method gives you access to the BSP source files. + Make a copy of the existing BSP, thus isolating your new + BSP work: + Copying the existing BSP file structure gives you a new area in which to work. + Make configuration and recipe changes to your new BSP: + Configuration changes involve the files in the BSP's conf + directory. + Changes include creating a machine-specific configuration file and editing the + layer.conf file. + The configuration changes identify the kernel you will be using. + Recipe changes include removing, modifying, or adding new recipe files that + instruct the build process on what features to include in the image. + Prepare for the build: + Before you actually initiate the build, you need to set up the build environment + by sourcing the environment initialization script. + After setting up the environment, you need to make some build configuration + changes to the local.conf and bblayers.conf + files. + Build the image: + The OpenEmbedded build system uses BitBake to create the image. + You need to decide on the type of image you are going to build (e.g. minimal, base, + core, sato, and so forth) and then start the build using the bitbake + command. + + +
+ +
+ "-dirty" String + + + If kernel images are being built with "-dirty" on the end of the version + string, this simply means that modifications in the source + directory have not been committed. + + $ git status + + + + + You can use the above Git command to report modified, removed, or added files. + You should commit those changes to the tree regardless of whether they will be saved, + exported, or used. + Once you commit the changes you need to rebuild the kernel. + + + + To brute force pickup and commit all such pending changes, enter the following: + + $ git add . + $ git commit -s -a -m "getting rid of -dirty" + + + + + Next, rebuild the kernel. + +
+
+ + diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml new file mode 100644 index 0000000000..1290994257 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-common.xml @@ -0,0 +1,392 @@ + %poky; ] > + + + +Yocto Project Kernel Concepts + +
+ Introduction + + This chapter provides conceptual information about the kernel: + + Kernel Goals + Kernel Development and Maintenance Overview + Kernel Architecture + Kernel Tools + + +
+ +
+ Kernel Goals + + The complexity of embedded kernel design has increased dramatically. + Whether it is managing multiple implementations of a particular feature or tuning and + optimizing board specific features, both flexibility and maintainability are key concerns. + The Linux kernels available through the Yocto Project are presented with the embedded + developer's needs in mind and have evolved to assist in these key concerns. + For example, prior methods such as applying hundreds of patches to an extracted + tarball have been replaced with proven techniques that allow easy inspection, + bisection and analysis of changes. + Application of these techniques also creates a platform for performing integration and + collaboration with the thousands of upstream development projects. + + + With all these considerations in mind, the Yocto Project's kernel and development team + strives to attain these goals: + + Allow the end user to leverage community best practices to seamlessly + manage the development, build and debug cycles. + Create a platform for performing integration and collaboration with the + thousands of upstream development projects that exist. + Provide mechanisms that support many different work flows, front-ends and + management techniques. + Deliver the most up-to-date kernel possible while still ensuring that + the baseline kernel is the most stable official release. + Include major technological features as part of the Yocto Project's + upward revision strategy. + Present a kernel Git repository that, similar to the upstream + kernel.org tree, + has a clear and continuous history. + Deliver a key set of supported kernel types, where each type is tailored + to meet a specific use (e.g. networking, consumer, devices, and so forth). + Employ a Git branching strategy that, from a developer's point of view, + results in a linear path from the baseline kernel.org, + through a select group of features and + ends with their BSP-specific commits. + + +
+ +
+ Yocto Project Kernel Development and Maintenance Overview + + Kernels available through the Yocto Project, like other kernels, are based off the Linux + kernel releases from . + At the beginning of a major development cycle, the Yocto Project team + chooses its kernel based on factors such as release timing, the anticipated release + timing of final upstream kernel.org versions, and Yocto Project + feature requirements. + Typically, the kernel chosen is in the + final stages of development by the community. + In other words, the kernel is in the release + candidate or "rc" phase and not yet a final release. + But, by being in the final stages of external development, the team knows that the + kernel.org final release will clearly be within the early stages of + the Yocto Project development window. + + + This balance allows the team to deliver the most up-to-date kernel + possible, while still ensuring that the team has a stable official release for + the baseline Linux kernel version. + + + The ultimate source for kernels available through the Yocto Project are released kernels + from kernel.org. + In addition to a foundational kernel from kernel.org, the + kernels available contain a mix of important new mainline + developments, non-mainline developments (when there is no alternative), + Board Support Package (BSP) developments, + and custom features. + These additions result in a commercially released Yocto Project Linux kernel that caters + to specific embedded designer needs for targeted hardware. + + + Once a kernel is officially released, the Yocto Project team goes into + their next development cycle, or upward revision (uprev) cycle, while still + continuing maintenance on the released kernel. + It is important to note that the most sustainable and stable way + to include feature development upstream is through a kernel uprev process. + Back-porting hundreds of individual fixes and minor features from various + kernel versions is not sustainable and can easily compromise quality. + + + During the uprev cycle, the Yocto Project team uses an ongoing analysis of + kernel development, BSP support, and release timing to select the best + possible kernel.org version. + The team continually monitors community kernel + development to look for significant features of interest. + The team does consider back-porting large features if they have a significant advantage. + User or community demand can also trigger a back-port or creation of new + functionality in the Yocto Project baseline kernel during the uprev cycle. + + + Generally speaking, every new kernel both adds features and introduces new bugs. + These consequences are the basic properties of upstream kernel development and are + managed by the Yocto Project team's kernel strategy. + It is the Yocto Project team's policy to not back-port minor features to the released kernel. + They only consider back-porting significant technological jumps - and, that is done + after a complete gap analysis. + The reason for this policy is that back-porting any small to medium sized change + from an evolving kernel can easily create mismatches, incompatibilities and very + subtle errors. + + + These policies result in both a stable and a cutting + edge kernel that mixes forward ports of existing features and significant and critical + new functionality. + Forward porting functionality in the kernels available through the Yocto Project kernel + can be thought of as a "micro uprev." + The many “micro uprevs” produce a kernel version with a mix of + important new mainline, non-mainline, BSP developments and feature integrations. + This kernel gives insight into new features and allows focused + amounts of testing to be done on the kernel, which prevents + surprises when selecting the next major uprev. + The quality of these cutting edge kernels is evolving and the kernels are used in leading edge + feature and BSP development. + +
+ +
+ Kernel Architecture + + This section describes the architecture of the kernels available through the + Yocto Project and provides information + on the mechanisms used to achieve that architecture. + + +
+ Overview + + As mentioned earlier, a key goal of the Yocto Project is to present the + developer with + a kernel that has a clear and continuous history that is visible to the user. + The architecture and mechanisms used achieve that goal in a manner similar to the + upstream kernel.org. + + + You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with + added features logically structured on top of the baseline. + The features are tagged and organized by way of a branching strategy implemented by the + source code manager (SCM) Git. + For information on Git as applied to the Yocto Project, see the + "Git" section in the + Yocto Project Development Manual. + + + The result is that the user has the ability to see the added features and + the commits that make up those features. + In addition to being able to see added features, the user can also view the history of what + made up the baseline kernel. + + + The following illustration shows the conceptual Yocto Project kernel. + + + + + + In the illustration, the "Kernel.org Branch Point" + marks the specific spot (or release) from + which the Yocto Project kernel is created. + From this point "up" in the tree, features and differences are organized and tagged. + + + The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel + type and BSP that is organized further up the tree. + Placing these common features in the + tree this way means features don't have to be duplicated along individual branches of the + structure. + + + From the Yocto Project Baseline Kernel, branch points represent specific functionality + for individual BSPs as well as real-time kernels. + The illustration represents this through three BSP-specific branches and a real-time + kernel branch. + Each branch represents some unique functionality for the BSP or a real-time kernel. + + + In this example structure, the real-time kernel branch has common features for all + real-time kernels and contains + more branches for individual BSP-specific real-time kernels. + The illustration shows three branches as an example. + Each branch points the way to specific, unique features for a respective real-time + kernel as they apply to a given BSP. + + + The resulting tree structure presents a clear path of markers (or branches) to the + developer that, for all practical purposes, is the kernel needed for any given set + of requirements. + +
+ +
+ Branching Strategy and Workflow + + The Yocto Project team creates kernel branches at points where functionality is + no longer shared and thus, needs to be isolated. + For example, board-specific incompatibilities would require different functionality + and would require a branch to separate the features. + Likewise, for specific kernel features, the same branching strategy is used. + + + This branching strategy results in a tree that has features organized to be specific + for particular functionality, single kernel types, or a subset of kernel types. + This strategy also results in not having to store the same feature twice + internally in the tree. + Rather, the kernel team stores the unique differences required to apply the + feature onto the kernel type in question. + + The Yocto Project team strives to place features in the tree such that they can be + shared by all boards and kernel types where possible. + However, during development cycles or when large features are merged, + the team cannot always follow this practice. + In those cases, the team uses isolated branches to merge features. + + + + BSP-specific code additions are handled in a similar manner to kernel-specific additions. + Some BSPs only make sense given certain kernel types. + So, for these types, the team creates branches off the end of that kernel type for all + of the BSPs that are supported on that kernel type. + From the perspective of the tools that create the BSP branch, the BSP is really no + different than a feature. + Consequently, the same branching strategy applies to BSPs as it does to features. + So again, rather than store the BSP twice, the team only stores the unique + differences for the BSP across the supported multiple kernels. + + + While this strategy can result in a tree with a significant number of branches, it is + important to realize that from the developer's point of view, there is a linear + path that travels from the baseline kernel.org, through a select + group of features and ends with their BSP-specific commits. + In other words, the divisions of the kernel are transparent and are not relevant + to the developer on a day-to-day basis. + From the developer's perspective, this path is the "master" branch. + The developer does not need to be aware of the existence of any other branches at all. + Of course, there is value in the existence of these branches + in the tree, should a person decide to explore them. + For example, a comparison between two BSPs at either the commit level or at the line-by-line + code diff level is now a trivial operation. + + + Working with the kernel as a structured tree follows recognized community best practices. + In particular, the kernel as shipped with the product, should be + considered an "upstream source" and viewed as a series of + historical and documented modifications (commits). + These modifications represent the development and stabilization done + by the Yocto Project kernel development team. + + + Because commits only change at significant release points in the product life cycle, + developers can work on a branch created + from the last relevant commit in the shipped Yocto Project kernel. + As mentioned previously, the structure is transparent to the developer + because the kernel tree is left in this state after cloning and building the kernel. + +
+ +
+ Source Code Manager - Git + + The Source Code Manager (SCM) is Git. + This SCM is the obvious mechanism for meeting the previously mentioned goals. + Not only is it the SCM for kernel.org but, + Git continues to grow in popularity and supports many different work flows, + front-ends and management techniques. + + + You can find documentation on Git at . + You can also get an introduction to Git as it applies to the Yocto Project in the + "Git" + section in the Yocto Project Development Manual. + These referenced sections overview Git and describe a minimal set of + commands that allows you to be functional using Git. + + You can use as much, or as little, of what Git has to offer to accomplish what + you need for your project. + You do not have to be a "Git Master" in order to use it with the Yocto Project. + + +
+
+ +
+ Kernel Configuration + + Kernel configuration, along with kernel features, defines how a kernel + image is built for the Yocto Project. + Through configuration settings, you can customize a Yocto Project kernel to be + specific to particular hardware. + For example, you can specify sound support or networking support. + This section describes basic concepts behind Kernel configuration within the + Yocto Project and references you to other areas for specific configuration + applications. + + + + Conceptually, configuration of a Yocto Project kernel occurs similarly to that needed for any + Linux kernel. + The build process for a Yocto Project kernel uses a .config file, which + is created through the Linux Kernel Configuration (LKC) tool. + You can directly set various configurations in the + .config file by using the menuconfig + tool as built by BitBake. + You can also define configurations in the file by using configuration fragments. + + It is not recommended that you edit the .config file directly. + + Here are some brief descriptions of the ways you can affect the + .config file: + + The menuconfig Tool: + One of many front-ends that allows you to define kernel configurations. + Some others are make config, + make nconfig, and make gconfig. + In the Yocto Project environment, you must use BitBake to build the + menuconfig tool before you can use it to define + configurations: + + $ bitbake linux-yocto -c menuconfig + + After the tool is built, you can interact with it normally. + You can see how menuconfig is used to change a simple + kernel configuration in the + "Configuring the Kernel" + section of the Yocto Project Development Manual. + For general information on menuconfig, see + . + + Configuration Fragments: A file with a + list of kernel options just as they would appear syntactically in the + .config file. + Configuration fragments are typically logical groupings and are assembled + by the OpenEmbedded build system to produce input used by the LKC + that ultimately generates the .config file. + The + KERNEL_FEATURES + variable can be used to list configuration fragments. + For further discussion on applying configuration fragments, see the + "Linux Kernel Configuration" + section in the Yocto Project Board Support Package (BSP) Guide. + + + +
+ +
+ Kernel Tools + + Since most standard workflows involve moving forward with an existing tree by + continuing to add and alter the underlying baseline, the tools that manage + the Yocto Project's kernel construction are largely hidden from the developer to + present a simplified view of the kernel for ease of use. + + + Fundamentally, the kernel tools that manage and construct the + Yocto Project kernel accomplish the following: + + Group patches into named, reusable features. + Allow top-down control of included features. + Bind kernel configurations to kernel patches and features. + Present a seamless Git repository that blends Yocto Project value + with the kernel.org history and development. + + +
+ + diff --git a/documentation/kernel-dev/kernel-dev-customization.xsl b/documentation/kernel-dev/kernel-dev-customization.xsl new file mode 100644 index 0000000000..8eb69050ba --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-customization.xsl @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/documentation/kernel-dev/kernel-dev-examples.xml b/documentation/kernel-dev/kernel-dev-examples.xml new file mode 100644 index 0000000000..9d9aef6d06 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-examples.xml @@ -0,0 +1,918 @@ + %poky; ] > + + + +Working with the Yocto Project Kernel + + +
+ Introduction + + This chapter describes how to accomplish tasks involving a kernel's tree structure. + The information is designed to help the developer that wants to modify the Yocto + Project kernel and contribute changes upstream to the Yocto Project. + The information covers the following: + + Tree construction + Build strategies + Workflow examples + + +
+ +
+ 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 + + 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, see + the "Workflow Examples". + + + + 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. + +
+ +
+ Workflow Examples + + + As previously noted, the Yocto Project kernel has built-in Git integration. + However, these utilities are not the only way to work with the kernel repository. + The Yocto Project has not made changes to Git or to other tools that + would invalidate alternate workflows. + Additionally, the way the kernel repository is constructed results in using + only core Git functionality, thus allowing any number of tools or front ends to use the + resulting tree. + + + + This section contains several workflow examples. + Many of the examples use Git commands. + You can find Git documentation at + . + You can find a simple overview of using Git with the Yocto Project in the + "Git" + section of the Yocto Project Development Manual. + + +
+ Change Inspection: Changes/Commits + + + A common question when working with a kernel is: + "What changes have been applied to this tree?" + + + + In projects that have a collection of directories that + contain patches to the kernel, it is possible to inspect or "grep" the contents + of the directories to get a general feel for the changes. + This sort of patch inspection is not an efficient way to determine what has been + done to the kernel. + The reason it is inefficient is because there are many optional patches that are + selected based on the kernel type and the feature description. + Additionally, patches could exist in directories that are not included in the search. + + + + A more efficient way to determine what has changed in the branch is to use + Git and inspect or search the kernel tree. + This method gives you a full view of not only the source code modifications, + but also provides the reasons for the changes. + + +
+ What Changed in a Kernel? + + + Following are a few examples that show how to use Git commands to examine changes. + Because Git repositories in the Yocto Project do not break existing Git + functionality, and because there exists many permutations of these types of + Git commands, many methods exist by which you can discover changes. + + In the following examples, unless you provide a commit range, + kernel.org history is blended with Yocto Project + kernel changes. + You can form ranges by using branch names from the kernel tree as the + upper and lower commit markers with the Git commands. + You can see the branch names through the web interface to the + Yocto Project source repositories at + . + For example, the branch names for the linux-yocto-3.4 + kernel repository can be seen at + . + + To see a full range of the changes, use the + git whatchanged command and specify a commit range + for the branch (<commit>..<commit>). + + + + Here is an example that looks at what has changed in the + emenlow branch of the + linux-yocto-3.4 kernel. + The lower commit range is the commit associated with the + standard/base branch, while + the upper commit range is the commit associated with the + standard/emenlow branch. + + $ git whatchanged origin/standard/base..origin/standard/emenlow + + + + + To see a summary of changes use the git log command. + Here is an example using the same branches: + + $ git log --oneline origin/standard/base..origin/standard/emenlow + + The git log output might be more useful than + the git whatchanged as you get + a short, one-line summary of each change and not the entire commit. + + + + If you want to see code differences associated with all the changes, use + the git diff command. + Here is an example: + + $ git diff origin/standard/base..origin/standard/emenlow + + + + + You can see the commit log messages and the text differences using the + git show command: + Here is an example: + + $ git show origin/standard/base..origin/standard/emenlow + + + + + You can create individual patches for each change by using the + git format-patch command. + Here is an example that that creates patch files for each commit and + places them in your Documents directory: + + $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow + + +
+ +
+ Show a Particular Feature or Branch Change + + + Developers use tags in the Yocto Project kernel tree to divide changes for significant + features or branches. + Once you know a particular tag, you can use Git commands + to show changes associated with the tag and find the branches that contain + the feature. + + Because BSP branch, kernel.org, and feature tags are all + present, there could be many tags. + + The git show <tag> command shows changes that are tagged by + a feature. + Here is an example that shows changes tagged by the systemtap + feature: + + $ git show systemtap + + You can use the git branch --contains <tag> command + to show the branches that contain a particular feature. + This command shows the branches that contain the systemtap + feature: + + $ git branch --contains systemtap + + + + + You can use many other comparisons to isolate BSP and kernel changes. + For example, you can compare against kernel.org tags + such as the v3.4 tag. + +
+
+ +
+ Development: Saving Kernel Modifications + + + Another common operation is to build a BSP supplied by the Yocto Project, make some + changes, rebuild, and then test. + Those local changes often need to be exported, shared or otherwise maintained. + + + + Since the Yocto Project kernel source tree is backed by Git, this activity is + much easier as compared to with previous releases. + Because Git tracks file modifications, additions and deletions, it is easy + to modify the code and later realize that you need to save the changes. + It is also easy to determine what has changed. + This method also provides many tools to commit, undo and export those modifications. + + + + This section and its sub-sections, describe general application of Git's + push and pull commands, which are used to + get your changes upstream or source your code from an upstream repository. + The Yocto Project provides scripts that help you work in a collaborative development + environment. + For information on these scripts, see the + "Using Scripts to Push a Change + Upstream and Request a Pull" and + "Using Email to Submit a Patch" + sections in the Yocto Project Development Manual. + + + + There are many ways to save kernel modifications. + The technique employed + depends on the destination for the patches: + + + Bulk storage + Internal sharing either through patches or by using Git + External submissions + Exporting for integration into another Source Code + Manager (SCM) + + + + + Because of the following list of issues, the destination of the patches also influences + the method for gathering them: + + + Bisectability + Commit headers + Division of subsystems for separate submission or review + + + +
+ Bulk Export + + + This section describes how you can "bulk" export changes that have not + been separated or divided. + This situation works well when you are simply storing patches outside of the kernel + source repository, either permanently or temporarily, and you are not committing + incremental changes during development. + + This technique is not appropriate for full integration of upstream submission + because changes are not properly divided and do not provide an avenue for per-change + commit messages. + Therefore, this example assumes that changes have not been committed incrementally + during development and that you simply must gather and export them. + + + # bulk export of ALL modifications without separation or division + # of the changes + + $ git add . + $ git commit -s -a -m <msg> + or + $ git commit -s -a # and interact with $EDITOR + + + + + The previous operations capture all the local changes in the project source + tree in a single Git commit. + And, that commit is also stored in the project's source tree. + + + + Once the changes are exported, you can restore them manually using a template + or through integration with the default_kernel. + + +
+ +
+ Incremental/Planned Sharing + + + This section describes how to save modifications when you are making incremental + commits or practicing planned sharing. + The examples in this section assume that you have incrementally committed + changes to the tree during development and now need to export them. + The sections that follow + describe how you can export your changes internally through either patches or by + using Git commands. + + + + During development, the following commands are of interest. + For full Git documentation, refer to the Git documentation at + . + + + # edit a file + $ vi <path>/file + # stage the change + $ git add <path>/file + # commit the change + $ git commit -s + # remove a file + $ git rm <path>/file + # commit the change + $ git commit -s + + ... etc. + + + + + Distributed development with Git is possible when you use a universally + agreed-upon unique commit identifier (set by the creator of the commit) that maps to a + specific change set with a specific parent. + This identifier is created for you when + you create a commit, and is re-created when you amend, alter or re-apply + a commit. + As an individual in isolation, this is of no interest. + However, if you + intend to share your tree with normal Git push and + pull operations for + distributed development, you should consider the ramifications of changing a + commit that you have already shared with others. + + + + Assuming that the changes have not been pushed upstream, or pulled into + another repository, you can update both the commit content and commit messages + associated with development by using the following commands: + + + $ Git add <path>/file + $ Git commit --amend + $ Git rebase or Git rebase -i + + + + + Again, assuming that the changes have not been pushed upstream, and that + no pending works-in-progress exist (use git status to check), then + you can revert (undo) commits by using the following commands: + + + # remove the commit, update working tree and remove all + # traces of the change + $ git reset --hard HEAD^ + # remove the commit, but leave the files changed and staged for re-commit + $ git reset --soft HEAD^ + # remove the commit, leave file change, but not staged for commit + $ git reset --mixed HEAD^ + + + + + You can create branches, "cherry-pick" changes, or perform any number of Git + operations until the commits are in good order for pushing upstream + or for pull requests. + After a push or pull command, + commits are normally considered + "permanent" and you should not modify them. + If the commits need to be changed, you can incrementally do so with new commits. + These practices follow standard Git workflow and the kernel.org best + practices, which is recommended. + + It is recommended to tag or branch before adding changes to a Yocto Project + BSP or before creating a new one. + The reason for this recommendation is because the branch or tag provides a + reference point to facilitate locating and exporting local changes. + + + +
+ Exporting Changes Internally by Using Patches + + + This section describes how you can extract committed changes from a working directory + by exporting them as patches. + Once the changes have been extracted, you can use the patches for upstream submission, + place them in a Yocto Project template for automatic kernel patching, + or apply them in many other common uses. + + + + This example shows how to create a directory with sequentially numbered patches. + Once the directory is created, you can apply it to a repository using the + git am command to reproduce the original commit and all + the related information such as author, date, commit log, and so forth. + + The new commit identifiers (ID) will be generated upon re-application. + This action reflects that the commit is now applied to an underlying commit + with a different ID. + + + # <first-commit> can be a tag if one was created before development + # began. It can also be the parent branch if a branch was created + # before development began. + + $ git format-patch -o <dir> <first commit>..<last commit> + + + + + In other words: + + # Identify commits of interest. + + # If the tree was tagged before development + $ git format-patch -o <save dir> <tag> + + # If no tags are available + $ git format-patch -o <save dir> HEAD^ # last commit + $ git format-patch -o <save dir> HEAD^^ # last 2 commits + $ git whatchanged # identify last commit + $ git format-patch -o <save dir> <commit id> + $ git format-patch -o <save dir> <rev-list> + + +
+ +
+ 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 to 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, the following command pushes the changes from your local branch + yocto/standard/common-pc/base to the remote branch with the same name + in the master repository //git.mycompany.com/pub/git/kernel-3.4. + + $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \ + yocto/standard/common-pc/base:yocto/standard/common-pc/base + + + + + A pull request entails using the git request-pull command 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. + + +
+
+ +
+ Exporting Changes for External (Upstream) Submission + + + This section describes how to export changes for external upstream submission. + If the patch series is large or the maintainer prefers to pull + changes, you can submit these changes by using a pull request. + However, it is common to send patches as an email series. + This method allows easy review and integration of the changes. + + Before sending patches for review be sure you understand the + community standards for submitting and documenting changes and follow their best practices. + For example, kernel patches should follow standards such as: + + + + Documentation/SubmittingPatches (in any linux + kernel source tree) + + + + + + The messages used to commit changes are a large part of these standards. + Consequently, be sure that the headers for each commit have the required information. + For information on how to follow the Yocto Project commit message standards, see the + "How to Submit a + Change" section in the Yocto Project Development Manual. + + + + If the initial commits were not properly documented or do not meet those standards, + you can re-base by using the git rebase -i command to + manipulate the commits and + get them into the required format. + Other techniques such as branching and cherry-picking commits are also viable options. + + + + Once you complete the commits, you can generate the email that sends the patches + to the maintainer(s) or lists that review and integrate changes. + The command git send-email is commonly used to ensure + that patches are properly + formatted for easy application and avoid mailer-induced patch damage. + + + + The following is an example of dumping patches for external submission: + + # 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 + # the editor is invoked for the 0/N patch, and when complete the entire + # series is sent via email for review + + +
+ +
+ Exporting Changes for Import into Another SCM + + + When you want to export changes for import into another + Source Code Manager (SCM), you can use any of the previously discussed + techniques. + However, if the patches are manually applied to a secondary tree and then + that tree is checked into the SCM, you can lose change information such as + commit logs. + This process is not recommended. + + + + Many SCMs can directly import Git commits, or can translate Git patches so that + information is not lost. + Those facilities are SCM-dependent and you should use them whenever possible. + +
+
+ +
+ Working with the Yocto Project Kernel in Another SCM + + + This section describes kernel development in an SCM other than Git, + which is not the same as exporting changes to another SCM described earlier. + For this scenario, you use the OpenEmbedded build system to + develop the kernel in a different SCM. + The following must be true for you to accomplish this: + + The delivered Yocto Project kernel must be exported into the second + SCM. + Development must be exported from that secondary SCM into a + format that can be used by the OpenEmbedded build system. + + + +
+ Exporting the Delivered Kernel to the SCM + + + Depending on the SCM, it might be possible to export the entire Yocto Project + kernel Git repository, branches and all, into a new environment. + This method is preferred because it has the most flexibility and potential to maintain + the meta data associated with each commit. + + + + When a direct import mechanism is not available, it is still possible to + export a branch (or series of branches) and check them into a new repository. + + + + The following commands illustrate some of the steps you could use to + import the yocto/standard/common-pc/base + kernel into a secondary SCM: + + $ git checkout yocto/standard/common-pc/base + $ cd .. ; echo linux/.git > .cvsignore + $ cvs import -m "initial import" linux MY_COMPANY start + + + + + You could now relocate the CVS repository and use it in a centralized manner. + + + + The following commands illustrate how you can condense and merge two BSPs into a + second SCM: + + $ git checkout yocto/standard/common-pc/base + $ git merge yocto/standard/common-pc-64/base + # resolve any conflicts and commit them + $ cd .. ; echo linux/.git > .cvsignore + $ cvs import -m "initial import" linux MY_COMPANY start + + +
+ +
+ Importing Changes for the Build + + + Once development has reached a suitable point in the second development + environment, you need to export the changes as patches. + To export them, place the changes in a recipe and + automatically apply them to the kernel during patching. + +
+
+ +
+ Creating a BSP Based on an Existing Similar BSP + + + This section overviews the process of creating a BSP based on an + existing similar BSP. + The information is introductory in nature and does not provide step-by-step examples. + For detailed information on how to create a new BSP, see + the "Creating a New BSP Layer Using the yocto-bsp Script" section in the + Yocto Project Board Support Package (BSP) Developer's Guide, or see the + Transcript:_creating_one_generic_Atom_BSP_from_another + wiki page. + + + + The basic steps you need to follow are: + + Make sure you have set up a local Source Directory: + You must create a local + Source Directory + by either creating a Git repository (recommended) or + extracting a Yocto Project release tarball. + Choose an existing BSP available with the Yocto Project: + Try to map your board features as closely to the features of a BSP that is + already supported and exists in the Yocto Project. + Starting with something as close as possible to your board makes developing + your BSP easier. + You can find all the BSPs that are supported and ship with the Yocto Project + on the Yocto Project's Download page at + . + Be sure you have the Base BSP: + You need to either have a local Git repository of the base BSP set up or + have downloaded and extracted the files from a release BSP tarball. + Either method gives you access to the BSP source files. + Make a copy of the existing BSP, thus isolating your new + BSP work: + Copying the existing BSP file structure gives you a new area in which to work. + Make configuration and recipe changes to your new BSP: + Configuration changes involve the files in the BSP's conf + directory. + Changes include creating a machine-specific configuration file and editing the + layer.conf file. + The configuration changes identify the kernel you will be using. + Recipe changes include removing, modifying, or adding new recipe files that + instruct the build process on what features to include in the image. + Prepare for the build: + Before you actually initiate the build, you need to set up the build environment + by sourcing the environment initialization script. + After setting up the environment, you need to make some build configuration + changes to the local.conf and bblayers.conf + files. + Build the image: + The OpenEmbedded build system uses BitBake to create the image. + You need to decide on the type of image you are going to build (e.g. minimal, base, + core, sato, and so forth) and then start the build using the bitbake + command. + + +
+ +
+ "-dirty" String + + + If kernel images are being built with "-dirty" on the end of the version + string, this simply means that modifications in the source + directory have not been committed. + + $ git status + + + + + You can use the above Git command to report modified, removed, or added files. + You should commit those changes to the tree regardless of whether they will be saved, + exported, or used. + Once you commit the changes you need to rebuild the kernel. + + + + To brute force pickup and commit all such pending changes, enter the following: + + $ git add . + $ git commit -s -a -m "getting rid of -dirty" + + + + + Next, rebuild the kernel. + +
+
+ + diff --git a/documentation/kernel-dev/kernel-dev-faq.xml b/documentation/kernel-dev/kernel-dev-faq.xml new file mode 100644 index 0000000000..9d9aef6d06 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-faq.xml @@ -0,0 +1,918 @@ + %poky; ] > + + + +Working with the Yocto Project Kernel + + +
+ Introduction + + This chapter describes how to accomplish tasks involving a kernel's tree structure. + The information is designed to help the developer that wants to modify the Yocto + Project kernel and contribute changes upstream to the Yocto Project. + The information covers the following: + + Tree construction + Build strategies + Workflow examples + + +
+ +
+ 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 + + 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, see + the "Workflow Examples". + + + + 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. + +
+ +
+ Workflow Examples + + + As previously noted, the Yocto Project kernel has built-in Git integration. + However, these utilities are not the only way to work with the kernel repository. + The Yocto Project has not made changes to Git or to other tools that + would invalidate alternate workflows. + Additionally, the way the kernel repository is constructed results in using + only core Git functionality, thus allowing any number of tools or front ends to use the + resulting tree. + + + + This section contains several workflow examples. + Many of the examples use Git commands. + You can find Git documentation at + . + You can find a simple overview of using Git with the Yocto Project in the + "Git" + section of the Yocto Project Development Manual. + + +
+ Change Inspection: Changes/Commits + + + A common question when working with a kernel is: + "What changes have been applied to this tree?" + + + + In projects that have a collection of directories that + contain patches to the kernel, it is possible to inspect or "grep" the contents + of the directories to get a general feel for the changes. + This sort of patch inspection is not an efficient way to determine what has been + done to the kernel. + The reason it is inefficient is because there are many optional patches that are + selected based on the kernel type and the feature description. + Additionally, patches could exist in directories that are not included in the search. + + + + A more efficient way to determine what has changed in the branch is to use + Git and inspect or search the kernel tree. + This method gives you a full view of not only the source code modifications, + but also provides the reasons for the changes. + + +
+ What Changed in a Kernel? + + + Following are a few examples that show how to use Git commands to examine changes. + Because Git repositories in the Yocto Project do not break existing Git + functionality, and because there exists many permutations of these types of + Git commands, many methods exist by which you can discover changes. + + In the following examples, unless you provide a commit range, + kernel.org history is blended with Yocto Project + kernel changes. + You can form ranges by using branch names from the kernel tree as the + upper and lower commit markers with the Git commands. + You can see the branch names through the web interface to the + Yocto Project source repositories at + . + For example, the branch names for the linux-yocto-3.4 + kernel repository can be seen at + . + + To see a full range of the changes, use the + git whatchanged command and specify a commit range + for the branch (<commit>..<commit>). + + + + Here is an example that looks at what has changed in the + emenlow branch of the + linux-yocto-3.4 kernel. + The lower commit range is the commit associated with the + standard/base branch, while + the upper commit range is the commit associated with the + standard/emenlow branch. + + $ git whatchanged origin/standard/base..origin/standard/emenlow + + + + + To see a summary of changes use the git log command. + Here is an example using the same branches: + + $ git log --oneline origin/standard/base..origin/standard/emenlow + + The git log output might be more useful than + the git whatchanged as you get + a short, one-line summary of each change and not the entire commit. + + + + If you want to see code differences associated with all the changes, use + the git diff command. + Here is an example: + + $ git diff origin/standard/base..origin/standard/emenlow + + + + + You can see the commit log messages and the text differences using the + git show command: + Here is an example: + + $ git show origin/standard/base..origin/standard/emenlow + + + + + You can create individual patches for each change by using the + git format-patch command. + Here is an example that that creates patch files for each commit and + places them in your Documents directory: + + $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow + + +
+ +
+ Show a Particular Feature or Branch Change + + + Developers use tags in the Yocto Project kernel tree to divide changes for significant + features or branches. + Once you know a particular tag, you can use Git commands + to show changes associated with the tag and find the branches that contain + the feature. + + Because BSP branch, kernel.org, and feature tags are all + present, there could be many tags. + + The git show <tag> command shows changes that are tagged by + a feature. + Here is an example that shows changes tagged by the systemtap + feature: + + $ git show systemtap + + You can use the git branch --contains <tag> command + to show the branches that contain a particular feature. + This command shows the branches that contain the systemtap + feature: + + $ git branch --contains systemtap + + + + + You can use many other comparisons to isolate BSP and kernel changes. + For example, you can compare against kernel.org tags + such as the v3.4 tag. + +
+
+ +
+ Development: Saving Kernel Modifications + + + Another common operation is to build a BSP supplied by the Yocto Project, make some + changes, rebuild, and then test. + Those local changes often need to be exported, shared or otherwise maintained. + + + + Since the Yocto Project kernel source tree is backed by Git, this activity is + much easier as compared to with previous releases. + Because Git tracks file modifications, additions and deletions, it is easy + to modify the code and later realize that you need to save the changes. + It is also easy to determine what has changed. + This method also provides many tools to commit, undo and export those modifications. + + + + This section and its sub-sections, describe general application of Git's + push and pull commands, which are used to + get your changes upstream or source your code from an upstream repository. + The Yocto Project provides scripts that help you work in a collaborative development + environment. + For information on these scripts, see the + "Using Scripts to Push a Change + Upstream and Request a Pull" and + "Using Email to Submit a Patch" + sections in the Yocto Project Development Manual. + + + + There are many ways to save kernel modifications. + The technique employed + depends on the destination for the patches: + + + Bulk storage + Internal sharing either through patches or by using Git + External submissions + Exporting for integration into another Source Code + Manager (SCM) + + + + + Because of the following list of issues, the destination of the patches also influences + the method for gathering them: + + + Bisectability + Commit headers + Division of subsystems for separate submission or review + + + +
+ Bulk Export + + + This section describes how you can "bulk" export changes that have not + been separated or divided. + This situation works well when you are simply storing patches outside of the kernel + source repository, either permanently or temporarily, and you are not committing + incremental changes during development. + + This technique is not appropriate for full integration of upstream submission + because changes are not properly divided and do not provide an avenue for per-change + commit messages. + Therefore, this example assumes that changes have not been committed incrementally + during development and that you simply must gather and export them. + + + # bulk export of ALL modifications without separation or division + # of the changes + + $ git add . + $ git commit -s -a -m <msg> + or + $ git commit -s -a # and interact with $EDITOR + + + + + The previous operations capture all the local changes in the project source + tree in a single Git commit. + And, that commit is also stored in the project's source tree. + + + + Once the changes are exported, you can restore them manually using a template + or through integration with the default_kernel. + + +
+ +
+ Incremental/Planned Sharing + + + This section describes how to save modifications when you are making incremental + commits or practicing planned sharing. + The examples in this section assume that you have incrementally committed + changes to the tree during development and now need to export them. + The sections that follow + describe how you can export your changes internally through either patches or by + using Git commands. + + + + During development, the following commands are of interest. + For full Git documentation, refer to the Git documentation at + . + + + # edit a file + $ vi <path>/file + # stage the change + $ git add <path>/file + # commit the change + $ git commit -s + # remove a file + $ git rm <path>/file + # commit the change + $ git commit -s + + ... etc. + + + + + Distributed development with Git is possible when you use a universally + agreed-upon unique commit identifier (set by the creator of the commit) that maps to a + specific change set with a specific parent. + This identifier is created for you when + you create a commit, and is re-created when you amend, alter or re-apply + a commit. + As an individual in isolation, this is of no interest. + However, if you + intend to share your tree with normal Git push and + pull operations for + distributed development, you should consider the ramifications of changing a + commit that you have already shared with others. + + + + Assuming that the changes have not been pushed upstream, or pulled into + another repository, you can update both the commit content and commit messages + associated with development by using the following commands: + + + $ Git add <path>/file + $ Git commit --amend + $ Git rebase or Git rebase -i + + + + + Again, assuming that the changes have not been pushed upstream, and that + no pending works-in-progress exist (use git status to check), then + you can revert (undo) commits by using the following commands: + + + # remove the commit, update working tree and remove all + # traces of the change + $ git reset --hard HEAD^ + # remove the commit, but leave the files changed and staged for re-commit + $ git reset --soft HEAD^ + # remove the commit, leave file change, but not staged for commit + $ git reset --mixed HEAD^ + + + + + You can create branches, "cherry-pick" changes, or perform any number of Git + operations until the commits are in good order for pushing upstream + or for pull requests. + After a push or pull command, + commits are normally considered + "permanent" and you should not modify them. + If the commits need to be changed, you can incrementally do so with new commits. + These practices follow standard Git workflow and the kernel.org best + practices, which is recommended. + + It is recommended to tag or branch before adding changes to a Yocto Project + BSP or before creating a new one. + The reason for this recommendation is because the branch or tag provides a + reference point to facilitate locating and exporting local changes. + + + +
+ Exporting Changes Internally by Using Patches + + + This section describes how you can extract committed changes from a working directory + by exporting them as patches. + Once the changes have been extracted, you can use the patches for upstream submission, + place them in a Yocto Project template for automatic kernel patching, + or apply them in many other common uses. + + + + This example shows how to create a directory with sequentially numbered patches. + Once the directory is created, you can apply it to a repository using the + git am command to reproduce the original commit and all + the related information such as author, date, commit log, and so forth. + + The new commit identifiers (ID) will be generated upon re-application. + This action reflects that the commit is now applied to an underlying commit + with a different ID. + + + # <first-commit> can be a tag if one was created before development + # began. It can also be the parent branch if a branch was created + # before development began. + + $ git format-patch -o <dir> <first commit>..<last commit> + + + + + In other words: + + # Identify commits of interest. + + # If the tree was tagged before development + $ git format-patch -o <save dir> <tag> + + # If no tags are available + $ git format-patch -o <save dir> HEAD^ # last commit + $ git format-patch -o <save dir> HEAD^^ # last 2 commits + $ git whatchanged # identify last commit + $ git format-patch -o <save dir> <commit id> + $ git format-patch -o <save dir> <rev-list> + + +
+ +
+ 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 to 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, the following command pushes the changes from your local branch + yocto/standard/common-pc/base to the remote branch with the same name + in the master repository //git.mycompany.com/pub/git/kernel-3.4. + + $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \ + yocto/standard/common-pc/base:yocto/standard/common-pc/base + + + + + A pull request entails using the git request-pull command 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. + + +
+
+ +
+ Exporting Changes for External (Upstream) Submission + + + This section describes how to export changes for external upstream submission. + If the patch series is large or the maintainer prefers to pull + changes, you can submit these changes by using a pull request. + However, it is common to send patches as an email series. + This method allows easy review and integration of the changes. + + Before sending patches for review be sure you understand the + community standards for submitting and documenting changes and follow their best practices. + For example, kernel patches should follow standards such as: + + + + Documentation/SubmittingPatches (in any linux + kernel source tree) + + + + + + The messages used to commit changes are a large part of these standards. + Consequently, be sure that the headers for each commit have the required information. + For information on how to follow the Yocto Project commit message standards, see the + "How to Submit a + Change" section in the Yocto Project Development Manual. + + + + If the initial commits were not properly documented or do not meet those standards, + you can re-base by using the git rebase -i command to + manipulate the commits and + get them into the required format. + Other techniques such as branching and cherry-picking commits are also viable options. + + + + Once you complete the commits, you can generate the email that sends the patches + to the maintainer(s) or lists that review and integrate changes. + The command git send-email is commonly used to ensure + that patches are properly + formatted for easy application and avoid mailer-induced patch damage. + + + + The following is an example of dumping patches for external submission: + + # 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 + # the editor is invoked for the 0/N patch, and when complete the entire + # series is sent via email for review + + +
+ +
+ Exporting Changes for Import into Another SCM + + + When you want to export changes for import into another + Source Code Manager (SCM), you can use any of the previously discussed + techniques. + However, if the patches are manually applied to a secondary tree and then + that tree is checked into the SCM, you can lose change information such as + commit logs. + This process is not recommended. + + + + Many SCMs can directly import Git commits, or can translate Git patches so that + information is not lost. + Those facilities are SCM-dependent and you should use them whenever possible. + +
+
+ +
+ Working with the Yocto Project Kernel in Another SCM + + + This section describes kernel development in an SCM other than Git, + which is not the same as exporting changes to another SCM described earlier. + For this scenario, you use the OpenEmbedded build system to + develop the kernel in a different SCM. + The following must be true for you to accomplish this: + + The delivered Yocto Project kernel must be exported into the second + SCM. + Development must be exported from that secondary SCM into a + format that can be used by the OpenEmbedded build system. + + + +
+ Exporting the Delivered Kernel to the SCM + + + Depending on the SCM, it might be possible to export the entire Yocto Project + kernel Git repository, branches and all, into a new environment. + This method is preferred because it has the most flexibility and potential to maintain + the meta data associated with each commit. + + + + When a direct import mechanism is not available, it is still possible to + export a branch (or series of branches) and check them into a new repository. + + + + The following commands illustrate some of the steps you could use to + import the yocto/standard/common-pc/base + kernel into a secondary SCM: + + $ git checkout yocto/standard/common-pc/base + $ cd .. ; echo linux/.git > .cvsignore + $ cvs import -m "initial import" linux MY_COMPANY start + + + + + You could now relocate the CVS repository and use it in a centralized manner. + + + + The following commands illustrate how you can condense and merge two BSPs into a + second SCM: + + $ git checkout yocto/standard/common-pc/base + $ git merge yocto/standard/common-pc-64/base + # resolve any conflicts and commit them + $ cd .. ; echo linux/.git > .cvsignore + $ cvs import -m "initial import" linux MY_COMPANY start + + +
+ +
+ Importing Changes for the Build + + + Once development has reached a suitable point in the second development + environment, you need to export the changes as patches. + To export them, place the changes in a recipe and + automatically apply them to the kernel during patching. + +
+
+ +
+ Creating a BSP Based on an Existing Similar BSP + + + This section overviews the process of creating a BSP based on an + existing similar BSP. + The information is introductory in nature and does not provide step-by-step examples. + For detailed information on how to create a new BSP, see + the "Creating a New BSP Layer Using the yocto-bsp Script" section in the + Yocto Project Board Support Package (BSP) Developer's Guide, or see the + Transcript:_creating_one_generic_Atom_BSP_from_another + wiki page. + + + + The basic steps you need to follow are: + + Make sure you have set up a local Source Directory: + You must create a local + Source Directory + by either creating a Git repository (recommended) or + extracting a Yocto Project release tarball. + Choose an existing BSP available with the Yocto Project: + Try to map your board features as closely to the features of a BSP that is + already supported and exists in the Yocto Project. + Starting with something as close as possible to your board makes developing + your BSP easier. + You can find all the BSPs that are supported and ship with the Yocto Project + on the Yocto Project's Download page at + . + Be sure you have the Base BSP: + You need to either have a local Git repository of the base BSP set up or + have downloaded and extracted the files from a release BSP tarball. + Either method gives you access to the BSP source files. + Make a copy of the existing BSP, thus isolating your new + BSP work: + Copying the existing BSP file structure gives you a new area in which to work. + Make configuration and recipe changes to your new BSP: + Configuration changes involve the files in the BSP's conf + directory. + Changes include creating a machine-specific configuration file and editing the + layer.conf file. + The configuration changes identify the kernel you will be using. + Recipe changes include removing, modifying, or adding new recipe files that + instruct the build process on what features to include in the image. + Prepare for the build: + Before you actually initiate the build, you need to set up the build environment + by sourcing the environment initialization script. + After setting up the environment, you need to make some build configuration + changes to the local.conf and bblayers.conf + files. + Build the image: + The OpenEmbedded build system uses BitBake to create the image. + You need to decide on the type of image you are going to build (e.g. minimal, base, + core, sato, and so forth) and then start the build using the bitbake + command. + + +
+ +
+ "-dirty" String + + + If kernel images are being built with "-dirty" on the end of the version + string, this simply means that modifications in the source + directory have not been committed. + + $ git status + + + + + You can use the above Git command to report modified, removed, or added files. + You should commit those changes to the tree regardless of whether they will be saved, + exported, or used. + Once you commit the changes you need to rebuild the kernel. + + + + To brute force pickup and commit all such pending changes, enter the following: + + $ git add . + $ git commit -s -a -m "getting rid of -dirty" + + + + + Next, rebuild the kernel. + +
+
+ + diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml new file mode 100644 index 0000000000..c1cc22bb7a --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-intro.xml @@ -0,0 +1,78 @@ + %poky; ] > + + + +Yocto Project Kernel Architecture and Use Manual + +
+ Introduction + + The Yocto Project presents kernels as a fully patched, history-clean Git + repositories. + Each repository represents selected features, board support, + and configurations extensively tested by the Yocto Project. + Yocto Project kernels allow the end user to leverage community + best practices to seamlessly manage the development, build and debug cycles. + + + This manual describes Yocto Project kernels by providing information + on history, organization, benefits, and use. + The manual consists of two sections: + + Concepts: Describes concepts behind a kernel. + You will understand how a kernel is organized and why it is organized in + the way it is. You will understand the benefits of a kernel's organization + and the mechanisms used to work with the kernel and how to apply it in your + design process. + Using a Kernel: Describes best practices + and "how-to" information + that lets you put a kernel to practical use. + Some examples are how to examine changes in a branch and how to + save kernel modifications. + + + + + For more information on the Linux kernel, see the following links: + + The Linux Foundation's guide for kernel development + process - + A fairly encompassing guide on Linux kernel development - + + + + + + For more discussion on the Yocto Project kernel, you can see these sections + in the Yocto Project Development Manual: + + + "Kernel Overview" + + "Kernel Modification Workflow" + + + "Patching the Kernel" + + "Configuring the Kernel" + + + + + For general information on the Yocto Project, visit the website at + . + +
+ + + + + + + + + diff --git a/documentation/kernel-dev/kernel-dev-style.css b/documentation/kernel-dev/kernel-dev-style.css new file mode 100644 index 0000000000..a90d4af291 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-style.css @@ -0,0 +1,979 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/kernel-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-image: url("figures/yocto-project-bw.png"); + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} + diff --git a/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml new file mode 100644 index 0000000000..8714c07744 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev.xml @@ -0,0 +1,104 @@ + %poky; ] > + + + + + + + + + + + + + + + Bruce Ashfield + + Wind River Corporation + + bruce.ashfield@windriver.com + + + + + + 0.9 + 24 November 2010 + The initial document draft released with the Yocto Project 0.9 Release. + + + 1.0 + 6 April 2011 + Released with the Yocto Project 1.0 Release. + + + 1.0.1 + 23 May 2011 + Released with the Yocto Project 1.0.1 Release. + + + 1.1 + 6 October 2011 + Released with the Yocto Project 1.1 Release. + + + 1.2 + April 2012 + Released with the Yocto Project 1.2 Release. + + + 1.3 + October 2012 + Released with the Yocto Project 1.3 Release. + + + 1.4 + Sometime in 2013 + Released with the Yocto Project 1.4 Release. + + + + + ©RIGHT_YEAR; + Linux Foundation + + + + + Permission is granted to copy, distribute and/or modify this document under + the terms of the Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by Creative Commons. + + + Due to production processes, there could be differences between the Yocto Project + documentation bundled in the release tarball and the + Yocto Project Kernel Architecture and Use Manual on + the Yocto Project website. + For the latest version of this manual, see the manual on the website. + + + + + + + + + + + + + + +