diff options
Diffstat (limited to 'documentation/kernel-manual')
| -rw-r--r-- | documentation/kernel-manual/Makefile | 42 | ||||
| -rwxr-xr-x | documentation/kernel-manual/figures/kernel-architecture-overview.png | bin | 40748 -> 0 bytes | |||
| -rwxr-xr-x | documentation/kernel-manual/figures/kernel-big-picture.png | bin | 173130 -> 0 bytes | |||
| -rw-r--r-- | documentation/kernel-manual/figures/kernel-title.png | bin | 14305 -> 0 bytes | |||
| -rwxr-xr-x | documentation/kernel-manual/figures/yocto-project-transp.png | bin | 8626 -> 0 bytes | |||
| -rw-r--r-- | documentation/kernel-manual/kernel-concepts.xml | 335 | ||||
| -rw-r--r-- | documentation/kernel-manual/kernel-doc-intro.xml | 57 | ||||
| -rw-r--r-- | documentation/kernel-manual/kernel-how-to.xml | 2178 | ||||
| -rw-r--r-- | documentation/kernel-manual/kernel-manual.xml | 72 | ||||
| -rw-r--r-- | documentation/kernel-manual/style.css | 968 | ||||
| -rw-r--r-- | documentation/kernel-manual/yocto-project-kernel-manual-customization.xsl | 8 |
11 files changed, 0 insertions, 3660 deletions
diff --git a/documentation/kernel-manual/Makefile b/documentation/kernel-manual/Makefile deleted file mode 100644 index a2eaced58..000000000 --- a/documentation/kernel-manual/Makefile +++ /dev/null @@ -1,42 +0,0 @@ -XSLTOPTS = --stringparam html.stylesheet style.css \ - --stringparam chapter.autolabel 1 \ - --stringparam appendix.autolabel A \ - --stringparam section.autolabel 1 \ - --stringparam section.label.includes.component.label 1 \ - --xinclude - -## -# These URI should be rewritten by your distribution's xml catalog to -# match your localy installed XSL stylesheets. -XSL_BASE_URI = http://docbook.sourceforge.net/release/xsl/current -XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl - -all: html pdf tarball - -pdf: - ../tools/poky-docbook-to-pdf kernel-manual.xml ../template - -## -# These URI should be rewritten by your distribution's xml catalog to -# match your localy installed XSL stylesheets. - -html: -# See http://www.sagehill.net/docbookxsl/HtmlOutput.html - -# xsltproc $(XSLTOPTS) -o yocto-project-qs.html $(XSL_XHTML_URI) yocto-project-qs.xml - xsltproc $(XSLTOPTS) -o kernel-manual.html yocto-project-kernel-manual-customization.xsl kernel-manual.xml - -tarball: html - tar -cvzf kernel-manual.tgz kernel-manual.html kernel-manual.pdf style.css figures/kernel-title.png figures/kernel-big-picture.png figures/kernel-architecture-overview.png - -validate: - xmllint --postvalid --xinclude --noout kernel-manual.xml - -OUTPUTS = kernel-manual.tgz kernel-manual.html kernel-manual.pdf -SOURCES = *.png *.xml *.css - -publish: - scp -r $(OUTPUTS) $(SOURCES) o-hand.com:/srv/www/pokylinux.org/doc/ - -clean: - rm -f $(OUTPUTS) diff --git a/documentation/kernel-manual/figures/kernel-architecture-overview.png b/documentation/kernel-manual/figures/kernel-architecture-overview.png Binary files differdeleted file mode 100755 index 2aad172db..000000000 --- a/documentation/kernel-manual/figures/kernel-architecture-overview.png +++ /dev/null diff --git a/documentation/kernel-manual/figures/kernel-big-picture.png b/documentation/kernel-manual/figures/kernel-big-picture.png Binary files differdeleted file mode 100755 index 49bac618e..000000000 --- a/documentation/kernel-manual/figures/kernel-big-picture.png +++ /dev/null diff --git a/documentation/kernel-manual/figures/kernel-title.png b/documentation/kernel-manual/figures/kernel-title.png Binary files differdeleted file mode 100644 index 965264ccc..000000000 --- a/documentation/kernel-manual/figures/kernel-title.png +++ /dev/null diff --git a/documentation/kernel-manual/figures/yocto-project-transp.png b/documentation/kernel-manual/figures/yocto-project-transp.png Binary files differdeleted file mode 100755 index 31d2b147f..000000000 --- a/documentation/kernel-manual/figures/yocto-project-transp.png +++ /dev/null diff --git a/documentation/kernel-manual/kernel-concepts.xml b/documentation/kernel-manual/kernel-concepts.xml deleted file mode 100644 index f26e2903e..000000000 --- a/documentation/kernel-manual/kernel-concepts.xml +++ /dev/null @@ -1,335 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id='kernel-concepts'> - -<title>Yocto Project Kernel Concepts</title> - -<section id='concepts-org'> - <title>Introduction</title> - <para> - This chapter provides conceptual information about the Yocto Project kernel: - <itemizedlist> - <listitem><para>Kernel Goals</para></listitem> - <listitem><para>Yocto Project Kernel Development and Maintenance Overview</para></listitem> - <listitem><para>Kernel Architecture</para></listitem> - <listitem><para>Kernel Tools</para></listitem> - </itemizedlist> - </para> -</section> - - <section id='kernel-goals'> - <title>Kernel Goals</title> - <para> - 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, flexibility and maintainability are key concerns. - The Yocto Project Linux kernel is presented with the embedded - developer's needs in mind and has 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. - </para> - <para> - With all these considerations in mind, the Yocto Project kernel and development team - strives to attain these goals: - <itemizedlist> - <listitem><para>Allow the end user to leverage community best practices to seamlessly - manage the development, build and debug cycles.</para></listitem> - <listitem><para>Create a platform for performing integration and collaboration with the - thousands of upstream development projects that exist.</para></listitem> - <listitem><para>Provide mechanisms that support many different work flows, front-ends and - management techniques.</para></listitem> - <listitem><para>Deliver the most up-to-date kernel possible while still ensuring that - the baseline kernel is the most stable official release.</para></listitem> - <listitem><para>Include major technological features as part of Yocto Project's up-rev - strategy.</para></listitem> - <listitem><para>Present a git tree, that just like the upstream kernel.org tree, has a - clear and continuous history.</para></listitem> - <listitem><para>Deliver a key set of supported kernel types, where each type is tailored - to a specific use case (i.g. networking, consumer, devices, and so forth).</para></listitem> - <listitem><para>Employ a git branching strategy that from a customer'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.</para></listitem> - </itemizedlist> - </para> - </section> - - <section id='kernel-big-picture'> - <title>Yocto Project Kernel Development and Maintenance Overview</title> - <para> - Yocto Project kernel, like other kernels, is based off the Linux kernel release - from <ulink url='http://www.kernel.org'></ulink>. - At the beginning of our major development cycle, we choose our Yocto Project kernel - based on factors like release timing, the anticipated release timing of "final" (i.e. non "rc") - upstream kernel.org versions, and Yocto Project feature requirements. - Typically this will be a kernel that is in the - final stages of development by the community (i.e. still in the release - candidate or "rc" phase) and not yet a final release. - But by being in the final stages of external development, we know that the - kernel.org final release will clearly land within the early stages of - the Yocto Project development window. - </para> - <para> - This balance allows us to deliver the most up-to-date kernel - as possible, while still ensuring that we have a stable official release as - our baseline kernel version. - </para> - <para> - The ultimate source for the Yocto Project kernel is a released kernel - from kernel.org. - In addition to a foundational kernel from kernel.org the released - Yocto Project kernel contains 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 kernel that caters - to specific embedded designer needs for targeted hardware. - </para> -<!-- <para> - The following figure represents the overall place the Yocto Project kernel fills. - </para> - <para> - <imagedata fileref="figures/kernel-big-picture.png" width="6in" depth="6in" align="center" scale="100" /> - </para> - <para> - In the figure the ultimate source for the Yocto Project kernel is a released kernel - from kernel.org. - In addition to a foundational kernel from kernel.org the commercially released - Yocto Project kernel contains a mix of important new mainline - developments, non-mainline developments, Board Support Package (BSP) developments, - and custom features. - These additions result in a commercially released Yocto Project kernel that caters - to specific embedded designer needs for targeted hardware. - </para> --> - <para> - Once a Yocto Project kernel is officially released the Yocto Project team goes into - their next development cycle, or "uprev" cycle while 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 of 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 illustration depicts this by showing the team looking back to kernel.org for new features, - BSP features, and significant bug fixes. --> - 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. - </para> - <para> - 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 simply back-porting any small to medium sized change - from an evolving kernel can easily create mismatches, incompatibilities and very - subtle errors. - </para> - <para> - 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 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. - </para> - </section> - - <section id='kernel-architecture'> - <title>Kernel Architecture</title> - <para> - This section describes the architecture of the Yocto Project kernel and provides information - on the mechanisms used to achieve that architecture. - </para> - - <section id='architecture-overview'> - <title>Overview</title> - <para> - As mentioned earlier, a key goal of 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. - - </para> - <para> - You can think of the Yocto Project kernel as consisting of a baseline 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. - 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 as well. - </para> - <para> - The following illustration shows the conceptual Yocto Project kernel. - </para> - <para> - <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" /> - </para> - <para> - 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. - </para> - <para> - 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. - </para> - <para> - 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. - </para> - <para> - 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. - </para> - <para> - The resulting tree structure presents a clear path of markers (or branches) to the user - that for all practical purposes is the kernel needed for any given set of requirements. - </para> - </section> - - <section id='branching-and-workflow'> - <title>Branching Strategy and Workflow</title> - <para> - 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 results in not having to store the same feature twice internally in the - tree. - Rather we store the unique differences required to apply the feature onto the kernel type - in question. - </para> - <note><para> - 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 this practice - cannot always be followed. - In those cases isolated branches are used for feature merging. - </para></note> - <para> - 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, we create 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, only the unique differences for the BSP across - the supported multiple kernels are uniquely stored. - </para> - <para> - While this strategy can result in a tree with a significant number of branches, it is - important to realize that from the user'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 user's perspective, this is the "master" branch. - They do not need not 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. - </para> - <para> - 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. - </para> - <para> - 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 user - because the kernel tree is left in this state after cloning and building the kernel. - </para> - </section> - - <section id='source-code-manager-git'> - <title>Source Code Manager - git</title> - <para> - The Source Code Manager (SCM) is git and it 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. - </para> - <note><para> - It should be noted that you can use as much, or as little, of what git has to offer - as is appropriate to your project. - </para></note> - </section> - </section> - - <section id='kernel-tools'> - <title>Kernel Tools</title> - <para> -Since most standard workflows involve moving forward with an existing tree by -continuing to add and alter the underlying baseline, the tools that manage -Yocto Project's kernel construction are largely hidden from the developer to -present a simplified view of the kernel for ease of use. -</para> -<para> -The fundamental properties of the tools that manage and construct the -kernel are: -<itemizedlist> - <listitem><para>the ability to group patches into named, reusable features</para></listitem> - <listitem><para>to allow top down control of included features</para></listitem> - <listitem><para>the binding of kernel configuration to kernel patches/features</para></listitem> - <listitem><para>the presentation of a seamless git repository that blends Yocto Project value with the kernel.org history and development</para></listitem> -</itemizedlist> -</para> -<!--<para> -The tools that construct a kernel tree will be discussed later in this -document. The following tools form the foundation of the Yocto Project -kernel toolkit: -<itemizedlist> - <listitem><para>git : distributed revision control system created by Linus Torvalds</para></listitem> - <listitem><para>guilt: quilt on top of git</para></listitem> - <listitem><para>*cfg : kernel configuration management and classification</para></listitem> - <listitem><para>kgit*: Yocto Project kernel tree creation and management tools</para></listitem> - <listitem><para>scc : series & configuration compiler</para></listitem> -</itemizedlist> -</para> --> - </section> - - - - - -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/kernel-manual/kernel-doc-intro.xml b/documentation/kernel-manual/kernel-doc-intro.xml deleted file mode 100644 index 05e5443b8..000000000 --- a/documentation/kernel-manual/kernel-doc-intro.xml +++ /dev/null @@ -1,57 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id='kernel-doc-intro'> - -<title>Yocto Project Kernel Architecture and Use Manual</title> - -<section id='book-intro'> - <title>Introduction</title> - <para> - The Yocto Project presents the kernel as a fully patched, history-clean git - repository. - The git tree represents the selected features, board support, - and configurations extensively tested by Yocto Project. - The Yocto Project kernel allows the end user to leverage community - best practices to seamlessly manage the development, build and debug cycles. - </para> - <para> - This manual describes the Yocto Project kernel by providing information - on its history, organization, benefits, and use. - The manual consists of two sections: - <itemizedlist> - <listitem><para>Concepts - Describes concepts behind the kernel. - You will understand how the kernel is organized and why it is organized in - the way it is. You will understand the benefits of the kernel's organization - and the mechanisms used to work with the kernel and how to apply it in your - design process.</para></listitem> - <listitem><para>Using the Kernel - Describes best practices and "how-to" information - that lets you put the kernel to practical use. Some examples are "How to Build a - Project Specific Tree", "How to Examine Changes in a Branch", and "Saving Kernel - Modifications."</para></listitem> - </itemizedlist> - </para> - <para> - For more information on the kernel, see the following links: - <itemizedlist> - <listitem><para><ulink url='http://ldn.linuxfoundation.org/book/1-a-guide-kernel-development-process'></ulink></para></listitem> - <listitem><para><ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem> - <listitem><para><ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem> - </itemizedlist> - <para> - You can find more information on Yocto Project by visiting the website at - <ulink url='http://www.yoctoproject.org'></ulink>. - </para> - </para> -</section> - - - - - - - -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml deleted file mode 100644 index 96325fe2a..000000000 --- a/documentation/kernel-manual/kernel-how-to.xml +++ /dev/null @@ -1,2178 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id='kernel-how-to'> - -<title>Working with the Yocto Project Kernel</title> - - -<section id='actions-org'> - <title>Introduction</title> - <para> - This chapter describes how to accomplish tasks involving the kernel's tree structure. - The information covers the following: - <itemizedlist> - <listitem><para>Tree construction</para></listitem> - <listitem><para>Build strategies</para></listitem> -<!-- <listitem><para>Series & Configuration Compiler</para></listitem> - <listitem><para>kgit</para></listitem> --> - <listitem><para>Workflow examples</para></listitem> -<!-- <listitem><para>Source Code Manager (SCM)</para></listitem> - <listitem><para>Board Support Package (BSP) template migration</para></listitem> - <listitem><para>BSP creation</para></listitem> - <listitem><para>Patching</para></listitem> - <listitem><para>Updating BSP patches and configuration</para></listitem> - <listitem><para>guilt</para></listitem> - <listitem><para>scc file example</para></listitem> - <listitem><para>"dirty" string</para></listitem> - <listitem><para>Transition kernel layer</para></listitem> --> - </itemizedlist> - </para> -</section> - - <section id='tree-construction'> - <title>Tree Construction</title> - <para> - The Yocto Project kernel repository, as shipped with the product, is created by - compiling and executing the set of feature descriptions for every BSP/feature - in the product. - Those feature descriptions list all necessary patches, - configuration, branching, tagging and feature divisions found in the kernel. - </para> - <para> - You can find the files used to describe all the valid features and BSPs in the Yocto Project - kernel in any clone of the kernel git tree. - The directory <filename>meta/cfg/kernel-cache/</filename> is a snapshot of all the kernel - configuration and feature descriptions (.scc) used to build the kernel repository. - You should realize, however, that browsing the snapshot of feature - descriptions and patches is not an effective way to determine what is in a - particular kernel branch. - Instead, you should use git directly to discover the changes - in a branch. - Using git is a efficient and flexible way to inspect changes to the kernel. - For examples showing how to use git to inspect kernel commits, see the following sections - in this chapter. - </para> - <note><para> - Ground up reconstruction of the complete kernel tree is an action only taken by the - Yocto Project team during an active development cycle. - Creating a project simply clones this tree to make it efficiently available for building - and development. - </para></note> - <para> - The general flow for constructing a project-specific kernel tree is as follows: - <orderedlist> - <listitem><para>A top-level kernel feature is passed to the kernel build subsystem. - Normally, this is a BSP for a particular kernel type.</para></listitem> - - <listitem><para>The file that describes the top-level feature is located by searching - these system directories:</para> - - <itemizedlist> - <listitem><para>The in-tree kernel-cache directories</para></listitem> -<!-- <listitem><para>kernel-*-cache directories in layers</para></listitem> --> - <listitem><para>Recipe SRC_URIs</para></listitem> -<!-- <listitem><para>configured and default templates</para></listitem> --> - </itemizedlist> - - <para>For a typical build a feature description of the format: - <bsp name>-<kernel type>.scc is the target of the search. - </para></listitem> - - <listitem><para>Once located, the feature description is either compiled into a simple script - of actions, or an existing equivalent script that was part of the - shipped kernel is located.</para></listitem> - - <listitem><para>Extra features are appended to the top-level feature description. - These features can come from the KERNEL_FEATURES variable in recipes.</para></listitem> - - <listitem><para>Each extra feature is located, compiled and appended to the script from - step #3</para></listitem> - - <listitem><para>The script is executed, and a meta-series is produced. - The meta-series is a description of all the branches, tags, patches and configuration that - needs to be applied to the base git repository to completely create the - BSP source (build) branch.</para></listitem> - - <listitem><para>The base repository is cloned, and the actions - listed in the meta-series are applied to the tree.</para></listitem> - - <listitem><para>The git repository is left with the desired branch checked out and any - required branching, patching and tagging has been performed.</para></listitem> - </orderedlist> - </para> - - <para> - The tree is now ready for configuration and compilation. - </para> - - <note><para>The end-user generated meta-series adds to the kernel as shipped with - the Yocto Project release. - Any add-ons and configuration data are applied to the end of an existing branch. - The full repository generation that is found in the - official Yocto Project kernel repositories is the combination of all - supported boards and configurations.</para> - - <para>This technique is flexible and allows the seamless blending of an immutable - history with additional deployment specific patches. - Any additions to the kernel become an integrated part of the branches. - </para></note> - -<!-- <note><para>It is key that feature descriptions indicate if any branches are - required, since the build system cannot automatically decide where a - BSP should branch or if that branch point needs a name with - significance. There is a single restriction enforced by the compilation - phase: - </para> - <para>A BSP must create a branch of the format <bsp name>-<kernel type>.</para> - - <para>This means that all merged/support BSPs must indicate where to start - its branch from, with the right name, in its .scc files. The scc - section describes the available branching commands in more detail. - </para> -</note> --> - -<!-- <para> -A summary of end user tree construction activities follow: -<itemizedlist> - <listitem><para>compile and link a full top-down kernel description from feature descriptions</para></listitem> - <listitem><para>execute the complete description to generate a meta-series</para></listitem> - <listitem><para>interpret the meta-series to create a customized git repository for the - board</para></listitem> - <listitem><para>migrate configuration fragments and configure the kernel</para></listitem> - <listitem><para>checkout the BSP branch and build</para></listitem> -</itemizedlist> -</para> --> - </section> - - <section id='build-strategy'> - <title>Build Strategy</title> - <para> - There are some prerequisites that must be met before starting the compilation - phase of the kernel build system: - </para> - - <itemizedlist> - <listitem><para>There must be a kernel git repository indicated in the SRC_URI.</para></listitem> - <listitem><para>There must be a BSP build branch - <bsp name>-<kernel type> in 0.9 or - <kernel type>/<bsp name> in 1.0.</para></listitem> - </itemizedlist> - - <para> - You can typically meet these prerequisites by running the tree construction/patching phase - of the build system. - However, other means do exist. - For examples of alternate workflows such as bootstrapping a BSP, see - the<link linkend='workflow-examples'> Workflow Examples</link> section in this manual. - </para> - - <para> - Before building a kernel it is configured by processing all of the - configuration "fragments" specified by the scc feature descriptions. - As the features are compiled, associated kernel configuration fragments are noted - and recorded in the meta-series in their compilation order. - The fragments are migrated, pre-processed and passed to the Linux Kernel - Configuration subsystem (lkc) as raw input in the form of a <filename>.config</filename> file. - The lkc uses its own internal dependency constraints to do the final - processing of that information and generates the final <filename>.config</filename> file - that is used during compilation. - </para> - - <para> - Using the board's architecture and other relevant values from the board's template - the Kernel compilation is started and a kernel image is produced. - </para> - - <para>The other thing that you will first see once you configure a kernel is that - it will generate a build tree that is separate from your git source tree. - This build tree has the name using the following form: - <literallayout class='monospaced'> - linux-<BSPname>-<kerntype>-build - </literallayout> - "kerntype" is one of the standard kernel types. - </para> - - <para> - The existing support in the kernel.org tree achieves this default functionality. - </para> - - <para> - What this means, is that all the generated files for a particular BSP are now in this directory. - The files include the final <filename>.config</filename>, all the <filename>.o</filename> - files, the <filename>.a</filename> files, and so forth. - Since each BSP has its own separate build directory in its own separate branch - of the git tree you can easily switch between different BSP builds. - </para> - </section> - -<!-- <section id='scc'> - <title>Series & Configuration Compiler (SCC)</title> -<para> -In early versions of the product, kernel patches were simply listed in a flat -file called "patches.list", and then quilt was added as a tool to help -traverse this list, which in quilt terms was called a "series" file. -</para> -<para> -Before the 2.0 release, it was already apparent that a static series file was -too inflexible, and that the series file had to become more dynamic and rely -on certain state (like kernel type) in order to determine whether a patch was -to be used or not. The 2.0 release already made use of some stateful -construction of series files, but since the delivery mechanism was unchanged -(tar + patches + series files), most people were not aware of anything really -different. The 3.0 release continues with this stateful construction of -series files, but since the delivery mechanism is changed (git + branches) it -now is more apparent to people. -</para> -<para> -As was previously mentioned, scc is a "series and configuration -compiler". Its role is to combine feature descriptions into a format that can -be used to generate a meta-series. A meta series contains all the required -information to construct a complete set of branches that are required to -build a desired board and feature set. The meta series is interpreted by the -kgit tools to create a git repository that could be built. -</para> -<para> -To illustrate how scc works, a feature description must first be understood. -A feature description is simply a small bash shell script that is executed by -scc in a controlled environment. Each feature description describes a set of -operations that add patches, modify existing patches or configure the -kernel. It is key that feature descriptions can include other features, and -hence allow the division of patches and configuration into named, reusable -containers. -</para> -<para> -Each feature description can use any of the following valid scc commands: -<itemizedlist> - <listitem><para>shell constructs: bash conditionals and other utilities can be used in a feature - description. During compilation, the working directory is the feature - description itself, so any command that is "raw shell" and not from the - list of supported commands, can not directly modify a git repository.</para></listitem> - - <listitem><para>patch <relative path>/<patch name>: outputs a patch to be included in a feature's patch set. Only the name of - the patch is supplied, the path is calculated from the currently set - patch directory, which is normally the feature directory itself.</para></listitem> - - <listitem><para>patch_trigger >condition< >action< <tgt>: indicate that a trigger should be set to perform an action on a - patch.</para> - -<para>The conditions can be: - - <itemizedlist> - <listitem><para>arch:<comma separated arch list or "all"></para></listitem> - <listitem><para>plat:<comma separated platform list or "all"></para></listitem> - </itemizedlist></para> -<para>The action can be: - <itemizedlist> - <listitem><para>exclude: This is used in exceptional situations where a patch - cannot be applied for certain reasons (arch or platform). - When the trigger is satisfied the patch will be removed from - the patch list.</para></listitem> - <listitem><para>include: This is used to include a patch only for a specific trigger. - Like exclude, this should only be used when necessary. - It takes 1 argument, the patch to include.</para></listitem> - </itemizedlist></para></listitem> - - <listitem><para>include <feature name> [after <feature>]: includes a feature for processing. The feature is "expanded" at the - position of the include directive. This means that any patches, - configuration or sub-includes of the feature will appear in the final - series before the commands that follow the include.</para> - <para> - include searches the include directories for a matching feature name, - include directories are passed to scc by the caller using -I <path> and - is transparent to the feature script. This means that <feature name> must - be relative to one of the search paths. For example, if - /opt/kernel-cache/feat/sched.scc is to be included and scc is invoked - with -I /opt/kernel-cache, then a feature would issue "include - feat/sched.scc" to include the feature. -</para> -<para> - The optional "after" directive allows a feature to modify the existing - order of includes and insert a feature after the named feature is - processed. Note: the "include foo after bar" must be issued before "bar" - is processed, so is normally only used by a new top level feature to - modify the order of features in something it is including.</para></listitem> - - <listitem><para>exclude <feature name>: Indicates that a particular feature should *not* be included even if an - 'include' directive is found. The exclude must be issued before the - include is processed, so is normally only used by a new top level feature - to modify the order of features in something it is including.</para></listitem> - - <listitem><para>git <command>: Issues any git command during tree construction. Note: this command is - not validated/sanitized so care must be taken to not damage the - tree. This can be used to script branching, tagging, pulls or other git - operations.</para></listitem> - - <listitem><para>dir <directory>: changes the working directory for "patch" directives. This can be used to - shorten a long sequence of patches by not requiring a common relative - directory to be issued each time.</para></listitem> - - <listitem><para>kconf <type> <fragment name>: associates a kernel config frag with the feature. - <type> can be - "hardware" or "non-hardware" and is used by the kernel configuration - subsystem to audit configuration. <fragment name> is the name of a file - in the current feature directory that contains a series of kernel - configuration options. There is no restriction on the chosen fragment - name, although a suffix of ".cfg" is recommended. Multiple fragment - specifications are supported.</para></listitem> - - <listitem><para>branch <branch name>: creates a branch in the tree. All subsequent patch commands will be - applied to the new branch and changes isolated from the rest of the - repository.</para></listitem> - - <listitem><para>scc_leaf <base feature> <branch name>: Performs a combination feature include and branch. This is mainly a - convenience directive, but has significance to some build system bindings - as a sentinel to indicate that this intends to create a branch that is - valid for kernel compilation.</para></listitem> - - <listitem><para>tag <tag name>: Tags the tree. The tag will be applied in processing order, so will - be after already applied patches and precede patches yet to be applied.</para></listitem> - - <listitem><para>define <var> <value>: Creates a variable with a particular value that can be used in subsequent - feature descriptions.</para></listitem> -</itemizedlist> - -</para> - </section> --> - -<!-- <section id='kgit-tools'> - <title>kgit Tools</title> -<para> -The kgit tools are responsible for constructing and maintaining the Wind -River kernel repository. These activities include importing, exporting, and -applying patches as well as sanity checking and branch management. From the -developers perspective, the kgit tools are hidden and rarely require -interactive use. But one tool in particular that warrants further description -is "kgit-meta". -</para> -<para> -kgit-meta is the actual application of feature description(s) to a kernel repo. -In other words, it is responsible for interpreting the meta series generated -from a scc compiled script. As a result, kgit-meta is coupled to the set of -commands permitted in a .scc feature description (listed in the scc section). -kgit-meta understands both the meta series format and how to use git and -guilt to modify a base git repository. It processes a meta-series line by -line, branching, tagging, patching and tracking changes that are made to the -base git repository. -</para> -<para> -Once kgit-meta has processed a meta-series, it leaves the repository with the -last branch checked out, and creates the necessary guilt infrastructure to -inspect the tree, or add to it via using guilt. As was previously mentioned, -guilt is not required, but is provided as a convenience. Other utilities such -as quilt, stgit, git or others can also be used to manipulate the git -repository. -</para> - </section> --> - - <section id='workflow-examples'> - <title>Workflow Examples</title> - - <para> - 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. - 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. - </para> - - <para> - This section contains several workflow examples. - </para> - - <section id='change-inspection-kernel-changes-commits'> - <title>Change Inspection: Kernel Changes/Commits</title> - - <para> - A common question when working with a BSP or kernel is: - "What changes have been applied to this tree?" - </para> - - <para> - 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. - </para> - - <para> - A more efficient way to determine what has changed in the kernel 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. - </para> - - <section id='what-changed-in-a-bsp'> - <title>What Changed in a BSP?</title> - - <para> - Following are a few examples that show how to use git to examine changes. - Note that because the Yocto Project git repository does not break existing git - functionality and because there exists many permutations of these types of - commands there are many more methods to discover changes. - </para> - - <note><para> - Unless you provide a commit range - (<kernel-type>..<bsp>-<kernel-type>), kernel.org history - is blended with Yocto Project changes. - </para></note> - - <literallayout class='monospaced'> - # full description of the changes - > git whatchanged <kernel type>..<kernel type>/<bsp> - > eg: git whatchanged yocto/standard/base..yocto/standard/common-pc/base - - # summary of the changes - > git log --pretty=oneline --abbrev-commit <kernel type>..<kernel type>/<bsp> - - # source code changes (one combined diff) - > git diff <kernel type>..<kernel type>/<bsp> - > git show <kernel type>..<kernel type>/<bsp> - - # dump individual patches per commit - > git format-patch -o <dir> <kernel type>..<kernel type>/<bsp> - - # determine the change history of a particular file - > git whatchanged <path to file> - - # determine the commits which touch each line in a file - > git blame <path to file> - </literallayout> - </section> - - <section id='show-a-particular-feature-or-branch-change'> - <title>Show a Particular Feature or Branch Change</title> - - <para> - Significant features or branches are tagged in the Yocto Project tree to divide - changes. - Remember to first determine (or add) the tag of interest. - </para> - - <note><para> - Because BSP branch, kernel.org, and feature tags are all present, there are many tags. - </para></note> - - <literallayout class='monospaced'> - # show the changes tagged by a feature - > git show <tag> - > eg: git show yaffs2 - - # determine which branches contain a feature - > git branch --contains <tag> - - # show the changes in a kernel type - > git whatchanged yocto/base..<kernel type> - > eg: git whatchanged yocto/base..yocto/standard/base - </literallayout> - - <para> - You can use many other comparisons to isolate BSP changes. - For example, you can compare against kernel.org tags (e.g. v2.6.27.18, etc), or - you can compare against subsystems (e.g. git whatchanged mm). - </para> - </section> - </section> - - <section id='development-saving-kernel-modifications'> - <title>Development: Saving Kernel Modifications</title> - - <para> - Another common operation is to build a BSP supplied by Yocto Project, make some - changes, rebuild and then test. - Those local changes often need to be exported, shared or otherwise maintained. - </para> - - <para> - 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 the changes should be saved. - It is also easy to determine what has changed. - This method also provides many tools to commit, undo and export those modifications. - </para> - - <para> - There are many ways to save kernel modifications. - The technique employed - depends on the destination for the patches: - - <itemizedlist> - <listitem><para>Bulk storage</para></listitem> - <listitem><para>Internal sharing either through patches or by using git</para></listitem> - <listitem><para>External submissions</para></listitem> - <listitem><para>Exporting for integration into another SCM</para></listitem> - </itemizedlist> - </para> - - <para> - Because of the following list of issues, the destination of the patches also influences - the method for gathering them: - - <itemizedlist> - <listitem><para>Bisectability</para></listitem> - <listitem><para>Commit headers</para></listitem> - <listitem><para>Division of subsystems for separate submission or review</para></listitem> - </itemizedlist> - </para> - - <section id='bulk-export'> - <title>Bulk Export</title> - - <para> - This section describes how you can export in "bulk" 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. - </para> - - <note><para> - 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. - </para></note> - - <literallayout class='monospaced'> - # bulk export of ALL modifications without separation or division - # of the changes - - > git add . - > git commit -s -a -m >commit message< - or - > git commit -s -a # and interact with $EDITOR - </literallayout> - - <para> - 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. - </para> - - <para> - Once the changes are exported, you can restore them manually using a template - or through integration with the <filename>default_kernel</filename>. - </para> - - </section> - - <section id='incremental-planned-sharing'> - <title>Incremental/Planned Sharing</title> - - <para> - This section describes how to save modifications when you are making incremental - commits or practicing planned sharing. - The examples in this section assume that changes have been incrementally committed - to the tree during development and now need to be exported. The sections that follow - describe how you can export your changes internally through either patches or by - using git commands. - </para> - - <para> - During development the following commands are of interest. - For full git documentation, refer to the git man pages or to an online resource such - as <ulink url='http://github.com'></ulink>. - - <literallayout class='monospaced'> - # 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. - </literallayout> - </para> - - <para> - 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. - </para> - - <para> - 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: - - <literallayout class='monospaced'> - > git add >path</file - > git commit --amend - > git rebase or git rebase -i - </literallayout> - </para> - - <para> - 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: - - <literallayout class='monospaced'> - # 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^ - </literallayout> - </para> - - <para> - 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, commits are normally considered - "permanent" and you should not modify them. - If they need to be changed you can incrementally do so with new commits. - These practices follow the standard "git" workflow and the kernel.org best - practices, which Yocto Project recommends. - </para> - - <note><para> - 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. - </para></note> - - <section id='export-internally-via-patches'> - <title>Exporting Changes Internally by Using Patches</title> - - <para> - This section describes how you can extract committed changes from a working directory - by exporting them as patches. - Once 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. - </para> - - <para> - 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 - <filename>git am</filename> command to reproduce the original commit and all - the related information such as author, date, commit log, and so forth. - </para> - - <note><para> - 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. - </para></note> - - <para> - <literallayout class='monospaced'> - # <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> - </literallayout> - </para> - - <para> - In other words: - <literallayout class='monospaced'> - # 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> - </literallayout> - </para> - - <!--<para> - See the "template patching" example for how to use the patches to - automatically apply to a new kernel build. - </para>--> - </section> - - <section id='export-internally-via-git'> - <title>Exporting Changes Internally by Using git</title> - - <para> - This section describes how you can export changes from a working directory - by pushing the changes into a master repository or by making a pull request. - Once you have pushed the changes in the master repository you can then - pull those same changes into a new kernel build at a later time. - </para> - - <para> - Use this command form to push the changes: - <literallayout class='monospaced'> - git push ssh://<master server>/<path to repo> <local branch>:<remote branch> - </literallayout> - </para> - - <para> - For example, the following command pushes the changes from your local branch - <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name - in the master repository <filename>//git.mycompany.com/pub/git/kernel-2.6.37</filename>. - <literallayout class='monospaced'> - > push ssh://git.mycompany.com/pub/git/kernel-2.6.37 yocto/standard/common-pc/base:yocto/standard/common-pc/base - </literallayout> - </para> - - <para> - A pull request entails using "git request-pull" to compose an email to the - maintainer requesting that a branch be pulled into the master repository, see - <ulink url='http://github.com/guides/pull-requests'></ulink> for an example. - </para> - - <note><para> - Other commands such as 'git stash' or branching can also be used to save - changes, but are not covered in this document. - </para></note> - - <!--<para> - See the section "importing from another SCM" for how a git push to the - default_kernel, can be used to automatically update the builds of all users - of a central git repository. - </para>--> - </section> - </section> - - <section id='export-for-external-upstream-submission'> - <title>Exporting Changes for External (Upstream) Submission</title> - - <para> - 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 sent patches as an email series. - This method allows easy review and integration of the changes. - </para> - - <note><para> - 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: - <itemizedlist> - <listitem><para><ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem> - <listitem><para><ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem> - <listitem><para>Documentation/SubmittingPatches (in any linux kernel source tree)</para></listitem> - </itemizedlist> - </para></note> - - <para> - 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. - 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. - </para> - - <para> - 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. - </para> - - <para> - The following is an example of dumping patches for external submission: - <literallayout class='monospaced'> - # 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 - </literallayout> - </para> - </section> - - <section id='export-for-import-into-other-scm'> - <title>Exporting Changes for Import into Another SCM</title> - - <para> - 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. - Yocto Project does not recommend this process. - </para> - - <para> - 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. - </para> - </section> - </section> - - <section id='scm-working-with-the-yocto-project-kernel-in-another-scm'> - <title>Working with the Yocto Project Kernel in Another SCM</title> - - <para> - This section describes kernel development in another SCM, which is not the same - as exporting changes to another SCM. - For this scenario you use the Yocto Project build system to - develop the kernel in a different SCM. - The following must be true for you to accomplish this: - <itemizedlist> - <listitem><para>The delivered Yocto Project kernel must be exported into the second - SCM.</para></listitem> - <listitem><para>Development must be exported from that secondary SCM into a - format that can be used by the Yocto Project build system.</para></listitem> - </itemizedlist> - </para> - - <section id='exporting-delivered-kernel-to-scm'> - <title>Exporting the Delivered Kernel to the SCM</title> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <para> - The following commands illustrate some of the steps you could use to - import the yocto/standard/common-pc/base kernel into a secondary SCM: - <literallayout class='monospaced'> - > git checkout yocto/standard/common-pc/base - > cd .. ; echo linux/.git > .cvsignore - > cvs import -m "initial import" linux MY_COMPANY start - </literallayout> - </para> - - <para> - You could now relocate the CVS repository and use it in a centralized manner. - </para> - - <para> - The following commands illustrate how you can condense and merge two BSPs into a second SCM: - <literallayout class='monospaced'> - > 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 - </literallayout> - </para> - </section> - - <section id='importing-changes-for-build'> - <title>Importing Changes for the Build</title> - - <para> - 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. - </para> -<!--<para> -If changes are imported directly into git, they must be propagated to the -wrll-linux-2.6.27/git/default_kernel bare clone of each individual build -to be present when the kernel is checked out. -</para> -<para> -The following example illustrates one variant of this workflow: -<literallayout class='monospaced'> - # on master git repository - > cd linux-2.6.27 - > git tag -d common_pc-standard-mark - > git pull ssh://<foo>@<bar>/pub/git/kernel-2.6.27 common_pc-standard:common_pc-standard - > git tag common_pc-standard-mark - - # on each build machine (or NFS share, etc) - > cd wrll-linux-2.6.27/git/default_kernel - > git fetch ssh://<foo>@<master server>/pub/git/kernel-2.6.27 - - # in the build, perform a from-scratch build of Linux and the new changes - # will be checked out and built. - > make linux -</literallayout> -</para> --> - </section> - </section> - -<!-- <section id='bsp-template-migration-from-2'> - <title>BSP: Template Migration from 2.0</title> -<para> -The move to a git-backed kernel build system in 3.0 introduced a small new -requirement for any BSP that is not integrated into the GA release of the -product: branching information. -</para> -<para> -As was previously mentioned in the background sections, branching information -is always required, since the kernel build system cannot make intelligent -branching decisions and must rely on the developer. This branching -information is provided via a .scc file. -</para> -<para> -A BSP template in 2.0 contained build system information (config.sh, etc) and -kernel patching information in the 'linux' subdirectory. The same holds true -in 3.0, with only minor changes in the kernel patching directory. -The ".smudge" files are now ".scc" files and now contain a full description - of the kernel branching, patching and configuration for the BSP. Where in - 2.0, they only contained kernel patching information. -</para> -<para> -The following illustrates the migration of a simple 2.0 BSP template to the -new 3.0 kernel build system. -</para> -<note><para> -Note: all operations are from the root of a customer layer. -</para></note> -<literallayout class='monospaced'> - templates/ - `‐‐ board - `‐‐ my_board - |‐‐ config.sh - |‐‐ include - `‐‐ linux - `‐‐ 2.6.x - |‐‐ knl-base.cfg - |‐‐ bsp.patch - `‐‐ my_bsp.smudge - - > mv templates/board/my_board/linux/2.6.x/* templates/board/my_board/linux - > rm -rf templates/board/my_board/linux/2.6.x/ - > mv templates/board/my_board/linux/my_bsp.smudge \ - templates/board/my_board/linux/my_bsp-standard.scc - > echo "kconf hardware knl-base.cfg" >> \ - templates/board/my_board/linux/my_bsp-standard.scc - > vi templates/board/my_board/linux/my_bsp-standard.scc - # add the following at the top of the file - scc_leaf ktypes/standard my_bsp-standard - - templates/ - `‐‐ board - `‐‐ my_board - |‐‐ config.sh - |‐‐ include - `‐‐ linux - |‐‐ knl-base.cfg - |‐‐ bsp.patch - `‐‐ my_bsp-standard.scc -</literallayout> -<para> -That's it. Configure and build. -</para> -<note><para>There is a naming convention for the .scc file, which allows the build - system to locate suitable feature descriptions for a board: -</para></note> -<literallayout class='monospaced'> - <bsp name>-<kernel type>.scc -</literallayout> -<para> - if this naming convention isn't followed your feature description will - not be located and a build error thrown. -</para> - </section> --> - - - - <section id='bsp-creating'> - <title>Creating a BSP Based on an Existing Similar BSP</title> - - <para> - This section provides an example for creating a BSP - that is based on an existing, and hopefully, similar - one. It assumes you will be using a local kernel - repository and will be pointing the kernel recipe at - that. Follow these steps and keep in mind your - particular situation and differences: - - <orderedlist> - <listitem><para> - Identify a machine configuration file that matches your machine. - </para> - - <para> - You can start with something in <filename>meta/conf/machine</filename> - <filename> - meta/conf/machine/atom-pc.conf</filename> for example. Or, you can start with a machine - configuration from any of the BSP layers in the meta-intel repository at - <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/'></ulink>, such as - <filename>meta-intel/meta-emenlow/conf/machine/emenlow.conf</filename>. - </para> - - <para> - The main difference between the two is that "emenlow" is in its own layer. - It is in its own layer because it needs extra machine-specific packages such as its - own video driver and other supporting packages. - The "atom-pc" is simpler and does not need any special packages - everything it needs can - be specified in the configuration file. - The "atom-pc" machine also supports all of Asus eee901, Acer Aspire One, Toshiba NB305, - and the Intel® Embedded Development Board 1-N450 with no changes. - </para> - - <para> - If you want to make minor changes to support a slightly different machine, you can - create a new configuration file for it and add it alongside the others. - You might consider keeping the common information separate and including it. - </para> - - <para> - Similarly, you can also use multiple configuration files for different machines even - if you do it as a separate layer like meta-emenlow. - </para> - - <para> - As an example consider this: - <itemizedlist> - <listitem><para>Copy meta-emenlow to meta-mymachine</para></listitem> - <listitem><para>Fix or remove anything you do not need. - For this example the only thing left was the kernel directory with a - <filename>linux-yocto_git.bbappend</filename> - file - and <filename>meta-mymachine/conf/machine/mymachine.conf</filename> - (linux-yocto is the kernel listed in - <filename>meta-emenlow/conf/machine/emenlow.conf</filename>)</para></listitem>. - <listitem><para>Add a new entry in the <filename>build/conf/bblayers.conf</filename> - so the new layer can be found by BitBake.</para></listitem> - </itemizedlist> - </para></listitem> - - <listitem><para> - Create a machine branch for your machine. - </para> - - <para> - For the kernel to compile successfully, you need to create a branch in the git repository - specifically named for your machine. - To create this branch first create a bare clone of the Yocto Project git repository. - Next, create a local clone of that: - <literallayout class='monospaced'> - $ git clone --bare git://git.yoctoproject.org/linux-yocto-2.6.37.git - linux-yocto-2.6.37.git - $ git clone linux-yocto-2.6.37.git linux-yocto-2.6.37 - </literallayout> - </para> - - <para> - Now create a branch in the local clone and push it to the bare clone: - <literallayout class='monospaced'> - $ git checkout -b yocto/standard/mymachine origin/yocto/standard/base - $ git push origin yocto/standard/mymachine:yocto/standard/mymachine - </literallayout> - </para></listitem> - - <listitem><para> - In a layer, create a <filename>linux-yocto_git.bbappend</filename> - file with the following: - </para> - - <para> - <literallayout class='monospaced'> - FILESEXTRAPATHS := "${THISDIR}/${PN}" - COMPATIBLE_MACHINE_mymachine = "mymachine" - - # It is often nice to have a local clone of the kernel repository, to - # allow patches to be staged, branches created, and so forth. Modify - # KSRC to point to your local clone as appropriate. - - KSRC ?= /path/to/your/bare/clone/for/example/linux-yocto-2.6.37.git - - # KMACHINE is the branch to be built, or alternatively - # KBRANCH can be directly set. - # KBRANCH is set to KMACHINE in the main linux-yocto_git.bb - # KBRANCH ?= "${LINUX_KERNEL_TYPE}/${KMACHINE}" - - KMACHINE_mymachine = "yocto/standard/mymachine" - - SRC_URI = "git://${KSRC};nocheckout=1;branch=${KBRANCH},meta;name=machine,meta" - </literallayout> - </para> - - <para> - After doing that, select the machine in <filename>build/conf/local.conf</filename>: - <literallayout class='monospaced'> - # - MACHINE ?= "mymachine" - # - </literallayout> - </para> - - <para> - You should now be able to build and boot an image with the new kernel: - <literallayout class='monospaced'> - $ bitbake poky-image-sato-live - </literallayout> - </para></listitem> - - <listitem><para> - Modify the kernel configuration for your machine. - </para> - - <para> - Of course, that will give you a kernel with the default configuration file, which is probably - not what you want. - If you just want to set some kernel configuration options, you can do that by - putting them in a file. - For example, inserting the following into some <filename>.cfg</filename> file: - <literallayout class='monospaced'> - CONFIG_NETDEV_1000=y - CONFIG_E1000E=y - </literallayout> - </para> - - <para> - And, another <filename>.cfg</filename> file would contain: - <literallayout class='monospaced'> - CONFIG_LOG_BUF_SHIFT=18 - </literallayout> - - <para> - These config fragments could then be picked up and - applied to the kernel .config by appending them to the kernel SRC_URI: - </para> - - <literallayout class='monospaced'> - SRC_URI_append_mymachine = " file://some.cfg \ - file://other.cfg \ - " - </literallayout> - </para> - - <para> - You could also add these directly to the git repository <filename>meta</filename> - branch as well. - However, the former method is a simple starting point. - </para></listitem> - - <listitem><para> - If you're also adding patches to the kernel, you can do the same thing. - Put your patches in the SRC_URI as well (plus <filename>.cfg</filename> for their kernel - configuration options if needed). - </para> - - <para> - Practically speaking, to generate the patches, you'd go to the source in the build tree: - <literallayout class='monospaced'> - build/tmp/work/mymachine-poky-linux/linux-yocto-2.6.37+git0+d1cd5c80ee97e81e130be8c3de3965b770f320d6_0+ -0431115c9d720fee5bb105f6a7411efb4f851d26-r13/linux - </literallayout> - </para> - - <para> - Then, modify the code there, using quilt to save the changes, and recompile until - it works: - <literallayout class='monospaced'> - $ bitbake -c compile -f linux-yocto - </literallayout> - </para></listitem> - - <listitem><para> - Once you have the final patch from quilt, copy it to the - SRC_URI location. - The patch is applied the next time you do a clean build. - Of course, since you have a branch for the BSP in git, it would be better to put it there instead. - For example, in this case, commit the patch to the "yocto/standard/mymachine" branch, and during the - next build it is applied from there. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='bsp-creating-bsp-without-a-local-kernel-repo'> - <title>Creating a BSP Based on an Existing Similar BSP Without a Local Kernel Repository</title> - - <para> - If you are creating a BSP based on an existing similar BSP but you do not have - a local kernel repository, the process is very similar to the process in - the previous section (<xref linkend='bsp-creating'/>). - </para> - - <para> - Follow the exact same process as described in the previous section with - these slight modifications: - </para> - <orderedlist> - <listitem><para>Perform Step 1 as is from the previous section.</para></listitem> - <listitem><para>Perform Step 2 as is from the previous section.</para></listitem> - <listitem><para>Perform Step 3 but do not modify the - KSRC line in the bbappend file.</para></listitem> - <listitem><para>Edit the <filename>local.conf</filename> so - that it contains the following: - <literallayout class='monospaced'> - YOCTO_KERNEL_EXTERNAL_BRANCH="<your-machine>-standard - </literallayout></para> - <para>Adding this statement to the file triggers BSP bootstrapping - to occur and the correct branches and base configuration to be used. - </para></listitem> - <listitem><para>Perform Step 4 as is from the previous section.</para></listitem> - <listitem><para>Perform Step 5 as is from the previous section.</para></listitem> - </orderedlist> - </section> - - -<!-- <section id='bsp-creating-a-new-bsp'> - <title>BSP: Creating a New BSP</title> -<para> -Although it is obvious that the structure of a new BSP uses the migrated -directory structure from the previous example,the first question is whether -or not the BSP is started from scratch. -</para> -<para> -If Yocto Project has a similar BSP, it is often easier to clone and update, -rather than start from scratch. If the mainline kernel has support, it is -easier to branch from the -standard kernel and begin development (and not be -concerned with undoing existing changes). This section covers both options. -</para> -<para> -In almost every scenario, the LDAT build system bindings must be completed -before either cloning or starting a new BSP from scratch. This is simply -because the board template files are required to configure a project/build -and create the necessary environment to begin working directly with the -kernel. If it is desired to start immediately with kernel development and -then add LDAT bindings, see the "bootstrapping a BSP" section. -</para> - <section id='creating-from-scratch'> - <title>Creating the BSP from Scratch</title> -<para> -To create the BSP from scratch you need to do the following: -<orderedlist> - <listitem><para>Create a board template for the new BSP in a layer.</para></listitem> - <listitem><para>Configure a build with the board.</para></listitem> - <listitem><para>Configure a kernel.</para></listitem> -</orderedlist> -</para> -<para> -Following is an example showing all three steps. You start by creating a board template for the new BSP in a layer. -<literallayout class='monospaced'> - templates/ - `‐‐ board - `‐‐ my_bsp - |‐‐ include - |‐‐ config.sh - `‐‐ linux - |‐‐ my_bsp.cfg - `‐‐ my_bsp-standard.scc - - > cat config.sh - TARGET_BOARD="my_bsp" - TARGET_LINUX_LINKS="bzImage" - TARGET_SUPPORTED_KERNEL="standard" - TARGET_SUPPORTED_ROOTFS="glibc_std" - BANNER="This BSP is *NOT* supported" - TARGET_PROCFAM="pentium4" - TARGET_PLATFORMS="GPP" - - > cat include - cpu/x86_32_i686 - karch/i386 - - > cat linux/my_bsp-standard.scc - scc_leaf ktypes/standard/standard.scc my_bsp-standard - - > cat linux/my_bsp.cfg - CONFIG_X86=y - CONFIG_SMP=y - CONFIG_VT=y - # etc, etc, etc -</literallayout> -</para> -<para> -Something like the following can now be added to a board build, and -a project can be started: -<literallayout class='monospaced'> - ‐‐enable-board=my_bsp \ - ‐‐with-layer=custom_bsp -</literallayout> -</para> -<para> -Now you can configure a kernel: -<literallayout class='monospaced'> - > make -C build linux.config -</literallayout> -</para> -<para> -You now have a kernel tree, which is branched and has no patches, ready for -development. -</para> - </section> --> - -<!-- <section id='cloning-an-existing-bsp'> - <title>Cloning an Existing BSP</title> -<para> -Cloning an existing BSP from the shipped product is similar to the "from -scratch" option and there are two distinct ways to achieve this goal: -<itemizedlist> - <listitem><para>Create a board template for the new BSP in a layer.</para></listitem> - <listitem><para>Clone the .scc and board config.</para></listitem> -</itemizedlist> -</para> -<para> -The first method is similar to the from scratch BSP where you create a board template for the new -BSP. Although in this case, copying an existing board template from -wrll-wrlinux/templates/board would be appropriate, since we are cloning an -existing BSP. Edit the config.sh, include and other board options for the new -BSP. -</para> -<para> -The second method is to clone the .scc and board config. -To do this, in the newly created board template, create a linux subdirectory and export -the .scc and configuration from the source BSP in the published Yocto Project -kernel. During construction, all of the configuration and patches were -captured, so it is simply a matter of extracting them. -</para> -<para> -Extraction can be accomplished using four different techniques: -<itemizedlist> - <listitem><para>Config and patches from the bare default_kernel.</para></listitem> - <listitem><para>Clone default_kernel and checkout wrs_base.</para></listitem> - <listitem><para>Clone default_kernel and checkout BSP branch.</para></listitem> - <listitem><para>Branch from the Yocto Project BSP.</para></listitem> -</itemizedlist> -</para> -<para> -Technique 1: config and patches from the bare default_kernel -<literallayout class='monospaced'> - > cd layers/wrll-linux-2.6.27/git/default_kernel - > git show checkpoint_end | filterdiff -i '*common_pc*' | patch -s -p2 -d /tmp - - # This will create two directories: cfg and patches. - - > cd /tmp/cfg/kernel-cache/bsp/common_pc/ - - # This directory contains all the patches and .scc files used to construct - # the BSP in the shipped tree. Copy the patches to the new BSP template, - # and add them to the .scc file created above. See "template patching" if - # more details are required. -</literallayout> -</para> -<para> -Technique 2: clone default_kernel and checkout wrs_base -<literallayout class='monospaced'> - > git clone layers/wrll-linux-2.6.27/git/default_kernel windriver-2.6.27 - > cd windriver-2.6.27 - > git checkout wrs_base - > cd wrs/cfg/kernel-cache/bsp/common_pc - -# again, this directory has all the patches and .scc files used to construct -# the BSP -</literallayout> -</para> -<para> -Technique 3: clone default_kernel and checkout BSP branch -<literallayout class='monospaced'> - > git clone layers/wrll-linux-2.6.27/git/default_kernel windriver-2.6.27 - > cd windriver-2.6.27 - > git checkout common_pc-standard - > git whatchanged - # browse patches and determine which ones are of interest, say there are - # 3 patches of interest - > git format-patch -o <path to BSP template>/linux HEAD^^^ - # update the .scc file to add the patches, see "template patches" if - # more details are required -</literallayout> -</para> -<para> -Technique #4: branch from the Yocto Project BSP -<note><para>This is potentially the most "different" technique, but is actually - the easiest to support and leverages the infrastructure. rtcore BSPs - are created in a similar manner to this. -</para></note> -</para> -<para> -In this technique the .scc file in the board template is slightly different - and indicates that the BSP should branch after the base Yocto Project BSP - of the correct kernel type, so to start a new BSP that inherits the - kernel patches of the common_pc-standard, the following would be done: -<literallayout class='monospaced'> - > cat linux/my_bsp-standard.scc - scc_leaf bsp/common_pc/common_pc-standard.scc my_bsp-standard -</literallayout> -</para> -<para> - And only kernel configuration (not patches) need be contained in the - board template. -</para> -<para> - This has the advantage of automatically picking up updates to the BSP - and not duplicating any patches for a similar board. -</para> - </section> --> - - <!-- <section id='bsp-bootstrapping'> - <title>BSP: Bootstrapping</title> -<para> -The previous examples created the board templates and configured a build -before beginning work on a new BSP. It is also possible for advanced users to -simply treat the Yocto Project git repository as an upstream source and begin -BSP development directly on the repository. This is the closest match to how -the kernel community at large would operate. -</para> -<para> -Two techniques exist to accomplish this: -</para> -<para> -Technique 1: upstream workflow -<literallayout class='monospaced'> - > git clone layers/wrll-linux-2.6.27/git/default_kernel windriver-2.6.27 - > cd windriver-2.6.27 - > git checkout -b my_bsp-standard common_pc-standard - - # edit files, import patches, generally do BSP development - - # at this point we can create the BSP template, and export the kernel - # changes using one of the techniques discussed in that section. For - # example, It is possible to push these changes, directly into the - # default_kernel and never directly manipulate or export patch files -</literallayout> -</para> -<para> -Technique 2: Yocto Project kernel build workflow -</para> -<para> - Create the BSP branch from the appropriate kernel type -<literallayout class='monospaced'> - > cd linux - # the naming convention for auto-build is <bsp>-<kernel type> - > git checkout -b my_bsp-standard standard -</literallayout> -</para> -<para> -Make changes, import patches, etc. -<literallayout class='monospaced'> - > ../../host-cross/bin/guilt init - # 'wrs/patches/my_bsp-standard' has now been created to - # manage the branches patches - - # option 1: edit files, guilt import - > ../../host-cross/bin/guilt new extra-version.patch - > vi Makefile - > ../../host-cross/bin/guilt refresh - # add a header - > ../../host-cross/bin/guilt header -e - # describe the patch using best practices, like the example below: - - ‐‐‐>‐‐‐>‐‐‐> cut here - From: Bruce Ashfield <bruce.ashfield@windriver.com> - - Adds an extra version to the kernel - - Modify the main EXTRAVERSION to show our bsp name - - Signed-off-by: Bruce Ashfield <bruce.ashfield@windriver.com> - ‐‐‐>‐‐‐>‐‐‐> cut here - - # option 2: import patches - > git am <patch> - or - > git apply <patch> - > git add <files> - > git commit -s - - # configure the board, save relevant options - > make ARCH=<arch> menuconfig - - # save the cfg changes for reconfiguration - > mkdir wrs/cfg/<cache>/my_bsp - > vi wrs/cfg/<cache>/my_bsp/my_bsp.cfg - - # classify the patches - > ../../host-cross/bin/kgit classify create <kernel-foo-cache>/my_bsp/my_bsp - # test build - > cd .. - > make linux TARGET_BOARD=my_bsp kprofile=my_bsp use_current_branch=1 -</literallayout> -</para> -<para> - Assuming the patches have been exported to the correct location, Future - builds will now find the board, apply the patches to the base tree and make - the relevant branches and structures and the special build options are no - longer required. -</para> - </section> - </section> --> - -<!-- <section id='patching'> - <title>Patching</title> -<para> -The most common way to apply patches to the kernel is via a template. -However, for more advanced applications (such as the sharing of patches between -multiple sub-features) it is possible to patch the kernel-cache. -This section covers both scenarios. -</para> - <section id='patching-template'> - <title>Patching: Template</title> -<para> -kernel -templates follow the same rules as any LDAT template. A directory should be -created in a recognized template location, with a 'linux' subdirectory. The -'linux' directory triggers LDAT to pass the dir as a potential patch location -to the kernel build system. Any .scc files found in that directory, will be -automatically appended to the end of the BSP branch (for the configured -board). -</para> -<para> -This behavior is essentially the same since previous product -releases. The only exception is the use of ".scc", which allows kernel -configuration AND patches to be applied in a template. -</para> -<note><para> -If creating a full template is not required, a .scc file can be placed at -the top of the build, along with configuration and patches. The build -system will pickup the .scc and add it onto the patch list automatically -</para></note> -<para> -As an example, consider a simple template to update a BP: -<literallayout class='monospaced'> - > cat templates/feature/extra_version/linux/extra_version.scc - patch 0001-extraversion-add-Wind-River-identifier.patch -</literallayout> -</para> -<para> -To illustrate how the previous template patch was created, the following -steps were performed: -<literallayout class='monospaced'> - > cd <board build>/build/linux - > vi Makefile - # modify EXTRAVERSION to have a unique string - > git commit -s -m "extraversion: add Yocto Project identifier" Makefile - > git format-patch -o <path to layer>/templates/feature/extra_version/linux/ - > echo "patch 0001-extraversion-add-Wind-River-identifier.patch" > \ - <path to layer>/templates/feature/extra_version/linux/extra_version.scc -</literallayout> -</para> -<para> -This next example creates a template with a linux subdirectory, just as we - always have for previous releases. -<literallayout class='monospaced'> - > mkdir templates/features/my_feature/linux -</literallayout> -</para> -<para> - In that directory place your feature description, your - patch and configuration (if required). -<literallayout class='monospaced'> - > ls templates/features/my_feature/linux - - version.patch - my_feature.scc - my_feature.cfg -</literallayout> -</para> -<para> - The .scc file describes the patches, configuration and - where in the patch order the feature should be inserted. -<literallayout class='monospaced'> - patch version.patch - kconf non-hardware my_feature.cfg -</literallayout> -</para> -<para> - Configure your build with the new template -<literallayout class='monospaced'> - ‐‐with-template=features/my_feature -</literallayout> -</para> -<para> -Build the kernel -<literallayout class='monospaced'> - > make linux -</literallayout> -</para> - </section> - - <section id='patching-kernel-cache'> - <title>Patching: Kernel Cache</title> -<para> -As previously mentioned, this example is included for completeness, and is for more advanced -applications (such as the sharing of patches between multiple sub-features). -Most patching should be done via templates, since that interface is -guaranteed not to change and the kernel-cache interface carries no such -guarantee. -</para> -<para> -At the top of a layer, create a kernel cache. The build system will recognize -any directory of the name 'kernel-*-cache' as a kernel cache. -<literallayout class='monospaced'> - > cd <my layer> - >mkdir kernel-temp-cache -</literallayout> -</para> -<para> -Make a directory with the BSP -<literallayout class='monospaced'> - > mkdir kernel-temp-cache - > mkdir kernel-temp-cache/my_feat -</literallayout> -</para> -<para> -Create the feature files as they were in technique #1 -<literallayout class='monospaced'> - > echo "patch my_patch.path" > kernel-temp-cache/my_feat/my_feature.scc -</literallayout> -</para> -<para> -Configure the build with the feature added to the kernel type -<literallayout class='monospaced'> - ‐‐with-kernel=standard+my_feat/my_feature.scc -</literallayout> -</para> -<para> -Build the kernel -<literallayout class='monospaced'> - > make linux -</literallayout> -</para> - </section> - </section> - - <section id='bsp-updating-patches-and-configuration'> - <title>BSP: Updating Patches and Configuration</title> -<para> -As was described in the "template patching" example, it is simple -to add patches to a BSP via a template, but often, it is desirable -to experiment and test patches before committing them to a template. -You can do this by modifying the BSP source. -</para> -<para> -Start as follows: -<literallayout class='monospaced'> - > cd linux - > git checkout <bspname>-<kernel name> - - > git am <patch> -</literallayout> -</para> -<para> -Or you can do this: -<literallayout class='monospaced'> - > kgit-import -t patch <patch> - - > cd .. - > make linux -</literallayout> -</para> -<para> -For details on conflict resolution and patch application, see the -git manual, or other suitable online references. -<literallayout class='monospaced'> - > git am <mbox> - # conflict - > git apply ‐‐reject .git/rebase-apply/0001 - # resolve conflict - > git am ‐‐resolved (or git am ‐‐skip, git am ‐‐abort) - # continue until complete -</literallayout> -</para> -<para> -Here is another example: -<literallayout class='monospaced'> - # merge the patches - # 1) single patch - > git am <mbox> - > git apply <patch< - > kgit import -t patch <patch> - - # 2) multiple patches - > git am <mbox> - > kgit import -t dir <dir> - - # if kgit -t dir is used, a patch resolution cycle such - # as this can be used: - - > kgit import -t dir <dir> - # locate rejects and resolve - # options: - > wiggle ‐‐replace <path to file> <path to reject> - > guilt refresh - or - > # manual resolution - > git add <files> - > git commit -s - or - > git apply ‐‐reject .git/rebase-apply/0001 - > git add <files> - > git am ‐‐resolved - or - > # merge tool of choice - - # continue series: - - > kgit import -t dir <dir> - or - > git am ‐‐continue -</literallayout> -</para> -<para> -Once all the patches have been tested and are satisfactory, they -should be exported via the techniques described in "saving kernel -modifications." -</para> -<para> -Once the kernel has been patched and configured for a BSP, it's -configuration commonly needs to be modified. This can be done by -running [menu|x]config on the kernel tree, or working with -configuration fragments. -</para> -<para> -Using menuconfig, the operation is as follows: -<literallayout class='monospaced'> - > make linux.menuconfig - > make linux.rebuild -</literallayout> -</para> -<para> -Once complete, the changes are in linux-<bsp>-<kernel type>-build/.config. -To permanently save these changes, compare the .config before and after the -menuconfig, and place those changes in a configuration fragment in the -template of your choice. -</para> -<para> -Using configuration fragments, the operation is as follows (using the -si_is8620 as an example BSP): -<literallayout class='monospaced'> - > vi linux/wrs/cfg/kernel-cache/bsp/si_is8620/si_is8620.cfg - > make linux.reconfig - > make linux.rebuild -</literallayout> -</para> -<para> -The modified configuration fragment can simply be copied out of the -linux/wrs/.. directory and placed in the appropriate template for future -application. -</para> - </section> - - <section id='tools-guilt'> - <title>Tools: guilt</title> -<para> -Yocto Project has guilt integrated as a kernel tool; therefore users that are -familiar with quilt may wish to use this tool to pop, push and refresh -their patches. Note: guilt should only be used for local operations, once -a set of changes has been pushed or pulled, they should no longer be popped -or refresh by guilt, since popping, refreshing and re-pushing patches -changes their commit IDs and creating non-fast forward branches. -</para> -<para> -The following example illustrates how to add patches a Yocto Project -BSP branch via guilt: -<literallayout class='monospaced'> - > cd build/linux - > git checkout common_pc-standard - > guilt new extra.patch - # edit files, make changes, etc - > guilt refresh - > guilt top - extra.patch - - # export that patch to an external location - > kgit export -p top /tmp -</literallayout> -</para> -<para> -Other guilt operations of interest are: -<literallayout class='monospaced'> - > guilt push, guilt push -a - > guilt pop - > guilt applied, guilt unapplied - > guilt top - > guilt refresh - > guilt header -e - > guilt next -</literallayout> -</para> -<note><para> -Guilt only uses git commands and git plumbing to perform its operations, -anything that guilt does can also be done using git directly. It is provided -as a convenience utility, but is not required and the developer can use whatever -tools or workflow they wish. -</para></note> -<para> -The following builds from the above instructions to show how guilt can be -used to assist in getting your BSP kernel patches ready. You should follow -the above instructions up to and including 'make linux.config'. In this -example I will create a new commit (patch) from scratch and import another -fictitious patch from some external public git tree (ie, a commit with full -message, signoff etc.). Please ensure you have host-cross/bin in your path. -<literallayout class='monospaced'> - %> cd linux - %> guilt-init - %> guilt-new -m fill_me_in_please first_one.patch - %> touch somefile.txt - %> guilt-add somefile.txt - %> guilt-header -e - %> guilt-refresh - %> guilt-import path_to_some_patch/patch_filename - %> guilt-push -</literallayout> -</para> -<para> -Here are a few notes about the above: -<itemizedlist> - <listitem><para>guilt-header -e ‐‐ this will open editing of the patch header in - EDITOR. As with a git commit the first line is the short log and - should be just that short and concise message about the commit. Follow - the short log with lines of text that will be the long description but - note Do not put a blank line after the short log. As usual you will - want to follow this with a blank line and then a signoff line.</para></listitem> - - <listitem><para>The last line in the example above has 2 dots on the end. If you - don't add the 2 periods on the end guilt will think you are sending - just one patch. The wrong one!</para></listitem> - - <listitem><para>The advantage to using guilt over not using guilt is that if you have a - review comment in the first patch (first_one.patch in the case of this - example) it is very easy to use guilt to pop the other patches off - allowing you to make the necessary changes without having to use more - inventive git type strategies.</para></listitem> -</itemizedlist> -</para> - </section> - - <section id='tools-scc-file-example'> - <title>Tools: scc File Example</title> -<para> -This section provides some scc file examples: leaf node, 'normal' mode, and transforms. -</para> - <section id='leaf-node'> - <title>Leaf Node</title> -<para> -The following example is a BSP branch with no child branches - a leaf on the tree. -<literallayout class='monospaced'> - # these are optional, but allow standalone tree construction - define WRS_BOARD <name> - define WRS_KERNEL <kern type> - define WRS_ARCH <arch> - - scc_leaf ktypes/standard common_pc-standard - # ^ ^ - # +‐‐ parent + branch name - - include common_pc.scc - # ^ - # +‐‐‐ include another feature -</literallayout> -</para> - </section> - - <section id='normal-mode'> - <title>'Normal' Mode</title> -<para> -Here is an example of 'normal' mode: -<literallayout class='monospaced'> - # +‐‐‐‐ name of file to read - # v - kconf hardware common_pc.cfg - # ^ ^ - # | +‐‐ 'type: hardware or non-hardware - # | - # +‐‐‐ kernel config - - # patches - patch 0002-atl2-add-atl2-driver.patch - patch 0003-net-remove-LLTX-in-atl2-driver.patch - patch 0004-net-add-net-poll-support-for-atl2-driver.patch -</literallayout> -</para> - - </section> - - <section id='transforms'> - <title>Transforms</title> -<para> -This section shows an example of transforms: -<literallayout class='monospaced'> - # either of the next two options will trigger an 'auto' - # branch from existing ones, since they change the commit - # order and hence must construct their own branch - - # this changes the order of future includes, if the - # passed feature is detected, the first feature is - # included AFTER it - include features/rt/rt.scc after features/kgdb/kgdb - # this also changes the order of existing branches - # this prevents the named feature from ever being - # included - exclude features/dynamic_ftrace/dynamic_ftrace.scc - - # inherit the standard kernel - include ktypes/standard/standard - - - # LTT supplies this, so we don't want the sub-chunk from RT. - patch_trigger arch:all exclude ftrace-upstream-tracepoints.patch - # ...but we still want the one unique tracepoint it added. - patch tracepoint-add-for-sched_resched_task.patch - - # these will change the named patches in the series into - # <patch name>.patch.<feature name> - # where the substituted patch is in this directory - patch_trigger arch:all ctx_mod dynamic_printk.patch - patch_trigger arch:all ctx_mod 0001-Implement-futex-macros-for-ARM.patch - # unconditionally exclude a patch - patch_trigger arch:all exclude ftrace-fix-ARM-crash.patch -</literallayout> -</para> - </section> - </section> --> - - <section id='tip-dirty-string'> - <title>"-dirty" String</title> - - <para> - 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. - <literallayout class='monospaced'> - > git status - </literallayout> - </para> - - <para> - You can use the git command above 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. - </para> - - <para> - To brute force pickup and commit all such pending changes enter the following: - <literallayout class='monospaced'> - > git add . - > git commit -s -a -m "getting rid of -dirty" - </literallayout> - </para> - - <para> - Next, rebuild the kernel. - </para> - </section> - -<!-- <section id='kernel-transition-kernel-layer'> - <title>Creating a Transition Kernel Layer</title> - - <para> - You can temporarily use a different base kernel in Yocto Project by doing the following: - - <orderedlist> - <listitem><para>Create a custom kernel layer.</para></listitem> - <listitem><para>Create a git repository of the transition kernel.</para></listitem> - </orderedlist> - </para> - - <para> - Once you meet those requirements you can build multiple boards and kernels. - You pay the setup cost only once. - You can then add additional BSPs and options. - </para> - - <para> - Once you have the transition kernel layer in place you can evaluate - another kernel's functionality with the goal of easing transition to an integrated and validated - Yocto Project kernel. - </para> --> - -<!--<para> -The next few sections describe the process: -</para> --> - <!-- <section id='creating-a-custom-kernel-layer'> - <title>Creating a Custom Kernel Layer</title> -<para> -The custom kernel layer must have the following minimum -elements: -<itemizedlist> - <listitem><para>An include of the shipped Yocto Project kernel layer.</para></listitem> - <listitem><para>A kernel-cache with an override of the standard kernel type.</para></listitem> -</itemizedlist> -</para> -<para> -This allows the inheritance of the kernel build infrastructure, -while overriding the list of patches that should be applied to -the base kernel. -</para> -<para> -The kernel layer can optionally include an override to the base -Yocto Project Linux BSP to inhibit the application of BSP specific -patches. If a custom BSP is being used, this is not required. -</para> - </section> --> - - <!-- <section id='git-repo-of-the-transition-kernel'> - <title>git Repo of the Transition Kernel</title> -<para> -The kernel build system requires a base kernel repository to -seed the build process. This repository must be found in the -same layer as the build infrastructure (i.e wrll-linux-2.6.27) -in the 'git' subdir, with the name 'default_kernel' -</para> -<para>Since Yocto Project Linux ships with a default_kernel -(the validated Yocto Project kernel) in the wrll-linux-2.6.27 -kernel layer, that must be removed and replaced with the -transition kernel. -</para> -<para>If the Yocto Project install cannot be directly modified -with the new default kernel, then the path to the transition -kernel layer's 'git' subdir must be passed to the build -process via: -<programlisting> -linux_GIT_BASE=<absolute path to layer>/git -</programlisting> -</para> -<para> -If the transition kernel has not been delivered via git, -then a git repo should be created, and bare cloned into -place. Creating this repository is as simple as: -<literallayout class='monospaced'> - > tar zxvf temp_kernel.tgz - > cd temp_kernel - > git init - > git add . - > git commit -a -m "Transition kernel baseline" - - 'temp_kernel' can now be cloned into place via: - - > cd <path to git base>/git - > git clone ‐‐bare <path to temp_kernel/temp_kernel default_kernel -</literallayout> -</para> - </section> --> - - <!-- <section id='building-the-kernel'> - <title>Building the Kernel</title> -<para> -Once these prerequisites have been met, the kernel can be -built with: -<literallayout class='monospaced'> - > make linux -</literallayout> -</para> -<para> -The new base kernel will be cloned into place and have any patches -indicated in the transition kernel's cache (or templates) applied. -The kernel build will detect the non-Yocto Project base repo and -use the HEAD of the tree for the build. -</para> - </section> --> - - <!-- <section id='example'> - <title>Example</title> -<para> -This example creates a kernel layer to build the latest -kernel.org tree as the 'common_pc' BSP. -<literallayout class='monospaced'> - > cd <path to layers> - > mkdir wrll-linux-my_version - > cd wrll-linux-my_version - > echo "wrll-linux-2.6.27" > include - > mkdir -p kernel-cache/ktypes/standard - > mkdir -p kernel-cache/bsp/common_pc - > echo "v2.6.29" > kernel-cache/kver - > echo "branch common_pc-standard" > kernel-cache/bsp/common_pc/common_pc.scc - > echo "kconf hardware common_pc.cfg" >> kernel-cache/bsp/common_pc/common_pc.scc - > echo "CONFIG_FOO=y" > kernel-cache/bsp/common_pc/common_pc.cfg - > mkdir git - > cd git - > git clone ‐‐bare git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git default_kernel -</literallayout> -</para> -<para> -Configure a build to use the new layer. This means that: -<literallayout class='monospaced'> - ‐‐enable-kernel-version=my_version -</literallayout> -</para> -<para> -Should be used to override the shipped default. -</para> -<para> -To build the kernel: -<literallayout class='monospaced'> - > cd build - > make linux_GIT_BASE=<layer path>/wrll-linux-my_version/git linux -</literallayout> -</para> -<para> -If this is to build without some user intervention (passing of the -GIT_BASE), you must do the clone into the wrll-linux-2.6.27/git directory. -</para> -<note><para>Unless you define valid "hardware.kcf" and "non-hardware.kcf" some -non fatal warnings will be seen. They can be fixed by populating these -files in the kernel-cache with valid hardware and non hardware config -options. -</para></note> - </section> --> -<!-- </section> --> - </section> - - - - - -<!-- <itemizedlist> - <listitem><para>Introduction to this section.</para></listitem> - <listitem><para>Constructing a project-specific kernel tree.</para></listitem> - <listitem><para>Building the kernel.</para></listitem> - <listitem><para>Seeing what has changed.</para></listitem> - <listitem><para>Seeing what has changed in a particular branch.</para></listitem> - <listitem><para>Modifying the kernel.</para></listitem> - <listitem><para>Saving modifications.</para></listitem> - <listitem><para>Storing patches outside of the kernel source repository (bulk export).</para></listitem> - <listitem><para>Working with incremental changes.</para></listitem> - <listitem><para>Extracting commited changes from a working directory (exporting internally through - patches.</para></listitem> - <listitem><para>Pushing commited changes.</para></listitem> - <listitem><para>Exporting for external (upstream) submission.</para></listitem> - <listitem><para>Exporting for import into another Source Control Manager (SCM).</para></listitem> - <listitem><para>Working with the Yocto Project kernel in another SCM.</para> - <itemizedlist> - <listitem><para>Exporting the delivered kernel to an SCM.</para></listitem> - <listitem><para>Importing changed for the build.</para></listitem> - </itemizedlist></listitem> - <listitem><para>Migrating templates from version 2.0.</para></listitem> - <listitem><para>Creating a new Board Support Package (BSP).</para> - <itemizedlist> - <listitem><para>Creating from scratch.</para></listitem> - <listitem><para>Cloning.</para></listitem> - </itemizedlist></listitem> - <listitem><para>BSP bootstrapping.</para></listitem> - <listitem><para>Applying patches to the kernel through a template.</para></listitem> - <listitem><para>Applying patches to the kernel without using a template.</para></listitem> - <listitem><para>Updating patches and configurations for a BSP.</para></listitem> - <listitem><para>Using guilt to add and export patches.</para></listitem> - <listitem><para>Using scc.</para></listitem> - <listitem><para>Building a 'dirty' image.</para></listitem> - <listitem><para>Temporarily using a different base kernel.</para></listitem> - <listitem><para>Creating a custom kernel layer.</para></listitem> - <listitem><para>Creating the git repository of the transition kernel.</para></listitem> - </itemizedlist> --> - - -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/kernel-manual/kernel-manual.xml b/documentation/kernel-manual/kernel-manual.xml deleted file mode 100644 index 875cbe314..000000000 --- a/documentation/kernel-manual/kernel-manual.xml +++ /dev/null @@ -1,72 +0,0 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<book id='kernel-manual' lang='en' - xmlns:xi="http://www.w3.org/2003/XInclude" - xmlns="http://docbook.org/ns/docbook" - > - <bookinfo> - - <mediaobject> - <imageobject> - <imagedata fileref='figures/kernel-title.png' - format='SVG' - align='left' scalefit='1' width='100%'/> - </imageobject> - </mediaobject> - - <title></title> - - <authorgroup> - <author> - <firstname>Bruce</firstname> <surname>Ashfield</surname> - <affiliation> - <orgname>Wind River Corporation</orgname> - </affiliation> - <email>bruce.ashfield@windriver.com</email> - </author> - </authorgroup> - - <revhistory> - <revision> - <revnumber>0.9</revnumber> - <date>24 November 2010</date> - <revremark>This revision is the initial document draft and corresponds with - the Yocto Project 0.9 Release.</revremark> - </revision> - <revision> - <revnumber>1.0</revnumber> - <date>6 April 2011</date> - <revremark>This revision corresponds with the Yocto Project 1.0 Release.</revremark> - </revision> - </revhistory> - - <copyright> - <year>2010-2011</year> - <holder>Linux Foundation</holder> - </copyright> - - <legalnotice> - <para> - Permission is granted to copy, distribute and/or modify this document under - the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. - </para> - </legalnotice> - - </bookinfo> - - <xi:include href="kernel-doc-intro.xml"/> - - <xi:include href="kernel-concepts.xml"/> - - <xi:include href="kernel-how-to.xml"/> - -<!-- <index id='index'> - <title>Index</title> - </index> ---> - -</book> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/kernel-manual/style.css b/documentation/kernel-manual/style.css deleted file mode 100644 index 33a01d125..000000000 --- a/documentation/kernel-manual/style.css +++ /dev/null @@ -1,968 +0,0 @@ -/* - 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; -} - -.reviewer { - color: red; -} - -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: 80%; - 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: #aaa; -} - - -.tip table th, -.warning table th, -.caution table th, -.note table th { - border-bottom-color: #aaa; -} - - -.warning { - background-color: #fea; -} - -.caution { - background-color: #fea; -} - -.tip { - background-color: #eff; -} - -.note { - background-color: #dfc; -} - -.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: #666666; - color: #fff; - padding: 20px; - margin: 20px; -} - -.tip h3, -.note h3 { - padding: 0em; - margin: 0em; - font-size: 2em; - font-weight: bold; - color: #fff; -} - -.tip a, -.note a { - color: #fff; - text-decoration: underline; -} diff --git a/documentation/kernel-manual/yocto-project-kernel-manual-customization.xsl b/documentation/kernel-manual/yocto-project-kernel-manual-customization.xsl deleted file mode 100644 index 8eb69050b..000000000 --- a/documentation/kernel-manual/yocto-project-kernel-manual-customization.xsl +++ /dev/null @@ -1,8 +0,0 @@ -<?xml version='1.0'?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - - <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> - -<!-- <xsl:param name="generate.toc" select="'article nop'"></xsl:param> --> - -</xsl:stylesheet> |
