diff options
Diffstat (limited to 'yocto-poky/documentation/kernel-dev')
13 files changed, 4961 insertions, 0 deletions
diff --git a/yocto-poky/documentation/kernel-dev/figures/kernel-architecture-overview.png b/yocto-poky/documentation/kernel-dev/figures/kernel-architecture-overview.png Binary files differnew file mode 100755 index 000000000..2aad172db --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/figures/kernel-architecture-overview.png diff --git a/yocto-poky/documentation/kernel-dev/figures/kernel-dev-title.png b/yocto-poky/documentation/kernel-dev/figures/kernel-dev-title.png Binary files differnew file mode 100644 index 000000000..7a8dd5437 --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/figures/kernel-dev-title.png diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml new file mode 100644 index 000000000..4fdb853f9 --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml @@ -0,0 +1,1088 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='kernel-dev-advanced'> +<title>Working with Advanced Metadata</title> + +<section id='kernel-dev-advanced-overview'> + <title>Overview</title> + + <para> + In addition to supporting configuration fragments and patches, the + Yocto Project kernel tools also support rich + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> that you can + use to define complex policies and Board Support Package (BSP) support. + The purpose of the Metadata and the tools that manage it, known as + the kern-tools (<filename>kern-tools-native_git.bb</filename>), is + to help you manage the complexity of the configuration and sources + used to support multiple BSPs and Linux kernel types. + </para> +</section> + +<section id='using-kernel-metadata-in-a-recipe'> + <title>Using Kernel Metadata in a Recipe</title> + + <para> + The kernel sources in the Yocto Project contain kernel Metadata, which + is located in the <filename>meta</filename> branches of the kernel + source Git repositories. + This Metadata defines Board Support Packages (BSPs) that + correspond to definitions in linux-yocto recipes for the same BSPs. + A BSP consists of an aggregation of kernel policy and hardware-specific + feature enablements. + The BSP can be influenced from within the linux-yocto recipe. + <note> + Linux kernel source that contains kernel Metadata is said to be + "linux-yocto style" kernel source. + A Linux kernel recipe that inherits from the + <filename>linux-yocto.inc</filename> include file is said to be a + "linux-yocto style" recipe. + </note> + </para> + + <para> + Every linux-yocto style recipe must define the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> + variable. + This variable is typically set to the same value as the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable, which is used by + <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>. + However, in some cases, the variable might instead refer to the + underlying platform of the <filename>MACHINE</filename>. + </para> + + <para> + Multiple BSPs can reuse the same <filename>KMACHINE</filename> + name if they are built using the same BSP description. + The "ep108-zynqmp" and "qemuzynqmp" BSP combination + in the <filename>meta-xilinx</filename> + layer is a good example of two BSPs using the same + <filename>KMACHINE</filename> value (i.e. "zynqmp"). + See the <link linkend='bsp-descriptions'>BSP Descriptions</link> section + for more information. + </para> + + <para> + Every linux-yocto style recipe must also indicate the Linux kernel + source repository branch used to build the Linux kernel. + The <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> + variable must be set to indicate the branch. + <note> + You can use the <filename>KBRANCH</filename> value to define an + alternate branch typically with a machine override as shown here + from the <filename>meta-emenlow</filename> layer: + <literallayout class='monospaced'> + KBRANCH_emenlow-noemgd = "standard/base" + </literallayout> + </note> + </para> + + <para> + The linux-yocto style recipes can optionally define the following + variables: + <literallayout class='monospaced'> + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink> + </literallayout> + </para> + + <para> + <filename>LINUX_KERNEL_TYPE</filename> defines the kernel type to be + used in assembling the configuration. + If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>, + it defaults to "standard". + Together with + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, + <filename>LINUX_KERNEL_TYPE</filename> defines the search + arguments used by the kernel tools to find the + appropriate description within the kernel Metadata with which to + build out the sources and configuration. + The linux-yocto recipes define "standard", "tiny", and "preempt-rt" + kernel types. + See the "<link linkend='kernel-types'>Kernel Types</link>" section + for more information on kernel types. + </para> + + <para> + During the build, the kern-tools search for the BSP description + file that most closely matches the <filename>KMACHINE</filename> + and <filename>LINUX_KERNEL_TYPE</filename> variables passed in from the + recipe. + The tools use the first BSP description it finds that match + both variables. + If the tools cannot find a match, they issue a warning such as + the following: + <literallayout class='monospaced'> + WARNING: Can't find any BSP hardware or required configuration fragments. + WARNING: Looked at meta/cfg/broken/emenlow-broken/hdw_frags.txt and + meta/cfg/broken/emenlow-broken/required_frags.txt in directory: + meta/cfg/broken/emenlow-broken + </literallayout> + In this example, <filename>KMACHINE</filename> was set to "emenlow-broken" + and <filename>LINUX_KERNEL_TYPE</filename> was set to "broken". + </para> + + <para> + The tools first search for the <filename>KMACHINE</filename> and + then for the <filename>LINUX_KERNEL_TYPE</filename>. + If the tools cannot find a partial match, they will use the + sources from the <filename>KBRANCH</filename> and any configuration + specified in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. + </para> + + <para> + You can use the <filename>KERNEL_FEATURES</filename> variable + to include features (configuration fragments, patches, or both) that + are not already included by the <filename>KMACHINE</filename> and + <filename>LINUX_KERNEL_TYPE</filename> variable combination. + For example, to include a feature specified as + "features/netfilter/netfilter.scc", + specify: + <literallayout class='monospaced'> + KERNEL_FEATURES += "features/netfilter/netfilter.scc" + </literallayout> + To include a feature called "cfg/sound.scc" just for the + <filename>qemux86</filename> machine, specify: + <literallayout class='monospaced'> + KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" + </literallayout> + The value of the entries in <filename>KERNEL_FEATURES</filename> + are dependent on their location within the kernel Metadata itself. + The examples here are taken from the <filename>meta</filename> + branch of the <filename>linux-yocto-3.19</filename> repository. + Within that branch, "features" and "cfg" are subdirectories of the + <filename>meta/cfg/kernel-cache</filename> directory. + For more information, see the + "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section. + <note> + The processing of the these variables has evolved some between the + 0.9 and 1.3 releases of the Yocto Project and associated + kern-tools sources. + The descriptions in this section are accurate for 1.3 and later + releases of the Yocto Project. + </note> + </para> +</section> + +<section id='kernel-metadata-location'> + <title>Kernel Metadata Location</title> + + <para> + Kernel Metadata can be defined in either the kernel recipe + (recipe-space) or in the kernel tree (in-tree). + Where you choose to define the Metadata depends on what you want + to do and how you intend to work. + Regardless of where you define the kernel Metadata, the syntax used + applies equally. + </para> + + <para> + If you are unfamiliar with the Linux kernel and only wish + to apply a configuration and possibly a couple of patches provided to + you by others, the recipe-space method is recommended. + This method is also a good approach if you are working with Linux kernel + sources you do not control or if you just do not want to maintain a + Linux kernel Git repository on your own. + For partial information on how you can define kernel Metadata in + the recipe-space, see the + "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>" + section. + </para> + + <para> + Conversely, if you are actively developing a kernel and are already + maintaining a Linux kernel Git repository of your own, you might find + it more convenient to work with the kernel Metadata in the same + repository as the Linux kernel sources. + This method can make iterative development of the Linux kernel + more efficient outside of the BitBake environment. + </para> + + <section id='recipe-space-metadata'> + <title>Recipe-Space Metadata</title> + + <para> + When stored in recipe-space, the kernel Metadata files reside in a + directory hierarchy below + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>. + For a linux-yocto recipe or for a Linux kernel recipe derived + by copying and modifying + <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename> + to a recipe in your layer, <filename>FILESEXTRAPATHS</filename> + is typically set to + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>. + See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>" + section for more information. + </para> + + <para> + Here is an example that shows a trivial tree of kernel Metadata + stored in recipe-space within a BSP layer: + <literallayout class='monospaced'> + meta-<replaceable>my_bsp_layer</replaceable>/ + `-- recipes-kernel + `-- linux + `-- linux-yocto + |-- bsp-standard.scc + |-- bsp.cfg + `-- standard.cfg + </literallayout> + </para> + + <para> + When the Metadata is stored in recipe-space, you must take + steps to ensure BitBake has the necessary information to decide + what files to fetch and when they need to be fetched again. + It is only necessary to specify the <filename>.scc</filename> + files on the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. + BitBake parses them and fetches any files referenced in the + <filename>.scc</filename> files by the <filename>include</filename>, + <filename>patch</filename>, or <filename>kconf</filename> commands. + Because of this, it is necessary to bump the recipe + <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> + value when changing the content of files not explicitly listed + in the <filename>SRC_URI</filename>. + </para> + </section> + + <section id='in-tree-metadata'> + <title>In-Tree Metadata</title> + + <para> + When stored in-tree, the kernel Metadata files reside in the + <filename>meta</filename> directory of the Linux kernel sources. + The <filename>meta</filename> directory can be present in the + same repository branch as the sources, + such as "master", or <filename>meta</filename> can be its own + orphan branch. + <note> + An orphan branch in Git is a branch with unique history and + content to the other branches in the repository. + Orphan branches are useful to track Metadata changes + independently from the sources of the Linux kernel, while + still keeping them together in the same repository. + </note> + For the purposes of this document, we will discuss all + in-tree Metadata as residing below the + <filename>meta/cfg/kernel-cache</filename> directory. + </para> + + <para> + Following is an example that shows how a trivial tree of Metadata + is stored in a custom Linux kernel Git repository: + <literallayout class='monospaced'> + meta/ + `-- cfg + `-- kernel-cache + |-- bsp-standard.scc + |-- bsp.cfg + `-- standard.cfg + </literallayout> + </para> + + <para> + To use a branch different from where the sources reside, + specify the branch in the <filename>KMETA</filename> variable + in your Linux kernel recipe. + Here is an example: + <literallayout class='monospaced'> + KMETA = "meta" + </literallayout> + To use the same branch as the sources, set + <filename>KMETA</filename> to an empty string: + <literallayout class='monospaced'> + KMETA = "" + </literallayout> + If you are working with your own sources and want to create an + orphan <filename>meta</filename> branch, use these commands + from within your Linux kernel Git repository: + <literallayout class='monospaced'> + $ git checkout --orphan meta + $ git rm -rf . + $ git commit --allow-empty -m "Create orphan meta branch" + </literallayout> + </para> + + <para> + If you modify the Metadata in the linux-yocto + <filename>meta</filename> branch, you must not forget to update + the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> + statements in the kernel's recipe. + In particular, you need to update the + <filename>SRCREV_meta</filename> variable to match the commit in + the <filename>KMETA</filename> branch you wish to use. + Changing the data in these branches and not updating the + <filename>SRCREV</filename> statements to match will cause the + build to fetch an older commit. + </para> + </section> +</section> + +<section id='kernel-metadata-syntax'> + <title>Kernel Metadata Syntax</title> + + <para> + The kernel Metadata consists of three primary types of files: + <filename>scc</filename> + <footnote> + <para> + <filename>scc</filename> stands for Series Configuration + Control, but the naming has less significance in the + current implementation of the tooling than it had in the + past. + Consider <filename>scc</filename> files to be description files. + </para> + </footnote> + description files, configuration fragments, and patches. + The <filename>scc</filename> files define variables and include or + otherwise reference any of the three file types. + The description files are used to aggregate all types of kernel + Metadata into + what ultimately describes the sources and the configuration required + to build a Linux kernel tailored to a specific machine. + </para> + + <para> + The <filename>scc</filename> description files are used to define two + fundamental types of kernel Metadata: + <itemizedlist> + <listitem><para>Features</para></listitem> + <listitem><para>Board Support Packages (BSPs)</para></listitem> + </itemizedlist> + </para> + + <para> + Features aggregate sources in the form of patches and configuration + fragments into a modular reusable unit. + You can use features to implement conceptually separate kernel + Metadata descriptions such as pure configuration fragments, + simple patches, complex features, and kernel types. + <link linkend='kernel-types'>Kernel types</link> define general + kernel features and policy to be reused in the BSPs. + </para> + + <para> + BSPs define hardware-specific features and aggregate them with kernel + types to form the final description of what will be assembled and built. + </para> + + <para> + While the kernel Metadata syntax does not enforce any logical + separation of configuration fragments, patches, features or kernel + types, best practices dictate a logical separation of these types + of Metadata. + The following Metadata file hierarchy is recommended: + <literallayout class='monospaced'> + <replaceable>base</replaceable>/ + bsp/ + cfg/ + features/ + ktypes/ + patches/ + </literallayout> + </para> + + <para> + The <filename>bsp</filename> directory contains the + <link linkend='bsp-descriptions'>BSP descriptions</link>. + The remaining directories all contain "features". + Separating <filename>bsp</filename> from the rest of the structure + aids conceptualizing intended usage. + </para> + + <para> + Use these guidelines to help place your <filename>scc</filename> + description files within the structure: + <itemizedlist> + <listitem><para>If your file contains + only configuration fragments, place the file in the + <filename>cfg</filename> directory.</para></listitem> + <listitem><para>If your file contains + only source-code fixes, place the file in the + <filename>patches</filename> directory.</para></listitem> + <listitem><para>If your file encapsulates + a major feature, often combining sources and configurations, + place the file in <filename>features</filename> directory. + </para></listitem> + <listitem><para>If your file aggregates + non-hardware configuration and patches in order to define a + base kernel policy or major kernel type to be reused across + multiple BSPs, place the file in <filename>ktypes</filename> + directory. + </para></listitem> + </itemizedlist> + </para> + + <para> + These distinctions can easily become blurred - especially as + out-of-tree features slowly merge upstream over time. + Also, remember that how the description files are placed is + a purely logical organization and has no impact on the functionality + of the kernel Metadata. + There is no impact because all of <filename>cfg</filename>, + <filename>features</filename>, <filename>patches</filename>, and + <filename>ktypes</filename>, contain "features" as far as the kernel + tools are concerned. + </para> + + <para> + Paths used in kernel Metadata files are relative to + <filename><base></filename>, which is either + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + if you are creating Metadata in + <link linkend='recipe-space-metadata'>recipe-space</link>, + or <filename>meta/cfg/kernel-cache/</filename> if you are creating + Metadata <link linkend='in-tree-metadata'>in-tree</link>. + </para> + + <section id='configuration'> + <title>Configuration</title> + + <para> + The simplest unit of kernel Metadata is the configuration-only + feature. + This feature consists of one or more Linux kernel configuration + parameters in a configuration fragment file + (<filename>.cfg</filename>) and a <filename>.scc</filename> file + that describes the fragment. + </para> + + <para> + The Symmetric Multi-Processing (SMP) fragment included in the + <filename>linux-yocto-3.19</filename> Git repository + consists of the following two files: + <literallayout class='monospaced'> + cfg/smp.scc: + define KFEATURE_DESCRIPTION "Enable SMP" + define KFEATURE_COMPATIBILITY all + + kconf hardware smp.cfg + + cfg/smp.cfg: + CONFIG_SMP=y + CONFIG_SCHED_SMT=y + # Increase default NR_CPUS from 8 to 64 so that platform with + # more than 8 processors can be all activated at boot time + CONFIG_NR_CPUS=64 + </literallayout> + You can find information on configuration fragment files in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>" + section of the Yocto Project Development Manual and in + the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" + section earlier in this manual. + </para> + + <para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink> + provides a short description of the fragment. + Higher level kernel tools use this description. + </para> + + <para> + The <filename>kconf</filename> command is used to include the + actual configuration fragment in an <filename>.scc</filename> + file, and the "hardware" keyword identifies the fragment as + being hardware enabling, as opposed to general policy, + which would use the "non-hardware" keyword. + The distinction is made for the benefit of the configuration + validation tools, which warn you if a hardware fragment + overrides a policy set by a non-hardware fragment. + <note> + The description file can include multiple + <filename>kconf</filename> statements, one per fragment. + </note> + </para> + + <para> + As described in the + "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" + section, you can use the following BitBake command to audit your + configuration: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c kernel_configcheck -f + </literallayout> + </para> + </section> + + <section id='patches'> + <title>Patches</title> + + <para> + Patch descriptions are very similar to configuration fragment + descriptions, which are described in the previous section. + However, instead of a <filename>.cfg</filename> file, these + descriptions work with source patches. + </para> + + <para> + A typical patch includes a description file and the patch itself: + <literallayout class='monospaced'> + patches/mypatch.scc: + patch mypatch.patch + + patches/mypatch.patch: + <replaceable>typical-patch</replaceable> + </literallayout> + You can create the typical <filename>.patch</filename> + file using <filename>diff -Nurp</filename> or + <filename>git format-patch</filename>. + </para> + + <para> + The description file can include multiple patch statements, + one per patch. + </para> + </section> + + <section id='features'> + <title>Features</title> + + <para> + Features are complex kernel Metadata types that consist + of configuration fragments (<filename>kconf</filename>), patches + (<filename>patch</filename>), and possibly other feature + description files (<filename>include</filename>). + </para> + + <para> + Here is an example that shows a feature description file: + <literallayout class='monospaced'> + features/myfeature.scc + define KFEATURE_DESCRIPTION "Enable myfeature" + + patch 0001-myfeature-core.patch + patch 0002-myfeature-interface.patch + + include cfg/myfeature_dependency.scc + kconf non-hardware myfeature.cfg + </literallayout> + This example shows how the <filename>patch</filename> and + <filename>kconf</filename> commands are used as well as + how an additional feature description file is included. + </para> + + <para> + Typically, features are less granular than configuration + fragments and are more likely than configuration fragments + and patches to be the types of things you want to specify + in the <filename>KERNEL_FEATURES</filename> variable of the + Linux kernel recipe. + See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>" + section earlier in the manual. + </para> + </section> + + <section id='kernel-types'> + <title>Kernel Types</title> + + <para> + A kernel type defines a high-level kernel policy by + aggregating non-hardware configuration fragments with + patches you want to use when building a Linux kernels of a + specific type. + Syntactically, kernel types are no different than features + as described in the "<link linkend='features'>Features</link>" + section. + The <filename>LINUX_KERNEL_TYPE</filename> variable in the kernel + recipe selects the kernel type. + See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>" + section for more information. + </para> + + <para> + As an example, the <filename>linux-yocto-3.19</filename> + tree defines three kernel types: "standard", + "tiny", and "preempt-rt": + <itemizedlist> + <listitem><para>"standard": + Includes the generic Linux kernel policy of the Yocto + Project linux-yocto kernel recipes. + This policy includes, among other things, which file + systems, networking options, core kernel features, and + debugging and tracing options are supported. + </para></listitem> + <listitem><para>"preempt-rt": + Applies the <filename>PREEMPT_RT</filename> + patches and the configuration options required to + build a real-time Linux kernel. + This kernel type inherits from the "standard" kernel type. + </para></listitem> + <listitem><para>"tiny": + Defines a bare minimum configuration meant to serve as a + base for very small Linux kernels. + The "tiny" kernel type is independent from the "standard" + configuration. + Although the "tiny" kernel type does not currently include + any source changes, it might in the future. + </para></listitem> + </itemizedlist> + </para> + + <para> + The "standard" kernel type is defined by + <filename>standard.scc</filename>: + <literallayout class='monospaced'> + # Include this kernel type fragment to get the standard features and + # configuration values. + + # Include all standard features + include standard-nocfg.scc + + kconf non-hardware standard.cfg + + # individual cfg block section + include cfg/fs/devtmpfs.scc + include cfg/fs/debugfs.scc + include cfg/fs/btrfs.scc + include cfg/fs/ext2.scc + include cfg/fs/ext3.scc + include cfg/fs/ext4.scc + + include cfg/net/ipv6.scc + include cfg/net/ip_nf.scc + include cfg/net/ip6_nf.scc + include cfg/net/bridge.scc + </literallayout> + </para> + + <para> + As with any <filename>.scc</filename> file, a + kernel type definition can aggregate other + <filename>.scc</filename> files with + <filename>include</filename> commands. + These definitions can also directly pull in + configuration fragments and patches with the + <filename>kconf</filename> and <filename>patch</filename> + commands, respectively. + </para> + + <note> + It is not strictly necessary to create a kernel type + <filename>.scc</filename> file. + The Board Support Package (BSP) file can implicitly define + the kernel type using a <filename>define + <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'>KTYPE</ulink> myktype</filename> + line. + See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>" + section for more information. + </note> + </section> + + <section id='bsp-descriptions'> + <title>BSP Descriptions</title> + + <para> + BSP descriptions combine kernel types with hardware-specific + features. + The hardware-specific portion is typically defined + independently, and then aggregated with each supported kernel + type. + Consider this simple BSP description that supports the + <replaceable>mybsp</replaceable> machine: + <literallayout class='monospaced'> + <replaceable>mybsp</replaceable>.scc: + define KMACHINE <replaceable>mybsp</replaceable> + define KTYPE standard + define KARCH i386 + + kconf <replaceable>mybsp</replaceable>.cfg + </literallayout> + Every BSP description should define the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>, + and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink> + variables. + These variables allow the OpenEmbedded build system to identify + the description as meeting the criteria set by the recipe being + built. + This simple example supports the "mybsp" machine for the "standard" + kernel and the "i386" architecture. + </para> + + <para> + Be aware that a hard link between the + <filename>KTYPE</filename> variable and a kernel type + description file does not exist. + Thus, if you do not have kernel types defined in your kernel + Metadata, you only need to ensure that the kernel recipe's + <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> + variable and the <filename>KTYPE</filename> variable in the + BSP description file match. + <note> + Future versions of the tooling make the specification of + <filename>KTYPE</filename> in the BSP optional. + </note> + </para> + + <para> + If you did want to separate your kernel policy from your + hardware configuration, you could do so by specifying a kernel + type, such as "standard" and including that description file + in the BSP description file. + See the "<link linkend='kernel-types'>Kernel Types</link>" section + for more information. + </para> + + <para> + You might also have multiple hardware configurations that you + aggregate into a single hardware description file that you + could include in the BSP description file, rather than referencing + a single <filename>.cfg</filename> file. + Consider the following: + <literallayout class='monospaced'> + <replaceable>mybsp</replaceable>.scc: + define KMACHINE mybsp + define KTYPE standard + define KARCH i386 + + include standard.scc + include <replaceable>mybsp</replaceable>-hw.scc + </literallayout> + </para> + + <para> + In the above example, <filename>standard.scc</filename> + aggregates all the configuration fragments, patches, and + features that make up your standard kernel policy whereas + <replaceable>mybsp</replaceable><filename>-hw.scc</filename> + aggregates all those necessary + to support the hardware available on the + <replaceable>mybsp</replaceable> machine. + For information on how to break a complete + <filename>.config</filename> file into the various + configuration fragments, see the + "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" + section. + </para> + + <para> + Many real-world examples are more complex. + Like any other <filename>.scc</filename> file, BSP + descriptions can aggregate features. + Consider the Minnow BSP definition from the + <filename>linux-yocto-3.19</filename> + Git repository: + <literallayout class='monospaced'> + minnow.scc: + include cfg/x86.scc + include features/eg20t/eg20t.scc + include cfg/dmaengine.scc + include features/power/intel.scc + include cfg/efi.scc + include features/usb/ehci-hcd.scc + include features/usb/ohci-hcd.scc + include features/usb/usb-gadgets.scc + include features/usb/touchscreen-composite.scc + include cfg/timer/hpet.scc + include cfg/timer/rtc.scc + include features/leds/leds.scc + include features/spi/spidev.scc + include features/i2c/i2cdev.scc + + # Earlyprintk and port debug requires 8250 + kconf hardware cfg/8250.cfg + + kconf hardware minnow.cfg + kconf hardware minnow-dev.cfg + </literallayout> + </para> + + <para> + The <filename>minnow.scc</filename> description file includes + a hardware configuration fragment + (<filename>minnow.cfg</filename>) specific to the Minnow + BSP as well as several more general configuration + fragments and features enabling hardware found on the + machine. + This description file is then included in each of the three + "minnow" description files for the supported kernel types + (i.e. "standard", "preempt-rt", and "tiny"). + Consider the "minnow" description for the "standard" kernel + type: + <literallayout class='monospaced'> + minnow-standard.scc: + define KMACHINE minnow + define KTYPE standard + define KARCH i386 + + include ktypes/standard + + include minnow.scc + + # Extra minnow configs above the minimal defined in minnow.scc + include cfg/efi-ext.scc + include features/media/media-all.scc + include features/sound/snd_hda_intel.scc + + # The following should really be in standard.scc + # USB live-image support + include cfg/usb-mass-storage.scc + include cfg/boot-live.scc + + # Basic profiling + include features/latencytop/latencytop.scc + include features/profiling/profiling.scc + + # Requested drivers that don't have an existing scc + kconf hardware minnow-drivers-extra.cfg + </literallayout> + The <filename>include</filename> command midway through the file + includes the <filename>minnow.scc</filename> description that + defines all hardware enablements for the BSP that is common to all + kernel types. + Using this command significantly reduces duplication. + </para> + + <para> + Now consider the "minnow" description for the "tiny" kernel type: + <literallayout class='monospaced'> + minnow-tiny.scc: + define KMACHINE minnow + define KTYPE tiny + define KARCH i386 + + include ktypes/tiny + + include minnow.scc + </literallayout> + As you might expect, the "tiny" description includes quite a + bit less. + In fact, it includes only the minimal policy defined by the + "tiny" kernel type and the hardware-specific configuration required + for booting the machine along with the most basic functionality of + the system as defined in the base "minnow" description file. + </para> + + <para> + Notice again the three critical variables: + <filename>KMACHINE</filename>, <filename>KTYPE</filename>, + and <filename>KARCH</filename>. + Of these variables, only the <filename>KTYPE</filename> has changed. + It is now set to "tiny". + </para> + </section> +</section> + +<section id='organizing-your-source'> + <title>Organizing Your Source</title> + + <para> + Many recipes based on the <filename>linux-yocto-custom.bb</filename> + recipe use Linux kernel sources that have only a single + branch - "master". + This type of repository structure is fine for linear development + supporting a single machine and architecture. + However, if you work with multiple boards and architectures, + a kernel source repository with multiple branches is more + efficient. + For example, suppose you need a series of patches for one board to boot. + Sometimes, these patches are works-in-progress or fundamentally wrong, + yet they are still necessary for specific boards. + In these situations, you most likely do not want to include these + patches in every kernel you build (i.e. have the patches as part of + the lone "master" branch). + It is situations like these that give rise to multiple branches used + within a Linux kernel sources Git repository. + </para> + + <para> + Repository organization strategies exist that maximize source reuse, + remove redundancy, and logically order your changes. + This section presents strategies for the following cases: + <itemizedlist> + <listitem><para>Encapsulating patches in a feature description + and only including the patches in the BSP descriptions of + the applicable boards.</para></listitem> + <listitem><para>Creating a machine branch in your + kernel source repository and applying the patches on that + branch only.</para></listitem> + <listitem><para>Creating a feature branch in your + kernel source repository and merging that branch into your + BSP when needed.</para></listitem> + </itemizedlist> + </para> + + <para> + The approach you take is entirely up to you + and depends on what works best for your development model. + </para> + + <section id='encapsulating-patches'> + <title>Encapsulating Patches</title> + + <para> + if you are reusing patches from an external tree and are not + working on the patches, you might find the encapsulated feature + to be appropriate. + Given this scenario, you do not need to create any branches in the + source repository. + Rather, you just take the static patches you need and encapsulate + them within a feature description. + Once you have the feature description, you simply include that into + the BSP description as described in the + "<link linkend='bsp-descriptions'>BSP Descriptions</link>" + section. + </para> + + <para> + You can find information on how to create patches and BSP + descriptions in the "<link linkend='patches'>Patches</link>" and + "<link linkend='bsp-descriptions'>BSP Descriptions</link>" + sections. + </para> + </section> + + <section id='machine-branches'> + <title>Machine Branches</title> + + <para> + When you have multiple machines and architectures to support, + or you are actively working on board support, it is more + efficient to create branches in the repository based on + individual machines. + Having machine branches allows common source to remain in the + "master" branch with any features specific to a machine stored + in the appropriate machine branch. + This organization method frees you from continually reintegrating + your patches into a feature. + </para> + + <para> + Once you have a new branch, you can set up your kernel Metadata + to use the branch a couple different ways. + In the recipe, you can specify the new branch as the + <filename>KBRANCH</filename> to use for the board as + follows: + <literallayout class='monospaced'> + KBRANCH = "mynewbranch" + </literallayout> + Another method is to use the <filename>branch</filename> command + in the BSP description: + <literallayout class='monospaced'> + mybsp.scc: + define KMACHINE mybsp + define KTYPE standard + define KARCH i386 + include standard.scc + + branch mynewbranch + + include mybsp-hw.scc + </literallayout> + </para> + + <para> + If you find + yourself with numerous branches, you might consider using a + hierarchical branching system similar to what the linux-yocto Linux + kernel repositories use: + <literallayout class='monospaced'> + <replaceable>common</replaceable>/<replaceable>kernel_type</replaceable>/<replaceable>machine</replaceable> + </literallayout> + </para> + + <para> + If you had two kernel types, "standard" and "small" for + instance, three machines, and <replaceable>common</replaceable> + as <filename>mydir</filename>, the branches in your + Git repository might look like this: + <literallayout class='monospaced'> + mydir/base + mydir/standard/base + mydir/standard/machine_a + mydir/standard/machine_b + mydir/standard/machine_c + mydir/small/base + mydir/small/machine_a + </literallayout> + </para> + + <para> + This organization can help clarify the branch relationships. + In this case, <filename>mydir/standard/machine_a</filename> + includes everything in <filename>mydir/base</filename> and + <filename>mydir/standard/base</filename>. + The "standard" and "small" branches add sources specific to those + kernel types that for whatever reason are not appropriate for the + other branches. + <note>The "base" branches are an artifact of the way Git manages + its data internally on the filesystem: Git will not allow you + to use <filename>mydir/standard</filename> and + <filename>mydir/standard/machine_a</filename> because it + would have to create a file and a directory named "standard". + </note> + </para> + </section> + + <section id='feature-branches'> + <title>Feature Branches</title> + + <para> + When you are actively developing new features, it can be more + efficient to work with that feature as a branch, rather than + as a set of patches that have to be regularly updated. + The Yocto Project Linux kernel tools provide for this with + the <filename>git merge</filename> command. + </para> + + <para> + To merge a feature branch into a BSP, insert the + <filename>git merge</filename> command after any + <filename>branch</filename> commands: + <literallayout class='monospaced'> + mybsp.scc: + define KMACHINE mybsp + define KTYPE standard + define KARCH i386 + include standard.scc + + branch mynewbranch + git merge myfeature + + include mybsp-hw.scc + </literallayout> + </para> + </section> +</section> + +<section id='scc-reference'> + <title>SCC Description File Reference</title> + + <para> + This section provides a brief reference for the commands you can use + within an SCC description file (<filename>.scc</filename>): + <itemizedlist> + <listitem><para><filename>branch [ref]</filename>: + Creates a new branch relative to the current branch + (typically <filename>${KTYPE}</filename>) using + the currently checked-out branch, or "ref" if specified. + </para></listitem> + <listitem><para><filename>define</filename>: + Defines variables, such as <filename>KMACHINE</filename>, + <filename>KTYPE</filename>, <filename>KARCH</filename>, + and <filename>KFEATURE_DESCRIPTION</filename>.</para></listitem> + <listitem><para><filename>include SCC_FILE</filename>: + Includes an SCC file in the current file. + The file is parsed as if you had inserted it inline. + </para></listitem> + <listitem><para><filename>kconf [hardware|non-hardware] CFG_FILE</filename>: + Queues a configuration fragment for merging into the final + Linux <filename>.config</filename> file.</para></listitem> + <listitem><para><filename>git merge GIT_BRANCH</filename>: + Merges the feature branch into the current branch. + </para></listitem> + <listitem><para><filename>patch PATCH_FILE</filename>: + Applies the patch to the current Git branch.</para></listitem> + </itemizedlist> + </para> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml new file mode 100644 index 000000000..27c82ceb5 --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml @@ -0,0 +1,1033 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='kernel-dev-common'> + +<title>Common Tasks</title> + +<para> + This chapter presents several common tasks you perform when you + work with the Yocto Project Linux kernel. + These tasks include preparing a layer, modifying an existing recipe, + iterative development, working with your own sources, and incorporating + out-of-tree modules. + <note> + The examples presented in this chapter work with the Yocto Project + 1.2.2 Release and forward. + </note> +</para> + + <section id='creating-and-preparing-a-layer'> + <title>Creating and Preparing a Layer</title> + + <para> + If you are going to be modifying kernel recipes, it is recommended + that you create and prepare your own layer in which to do your + work. + Your layer contains its own + <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> + append files + (<filename>.bbappend</filename>) and provides a convenient + mechanism to create your own recipe files + (<filename>.bb</filename>). + For details on how to create and work with layers, see the following + sections in the Yocto Project Development Manual: + <itemizedlist> + <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" for + general information on layers and how to create layers.</para></listitem> + <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" for + specific instructions on setting up a layer for kernel + development.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='modifying-an-existing-recipe'> + <title>Modifying an Existing Recipe</title> + + <para> + In many cases, you can customize an existing linux-yocto recipe to + meet the needs of your project. + Each release of the Yocto Project provides a few Linux + kernel recipes from which you can choose. + These are located in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + in <filename>meta/recipes-kernel/linux</filename>. + </para> + + <para> + Modifying an existing recipe can consist of the following: + <itemizedlist> + <listitem><para>Creating the append file</para></listitem> + <listitem><para>Applying patches</para></listitem> + <listitem><para>Changing the configuration</para></listitem> + </itemizedlist> + </para> + + <para> + Before modifying an existing recipe, be sure that you have created + a minimal, custom layer from which you can work. + See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>" + section for some general resources. + You can also see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section + of the Yocto Project Development Manual for a detailed + example. + </para> + + <section id='creating-the-append-file'> + <title>Creating the Append File</title> + + <para> + You create this file in your custom layer. + You also name it accordingly based on the linux-yocto recipe + you are using. + For example, if you are modifying the + <filename>meta/recipes-kernel/linux/linux-yocto_3.19.bb</filename> + recipe, the append file will typically be located as follows + within your custom layer: + <literallayout class='monospaced'> + <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_3.19.bbappend + </literallayout> + The append file should initially extend the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> + search path by prepending the directory that contains your + files to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + variable as follows: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + </literallayout> + The path <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> + expands to "linux-yocto" in the current directory for this + example. + If you add any new files that modify the kernel recipe and you + have extended <filename>FILESPATH</filename> as + described above, you must place the files in your layer in the + following area: + <literallayout class='monospaced'> + <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto/ + </literallayout> + <note>If you are working on a new machine Board Support Package + (BSP), be sure to refer to the + <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. + </note> + </para> + </section> + + <section id='applying-patches'> + <title>Applying Patches</title> + + <para> + If you have a single patch or a small series of patches + that you want to apply to the Linux kernel source, you + can do so just as you would with any other recipe. + You first copy the patches to the path added to + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + in your <filename>.bbappend</filename> file as described in + the previous section, and then reference them in + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statements. + </para> + + <para> + For example, you can apply a three-patch series by adding the + following lines to your linux-yocto + <filename>.bbappend</filename> file in your layer: + <literallayout class='monospaced'> + SRC_URI += "file://0001-first-change.patch" + SRC_URI += "file://0002-second-change.patch" + SRC_URI += "file://0003-third-change.patch" + </literallayout> + The next time you run BitBake to build the Linux kernel, + BitBake detects the change in the recipe and fetches and + applies the patches before building the kernel. + </para> + + <para> + For a detailed example showing how to patch the kernel, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" + section in the Yocto Project Development Manual. + </para> + </section> + + <section id='changing-the-configuration'> + <title>Changing the Configuration</title> + + <para> + You can make wholesale or incremental changes to the final + <filename>.config</filename> file used for the eventual + Linux kernel configuration by including a + <filename>defconfig</filename> file and by specifying + configuration fragments in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + to be applied to that file. + </para> + + <para> + If you have a complete, working Linux kernel + <filename>.config</filename> + file you want to use for the configuration, as before, copy + that file to the appropriate <filename>${PN}</filename> + directory in your layer's + <filename>recipes-kernel/linux</filename> directory, + and rename the copied file to "defconfig". + Then, add the following lines to the linux-yocto + <filename>.bbappend</filename> file in your layer: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + SRC_URI += "file://defconfig" + </literallayout> + The <filename>SRC_URI</filename> tells the build system how to + search for the file, while the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + extends the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> + variable (search directories) to include the + <filename>${PN}</filename> directory you created to hold the + configuration changes. + </para> + + <note> + The build system applies the configurations from the + <filename>defconfig</filename> file before applying any + subsequent configuration fragments. + The final kernel configuration is a combination of the + configurations in the <filename>defconfig</filename> file and + any configuration fragments you provide. + You need to realize that if you have any configuration + fragments, the build system applies these on top of and + after applying the existing <filename>defconfig</filename> + file configurations. + </note> + + <para> + Generally speaking, the preferred approach is to determine the + incremental change you want to make and add that as a + configuration fragment. + For example, if you want to add support for a basic serial + console, create a file named <filename>8250.cfg</filename> in + the <filename>${PN}</filename> directory with the following + content (without indentation): + <literallayout class='monospaced'> + CONFIG_SERIAL_8250=y + CONFIG_SERIAL_8250_CONSOLE=y + CONFIG_SERIAL_8250_PCI=y + CONFIG_SERIAL_8250_NR_UARTS=4 + CONFIG_SERIAL_8250_RUNTIME_UARTS=4 + CONFIG_SERIAL_CORE=y + CONFIG_SERIAL_CORE_CONSOLE=y + </literallayout> + Next, include this configuration fragment and extend the + <filename>FILESPATH</filename> variable in your + <filename>.bbappend</filename> file: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + SRC_URI += "file://8250.cfg" + </literallayout> + The next time you run BitBake to build the Linux kernel, BitBake + detects the change in the recipe and fetches and applies the + new configuration before building the kernel. + </para> + + <para> + For a detailed example showing how to configure the kernel, + see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>" + section in the Yocto Project Development Manual. + </para> + </section> + + <section id='using-an-in-tree-defconfig-file'> + <title>Using an "In-Tree" <filename>defconfig</filename> File</title> + + <para> + It might be desirable to have kernel configuration fragment + support through a <filename>defconfig</filename> file that + is pulled from the kernel source tree for the configured + machine. + By default, the OpenEmbedded build system looks for + <filename>defconfig</filename> files in the layer used for + Metadata, which is "out-of-tree", and then configures them + using the following: + <literallayout class='monospaced'> + SRC_URI += "file://defconfig" + </literallayout> + If you do not want to maintain copies of + <filename>defconfig</filename> files in your layer but would + rather allow users to use the default configuration from the + kernel tree and still be able to add configuration fragments + to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + through, for example, append files, you can direct the + OpenEmbedded build system to use a + <filename>defconfig</filename> file that is "in-tree". + </para> + + <para> + To specify an "in-tree" <filename>defconfig</filename> file, + edit the recipe that builds your kernel so that it has the + following command form: + <literallayout class='monospaced'> + KBUILD_DEFCONFIG_<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'>KMACHINE</ulink> ?= <replaceable>defconfig_file</replaceable> + </literallayout> + You need to append the variable with + <filename>KMACHINE</filename> and then supply the path to + your "in-tree" <filename>defconfig</filename> file. + </para> + + <para> + Aside from modifying your kernel recipe and providing your own + <filename>defconfig</filename> file, you need to be sure no + files or statements set <filename>SRC_URI</filename> to use a + <filename>defconfig</filename> other than your "in-tree" + file (e.g. a kernel's <filename>linux-</filename><replaceable>machine</replaceable><filename>.inc</filename> + file). + In other words, if the build system detects a statement + that identifies an "out-of-tree" + <filename>defconfig</filename> file, that statement + will override your + <filename>KBUILD_DEFCONFIG</filename> variable. + </para> + + <para> + See the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG'><filename>KBUILD_DEFCONFIG</filename></ulink> + variable description for more information. + </para> + </section> + </section> + + <section id='using-an-iterative-development-process'> + <title>Using an Iterative Development Process</title> + + <para> + If you do not have existing patches or configuration files, + you can iteratively generate them from within the BitBake build + environment as described within this section. + During an iterative workflow, running a previously completed BitBake + task causes BitBake to invalidate the tasks that follow the + completed task in the build sequence. + Invalidated tasks rebuild the next time you run the build using + BitBake. + </para> + + <para> + As you read this section, be sure to substitute the name + of your Linux kernel recipe for the term + "linux-yocto". + </para> + + <section id='tip-dirty-string'> + <title>"-dirty" String</title> + +<!-- + <para> + <emphasis>AR - Darren Hart:</emphasis> This section + originated from the old Yocto Project Kernel Architecture + and Use Manual. + It was decided we need to put it in this section here. + Darren needs to figure out where we want it and what part + of it we want (all, revision???) + </para> +--> + + <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 above Git command to report modified, + removed, or added files. + You should commit those changes to the tree regardless of + whether they will be saved, exported, or used. + Once you commit the changes, you need to rebuild the kernel. + </para> + + <para> + To force a pickup and commit of 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='generating-configuration-files'> + <title>Generating Configuration Files</title> + + <para> + You can manipulate the <filename>.config</filename> file + used to build a linux-yocto recipe with the + <filename>menuconfig</filename> command as follows: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c menuconfig + </literallayout> + This command starts the Linux kernel configuration tool, + which allows you to prepare a new + <filename>.config</filename> file for the build. + When you exit the tool, be sure to save your changes + at the prompt. + </para> + + <para> + The resulting <filename>.config</filename> file is + located in + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> under the + <filename>linux-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${<ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>}-build</filename> directory. + You can use the entire <filename>.config</filename> file as the + <filename>defconfig</filename> file as described in the + "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section. + </para> + + <para> + A better method is to create a configuration fragment using the + differences between two configuration files: one previously + created and saved, and one freshly created using the + <filename>menuconfig</filename> tool. + </para> + + <para> + To create a configuration fragment using this method, follow + these steps: + <orderedlist> + <listitem><para>Complete a build at least through the kernel + configuration task as follows: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c kernel_configme -f + </literallayout> + This step ensures that you will be creating a + <filename>.config</filename> file from a known state. + Because situations exist where your build state might + become unknown, it is best to run the previous + command prior to starting up + <filename>menuconfig</filename>. + </para></listitem> + <listitem><para>Run the <filename>menuconfig</filename> + command: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c menuconfig + </literallayout></para></listitem> + <listitem><para>Run the <filename>diffconfig</filename> + command to prepare a configuration fragment. + The resulting file <filename>fragment.cfg</filename> + will be placed in the + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> directory: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c diffconfig + </literallayout></para></listitem> + </orderedlist> + </para> + + <para> + The <filename>diffconfig</filename> command creates a file that is a + list of Linux kernel <filename>CONFIG_</filename> assignments. + See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>" + section for information on how to use the output as a + configuration fragment. + <note> + You can also use this method to create configuration + fragments for a BSP. + See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>" + section for more information. + </note> + </para> + + <para> + The kernel tools also provide configuration validation. + You can use these tools to produce warnings for when a + requested configuration does not appear in the final + <filename>.config</filename> file or when you override a + policy configuration in a hardware configuration fragment. + Here is an example with some sample output of the command + that runs these tools: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c kernel_configcheck -f + + ... + + NOTE: validating kernel configuration + This BSP sets 3 invalid/obsolete kernel options. + These config options are not offered anywhere within this kernel. + The full list can be found in your kernel src dir at: + meta/cfg/standard/mybsp/invalid.cfg + + This BSP sets 21 kernel options that are possibly non-hardware related. + The full list can be found in your kernel src dir at: + meta/cfg/standard/mybsp/specified_non_hdw.cfg + + WARNING: There were 2 hardware options requested that do not + have a corresponding value present in the final ".config" file. + This probably means you are not getting the config you wanted. + The full list can be found in your kernel src dir at: + meta/cfg/standard/mybsp/mismatch.cfg + </literallayout> + </para> + + <para> + The output describes the various problems that you can + encounter along with where to find the offending configuration + items. + You can use the information in the logs to adjust your + configuration files and then repeat the + <filename>kernel_configme</filename> and + <filename>kernel_configcheck</filename> commands until + they produce no warnings. + </para> + + <para> + For more information on how to use the + <filename>menuconfig</filename> tool, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>" + section in the Yocto Project Development Manual. + </para> + </section> + + <section id='modifying-source-code'> + <title>Modifying Source Code</title> + + <para> + You can experiment with source code changes and create a + simple patch without leaving the BitBake environment. + To get started, be sure to complete a build at + least through the kernel configuration task: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c kernel_configme -f + </literallayout> + Taking this step ensures you have the sources prepared + and the configuration completed. + You can find the sources in the + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/linux</filename> directory. + </para> + + <para> + You can edit the sources as you would any other Linux source + tree. + However, keep in mind that you will lose changes if you + trigger the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink> + task for the recipe. + You can avoid triggering this task by not using BitBake to + run the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>cleanall</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>cleansstate</filename></ulink>, + or forced + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>fetch</filename></ulink> + commands. + Also, do not modify the recipe itself while working + with temporary changes or BitBake might run the + <filename>fetch</filename> command depending on the + changes to the recipe. + </para> + + <para> + To test your temporary changes, instruct BitBake to run the + <filename>compile</filename> again. + The <filename>-f</filename> option forces the command to run + even though BitBake might think it has already done so: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c compile -f + </literallayout> + If the compile fails, you can update the sources and repeat + the <filename>compile</filename>. + Once compilation is successful, you can inspect and test + the resulting build (i.e. kernel, modules, and so forth) from + the following build directory: + <literallayout class='monospaced'> + ${WORKDIR}/linux-${PACKAGE_ARCH}-${LINUX_KERNEL_TYPE}-build + </literallayout> + Alternatively, you can run the <filename>deploy</filename> + command to place the kernel image in the + <filename>tmp/deploy/images</filename> directory: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c deploy + </literallayout> + And, of course, you can perform the remaining installation and + packaging steps by issuing: + <literallayout class='monospaced'> + $ bitbake linux-yocto + </literallayout> + </para> + + <para> + For rapid iterative development, the edit-compile-repeat loop + described in this section is preferable to rebuilding the + entire recipe because the installation and packaging tasks + are very time consuming. + </para> + + <para> + Once you are satisfied with your source code modifications, + you can make them permanent by generating patches and + applying them to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement as described in the + "<link linkend='applying-patches'>Applying Patches</link>" + section. + If you are not familiar with generating patches, refer to the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>" + section in the Yocto Project Development Manual. + </para> + </section> + </section> + + <section id='working-with-your-own-sources'> + <title>Working With Your Own Sources</title> + + <para> + If you cannot work with one of the Linux kernel + versions supported by existing linux-yocto recipes, you can + still make use of the Yocto Project Linux kernel tooling by + working with your own sources. + When you use your own sources, you will not be able to + leverage the existing kernel + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> and + stabilization work of the linux-yocto sources. + However, you will be able to manage your own Metadata in the same + format as the linux-yocto sources. + Maintaining format compatibility facilitates converging with + linux-yocto on a future, mutually-supported kernel version. + </para> + + <para> + To help you use your own sources, the Yocto Project provides a + linux-yocto custom recipe + (<filename>linux-yocto-custom.bb</filename>) that uses + <filename>kernel.org</filename> sources + and the Yocto Project Linux kernel tools for managing + kernel Metadata. + You can find this recipe in the + <filename>poky</filename> Git repository of the + Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink> + at: + <literallayout class="monospaced"> + poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb + </literallayout> + </para> + + <para> + Here are some basic steps you can use to work with your own sources: + <orderedlist> + <listitem><para>Copy the <filename>linux-yocto-custom.bb</filename> + recipe to your layer and give it a meaningful name. + The name should include the version of the Linux kernel you + are using (e.g. + <filename>linux-yocto-myproject_3.19.bb</filename>, + where "3.19" is the base version of the Linux kernel + with which you would be working).</para></listitem> + <listitem><para>In the same directory inside your layer, + create a matching directory + to store your patches and configuration files (e.g. + <filename>linux-yocto-myproject</filename>). + </para></listitem> + <listitem><para>Make sure you have either a + <filename>defconfig</filename> file or configuration + fragment files. + When you use the <filename>linux-yocto-custom.bb</filename> + recipe, you must specify a configuration. + If you do not have a <filename>defconfig</filename> file, + you can run the following: + <literallayout class='monospaced'> + $ make defconfig + </literallayout> + After running the command, copy the resulting + <filename>.config</filename> to the + <filename>files</filename> directory as "defconfig" and + then add it to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable in the recipe.</para> + <para>Running the <filename>make defconfig</filename> + command results in the default configuration for your + architecture as defined by your kernel. + However, no guarantee exists that this configuration is + valid for your use case, or that your board will even boot. + This is particularly true for non-x86 architectures. + To use non-x86 <filename>defconfig</filename> files, you + need to be more specific and find one that matches your + board (i.e. for arm, you look in + <filename>arch/arm/configs</filename> and use the one that + is the best starting point for your board). + </para></listitem> + <listitem><para>Edit the following variables in your recipe + as appropriate for your project: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>: + The <filename>SRC_URI</filename> should specify + a Git repository that uses one of the supported Git + fetcher protocols (i.e. <filename>file</filename>, + <filename>git</filename>, <filename>http</filename>, + and so forth). + The <filename>SRC_URI</filename> variable should + also specify either a <filename>defconfig</filename> + file or some configuration fragment files. + The skeleton recipe provides an example + <filename>SRC_URI</filename> as a syntax reference. + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>: + The Linux kernel version you are using (e.g. + "3.19").</para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>: + The Linux kernel <filename>CONFIG_LOCALVERSION</filename> + that is compiled into the resulting kernel and visible + through the <filename>uname</filename> command. + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>: + The commit ID from which you want to build. + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>: + Treat this variable the same as you would in any other + recipe. + Increment the variable to indicate to the OpenEmbedded + build system that the recipe has changed. + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>: + The default <filename>PV</filename> assignment is + typically adequate. + It combines the <filename>LINUX_VERSION</filename> + with the Source Control Manager (SCM) revision + as derived from the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink> + variable. + The combined results are a string with + the following form: + <literallayout class='monospaced'> + 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 + </literallayout> + While lengthy, the extra verbosity in <filename>PV</filename> + helps ensure you are using the exact + sources from which you intend to build. + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>: + A list of the machines supported by your new recipe. + This variable in the example recipe is set + by default to a regular expression that matches + only the empty string, "(^$)". + This default setting triggers an explicit build + failure. + You must change it to match a list of the machines + that your new recipe supports. + For example, to support the <filename>qemux86</filename> + and <filename>qemux86-64</filename> machines, use + the following form: + <literallayout class='monospaced'> + COMPATIBLE_MACHINE = "qemux86|qemux86-64" + </literallayout></para></listitem> + </itemizedlist></para></listitem> + <listitem><para>Provide further customizations to your recipe + as needed just as you would customize an existing + linux-yocto recipe. + See the "<link linkend='modifying-an-existing-recipe'>Modifying + an Existing Recipe</link>" section for information. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='working-with-out-of-tree-modules'> + <title>Working with Out-of-Tree Modules</title> + + <para> + This section describes steps to build out-of-tree modules on + your target and describes how to incorporate out-of-tree modules + in the build. + </para> + + <section id='building-out-of-tree-modules-on-the-target'> + <title>Building Out-of-Tree Modules on the Target</title> + + <para> + While the traditional Yocto Project development model would be + to include kernel modules as part of the normal build + process, you might find it useful to build modules on the + target. + This could be the case if your target system is capable + and powerful enough to handle the necessary compilation. + Before deciding to build on your target, however, you should + consider the benefits of using a proper cross-development + environment from your build host. + </para> + + <para> + If you want to be able to build out-of-tree modules on + the target, there are some steps you need to take + on the target that is running your SDK image. + Briefly, the <filename>kernel-dev</filename> package + is installed by default on all + <filename>*.sdk</filename> images and the + <filename>kernel-devsrc</filename> package is installed + on many of the <filename>*.sdk</filename> images. + However, you need to create some scripts prior to + attempting to build the out-of-tree modules on the target + that is running that image. + </para> + + <para> + Prior to attempting to build the out-of-tree modules, + you need to be on the target as root and you need to + change to the <filename>/usr/src/kernel</filename> directory. + Next, <filename>make</filename> the scripts: + <literallayout class='monospaced'> + # cd /usr/src/kernel + # make scripts + </literallayout> + Because all SDK image recipes include + <filename>dev-pkgs</filename>, the + <filename>kernel-dev</filename> packages will be installed + as part of the SDK image and the + <filename>kernel-devsrc</filename> packages will be installed + as part of applicable SDK images. + The SDK uses the scripts when building out-of-tree + modules. + Once you have switched to that directory and created the + scripts, you should be able to build your out-of-tree modules + on the target. + </para> + </section> + + <section id='incorporating-out-of-tree-modules'> + <title>Incorporating Out-of-Tree Modules</title> + + <para> + While it is always preferable to work with sources integrated + into the Linux kernel sources, if you need an external kernel + module, the <filename>hello-mod.bb</filename> recipe is + available as a template from which you can create your + own out-of-tree Linux kernel module recipe. + </para> + + <para> + This template recipe is located in the + <filename>poky</filename> Git repository of the + Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink> + at: + <literallayout class="monospaced"> + poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb + </literallayout> + </para> + + <para> + To get started, copy this recipe to your layer and give it a + meaningful name (e.g. <filename>mymodule_1.0.bb</filename>). + In the same directory, create a new directory named + <filename>files</filename> where you can store any source files, + patches, or other files necessary for building + the module that do not come with the sources. + Finally, update the recipe as needed for the module. + Typically, you will need to set the following variables: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> + </para></listitem> + </itemizedlist> + </para> + + <para> + Depending on the build system used by the module sources, + you might need to make some adjustments. + For example, a typical module <filename>Makefile</filename> + looks much like the one provided with the + <filename>hello-mod</filename> template: + <literallayout class='monospaced'> + obj-m := hello.o + + SRC := $(shell pwd) + + all: + $(MAKE) -C $(KERNEL_SRC) M=$(SRC) + + modules_install: + $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install + ... + </literallayout> + </para> + + <para> + The important point to note here is the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink> + variable. + The + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-module'><filename>module</filename></ulink> + class sets this variable and the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink> + variable to + <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename> + with the necessary Linux kernel build information to build + modules. + If your module <filename>Makefile</filename> uses a different + variable, you might want to override the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink> + step, or create a patch to + the <filename>Makefile</filename> to work with the more typical + <filename>KERNEL_SRC</filename> or + <filename>KERNEL_PATH</filename> variables. + </para> + + <para> + After you have prepared your recipe, you will likely want to + include the module in your images. + To do this, see the documentation for the following variables in + the Yocto Project Reference Manual and set one of them + appropriately for your machine configuration file: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink> + </para></listitem> + </itemizedlist> + </para> + + <para> + Modules are often not required for boot and can be excluded from + certain build configurations. + The following allows for the most flexibility: + <literallayout class='monospaced'> + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" + </literallayout> + The value is derived by appending the module filename without + the <filename>.ko</filename> extension to the string + "kernel-module-". + </para> + + <para> + Because the variable is + <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> + and not a + <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> + variable, the build will not fail if this module is not + available to include in the image. + </para> + </section> + </section> + + + <section id='inspecting-changes-and-commits'> + <title>Inspecting Changes and Commits</title> + + <para> + A common question when working with a kernel is: + "What changes have been applied to this tree?" + Rather than using "grep" across directories to see what has + changed, you can use Git to inspect or search the kernel tree. + Using Git is an efficient way to see what has changed in the tree. + </para> + + <section id='what-changed-in-a-kernel'> + <title>What Changed in a Kernel?</title> + + <para> + Following are a few examples that show how to use Git + commands to examine changes. + These examples are by no means the only way to see changes. + <note> + In the following examples, unless you provide a commit + range, <filename>kernel.org</filename> history is blended + with Yocto Project kernel changes. + You can form ranges by using branch names from the + kernel tree as the upper and lower commit markers with + the Git commands. + You can see the branch names through the web interface + to the Yocto Project source repositories at + <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>. + </note> + To see a full range of the changes, use the + <filename>git whatchanged</filename> command and specify a + commit range for the branch + (<replaceable>commit</replaceable><filename>..</filename><replaceable>commit</replaceable>). + </para> + + <para> + Here is an example that looks at what has changed in the + <filename>emenlow</filename> branch of the + <filename>linux-yocto-3.19</filename> kernel. + The lower commit range is the commit associated with the + <filename>standard/base</filename> branch, while + the upper commit range is the commit associated with the + <filename>standard/emenlow</filename> branch. + <literallayout class='monospaced'> + $ git whatchanged origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + + <para> + To see short, one line summaries of changes use the + <filename>git log</filename> command: + <literallayout class='monospaced'> + $ git log --oneline origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + + <para> + Use this command to see code differences for the changes: + <literallayout class='monospaced'> + $ git diff origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + + <para> + Use this command to see the commit log messages and the + text differences: + <literallayout class='monospaced'> + $ git show origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + + <para> + Use this command to create individual patches for + each change. + Here is an example that that creates patch files for each + commit and places them in your <filename>Documents</filename> + directory: + <literallayout class='monospaced'> + $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + </section> + + <section id='showing-a-particular-feature-or-branch-change'> + <title>Showing a Particular Feature or Branch Change</title> + + <para> + Tags in the Yocto Project kernel tree divide changes for + significant features or branches. + The <filename>git show</filename> <replaceable>tag</replaceable> + command shows changes based on a tag. + Here is an example that shows <filename>systemtap</filename> + changes: + <literallayout class='monospaced'> + $ git show systemtap + </literallayout> + You can use the + <filename>git branch --contains</filename> <replaceable>tag</replaceable> + command to show the branches that contain a particular feature. + This command shows the branches that contain the + <filename>systemtap</filename> feature: + <literallayout class='monospaced'> + $ git branch --contains systemtap + </literallayout> + </para> + </section> + </section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml new file mode 100644 index 000000000..ac91749cd --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml @@ -0,0 +1,253 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<appendix id='kernel-dev-concepts-appx'> +<title>Advanced Kernel Concepts</title> + + <section id='kernel-big-picture'> + <title>Yocto Project Kernel Development and Maintenance</title> + <para> + Kernels available through the Yocto Project, like other kernels, are based off the Linux + kernel releases from <ulink url='http://www.kernel.org'></ulink>. + At the beginning of a major development cycle, the Yocto Project team + chooses its kernel based on factors such as release timing, the anticipated release + timing of final upstream <filename>kernel.org</filename> versions, and Yocto Project + feature requirements. + Typically, the kernel chosen is in the + final stages of development by the community. + In other words, the kernel is in the release + candidate or "rc" phase and not yet a final release. + But, by being in the final stages of external development, the team knows that the + <filename>kernel.org</filename> final release will clearly be within the early stages of + the Yocto Project development window. + </para> + <para> + This balance allows the team to deliver the most up-to-date kernel + possible, while still ensuring that the team has a stable official release for + the baseline Linux kernel version. + </para> + <para> + The ultimate source for kernels available through the Yocto Project are released kernels + from <filename>kernel.org</filename>. + In addition to a foundational kernel from <filename>kernel.org</filename>, the + kernels available contain a mix of important new mainline + developments, non-mainline developments (when there is no alternative), + Board Support Package (BSP) developments, + and custom features. + These additions result in a commercially released Yocto Project Linux kernel that caters + to specific embedded designer needs for targeted hardware. + </para> + <para> + Once a kernel is officially released, the Yocto Project team goes into + their next development cycle, or upward revision (uprev) cycle, while still + continuing maintenance on the released kernel. + It is important to note that the most sustainable and stable way + to include feature development upstream is through a kernel uprev process. + Back-porting hundreds of individual fixes and minor features from various + kernel versions is not sustainable and can easily compromise quality. + </para> + <para> + 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 <filename>kernel.org</filename> version. + The team continually monitors community kernel + development to look for significant features of interest. + The team does consider back-porting large features if they have a significant advantage. + User or community demand can also trigger a back-port or creation of new + functionality in the Yocto Project baseline kernel during the uprev cycle. + </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 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 kernels available through the Yocto Project kernel + can be thought of as a "micro uprev." + The many “micro uprevs” produce a kernel version with a mix of + important new mainline, non-mainline, BSP developments and feature integrations. + This kernel gives insight into new features and allows focused + amounts of testing to be done on the kernel, which prevents + surprises when selecting the next major uprev. + The quality of these cutting edge kernels is evolving and the kernels are used in leading edge + feature and BSP development. + </para> + </section> + + <section id='kernel-architecture'> + <title>Kernel Architecture</title> + <para> + This section describes the architecture of the kernels available through the + Yocto Project 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 the Yocto Project is to present the + developer with + a kernel that has a clear and continuous history that is visible to the user. + The architecture and mechanisms used achieve that goal in a manner similar to the + upstream <filename>kernel.org</filename>. + </para> + <para> + You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with + added features logically structured on top of the baseline. + The features are tagged and organized by way of a branching strategy implemented by the + source code manager (SCM) Git. + For information on Git as applied to the Yocto Project, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the + Yocto Project Development Manual. + </para> + <para> + 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. + </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 do not 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 + developer 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. + </para> + <para> + This branching strategy results in a tree that has features organized to be specific + for particular functionality, single kernel types, or a subset of kernel types. + This strategy also results in not having to store the same feature twice + internally in the tree. + Rather, the kernel team stores the unique differences required to apply the + feature onto the kernel type in question. + <note> + The Yocto Project team strives to place features in the tree such that they can be + shared by all boards and kernel types where possible. + However, during development cycles or when large features are merged, + the team cannot always follow this practice. + In those cases, the team uses isolated branches to merge features. + </note> + </para> + <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, the team creates branches off the end of that kernel type for all + of the BSPs that are supported on that kernel type. + From the perspective of the tools that create the BSP branch, the BSP is really no + different than a feature. + Consequently, the same branching strategy applies to BSPs as it does to features. + So again, rather than store the BSP twice, the team only stores the unique + differences for the BSP across the supported multiple kernels. + </para> + <para> + While this strategy can result in a tree with a significant number of branches, it is + important to realize that from the developer's point of view, there is a linear + path that travels from the baseline <filename>kernel.org</filename>, through a select + group of features and ends with their BSP-specific commits. + In other words, the divisions of the kernel are transparent and are not relevant + to the developer on a day-to-day basis. + From the developer's perspective, this path is the "master" branch. + The developer does not need to be aware of the existence of any other branches at all. + Of course, there is value in the existence of these branches + in the tree, should a person decide to explore them. + For example, a comparison between two BSPs at either the commit level or at the line-by-line + code <filename>diff</filename> 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 developer + 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. + This SCM is the obvious mechanism for meeting the previously mentioned goals. + Not only is it the SCM for <filename>kernel.org</filename> but, + Git continues to grow in popularity and supports many different work flows, + front-ends and management techniques. + </para> + <para> + You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>. + You can also get an introduction to Git as it applies to the Yocto Project in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" + section in the Yocto Project Development Manual. + These referenced sections overview Git and describe a minimal set of + commands that allows you to be functional using Git. + <note> + You can use as much, or as little, of what Git has to offer to accomplish what + you need for your project. + You do not have to be a "Git Master" in order to use it with the Yocto Project. + </note> + </para> + </section> + </section> +</appendix> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-customization.xsl b/yocto-poky/documentation/kernel-dev/kernel-dev-customization.xsl new file mode 100644 index 000000000..325b738e9 --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-customization.xsl @@ -0,0 +1,26 @@ +<?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://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> + +<!-- + + <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> + + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> + +--> + + <xsl:include href="../template/permalinks.xsl"/> + <xsl:include href="../template/section.title.xsl"/> + <xsl:include href="../template/component.title.xsl"/> + <xsl:include href="../template/division.title.xsl"/> + <xsl:include href="../template/formal.object.heading.xsl"/> + + <xsl:param name="html.stylesheet" select="'kernel-dev-style.css'" /> + <xsl:param name="chapter.autolabel" select="1" /> + <xsl:param name="appendix.autolabel">A</xsl:param> + <xsl:param name="section.autolabel" select="1" /> + <xsl:param name="section.label.includes.component.label" select="1" /> + +</xsl:stylesheet> diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl b/yocto-poky/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl new file mode 100644 index 000000000..3c56a5a9e --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl @@ -0,0 +1,35 @@ +<?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://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" /> + +<!-- + + <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" /> + + <xsl:import + href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> + +--> + + <xsl:param name="chunker.output.indent" select="'yes'"/> + <xsl:param name="chunk.quietly" select="1"/> + <xsl:param name="chunk.first.sections" select="1"/> + <xsl:param name="chunk.section.depth" select="10"/> + <xsl:param name="use.id.as.filename" select="1"/> + <xsl:param name="ulink.target" select="'_self'" /> + <xsl:param name="base.dir" select="'html/kernel-dev/'"/> + <xsl:param name="html.stylesheet" select="'../book.css'"/> + <xsl:param name="eclipse.manifest" select="0"/> + <xsl:param name="create.plugin.xml" select="0"/> + <xsl:param name="suppress.navigation" select="1"/> + <xsl:param name="generate.index" select="0"/> + <xsl:param name="chapter.autolabel" select="1" /> + <xsl:param name="appendix.autolabel">A</xsl:param> + <xsl:param name="section.autolabel" select="1" /> + <xsl:param name="section.label.includes.component.label" select="1" /> +</xsl:stylesheet> diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-examples.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-examples.xml new file mode 100644 index 000000000..9d9aef6d0 --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-examples.xml @@ -0,0 +1,918 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<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 a kernel's tree structure. + The information is designed to help the developer that wants to modify the Yocto + Project kernel and contribute changes upstream to the Yocto Project. + The information covers the following: + <itemizedlist> + <listitem><para>Tree construction</para></listitem> + <listitem><para>Build strategies</para></listitem> + <listitem><para>Workflow examples</para></listitem> + </itemizedlist> + </para> +</section> + + <section id='tree-construction'> + <title>Tree Construction</title> + <para> + This section describes construction of the Yocto Project kernel source repositories + as accomplished by the Yocto Project team to create kernel repositories. + These kernel repositories are found under the heading "Yocto Linux Kernel" at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink> + and can be shipped as part of a Yocto Project release. + The team creates these repositories by + compiling and executing the set of feature descriptions for every BSP/feature + in the product. + Those feature descriptions list all necessary patches, + configuration, branching, tagging and feature divisions found in a kernel. + Thus, the Yocto Project kernel repository (or tree) is built. + </para> + <para> + The existence of this tree allows you to access and clone a particular + Yocto Project kernel repository and use it to build images based on their configurations + and features. + </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 Yocto Project kernel source repository + Git tree. + For example, the following command clones the Yocto Project baseline kernel that + branched off of <filename>linux.org</filename> version 3.4: + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/linux-yocto-3.4 + </literallayout> + For another example of how to set up a local Git repository of the Yocto Project + kernel files, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted + item in the Yocto Project Development Manual. + </para> + <para> + Once you have cloned the kernel Git repository on your local machine, you can + switch to the <filename>meta</filename> branch within the repository. + Here is an example that assumes the local Git repository for the kernel is in + a top-level directory named <filename>linux-yocto-3.4</filename>: + <literallayout class='monospaced'> + $ cd ~/linux-yocto-3.4 + $ git checkout -b meta origin/meta + </literallayout> + Once you have checked out and switched to the <filename>meta</filename> branch, + you can see a snapshot of all the kernel configuration and feature descriptions that are + used to build that particular kernel repository. + These descriptions are in the form of <filename>.scc</filename> files. + </para> + <para> + You should realize, however, that browsing your local kernel repository + for feature descriptions and patches is not an effective way to determine what is in a + particular kernel branch. + Instead, you should use Git directly to discover the changes in a branch. + Using Git is an efficient and flexible way to inspect changes to the kernel. + For examples showing how to use Git to inspect kernel commits, see the following sections + in this chapter. + <note> + Ground up reconstruction of the complete kernel tree is an action only taken by the + Yocto Project team during an active development cycle. + When you create a clone of the kernel Git repository, you are simply making it + efficiently available for building and development. + </note> + </para> + <para> + The following steps describe what happens when the Yocto Project Team constructs + the Yocto Project kernel source Git repository (or tree) found at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the + introduction of a new top-level kernel feature or BSP. + These are the actions that effectively create the tree + that includes the new feature, patch or BSP: + <orderedlist> + <listitem><para>A top-level kernel feature is passed to the kernel build subsystem. + Normally, this feature 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: + <itemizedlist> + <listitem><para>The in-tree kernel-cache directories, which are located + in <filename>meta/cfg/kernel-cache</filename></para></listitem> + <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements + found in recipes</para></listitem> + </itemizedlist> + For a typical build, the target of the search is a + feature description in an <filename>.scc</filename> file + whose name follows this format: + <literallayout class='monospaced'> + <bsp_name>-<kernel_type>.scc + </literallayout> + </para></listitem> + <listitem><para>Once located, the feature description is either compiled into a simple script + of actions, or into an existing equivalent script that is already part of the + shipped kernel.</para></listitem> + <listitem><para>Extra features are appended to the top-level feature description. + These features can come from the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> + variable in recipes.</para></listitem> + <listitem><para>Each extra feature is located, compiled and appended to the script + as described in step three.</para></listitem> + <listitem><para>The script is executed to produce a series of <filename>meta-*</filename> + directories. + These directories are descriptions of all the branches, tags, patches and configurations that + need to be applied to the base Git repository to completely create the + source (build) branch for the new BSP or feature.</para></listitem> + <listitem><para>The base repository is cloned, and the actions + listed in the <filename>meta-*</filename> directories 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 kernel tree is now ready for developer consumption to be locally cloned, + configured, and built into a Yocto Project kernel specific to some target hardware. + <note><para>The generated <filename>meta-*</filename> directories add to the kernel + as shipped with the Yocto Project release. + Any add-ons and configuration data are applied to the end of an existing branch. + The full repository generation that is found in the + official Yocto Project kernel repositories at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink> + is the combination of all supported boards and configurations.</para> + <para>The technique the Yocto Project team uses is flexible and allows for seamless + blending of an immutable history with additional patches specific to a + deployment. + Any additions to the kernel become an integrated part of the branches.</para> + </note> + </para> + </section> + + <section id='build-strategy'> + <title>Build Strategy</title> + <para> + Once a local Git repository of the Yocto Project kernel exists on a development system, + you can consider the compilation phase of kernel development - building a kernel image. + Some prerequisites exist that are validated by the build process before compilation + starts: + </para> + + <itemizedlist> + <listitem><para>The + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points + to the kernel Git repository.</para></listitem> + <listitem><para>A BSP build branch exists. + This branch has the following form: + <literallayout class='monospaced'> + <kernel_type>/<bsp_name> + </literallayout></para></listitem> + </itemizedlist> + + <para> + The OpenEmbedded build system makes sure these conditions exist before attempting compilation. + Other means, however, do exist, such as as bootstrapping a BSP, see + the "<link linkend='workflow-examples'>Workflow Examples</link>". + </para> + + <para> + Before building a kernel, the build process verifies the tree + and configures the kernel by processing all of the + configuration "fragments" specified by feature descriptions in the <filename>.scc</filename> + files. + As the features are compiled, associated kernel configuration fragments are noted + and recorded in the <filename>meta-*</filename> series of directories in their compilation order. + The fragments are migrated, pre-processed and passed to the Linux Kernel + Configuration subsystem (<filename>lkc</filename>) as raw input in the form + of a <filename>.config</filename> file. + The <filename>lkc</filename> 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, + kernel compilation is started and a kernel image is produced. + </para> + + <para> + The other thing that you notice once you configure a kernel is that + the build process generates a build tree that is separate from your kernel's local Git + source repository tree. + This build tree has a name that uses the following form, where + <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one + of the Yocto Project supported kernel types (e.g. "standard"): + <literallayout class='monospaced'> + linux-${MACHINE}-<kernel_type>-build + </literallayout> + </para> + + <para> + The existing support in the <filename>kernel.org</filename> tree achieves this + default functionality. + </para> + + <para> + This behavior means that all the generated files for a particular machine or BSP are now in + the build tree directory. + The files include the final <filename>.config</filename> file, all the <filename>.o</filename> + files, the <filename>.a</filename> files, and so forth. + Since each machine or BSP has its own separate build directory in its own separate branch + of the Git repository, you can easily switch between different builds. + </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. + The Yocto Project has not made changes to Git or to other tools that + would invalidate alternate workflows. + Additionally, the way the kernel repository is constructed results in using + only core Git functionality, thus allowing any number of tools or front ends to use the + resulting tree. + </para> + + <para> + This section contains several workflow examples. + Many of the examples use Git commands. + You can find Git documentation at + <ulink url='http://git-scm.com/documentation'></ulink>. + You can find a simple overview of using Git with the Yocto Project in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" + section of the Yocto Project Development Manual. + </para> + + <section id='change-inspection-kernel-changes-commits'> + <title>Change Inspection: Changes/Commits</title> + + <para> + A common question when working with a 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 branch is to use + Git and inspect or search the kernel tree. + This method gives you a full view of not only the source code modifications, + but also provides the reasons for the changes. + </para> + + <section id='what-changed-in-a-kernel'> + <title>What Changed in a Kernel?</title> + + <para> + Following are a few examples that show how to use Git commands to examine changes. + Because Git repositories in the Yocto Project do not break existing Git + functionality, and because there exists many permutations of these types of + Git commands, many methods exist by which you can discover changes. + <note> + In the following examples, unless you provide a commit range, + <filename>kernel.org</filename> history is blended with Yocto Project + kernel changes. + You can form ranges by using branch names from the kernel tree as the + upper and lower commit markers with the Git commands. + You can see the branch names through the web interface to the + Yocto Project source repositories at + <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>. + For example, the branch names for the <filename>linux-yocto-3.4</filename> + kernel repository can be seen at + <ulink url='http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>. + </note> + To see a full range of the changes, use the + <filename>git whatchanged</filename> command and specify a commit range + for the branch (<filename><commit>..<commit></filename>). + </para> + + <para> + Here is an example that looks at what has changed in the + <filename>emenlow</filename> branch of the + <filename>linux-yocto-3.4</filename> kernel. + The lower commit range is the commit associated with the + <filename>standard/base</filename> branch, while + the upper commit range is the commit associated with the + <filename>standard/emenlow</filename> branch. + <literallayout class='monospaced'> + $ git whatchanged origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + + <para> + To see a summary of changes use the <filename>git log</filename> command. + Here is an example using the same branches: + <literallayout class='monospaced'> + $ git log --oneline origin/standard/base..origin/standard/emenlow + </literallayout> + The <filename>git log</filename> output might be more useful than + the <filename>git whatchanged</filename> as you get + a short, one-line summary of each change and not the entire commit. + </para> + + <para> + If you want to see code differences associated with all the changes, use + the <filename>git diff</filename> command. + Here is an example: + <literallayout class='monospaced'> + $ git diff origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + + <para> + You can see the commit log messages and the text differences using the + <filename>git show</filename> command: + Here is an example: + <literallayout class='monospaced'> + $ git show origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + + <para> + You can create individual patches for each change by using the + <filename>git format-patch</filename> command. + Here is an example that that creates patch files for each commit and + places them in your <filename>Documents</filename> directory: + <literallayout class='monospaced'> + $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + </section> + + <section id='show-a-particular-feature-or-branch-change'> + <title>Show a Particular Feature or Branch Change</title> + + <para> + Developers use tags in the Yocto Project kernel tree to divide changes for significant + features or branches. + Once you know a particular tag, you can use Git commands + to show changes associated with the tag and find the branches that contain + the feature. + <note> + Because BSP branch, <filename>kernel.org</filename>, and feature tags are all + present, there could be many tags. + </note> + The <filename>git show <tag></filename> command shows changes that are tagged by + a feature. + Here is an example that shows changes tagged by the <filename>systemtap</filename> + feature: + <literallayout class='monospaced'> + $ git show systemtap + </literallayout> + You can use the <filename>git branch --contains <tag></filename> command + to show the branches that contain a particular feature. + This command shows the branches that contain the <filename>systemtap</filename> + feature: + <literallayout class='monospaced'> + $ git branch --contains systemtap + </literallayout> + </para> + + <para> + You can use many other comparisons to isolate BSP and kernel changes. + For example, you can compare against <filename>kernel.org</filename> tags + such as the <filename>v3.4</filename> tag. + </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 the 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 you need to save the changes. + It is also easy to determine what has changed. + This method also provides many tools to commit, undo and export those modifications. + </para> + + <para> + This section and its sub-sections, describe general application of Git's + <filename>push</filename> and <filename>pull</filename> commands, which are used to + get your changes upstream or source your code from an upstream repository. + The Yocto Project provides scripts that help you work in a collaborative development + environment. + For information on these scripts, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change + Upstream and Request a Pull</ulink>" and + "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>" + sections in the Yocto Project Development Manual. + </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 Source Code + Manager (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 "bulk" export changes that have not + been separated or divided. + This situation works well when you are simply storing patches outside of the kernel + source repository, either permanently or temporarily, and you are not committing + incremental changes during development. + <note> + 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. + </note> + <literallayout class='monospaced'> + # bulk export of ALL modifications without separation or division + # of the changes + + $ git add . + $ git commit -s -a -m <msg> + or + $ git commit -s -a # and interact with $EDITOR + </literallayout> + </para> + + <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 you have incrementally committed + changes to the tree during development and now need to export them. + The sections that follow + describe how you can export your changes internally through either patches or by + using Git commands. + </para> + + <para> + During development, the following commands are of interest. + For full Git documentation, refer to the Git documentation at + <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 <filename>push</filename> and + <filename>pull</filename> 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 <filename>git status</filename> 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 <filename>push</filename> or <filename>pull</filename> command, + commits are normally considered + "permanent" and you should not modify them. + If the commits need to be changed, you can incrementally do so with new commits. + These practices follow standard Git workflow and the <filename>kernel.org</filename> best + practices, which is recommended. + <note> + 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. + </note> + </para> + + <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 the changes have been extracted, you can use the patches for upstream submission, + place them in a Yocto Project template for automatic kernel patching, + or apply them in many other common uses. + </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. + <note> + 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. + </note> + <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> + </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 to 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-3.4</filename>. + <literallayout class='monospaced'> + $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \ + yocto/standard/common-pc/base:yocto/standard/common-pc/base + </literallayout> + </para> + + <para> + A pull request entails using the <filename>git request-pull</filename> command 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. + <note> + Other commands such as <filename>git stash</filename> or branching can also be used to save + changes, but are not covered in this document. + </note> + </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 send patches as an email series. + This method allows easy review and integration of the changes. + <note> + 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://linux.yyz.us/patch-format.html'></ulink></para></listitem> + <listitem><para>Documentation/SubmittingPatches (in any linux + kernel source tree)</para></listitem> + </itemizedlist> + </note> + </para> + + <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. + For information on how to follow the Yocto Project commit message standards, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a + Change</ulink>" section in the Yocto Project Development Manual. + </para> + + <para> + If the initial commits were not properly documented or do not meet those standards, + you can re-base by using the <filename>git rebase -i</filename> 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 <filename>git send-email</filename> 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. + This process is not recommended. + </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 an SCM other than Git, + which is not the same as exporting changes to another SCM described earlier. + For this scenario, you use the OpenEmbedded build system to + develop the kernel in a different SCM. + The following must be true for you to accomplish this: + <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 OpenEmbedded 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 <filename>yocto/standard/common-pc/base</filename> + 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> + </section> + </section> + + <section id='bsp-creating'> + <title>Creating a BSP Based on an Existing Similar BSP</title> + + <para> + This section overviews the process of creating a BSP based on an + existing similar BSP. + The information is introductory in nature and does not provide step-by-step examples. + For detailed information on how to create a new BSP, see + the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the + Yocto Project Board Support Package (BSP) Developer's Guide, or see the + <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink> + wiki page. + </para> + + <para> + The basic steps you need to follow are: + <orderedlist> + <listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis> + You must create a local + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + by either creating a Git repository (recommended) or + extracting a Yocto Project release tarball.</para></listitem> + <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis> + Try to map your board features as closely to the features of a BSP that is + already supported and exists in the Yocto Project. + Starting with something as close as possible to your board makes developing + your BSP easier. + You can find all the BSPs that are supported and ship with the Yocto Project + on the Yocto Project's Download page at + <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem> + <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis> + You need to either have a local Git repository of the base BSP set up or + have downloaded and extracted the files from a release BSP tarball. + Either method gives you access to the BSP source files.</para></listitem> + <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new + BSP work:</emphasis> + Copying the existing BSP file structure gives you a new area in which to work.</para></listitem> + <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis> + Configuration changes involve the files in the BSP's <filename>conf</filename> + directory. + Changes include creating a machine-specific configuration file and editing the + <filename>layer.conf</filename> file. + The configuration changes identify the kernel you will be using. + Recipe changes include removing, modifying, or adding new recipe files that + instruct the build process on what features to include in the image.</para></listitem> + <listitem><para><emphasis>Prepare for the build:</emphasis> + Before you actually initiate the build, you need to set up the build environment + by sourcing the environment initialization script. + After setting up the environment, you need to make some build configuration + changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename> + files.</para></listitem> + <listitem><para><emphasis>Build the image:</emphasis> + The OpenEmbedded build system uses BitBake to create the image. + You need to decide on the type of image you are going to build (e.g. minimal, base, + core, sato, and so forth) and then start the build using the <filename>bitbake</filename> + command.</para></listitem> + </orderedlist> + </para> + </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 above Git command to report modified, removed, or added files. + You should commit those changes to the tree regardless of whether they will be saved, + exported, or used. + Once you commit the changes you need to rebuild the kernel. + </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> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-faq.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-faq.xml new file mode 100644 index 000000000..2b99ad2dd --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-faq.xml @@ -0,0 +1,140 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<appendix id='kernel-dev-faq'> +<title>Kernel Development FAQ</title> + +<section id='kernel-dev-faq-section'> + <title>Common Questions and Solutions</title> + + <para> + The following lists some solutions for common questions. + + + <qandaset> + <qandaentry> + <question> + <para> + How do I use my own Linux kernel <filename>.config</filename> + file? + </para> + </question> + <answer> + <para> + Refer to the "<link linkend='changing-the-configuration'>Changing the Configuration</link>" + section for information. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I create configuration fragments? + </para> + </question> + <answer> + <para> + Refer to the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" + section for information. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I use my own Linux kernel sources? + </para> + </question> + <answer> + <para> + Refer to the "<link linkend='working-with-your-own-sources'>Working With Your Own Sources</link>" + section for information. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I install/not-install the kernel image on the rootfs? + </para> + </question> + <answer> + <para> + The kernel image (e.g. <filename>vmlinuz</filename>) is provided + by the <filename>kernel-image</filename> package. + Image recipes depend on <filename>kernel-base</filename>. + To specify whether or not the kernel + image is installed in the generated root filesystem, override + <filename>RDEPENDS_kernel-base</filename> to include or not + include "kernel-image".</para> + <para>See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>" + section in the Yocto Project Development Manual for information on + how to use an append file to override metadata. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I install a specific kernel module? + </para> + </question> + <answer> + <para> + Linux kernel modules are packaged individually. + To ensure a specific kernel module is included in an image, + include it in the appropriate machine + <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> + variable.</para> + <para>These other variables are useful for installing specific + modules: + <literallayout class='monospaced'> + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink> + </literallayout> + For example, set the following in the <filename>qemux86.conf</filename> + file to include the <filename>ab123</filename> kernel modules + with images built for the <filename>qemux86</filename> machine: + <literallayout class='monospaced'> + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" + </literallayout> + For more information, see the + "<link linkend='incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</link>" + section. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I change the Linux kernel command line? + </para> + </question> + <answer> + <para> + The Linux kernel command line is typically specified in + the machine config using the <filename>APPEND</filename> variable. + For example, you can add some helpful debug information doing + the following: + <literallayout class='monospaced'> + APPEND += "printk.time=y initcall_debug debug" + </literallayout> + </para> + </answer> + </qandaentry> + </qandaset> + </para> +</section> +</appendix> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml new file mode 100644 index 000000000..263e50098 --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml @@ -0,0 +1,149 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='kernel-dev-intro'> +<title>Introduction</title> + +<!-- +<para> + <emphasis>AR - Darren Hart:</emphasis> See if the concepts in these + three bullets are adequately covered in somewhere in this manual: + <itemizedlist> + <listitem><para>Do we convey that our kernel Git repositories + have a clear and continuous history, similar to the way the + kernel Git repositories for <filename>kernel.org</filename> + do. + </para></listitem> + <listitem><para>Does the manual note that Yocto Project delivers + a key set of supported kernel types, where + each type is tailored to meet a specific use (e.g. networking, + consumer, devices, and so forth).</para></listitem> + <listitem><para>Do we convey that the Yocto Project uses a + Git branching strategy that, from a + developer's point of view, results in a linear path from the + baseline kernel.org, through a select group of features and + ends with their BSP-specific commits.</para></listitem> + </itemizedlist> +</para> +--> + + <section id='kernel-dev-overview'> + <title>Overview</title> + + <para> + Regardless of how you intend to make use of the Yocto Project, + chances are you will work with the Linux kernel. + This manual provides background information on the Yocto Linux kernel + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>, + describes common tasks you can perform using the kernel tools, + and shows you how to use the kernel Metadata needed to work with + the kernel inside the Yocto Project. + </para> + + <para> + Each Yocto Project release has a set of linux-yocto recipes, whose + Git repositories you can view in the Yocto + <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under + the "Yocto Linux Kernel" heading. + New recipes for the release track the latest upstream developments + and introduce newly-supported platforms. + Previous recipes in the release are refreshed and supported for at + least one additional release. + As they align, these previous releases are updated to include the + latest from the + <ulink url='&YOCTO_HOME_URL;/organization/long-term-support-initiative-ltsi'>Long Term Support Initiative</ulink> + (LTSI) project. + Also included is a linux-yocto development recipe + (<filename>linux-yocto-dev.bb</filename>) should you want to work + with the very latest in upstream Linux kernel development and + kernel Metadata development. + </para> + + <para> + The Yocto Project also provides a powerful set of kernel + tools for managing Linux kernel sources and configuration data. + You can use these tools to make a single configuration change, + apply multiple patches, or work with your own kernel sources. + </para> + + <para> + In particular, the kernel tools allow you to generate configuration + fragments that specify only what you must, and nothing more. + Configuration fragments only need to contain the highest level + visible <filename>CONFIG</filename> options as presented by the Linux + kernel <filename>menuconfig</filename> system. + Contrast this against a complete Linux kernel + <filename>.config</filename>, which includes all the automatically + selected <filename>CONFIG</filename> options. + This efficiency reduces your maintenance effort and allows you + to further separate your configuration in ways that make sense for + your project. + A common split separates policy and hardware. + For example, all your kernels might support + the <filename>proc</filename> and <filename>sys</filename> filesystems, + but only specific boards require sound, USB, or specific drivers. + Specifying these configurations individually allows you to aggregate + them together as needed, but maintains them in only one place. + Similar logic applies to separating source changes. + </para> + + <para> + If you do not maintain your own kernel sources and need to make + only minimal changes to the sources, the released recipes provide a + vetted base upon which to layer your changes. + Doing so allows you to benefit from the continual kernel + integration and testing performed during development of the + Yocto Project. + </para> + + <para> + If, instead, you have a very specific Linux kernel source tree + and are unable to align with one of the official linux-yocto + recipes, an alternative exists by which you can use the Yocto + Project Linux kernel tools with your own kernel sources. + </para> + </section> + + <section id='kernel-dev-other-resources'> + <title>Other Resources</title> + + <para> + The sections that follow provide instructions for completing + specific Linux kernel development tasks. + These instructions assume you are comfortable working with + <ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink> + recipes and basic open-source development tools. + Understanding these concepts will facilitate the process of working + with the kernel recipes. + If you find you need some additional background, please be sure to + review and understand the following documentation: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink> + </para></listitem> + <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-modifying-source-code'>Modifying Source Code</ulink>" + section in the Yocto Project Development Manual + </para></listitem> + <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section + in the Yocto Project Development Manual</para></listitem> + <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel'>Modifying the Kernel</ulink>" section + in the Yocto Project Development Manual.</para></listitem> + </itemizedlist> + </para> + + <para> + Finally, while this document focuses on the manual creation of + recipes, patches, and configuration files, the Yocto Project + Board Support Package (BSP) tools are available to automate + this process with existing content and work well to create the + initial framework and boilerplate code. + For details on these tools, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>" + section in the Yocto Project Board Support Package (BSP) Developer's + Guide. + </para> + </section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml new file mode 100644 index 000000000..6bb0cf6fd --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml @@ -0,0 +1,220 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<appendix id='kernel-dev-maint-appx'> +<title>Kernel Maintenance</title> + + <section id='tree-construction'> + <title>Tree Construction</title> + <para> + This section describes construction of the Yocto Project kernel source repositories + as accomplished by the Yocto Project team to create kernel repositories. + These kernel repositories are found under the heading "Yocto Linux Kernel" at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink> + and can be shipped as part of a Yocto Project release. + The team creates these repositories by + compiling and executing the set of feature descriptions for every BSP + and feature in the product. + Those feature descriptions list all necessary patches, + configuration, branching, tagging and feature divisions found in a kernel. + Thus, the Yocto Project kernel repository (or tree) is built. + </para> + <para> + The existence of this tree allows you to access and clone a particular + Yocto Project kernel repository and use it to build images based on their configurations + and features. + </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 Yocto Project kernel source repository + Git tree. + For example, the following command clones the Yocto Project baseline kernel that + branched off of <filename>linux.org</filename> version 3.19: + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/linux-yocto-3.19 + </literallayout> + For another example of how to set up a local Git repository of the Yocto Project + kernel files, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted + item in the Yocto Project Development Manual. + </para> + <para> + Once you have cloned the kernel Git repository on your local machine, you can + switch to the <filename>meta</filename> branch within the repository. + Here is an example that assumes the local Git repository for the kernel is in + a top-level directory named <filename>linux-yocto-3.19</filename>: + <literallayout class='monospaced'> + $ cd linux-yocto-3.19 + $ git checkout -b meta origin/meta + </literallayout> + Once you have checked out and switched to the <filename>meta</filename> branch, + you can see a snapshot of all the kernel configuration and feature descriptions that are + used to build that particular kernel repository. + These descriptions are in the form of <filename>.scc</filename> files. + </para> + <para> + You should realize, however, that browsing your local kernel repository + for feature descriptions and patches is not an effective way to determine what is in a + particular kernel branch. + Instead, you should use Git directly to discover the changes in a branch. + Using Git is an efficient and flexible way to inspect changes to the kernel. + <note> + Ground up reconstruction of the complete kernel tree is an action only taken by the + Yocto Project team during an active development cycle. + When you create a clone of the kernel Git repository, you are simply making it + efficiently available for building and development. + </note> + </para> + <para> + The following steps describe what happens when the Yocto Project Team constructs + the Yocto Project kernel source Git repository (or tree) found at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the + introduction of a new top-level kernel feature or BSP. + These are the actions that effectively create the tree + that includes the new feature, patch or BSP: + <orderedlist> + <listitem><para>A top-level kernel feature is passed to the kernel build subsystem. + Normally, this feature 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: + <itemizedlist> + <listitem><para>The in-tree kernel-cache directories, which are located + in <filename>meta/cfg/kernel-cache</filename></para></listitem> + <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements + found in recipes</para></listitem> + </itemizedlist> + For a typical build, the target of the search is a + feature description in an <filename>.scc</filename> file + whose name follows this format: + <literallayout class='monospaced'> + <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc + </literallayout> + </para></listitem> + <listitem><para>Once located, the feature description is either compiled into a simple script + of actions, or into an existing equivalent script that is already part of the + shipped kernel.</para></listitem> + <listitem><para>Extra features are appended to the top-level feature description. + These features can come from the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> + variable in recipes.</para></listitem> + <listitem><para>Each extra feature is located, compiled and appended to the script + as described in step three.</para></listitem> + <listitem><para>The script is executed to produce a series of <filename>meta-*</filename> + directories. + These directories are descriptions of all the branches, tags, patches and configurations that + need to be applied to the base Git repository to completely create the + source (build) branch for the new BSP or feature.</para></listitem> + <listitem><para>The base repository is cloned, and the actions + listed in the <filename>meta-*</filename> directories 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 kernel tree is now ready for developer consumption to be locally cloned, + configured, and built into a Yocto Project kernel specific to some target hardware. + <note><para>The generated <filename>meta-*</filename> directories add to the kernel + as shipped with the Yocto Project release. + Any add-ons and configuration data are applied to the end of an existing branch. + The full repository generation that is found in the + official Yocto Project kernel repositories at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink> + is the combination of all supported boards and configurations.</para> + <para>The technique the Yocto Project team uses is flexible and allows for seamless + blending of an immutable history with additional patches specific to a + deployment. + Any additions to the kernel become an integrated part of the branches.</para> + </note> + </para> + </section> + + <section id='build-strategy'> + <title>Build Strategy</title> + +<!-- + <para> + <emphasis>AR - Darren Hart:</emphasis> Some parts of this section + need to be in the + "<link linkend='using-an-iterative-development-process'>Using an Iterative Development Process</link>" + section. + Darren needs to figure out which parts and identify them. + </para> +--> + + <para> + Once a local Git repository of the Yocto Project kernel exists on a development system, + you can consider the compilation phase of kernel development - building a kernel image. + Some prerequisites exist that are validated by the build process before compilation + starts: + </para> + + <itemizedlist> + <listitem><para>The + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points + to the kernel Git repository.</para></listitem> + <listitem><para>A BSP build branch exists. + This branch has the following form: + <literallayout class='monospaced'> + <replaceable>kernel_type</replaceable>/<replaceable>bsp_name</replaceable> + </literallayout></para></listitem> + </itemizedlist> + + <para> + The OpenEmbedded build system makes sure these conditions exist before attempting compilation. + Other means, however, do exist, such as as bootstrapping a BSP. + </para> + + <para> + Before building a kernel, the build process verifies the tree + and configures the kernel by processing all of the + configuration "fragments" specified by feature descriptions in the <filename>.scc</filename> + files. + As the features are compiled, associated kernel configuration fragments are noted + and recorded in the <filename>meta-*</filename> series of directories in their compilation order. + The fragments are migrated, pre-processed and passed to the Linux Kernel + Configuration subsystem (<filename>lkc</filename>) as raw input in the form + of a <filename>.config</filename> file. + The <filename>lkc</filename> 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, + kernel compilation is started and a kernel image is produced. + </para> + + <para> + The other thing that you notice once you configure a kernel is that + the build process generates a build tree that is separate from your kernel's local Git + source repository tree. + This build tree has a name that uses the following form, where + <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one + of the Yocto Project supported kernel types (e.g. "standard"): + <literallayout class='monospaced'> + linux-${MACHINE}-<replaceable>kernel_type</replaceable>-build + </literallayout> + </para> + + <para> + The existing support in the <filename>kernel.org</filename> tree achieves this + default functionality. + </para> + + <para> + This behavior means that all the generated files for a particular machine or BSP are now in + the build tree directory. + The files include the final <filename>.config</filename> file, all the <filename>.o</filename> + files, the <filename>.a</filename> files, and so forth. + Since each machine or BSP has its own separate + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + in its own separate branch + of the Git repository, you can easily switch between different builds. + </para> + </section> +</appendix> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-style.css b/yocto-poky/documentation/kernel-dev/kernel-dev-style.css new file mode 100644 index 000000000..6e0c1c7fc --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-style.css @@ -0,0 +1,984 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/kernel-dev-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;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev.xml b/yocto-poky/documentation/kernel-dev/kernel-dev.xml new file mode 100644 index 000000000..e3df2cc23 --- /dev/null +++ b/yocto-poky/documentation/kernel-dev/kernel-dev.xml @@ -0,0 +1,115 @@ +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<book id='kernel-dev' lang='en' + xmlns:xi="http://www.w3.org/2003/XInclude" + xmlns="http://docbook.org/ns/docbook" + > + <bookinfo> + + <mediaobject> + <imageobject> + <imagedata fileref='figures/kernel-dev-title.png' + format='SVG' + align='left' scalefit='1' width='100%'/> + </imageobject> + </mediaobject> + + <title> + Yocto Project Linux Kernel Development Manual + </title> + + <authorgroup> + <author> + <firstname>Darren</firstname> <surname>Hart</surname> + <affiliation> + <orgname>Intel Corporation</orgname> + </affiliation> + <email>darren.hart@intel.com</email> + </author> + </authorgroup> + + <revhistory> + <revision> + <revnumber>1.4</revnumber> + <date>April 2013</date> + <revremark>Released with the Yocto Project 1.4 Release.</revremark> + </revision> + <revision> + <revnumber>1.5</revnumber> + <date>October 2013</date> + <revremark>Released with the Yocto Project 1.5 Release.</revremark> + </revision> + <revision> + <revnumber>1.5.1</revnumber> + <date>January 2014</date> + <revremark>Released with the Yocto Project 1.5.1 Release.</revremark> + </revision> + <revision> + <revnumber>1.6</revnumber> + <date>April 2014</date> + <revremark>Released with the Yocto Project 1.6 Release.</revremark> + </revision> + <revision> + <revnumber>1.7</revnumber> + <date>October 2014</date> + <revremark>Released with the Yocto Project 1.7 Release.</revremark> + </revision> + <revision> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> + <revision> + <revnumber>1.9</revnumber> + <date>October 2015</date> + <revremark>Released with the Yocto Project 1.9 Release.</revremark> + </revision> + </revhistory> + + <copyright> + <year>©RIGHT_YEAR;</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> + <note> + For the latest version of this manual associated with this + Yocto Project release, see the + <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink> + from the Yocto Project website. + </note> + </legalnotice> + + </bookinfo> + + <xi:include href="kernel-dev-intro.xml"/> + + <xi:include href="kernel-dev-common.xml"/> + + <xi:include href="kernel-dev-advanced.xml"/> + + <xi:include href="kernel-dev-concepts-appx.xml"/> + + <xi:include href="kernel-dev-maint-appx.xml"/> + +<!-- + <xi:include href="kernel-dev-examples.xml"/> +--> + + <xi:include href="kernel-dev-faq.xml"/> + +<!-- <index id='index'> + <title>Index</title> + </index> +--> + +</book> +<!-- +vim: expandtab tw=80 ts=4 +--> |
