diff options
author | Dave Cobbley <david.j.cobbley@linux.intel.com> | 2018-08-14 20:05:37 +0300 |
---|---|---|
committer | Brad Bishop <bradleyb@fuzziesquirrel.com> | 2018-08-23 04:26:31 +0300 |
commit | eb8dc40360f0cfef56fb6947cc817a547d6d9bc6 (patch) | |
tree | de291a73dc37168da6370e2cf16c347d1eba9df8 /poky/documentation/kernel-dev | |
parent | 9c3cf826d853102535ead04cebc2d6023eff3032 (diff) | |
download | openbmc-eb8dc40360f0cfef56fb6947cc817a547d6d9bc6.tar.xz |
[Subtree] Removing import-layers directory
As part of the move to subtrees, need to bring all the import layers
content to the top level.
Change-Id: I4a163d10898cbc6e11c27f776f60e1a470049d8f
Signed-off-by: Dave Cobbley <david.j.cobbley@linux.intel.com>
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Diffstat (limited to 'poky/documentation/kernel-dev')
14 files changed, 6560 insertions, 0 deletions
diff --git a/poky/documentation/kernel-dev/figures/kernel-architecture-overview.png b/poky/documentation/kernel-dev/figures/kernel-architecture-overview.png Binary files differnew file mode 100755 index 000000000..2aad172db --- /dev/null +++ b/poky/documentation/kernel-dev/figures/kernel-architecture-overview.png diff --git a/poky/documentation/kernel-dev/figures/kernel-dev-flow.png b/poky/documentation/kernel-dev/figures/kernel-dev-flow.png Binary files differnew file mode 100644 index 000000000..793a395e8 --- /dev/null +++ b/poky/documentation/kernel-dev/figures/kernel-dev-flow.png diff --git a/poky/documentation/kernel-dev/figures/kernel-dev-title.png b/poky/documentation/kernel-dev/figures/kernel-dev-title.png Binary files differnew file mode 100644 index 000000000..7a8dd5437 --- /dev/null +++ b/poky/documentation/kernel-dev/figures/kernel-dev-title.png diff --git a/poky/documentation/kernel-dev/figures/kernel-overview-2-generic.png b/poky/documentation/kernel-dev/figures/kernel-overview-2-generic.png Binary files differnew file mode 100644 index 000000000..ee2cdb206 --- /dev/null +++ b/poky/documentation/kernel-dev/figures/kernel-overview-2-generic.png diff --git a/poky/documentation/kernel-dev/kernel-dev-advanced.xml b/poky/documentation/kernel-dev/kernel-dev-advanced.xml new file mode 100644 index 000000000..5c76ed239 --- /dev/null +++ b/poky/documentation/kernel-dev/kernel-dev-advanced.xml @@ -0,0 +1,1256 @@ +<!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 (<filename>yocto-kernel-cache</filename>)</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_REF_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 is + to help you manage the complexity of the configuration and sources + used to support multiple BSPs and Linux kernel types. + </para> + + <para> + Kernel Metadata exists in many places. + One area in the Yocto Project + <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> + is the <filename>yocto-kernel-cache</filename> Git repository. + You can find this repository grouped under the "Yocto Linux Kernel" + heading in the + <ulink url='&YOCTO_GIT_URL;'>Yocto Project Source Repositories</ulink>. + </para> + + <para> + Kernel development tools ("kern-tools") exist also in the Yocto + Project Source Repositories under the "Yocto Linux Kernel" heading + in the <filename>yocto-kernel-tools</filename> Git repository. + The recipe that builds these tools is + <filename>meta/recipes-kernel/kern-tools/kern-tools-native_git.bb</filename> + in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky</filename>). + </para> +</section> + +<section id='using-kernel-metadata-in-a-recipe'> + <title>Using Kernel Metadata in a Recipe</title> + + <para> + As mentioned in the introduction, the Yocto Project contains kernel + Metadata, which is located in the + <filename>yocto-kernel-cache</filename> Git repository. + This Metadata defines Board Support Packages (BSPs) that + correspond to definitions in linux-yocto recipes for corresponding BSPs. + A BSP consists of an aggregation of kernel policy and enabled + hardware-specific features. + The BSP can be influenced from within the linux-yocto recipe. + <note> + A Linux kernel recipe that contains kernel Metadata (e.g. + inherits from the <filename>linux-yocto.inc</filename> 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 + <filename>MACHINE</filename> variable, which is used by + <ulink url='&YOCTO_DOCS_REF_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. + Multiple Corei7-based BSPs could share the same "intel-corei7-64" + value for <filename>KMACHINE</filename>. + It is important to realize that <filename>KMACHINE</filename> is + just for kernel mapping, while <filename>MACHINE</filename> + is the machine type within a BSP Layer. + Even with this distinction, however, these two variables can hold + the same value. + 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-yocto-bsp</filename> layer: + <literallayout class='monospaced'> + KBRANCH_edgerouter = "standard/edgerouter" + </literallayout> + </note> + </para> + + <para> + The linux-yocto style recipes can optionally define the following + variables: + <literallayout class='monospaced'> + KERNEL_FEATURES + LINUX_KERNEL_TYPE + </literallayout> + </para> + + <para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> + 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 <filename>KMACHINE</filename>, + <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. + </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 + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> + 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>yocto-kernel-cache</filename> repository. + Each branch of this repository contains "features" and "cfg" + subdirectories at the top-level. + For more information, see the + "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" + section. + </para> +</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 + <replaceable>base</replaceable>, 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 the top level of + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/'><filename>yocto-kernel-cache</filename></ulink> + if you are creating + <link linkend='metadata-outside-the-recipe-space'>Metadata outside of the recipe-space</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> + As an example, consider the Symmetric Multi-Processing (SMP) + fragment used with the <filename>linux-yocto-4.12</filename> + kernel as defined outside of the recipe space (i.e. + <filename>yocto-kernel-cache</filename>). + This Metadata consists of two files: <filename>smp.scc</filename> + and <filename>smp.cfg</filename>. + You can find these files in the <filename>cfg</filename> directory + of the <filename>yocto-4.12</filename> branch in the + <filename>yocto-kernel-cache</filename> Git repository: + <literallayout class='monospaced'> + cfg/smp.scc: + define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds" + 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 + # The following is needed when setting NR_CPUS to something + # greater than 8 on x86 architectures, it should be automatically + # disregarded by Kconfig when using a different arch + CONFIG_X86_BIGSMP=y + </literallayout> + You can find general information on configuration fragment files in + the + "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>" + section. + </para> + + <para> + Within the <filename>smp.scc</filename> file, the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink> + statement provides a short description of the fragment. + Higher level kernel tools use this description. + </para> + + <para> + Also within the <filename>smp.scc</filename> file, the + <filename>kconf</filename> command includes 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='validating-configuration'>Validating Configuration</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 (i.e. + <filename>.patch</filename> files). + </para> + + <para> + A typical patch includes a description file and the patch itself. + As an example, consider the build patches used with the + <filename>linux-yocto-4.12</filename> kernel as defined outside of + the recipe space (i.e. <filename>yocto-kernel-cache</filename>). + This Metadata consists of several files: + <filename>build.scc</filename> and a set of + <filename>*.patch</filename> files. + You can find these files in the <filename>patches/build</filename> + directory of the <filename>yocto-4.12</filename> branch in the + <filename>yocto-kernel-cache</filename> Git repository. + </para> + + <para> + The following listings show the <filename>build.scc</filename> + file and part of the + <filename>modpost-mask-trivial-warnings.patch</filename> file: + <literallayout class='monospaced'> + patches/build/build.scc: + patch arm-serialize-build-targets.patch + patch powerpc-serialize-image-targets.patch + patch kbuild-exclude-meta-directory-from-distclean-processi.patch + + # applied by kgit + # patch kbuild-add-meta-files-to-the-ignore-li.patch + + patch modpost-mask-trivial-warnings.patch + patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch + + patches/build/modpost-mask-trivial-warnings.patch: + From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001 + From: Paul Gortmaker <paul.gortmaker@windriver.com> + Date: Sun, 25 Jan 2009 17:58:09 -0500 + Subject: [PATCH] modpost: mask trivial warnings + + Newer HOSTCC will complain about various stdio fcns because + . + . + . + char *dump_write = NULL, *files_source = NULL; + int opt; + -- + 2.10.1 + + generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT) + </literallayout> + The description file can include multiple patch statements where + each statement handles a single patch. + In the example <filename>build.scc</filename> file, five patch + statements exist for the five patches in the directory. + </para> + + <para> + You can create a typical <filename>.patch</filename> file using + <filename>diff -Nurp</filename> or + <filename>git format-patch</filename> commands. + For information on how to create patches, see the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + and + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + sections. + </para> + </section> + + <section id='features'> + <title>Features</title> + + <para> + Features are complex kernel Metadata types that consist + of configuration fragments, patches, and possibly other feature + description files. + As an example, consider the following generic listing: + <literallayout class='monospaced'> + features/<replaceable>myfeature</replaceable>.scc + define KFEATURE_DESCRIPTION "Enable <replaceable>myfeature</replaceable>" + + patch 0001-<replaceable>myfeature</replaceable>-core.patch + patch 0002-<replaceable>myfeature</replaceable>-interface.patch + + include cfg/<replaceable>myfeature</replaceable>_dependency.scc + kconf non-hardware <replaceable>myfeature</replaceable>.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 with + the <filename>include</filename> command. + </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 kernel of a + specific type (e.g. a real-time kernel). + Syntactically, kernel types are no different than features + as described in the "<link linkend='features'>Features</link>" + section. + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> + variable in the kernel recipe selects the kernel type. + For example, in the <filename>linux-yocto_4.12.bb</filename> + kernel recipe found in + <filename>poky/meta/recipes-kernel/linux</filename>, a + <ulink url='&YOCTO_DOCS_BB_URL;#require-inclusion'><filename>require</filename></ulink> + directive includes the + <filename>poky/meta/recipes-kernel/linux/linux-yocto.inc</filename> + file, which has the following statement that defines the default + kernel type: + <literallayout class='monospaced'> + LINUX_KERNEL_TYPE ??= "standard" + </literallayout> + </para> + + <para> + Another example would be the real-time kernel (i.e. + <filename>linux-yocto-rt_4.12.bb</filename>). + This kernel recipe directly sets the kernel type as follows: + <literallayout class='monospaced'> + LINUX_KERNEL_TYPE = "preempt-rt" + </literallayout> + <note> + You can find kernel recipes in the + <filename>meta/recipes-kernel/linux</filename> directory of the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>). + See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>" + section for more information. + </note> + </para> + + <para> + Three kernel types ("standard", "tiny", and "preempt-rt") are + supported for Linux Yocto kernels: + <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> + For any given kernel type, the Metadata is defined by the + <filename>.scc</filename> (e.g. <filename>standard.scc</filename>). + Here is a partial listing for the <filename>standard.scc</filename> + file, which is found in the <filename>ktypes/standard</filename> + directory of the <filename>yocto-kernel-cache</filename> Git + repository: + <literallayout class='monospaced'> + # Include this kernel type fragment to get the standard features and + # configuration values. + + # Note: if only the features are desired, but not the configuration + # then this should be included as: + # include ktypes/standard/standard.scc nocfg + # if no chained configuration is desired, include it as: + # include ktypes/standard/standard.scc nocfg inherit + + + + include ktypes/base/base.scc + branch standard + + kconf non-hardware standard.cfg + + include features/kgdb/kgdb.scc + . + . + . + + include cfg/net/ip6_nf.scc + include cfg/net/bridge.scc + + include cfg/systemd.scc + + include features/rfkill/rfkill.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 (i.e. <filename>*.scc</filename> files) + combine kernel types with hardware-specific features. + The hardware-specific Metadata is typically defined + independently in the BSP layer, and then aggregated with each + supported kernel type. + <note> + For BSPs supported by the Yocto Project, the BSP description + files are located in the <filename>bsp</filename> directory + of the + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink> + repository organized under the "Yocto Linux Kernel" heading + in the + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>. + </note> + </para> + + <para> + This section overviews the BSP description structure, the + aggregation concepts, and presents a detailed example using + a BSP supported by the Yocto Project (i.e. BeagleBone Board). + For complete information on BSP layer file hierarchy, see the + <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. + </para> + + <section id='bsp-description-file-overview'> + <title>Overview</title> + + <para> + For simplicity, consider the following root BSP layer + description files for the BeagleBone board. + These files employ both a structure and naming convention + for consistency. + The naming convention for the file is as follows: + <literallayout class='monospaced'> + <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc + </literallayout> + Here are some example root layer BSP filenames for the + BeagleBone Board BSP, which is supported by the Yocto Project: + <literallayout class='monospaced'> + beaglebone-standard.scc + beaglebone-preempt-rt.scc + </literallayout> + Each file uses the root name (i.e "beaglebone") BSP name + followed by the kernel type. + </para> + + <para> + Examine the <filename>beaglebone-standard.scc</filename> + file: + <literallayout class='monospaced'> + define KMACHINE beaglebone + define KTYPE standard + define KARCH arm + + include ktypes/standard/standard.scc + branch beaglebone + + include beaglebone.scc + + # default policy for standard kernels + include features/latencytop/latencytop.scc + include features/profiling/profiling.scc + </literallayout> + Every top-level BSP description file 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 example supports the "beaglebone" machine for the + "standard" kernel and the "arm" 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 the kernel type defined in your kernel + Metadata as it is here, you only need to ensure that the + <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> + variable in the kernel recipe and the + <filename>KTYPE</filename> variable in the BSP description + file match. + </para> + + <para> + To separate your kernel policy from your hardware configuration, + you include a kernel type (<filename>ktype</filename>), such as + "standard". + In the previous example, this is done using the following: + <literallayout class='monospaced'> + include ktypes/standard/standard.scc + </literallayout> + This file aggregates all the configuration fragments, patches, + and features that make up your standard kernel policy. + See the "<link linkend='kernel-types'>Kernel Types</link>" + section for more information. + </para> + + <para> + To aggregate common configurations and features specific to the + kernel for <replaceable>mybsp</replaceable>, use the following: + <literallayout class='monospaced'> + include <replaceable>mybsp</replaceable>.scc + </literallayout> + You can see that in the BeagleBone example with the following: + <literallayout class='monospaced'> + include beaglebone.scc + </literallayout> + For information on how to break a complete + <filename>.config</filename> file into the various + configuration fragments, see the + "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>" + section. + </para> + + <para> + Finally, if you have any configurations specific to the + hardware that are not in a <filename>*.scc</filename> file, + you can include them as follows: + <literallayout class='monospaced'> + kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg + </literallayout> + The BeagleBone example does not include these types of + configurations. + However, the Malta 32-bit board does ("mti-malta32"). + Here is the <filename>mti-malta32-le-standard.scc</filename> + file: + <literallayout class='monospaced'> + define KMACHINE mti-malta32-le + define KMACHINE qemumipsel + define KTYPE standard + define KARCH mips + + include ktypes/standard/standard.scc + branch mti-malta32 + + include mti-malta32.scc + kconf hardware mti-malta32-le.cfg + </literallayout> + </para> + </section> + + <section id='bsp-description-file-example-minnow'> + <title>Example</title> + + <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 given the + <filename>linux-yocto-4.4</filename> branch of the + <filename>yocto-kernel-cache</filename> (i.e. + <filename>yocto-kernel-cache/bsp/minnow/minnow.scc</filename>): + <note> + Although the Minnow Board BSP is unused, the Metadata + remains and is being used here just as an example. + </note> + <literallayout class='monospaced'> + 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 features/leds/leds.scc + include features/spi/spidev.scc + include features/i2c/i2cdev.scc + include features/mei/mei-txe.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 <filename>minnow.scc</filename> 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 (i.e. <filename>minnow-standard.scc</filename>: + <literallayout class='monospaced'> + 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 enabled hardware 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 (i.e. <filename>minnow-tiny.scc</filename>): + <literallayout class='monospaced'> + 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: + <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>. + Of these variables, only <filename>KTYPE</filename> + has changed to specify the "tiny" kernel type. + </para> + </section> + </section> +</section> + +<section id='kernel-metadata-location'> + <title>Kernel Metadata Location</title> + + <para> + Kernel Metadata always exists outside of the kernel tree either + defined in a kernel recipe (recipe-space) or outside of the recipe. + 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 kernel Metadata kept outside the + recipe-space. + Working with Metadata in this area 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> + + <para> + If the BSP description is in recipe space, you cannot simply list + the <filename>*.scc</filename> in the <filename>SRC_URI</filename> + statement. + You need to use the following form from your kernel append file: + <literallayout class='monospaced'> + SRC_URI_append_<replaceable>myplatform</replaceable> = " \ + file://<replaceable>myplatform</replaceable>;type=kmeta;destsuffix=<replaceable>myplatform</replaceable> \ + " + </literallayout> + </para> + </section> + + <section id='metadata-outside-the-recipe-space'> + <title>Metadata Outside the Recipe-Space</title> + + <para> + When stored outside of the recipe-space, the kernel Metadata + files reside in a separate repository. + The OpenEmbedded build system adds the Metadata to the build as + a "type=kmeta" repository through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable. + As an example, consider the following <filename>SRC_URI</filename> + statement from the <filename>linux-yocto_4.12.bb</filename> + kernel recipe: + <literallayout class='monospaced'> + SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \ + git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" + </literallayout> + <filename>${KMETA}</filename>, in this context, is simply used to + name the directory into which the Git fetcher places the Metadata. + This behavior is no different than any multi-repository + <filename>SRC_URI</filename> statement used in a recipe (e.g. + see the previous section). + </para> + + <para> + You can keep kernel Metadata in a "kernel-cache", which is a + directory containing configuration fragments. + As with any Metadata kept outside the recipe-space, you simply + need to use the <filename>SRC_URI</filename> statement with the + "type=kmeta" attribute. + Doing so makes the kernel Metadata available during the + configuration phase. + </para> + + <para> + If you modify the Metadata, you must not forget to update the + <filename>SRCREV</filename> 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='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 + Yocto Linux Kernel Git 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 + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>, + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>. + </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/poky/documentation/kernel-dev/kernel-dev-common.xml b/poky/documentation/kernel-dev/kernel-dev-common.xml new file mode 100644 index 000000000..299bac407 --- /dev/null +++ b/poky/documentation/kernel-dev/kernel-dev-common.xml @@ -0,0 +1,2706 @@ +<!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 your host development system for + kernel development, preparing a layer, modifying an existing recipe, + patching the kernel, configuring the kernel, 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 + 2.4 Release and forward. + </note> + </para> + + <section id='preparing-the-build-host-to-work-on-the-kernel'> + <title>Preparing the Build Host to Work on the Kernel</title> + + <para> + Before you can do any kernel development, you need to be + sure your build host is set up to use the Yocto Project. + For information on how to get set up, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>" + section in the Yocto Project Development Tasks Manual. + Part of preparing the system is creating a local Git + repository of the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + (<filename>poky</filename>) on your system. + Follow the steps in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>" + section in the Yocto Project Development Tasks Manual to set up your + Source Directory. + <note> + Be sure you check out the appropriate development branch or + you create your local branch by checking out a specific tag + to get the desired version of Yocto Project. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>" + and + "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>" + sections in the Yocto Project Development Tasks Manual for more + information. + </note> + </para> + + <para> + Kernel development is best accomplished using + <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink> + and not through traditional kernel workflow methods. + The remainder of this section provides information for both + scenarios. + </para> + + <section id='getting-ready-to-develop-using-devtool'> + <title>Getting Ready to Develop Using <filename>devtool</filename></title> + + <para> + Follow these steps to prepare to update the kernel image using + <filename>devtool</filename>. + Completing this procedure leaves you with a clean kernel image + and ready to make modifications as described in the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + section: + <orderedlist> + <listitem><para> + <emphasis>Initialize the BitBake Environment:</emphasis> + Before building an extensible SDK, you need to + initialize the BitBake build environment by sourcing the + build environment script + (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>): + <literallayout class='monospaced'> + $ cd ~/poky + $ source oe-init-build-env + </literallayout> + <note> + The previous commands assume the + <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> + (i.e. <filename>poky</filename>) have been cloned + using Git and the local repository is named + "poky". + </note> + </para></listitem> + <listitem><para> + <emphasis>Prepare Your <filename>local.conf</filename> File:</emphasis> + By default, the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable is set to "qemux86", which is fine if you are + building for the QEMU emulator in 32-bit mode. + However, if you are not, you need to set the + <filename>MACHINE</filename> variable appropriately in + your <filename>conf/local.conf</filename> file found in + the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + (i.e. <filename>~/poky/build</filename> in this + example).</para> + + <para>Also, since you are preparing to work on the + kernel image, you need to set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> + variable to include kernel modules.</para> + + <para>This example uses the default "qemux86" for the + <filename>MACHINE</filename> variable but needs to + add the "kernel-modules": + <literallayout class='monospaced'> + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create a Layer for Patches:</emphasis> + You need to create a layer to hold patches created + for the kernel image. + You can use the + <filename>bitbake-layers create-layer</filename> + command as follows: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake-layers create-layer ../../meta-mylayer + NOTE: Starting bitbake server... + Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' + $ + </literallayout> + <note> + For background information on working with + common and BSP layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Tasks + Manual and the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + section in the Yocto Project Board Support (BSP) + Developer's Guide, respectively. + For information on how to use the + <filename>bitbake-layers create-layer</filename> + command to quickly set up a layer, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" + section in the Yocto Project Development Tasks + Manual. + </note> + </para></listitem> + <listitem><para> + <emphasis>Inform the BitBake Build Environment About + Your Layer:</emphasis> + As directed when you created your layer, you need to + add the layer to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> + variable in the <filename>bblayers.conf</filename> file + as follows: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake-layers add-layer ../../meta-mylayer + NOTE: Starting bitbake server... + $ + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Build the Extensible SDK:</emphasis> + Use BitBake to build the extensible SDK specifically + for use with images to be run using QEMU: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake core-image-minimal -c populate_sdk_ext + </literallayout> + Once the build finishes, you can find the SDK installer + file (i.e. <filename>*.sh</filename> file) in the + following directory: + <literallayout class='monospaced'> + ~/poky/build/tmp/deploy/sdk + </literallayout> + For this example, the installer file is named + <filename>poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh</filename> + </para></listitem> + <listitem><para> + <emphasis>Install the Extensible SDK:</emphasis> + Use the following command to install the SDK. + For this example, install the SDK in the default + <filename>~/poky_sdk</filename> directory: + <literallayout class='monospaced'> + $ cd ~/poky/build/tmp/deploy/sdk + $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh + Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO; + ============================================================================ + Enter target directory for SDK (default: ~/poky_sdk): + You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y + Extracting SDK......................................done + Setting it up... + Extracting buildtools... + Preparing build system... + Parsing recipes: 100% |#################################################################| Time: 0:00:52 + Initializing tasks: 100% |############## ###############################################| Time: 0:00:04 + Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00 + Parsing recipes: 100% |#################################################################| Time: 0:00:33 + Initializing tasks: 100% |##############################################################| Time: 0:00:00 + done + SDK has been successfully set up and is ready to be used. + Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. + $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux + </literallayout> + </para></listitem> + <listitem><para id='setting-up-the-esdk-terminal'> + <emphasis>Set Up a New Terminal to Work With the + Extensible SDK:</emphasis> + You must set up a new terminal to work with the SDK. + You cannot use the same BitBake shell used to build the + installer.</para> + + <para>After opening a new shell, run the SDK environment + setup script as directed by the output from installing + the SDK: + <literallayout class='monospaced'> + $ source ~/poky_sdk/environment-setup-i586-poky-linux + "SDK environment now set up; additionally you may now run devtool to perform development tasks. + Run devtool --help for further details. + </literallayout> + <note> + If you get a warning about attempting to use the + extensible SDK in an environment set up to run + BitBake, you did not use a new shell. + </note> + </para></listitem> + <listitem><para> + <emphasis>Build the Clean Image:</emphasis> + The final step in preparing to work on the kernel is to + build an initial image using + <filename>devtool</filename> in the new terminal you + just set up and initialized for SDK work: + <literallayout class='monospaced'> + $ devtool build-image + Parsing recipes: 100% |##########################################| Time: 0:00:05 + Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors. + WARNING: No packages to add, building image core-image-minimal unmodified + Loading cache: 100% |############################################| Time: 0:00:00 + Loaded 1299 entries from dependency cache. + NOTE: Resolving any missing task queue dependencies + Initializing tasks: 100% |#######################################| Time: 0:00:07 + Checking sstate mirror object availability: 100% |###############| Time: 0:00:00 + NOTE: Executing SetScene Tasks + NOTE: Executing RunQueue Tasks + NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded. + NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86 + </literallayout> + If you were building for actual hardware and not for + emulation, you could flash the image to a USB stick + on <filename>/dev/sdd</filename> and boot your device. + For an example that uses a Minnowboard, see the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink> + Wiki page. + </para></listitem> + </orderedlist> + </para> + + <para> + At this point you have set up to start making modifications to + the kernel by using the extensible SDK. + For a continued example, see the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + section. + </para> + </section> + + <section id='getting-ready-for-traditional-kernel-development'> + <title>Getting Ready for Traditional Kernel Development</title> + + <para> + Getting ready for traditional kernel development using the Yocto + Project involves many of the same steps as described in the + previous section. + However, you need to establish a local copy of the kernel source + since you will be editing these files. + </para> + + <para> + Follow these steps to prepare to update the kernel image using + traditional kernel development flow with the Yocto Project. + Completing this procedure leaves you ready to make modifications + to the kernel source as described in the + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + section: + <orderedlist> + <listitem><para> + <emphasis>Initialize the BitBake Environment:</emphasis> + Before you can do anything using BitBake, you need to + initialize the BitBake build environment by sourcing the + build environment script + (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>). + Also, for this example, be sure that the local branch + you have checked out for <filename>poky</filename> is + the Yocto Project &DISTRO_NAME; branch. + If you need to checkout out the &DISTRO_NAME; branch, + see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking out by Branch in Poky</ulink>" + section in the Yocto Project Development Tasks Manual. + <literallayout class='monospaced'> + $ cd ~/poky + $ git branch + master + * &DISTRO_NAME; + $ source oe-init-build-env + </literallayout> + <note> + The previous commands assume the + <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> + (i.e. <filename>poky</filename>) have been cloned + using Git and the local repository is named + "poky". + </note> + </para></listitem> + <listitem><para> + <emphasis>Prepare Your <filename>local.conf</filename> + File:</emphasis> + By default, the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable is set to "qemux86", which is fine if you are + building for the QEMU emulator in 32-bit mode. + However, if you are not, you need to set the + <filename>MACHINE</filename> variable appropriately in + your <filename>conf/local.conf</filename> file found + in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + (i.e. <filename>~/poky/build</filename> in this + example).</para> + + <para>Also, since you are preparing to work on the + kernel image, you need to set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> + variable to include kernel modules.</para> + + <para>This example uses the default "qemux86" for the + <filename>MACHINE</filename> variable but needs to + add the "kernel-modules": + <literallayout class='monospaced'> + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create a Layer for Patches:</emphasis> + You need to create a layer to hold patches created + for the kernel image. + You can use the + <filename>bitbake-layers create-layer</filename> + command as follows: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake-layers create-layer ../../meta-mylayer + NOTE: Starting bitbake server... + Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' + </literallayout> + <note> + For background information on working with + common and BSP layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Tasks + Manual and the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + section in the Yocto Project Board Support (BSP) + Developer's Guide, respectively. + For information on how to use the + <filename>bitbake-layers create-layer</filename> + command to quickly set up a layer, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" + section in the Yocto Project Development Tasks + Manual. + </note> + </para></listitem> + <listitem><para> + <emphasis>Inform the BitBake Build Environment About + Your Layer:</emphasis> + As directed when you created your layer, you need to add + the layer to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> + variable in the <filename>bblayers.conf</filename> file + as follows: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake-layers add-layer ../../meta-mylayer + NOTE: Starting bitbake server ... + $ + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create a Local Copy of the Kernel Git + Repository:</emphasis> + You can find Git repositories of supported Yocto Project + kernels organized under "Yocto Linux Kernel" in the + Yocto Project Source Repositories at + <ulink url='&YOCTO_GIT_URL;'></ulink>. + </para> + + <para> + For simplicity, it is recommended that you create your + copy of the kernel Git repository outside of the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>, + which is usually named <filename>poky</filename>. + Also, be sure you are in the + <filename>standard/base</filename> branch. + </para> + + <para> + The following commands show how to create a local copy + of the <filename>linux-yocto-4.12</filename> kernel and + be in the <filename>standard/base</filename> branch. + <note> + The <filename>linux-yocto-4.12</filename> kernel + can be used with the Yocto Project 2.4 release + and forward. + You cannot use the + <filename>linux-yocto-4.12</filename> kernel with + releases prior to Yocto Project 2.4: + </note> + <literallayout class='monospaced'> + $ cd ~ + $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base + Cloning into 'linux-yocto-4.12'... + remote: Counting objects: 6097195, done. + remote: Compressing objects: 100% (901026/901026), done. + remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256) + Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done. + Resolving deltas: 100% (5152604/5152604), done. + Checking connectivity... done. + Checking out files: 100% (59846/59846), done. + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create a Local Copy of the Kernel Cache Git + Repository:</emphasis> + For simplicity, it is recommended that you create your + copy of the kernel cache Git repository outside of the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>, + which is usually named <filename>poky</filename>. + Also, for this example, be sure you are in the + <filename>yocto-4.12</filename> branch. + </para> + + <para> + The following commands show how to create a local copy + of the <filename>yocto-kernel-cache</filename> and + be in the <filename>yocto-4.12</filename> branch: + <literallayout class='monospaced'> + $ cd ~ + $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12 + Cloning into 'yocto-kernel-cache'... + remote: Counting objects: 22639, done. + remote: Compressing objects: 100% (9761/9761), done. + remote: Total 22639 (delta 12400), reused 22586 (delta 12347) + Receiving objects: 100% (22639/22639), 22.34 MiB | 6.27 MiB/s, done. + Resolving deltas: 100% (12400/12400), done. + Checking connectivity... done. + </literallayout> + </para></listitem> + </orderedlist> + </para> + + <para> + At this point, you are ready to start making modifications to + the kernel using traditional kernel development steps. + For a continued example, see the + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + section. + </para> + </section> + </section> + + <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_REF_URL;#bitbake-term'>BitBake</ulink> + append files (<filename>.bbappend</filename>) and provides a + convenient mechanism to create your own recipe files + (<filename>.bb</filename>) as well as store and use kernel + patch files. + For background information on working with layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Tasks Manual. + <note><title>Tip</title> + The Yocto Project comes with many tools that simplify + tasks you need to perform. + One such tool is the + <filename>bitbake-layers create-layer</filename> + command, which simplifies creating a new layer. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" + section in the Yocto Project Development Tasks Manual for + information on how to use this script to quick set up a + new layer. + </note> + </para> + + <para> + To better understand the layer you create for kernel development, + the following section describes how to create a layer + without the aid of tools. + These steps assume creation of a layer named + <filename>mylayer</filename> in your home directory: + <orderedlist> + <listitem><para> + <emphasis>Create Structure</emphasis>: + Create the layer's structure: + <literallayout class='monospaced'> + $ cd $HOME + $ mkdir meta-mylayer + $ mkdir meta-mylayer/conf + $ mkdir meta-mylayer/recipes-kernel + $ mkdir meta-mylayer/recipes-kernel/linux + $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto + </literallayout> + The <filename>conf</filename> directory holds your + configuration files, while the + <filename>recipes-kernel</filename> directory holds your + append file and eventual patch files. + </para></listitem> + <listitem><para> + <emphasis>Create the Layer Configuration File</emphasis>: + Move to the <filename>meta-mylayer/conf</filename> + directory and create the <filename>layer.conf</filename> + file as follows: + <literallayout class='monospaced'> + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have recipes-* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "mylayer" + BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" + BBFILE_PRIORITY_mylayer = "5" + </literallayout> + Notice <filename>mylayer</filename> as part of the last + three statements. + </para></listitem> + <listitem><para> + <emphasis>Create the Kernel Recipe Append File</emphasis>: + Move to the + <filename>meta-mylayer/recipes-kernel/linux</filename> + directory and create the kernel's append file. + This example uses the + <filename>linux-yocto-4.12</filename> kernel. + Thus, the name of the append file is + <filename>linux-yocto_4.12.bbappend</filename>: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + SRC_URI_append += "file://<replaceable>patch-file-one</replaceable>" + SRC_URI_append += "file://<replaceable>patch-file-two</replaceable>" + SRC_URI_append += "file://<replaceable>patch-file-three</replaceable>" + </literallayout> + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statements enable the OpenEmbedded build system to find + patch files. + For more information on using append files, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" + section in the Yocto Project Development Tasks Manual. + </para></listitem> + </orderedlist> + </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_REF_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 information. + </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_4.12.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_4.12.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> + + <para> + As an example, consider the following append file + used by the BSPs in <filename>meta-yocto-bsp</filename>: + <literallayout class='monospaced'> + meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend + </literallayout> + The following listing shows the file. + Be aware that the actual commit ID strings in this + example listing might be different than the actual strings + in the file from the <filename>meta-yocto-bsp</filename> + layer upstream. + <literallayout class='monospaced'> + KBRANCH_genericx86 = "standard/base" + KBRANCH_genericx86-64 = "standard/base" + + KMACHINE_genericx86 ?= "common-pc" + KMACHINE_genericx86-64 ?= "common-pc-64" + KBRANCH_edgerouter = "standard/edgerouter" + KBRANCH_beaglebone = "standard/beaglebone" + KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb" + + SRCREV_machine_genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" + SRCREV_machine_genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" + SRCREV_machine_edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" + SRCREV_machine_beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" + SRCREV_machine_mpc8315e-rdb ?= "2d1d010240846d7bff15d1fcc0cb6eb8a22fc78a" + + + COMPATIBLE_MACHINE_genericx86 = "genericx86" + COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" + COMPATIBLE_MACHINE_edgerouter = "edgerouter" + COMPATIBLE_MACHINE_beaglebone = "beaglebone" + COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb" + + LINUX_VERSION_genericx86 = "4.12.7" + LINUX_VERSION_genericx86-64 = "4.12.7" + LINUX_VERSION_edgerouter = "4.12.10" + LINUX_VERSION_beaglebone = "4.12.10" + LINUX_VERSION_mpc8315e-rdb = "4.12.10" + </literallayout> + This append file contains statements used to support + several BSPs that ship with the Yocto Project. + The file defines machines using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink> + variable and uses the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> + variable to ensure the machine name used by the OpenEmbedded + build system maps to the machine name used by the Linux Yocto + kernel. + The file also uses the optional + <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> + variable to ensure the build process uses the + appropriate kernel branch. + </para> + + <para> + Although this particular example does not use it, the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> + variable could be used to enable features specific to + the kernel. + The append file points to specific commits in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + Git repository and the <filename>meta</filename> Git repository + branches to identify the exact kernel needed to build the + BSP. + </para> + + <para> + One thing missing in this particular BSP, which you will + typically need when developing a BSP, is the kernel + configuration file (<filename>.config</filename>) for your BSP. + When developing a BSP, you probably have a kernel configuration + file or a set of kernel configuration files that, when taken + together, define the kernel configuration for your BSP. + You can accomplish this definition by putting the configurations + in a file or a set of files inside a directory located at the + same level as your kernel's append file and having the same + name as the kernel's main recipe file. + With all these conditions met, simply reference those files in + the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement in the append file. + </para> + + <para> + For example, suppose you had some configuration options + in a file called <filename>network_configs.cfg</filename>. + You can place that file inside a directory named + <filename>linux-yocto</filename> and then add + a <filename>SRC_URI</filename> statement such as the + following to the append file. + When the OpenEmbedded build system builds the kernel, the + configuration options are picked up and applied. + <literallayout class='monospaced'> + SRC_URI += "file://network_configs.cfg" + </literallayout> + </para> + + <para> + To group related configurations into multiple files, you + perform a similar procedure. + Here is an example that groups separate configurations + specifically for Ethernet and graphics into their own + files and adds the configurations by using a + <filename>SRC_URI</filename> statement like the following + in your append file: + <literallayout class='monospaced'> + SRC_URI += "file://myconfig.cfg \ + file://eth.cfg \ + file://gfx.cfg" + </literallayout> + </para> + + <para> + Another variable you can use in your kernel recipe append + file is the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + variable. + When you use this statement, you are extending the locations + used by the OpenEmbedded system to look for files and + patches as the recipe is processed. + </para> + + <note> + <para> + Other methods exist to accomplish grouping and defining + configuration options. + For example, if you are working with a local clone of the + kernel repository, you could checkout the kernel's + <filename>meta</filename> branch, make your changes, and + then push the changes to the local bare clone of the + kernel. + The result is that you directly add configuration options + to the <filename>meta</filename> branch for your BSP. + The configuration options will likely end up in that + location anyway if the BSP gets added to the Yocto Project. + </para> + + <para> + In general, however, the Yocto Project maintainers take + care of moving the <filename>SRC_URI</filename>-specified + configuration options to the kernel's + <filename>meta</filename> branch. + Not only is it easier for BSP developers to not have to + worry about putting those configurations in the branch, + but having the maintainers do it allows them to apply + 'global' knowledge about the kinds of common configuration + options multiple BSPs in the tree are typically using. + This allows for promotion of common configurations into + common features. + </para> + </note> + </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 using + <filename>devtool</filename>, see the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + and + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + sections. + </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 + "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" + section. + </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, + use the following statement form: + <literallayout class='monospaced'> + KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable> + </literallayout> + Here is an example that appends the + <filename>KBUILD_DEFCONFIG</filename> variable with + "common-pc" and provides the path to the "in-tree" + <filename>defconfig</filename> file: + <literallayout class='monospaced'> + KBUILD_DEFCONFIG_common-pc ?= "/home/scottrif/configfiles/my_defconfig_file" + </literallayout> + </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-devtool-to-patch-the-kernel"> + <title>Using <filename>devtool</filename> to Patch the Kernel</title> + + <para> + The steps in this procedure show you how you can patch the + kernel using the extensible SDK and <filename>devtool</filename>. + <note> + Before attempting this procedure, be sure you have performed + the steps to get ready for updating the kernel as described + in the + "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" + section. + </note> + </para> + + <para> + Patching the kernel involves changing or adding configurations + to an existing kernel, changing or adding recipes to the kernel + that are needed to support specific hardware features, or even + altering the source code itself. + </para> + + <para> + This example creates a simple patch by adding some QEMU emulator + console output at boot time through <filename>printk</filename> + statements in the kernel's <filename>calibrate.c</filename> source + code file. + Applying the patch and booting the modified image causes the added + messages to appear on the emulator's console. + The example is a continuation of the setup procedure found in + the + "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" + Section. + <orderedlist> + <listitem><para> + <emphasis>Check Out the Kernel Source Files:</emphasis> + First you must use <filename>devtool</filename> to checkout + the kernel source code in its workspace. + Be sure you are in the terminal set up to do work + with the extensible SDK. + <note> + See this + <link linkend='setting-up-the-esdk-terminal'>step</link> + in the + "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" + section for more information. + </note> + Use the following <filename>devtool</filename> command + to check out the code: + <literallayout class='monospaced'> + $ devtool modify linux-yocto + </literallayout> + <note> + During the checkout operation, a bug exists that could + cause errors such as the following to appear: + <literallayout class='monospaced'> + ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus + be3a89ce7c47178880ba7bf6293d7404 for + /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack + </literallayout> + You can safely ignore these messages. + The source code is correctly checked out. + </note> + </para></listitem> + <listitem><para> + <emphasis>Edit the Source Files</emphasis> + Follow these steps to make some simple changes to the source + files: + <orderedlist> + <listitem><para> + <emphasis>Change the working directory</emphasis>: + In the previous step, the output noted where you can find + the source files (e.g. + <filename>~/poky_sdk/workspace/sources/linux-yocto</filename>). + Change to where the kernel source code is before making + your edits to the <filename>calibrate.c</filename> file: + <literallayout class='monospaced'> + $ cd ~/poky_sdk/workspace/sources/linux-yocto + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Edit the source file</emphasis>: + Edit the <filename>init/calibrate.c</filename> file to have + the following changes: + <literallayout class='monospaced'> + void calibrate_delay(void) + { + unsigned long lpj; + static bool printed; + int this_cpu = smp_processor_id(); + + printk("*************************************\n"); + printk("* *\n"); + printk("* HELLO YOCTO KERNEL *\n"); + printk("* *\n"); + printk("*************************************\n"); + + if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { + . + . + . + </literallayout> + </para></listitem> + </orderedlist> + </para></listitem> + <listitem><para> + <emphasis>Build the Updated Kernel Source:</emphasis> + To build the updated kernel source, use + <filename>devtool</filename>: + <literallayout class='monospaced'> + $ devtool build linux-yocto + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create the Image With the New Kernel:</emphasis> + Use the <filename>devtool build-image</filename> command + to create a new image that has the new kernel. + <note> + If the image you originally created resulted in a Wic + file, you can use an alternate method to create the new + image with the updated kernel. + For an example, see the steps in the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink> + Wiki Page. + </note> + <literallayout class='monospaced'> + $ cd ~ + $ devtool build-image core-image-minimal + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Test the New Image:</emphasis> + For this example, you can run the new image using QEMU + to verify your changes: + <orderedlist> + <listitem><para> + <emphasis>Boot the image</emphasis>: + Boot the modified image in the QEMU emulator + using this command: + <literallayout class='monospaced'> + $ runqemu qemux86 + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Verify the changes</emphasis>: + Log into the machine using <filename>root</filename> + with no password and then use the following shell + command to scroll through the console's boot output. + <literallayout class='monospaced'> + # dmesg | less + </literallayout> + You should see the results of your + <filename>printk</filename> statements + as part of the output when you scroll down the + console window. + </para></listitem> + </orderedlist> + </para></listitem> + <listitem><para> + <emphasis>Stage and commit your changes</emphasis>: + Within your eSDK terminal, change your working directory to + where you modified the <filename>calibrate.c</filename> + file and use these Git commands to stage and commit your + changes: + <literallayout class='monospaced'> + $ cd ~/poky_sdk/workspace/sources/linux-yocto + $ git status + $ git add init/calibrate.c + $ git commit -m "calibrate: Add printk example" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Export the Patches and Create an Append File:</emphasis> + To export your commits as patches and create a + <filename>.bbappend</filename> file, use the following + command in the terminal used to work with the extensible + SDK. + This example uses the previously established layer named + <filename>meta-mylayer</filename>. + <note> + See Step 3 of the + "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using devtool</link>" + section for information on setting up this layer. + </note> + <literallayout class='monospaced'> + $ devtool finish linux-yocto ~/meta-mylayer + </literallayout> + Once the command finishes, the patches and the + <filename>.bbappend</filename> file are located in the + <filename>~/meta-mylayer/recipes-kernel/linux</filename> + directory. + </para></listitem> + <listitem><para> + <emphasis>Build the Image With Your Modified Kernel:</emphasis> + You can now build an image that includes your kernel + patches. + Execute the following command from your + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + in the terminal set up to run BitBake: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake core-image-minimal + </literallayout> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id="using-traditional-kernel-development-to-patch-the-kernel"> + <title>Using Traditional Kernel Development to Patch the Kernel</title> + + <para> + The steps in this procedure show you how you can patch the + kernel using traditional kernel development (i.e. not using + <filename>devtool</filename> and the extensible SDK as + described in the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + section). + <note> + Before attempting this procedure, be sure you have performed + the steps to get ready for updating the kernel as described + in the + "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" + section. + </note> + </para> + + <para> + Patching the kernel involves changing or adding configurations + to an existing kernel, changing or adding recipes to the kernel + that are needed to support specific hardware features, or even + altering the source code itself. + </para> + + <para> + The example in this section creates a simple patch by adding some + QEMU emulator console output at boot time through + <filename>printk</filename> statements in the kernel's + <filename>calibrate.c</filename> source code file. + Applying the patch and booting the modified image causes the added + messages to appear on the emulator's console. + The example is a continuation of the setup procedure found in + the + "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" + Section. + <orderedlist> + <listitem><para> + <emphasis>Edit the Source Files</emphasis> + Prior to this step, you should have used Git to create a + local copy of the repository for your kernel. + Assuming you created the repository as directed in the + "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" + section, use the following commands to edit the + <filename>calibrate.c</filename> file: + <orderedlist> + <listitem><para> + <emphasis>Change the working directory</emphasis>: + You need to locate the source files in the + local copy of the kernel Git repository: + Change to where the kernel source code is before making + your edits to the <filename>calibrate.c</filename> file: + <literallayout class='monospaced'> + $ cd ~/linux-yocto-4.12/init + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Edit the source file</emphasis>: + Edit the <filename>calibrate.c</filename> file to have + the following changes: + <literallayout class='monospaced'> + void calibrate_delay(void) + { + unsigned long lpj; + static bool printed; + int this_cpu = smp_processor_id(); + + printk("*************************************\n"); + printk("* *\n"); + printk("* HELLO YOCTO KERNEL *\n"); + printk("* *\n"); + printk("*************************************\n"); + + if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { + . + . + . + </literallayout> + </para></listitem> + </orderedlist> + </para></listitem> + <listitem><para> + <emphasis>Stage and Commit Your Changes:</emphasis> + Use standard Git commands to stage and commit the changes + you just made: + <literallayout class='monospaced'> + $ git add calibrate.c + $ git commit -m "calibrate.c - Added some printk statements" + </literallayout> + If you do not stage and commit your changes, the OpenEmbedded + Build System will not pick up the changes. + </para></listitem> + <listitem><para> + <emphasis>Update Your <filename>local.conf</filename> File + to Point to Your Source Files:</emphasis> + In addition to your <filename>local.conf</filename> file + specifying to use "kernel-modules" and the "qemux86" + machine, it must also point to the updated kernel source + files. + Add + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> + statements similar to the following to your + <filename>local.conf</filename>: + <literallayout class='monospaced'> + $ cd ~/poky/build/conf + </literallayout> + Add the following to the <filename>local.conf</filename>: + <literallayout class='monospaced'> + SRC_URI_pn-linux-yocto = "git:///<replaceable>path-to</replaceable>/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ + git:///<replaceable>path-to</replaceable>/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" + SRCREV_meta_qemux86 = "${AUTOREV}" + SRCREV_machine_qemux86 = "${AUTOREV}" + </literallayout> + <note> + Be sure to replace + <replaceable>path-to</replaceable> with the pathname + to your local Git repositories. + Also, you must be sure to specify the correct branch + and machine types. + For this example, the branch is + <filename>standard/base</filename> and the machine is + "qemux86". + </note> + </para></listitem> + <listitem><para> + <emphasis>Build the Image:</emphasis> + With the source modified, your changes staged and + committed, and the <filename>local.conf</filename> file + pointing to the kernel files, you can now use BitBake to + build the image: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake core-image-minimal + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Boot the image</emphasis>: + Boot the modified image in the QEMU emulator + using this command. + When prompted to login to the QEMU console, use "root" + with no password: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ runqemu qemux86 + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Look for Your Changes:</emphasis> + As QEMU booted, you might have seen your changes rapidly + scroll by. + If not, use these commands to see your changes: + <literallayout class='monospaced'> + # dmesg | less + </literallayout> + You should see the results of your + <filename>printk</filename> statements + as part of the output when you scroll down the + console window. + </para></listitem> + <listitem><para> + <emphasis>Generate the Patch File:</emphasis> + Once you are sure that your patch works correctly, you + can generate a <filename>*.patch</filename> file in the + kernel source repository: + <literallayout class='monospaced'> + $ cd ~/linux-yocto-4.12/init + $ git format-patch -1 + 0001-calibrate.c-Added-some-printk-statements.patch + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Move the Patch File to Your Layer:</emphasis> + In order for subsequent builds to pick up patches, you + need to move the patch file you created in the previous + step to your layer <filename>meta-mylayer</filename>. + For this example, the layer created earlier is located + in your home directory as <filename>meta-mylayer</filename>. + When the layer was created using the + <filename>yocto-create</filename> script, no additional + hierarchy was created to support patches. + Before moving the patch file, you need to add additional + structure to your layer using the following commands: + <literallayout class='monospaced'> + $ cd ~/meta-mylayer + $ mkdir recipes-kernel + $ mkdir recipes-kernel/linux + $ mkdir recipes-kernel/linux/linux-yocto + </literallayout> + Once you have created this hierarchy in your layer, you can + move the patch file using the following command: + <literallayout class='monospaced'> + $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create the Append File:</emphasis> + Finally, you need to create the + <filename>linux-yocto_4.12.bbappend</filename> file and + insert statements that allow the OpenEmbedded build + system to find the patch. + The append file needs to be in your layer's + <filename>recipes-kernel/linux</filename> + directory and it must be named + <filename>linux-yocto_4.12.bbappend</filename> and have + the following contents: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + SRC_URI_append = " file://0001-calibrate.c-Added-some-printk-statements.patch" + </literallayout> + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statements enable the OpenEmbedded build system to find + the patch file.</para> + + <para>For more information on append files and patches, + see the + "<link linkend='creating-the-append-file'>Creating the Append File</link>" + and + "<link linkend='applying-patches'>Applying Patches</link>" + sections. + You can also see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer"</ulink>" + section in the Yocto Project Development Tasks Manual. + <note> + To build <filename>core-image-minimal</filename> + again and see the effects of your patch, you can + essentially eliminate the temporary source files + saved in <filename>poky/build/tmp/work/...</filename> + and residual effects of the build by entering the + following sequence of commands: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake -c cleanall yocto-linux + $ bitbake core-image-minimal -c cleanall + $ bitbake core-image-minimal + $ runqemu qemux86 + </literallayout> + </note> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='configuring-the-kernel'> + <title>Configuring the Kernel</title> + + <para> + Configuring the Yocto Project kernel consists of making sure the + <filename>.config</filename> file has all the right information + in it for the image you are building. + You can use the <filename>menuconfig</filename> tool and + configuration fragments to make sure your + <filename>.config</filename> file is just how you need it. + You can also save known configurations in a + <filename>defconfig</filename> file that the build system can use + for kernel configuration. + </para> + + <para> + This section describes how to use <filename>menuconfig</filename>, + create and use configuration fragments, and how to interactively + modify your <filename>.config</filename> file to create the + leanest kernel configuration file possible. + </para> + + <para> + For more information on kernel configuration, see the + "<link linkend='changing-the-configuration'>Changing the Configuration</link>" + section. + </para> + + <section id='using-menuconfig'> + <title>Using <filename>menuconfig</filename></title> + + <para> + The easiest way to define kernel configurations is to set + them through the <filename>menuconfig</filename> tool. + This tool provides an interactive method with which + to set kernel configurations. + For general information on <filename>menuconfig</filename>, see + <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>. + </para> + + <para> + To use the <filename>menuconfig</filename> tool in the Yocto + Project development environment, you must launch it using + BitBake. + Thus, the environment must be set up using the + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + script found in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. + You must also be sure of the state of your build's + configuration in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. + The following commands initialize the BitBake environment, + run the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink> + task, and launch <filename>menuconfig</filename>. + These commands assume the Source Directory's top-level folder + is <filename>~/poky</filename>: + <literallayout class='monospaced'> + $ cd poky + $ source oe-init-build-env + $ bitbake linux-yocto -c kernel_configme -f + $ bitbake linux-yocto -c menuconfig + </literallayout> + Once <filename>menuconfig</filename> comes up, its standard + interface allows you to interactively examine and configure + all the kernel configuration parameters. + After making your changes, simply exit the tool and save your + changes to create an updated version of the + <filename>.config</filename> configuration file. + <note> + You can use the entire <filename>.config</filename> file + as the <filename>defconfig</filename> file. + For information on <filename>defconfig</filename> files, + see the + "<link linkend='changing-the-configuration'>Changing the Configuration</link>", + "<link linkend='using-an-in-tree-defconfig-file'>Using an In-Tree <filename>defconfig</filename> File</link>, + and + "<link linkend='creating-a-defconfig-file'>Creating a <filename>defconfig</filename> File</link>" + sections. + </note> + </para> + + <para> + Consider an example that configures the "CONFIG_SMP" setting + for the <filename>linux-yocto-4.12</filename> kernel. + <note> + The OpenEmbedded build system recognizes this kernel as + <filename>linux-yocto</filename> through Metadata (e.g. + <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink><filename>_linux-yocto ?= "12.4%"</filename>). + </note> + Once <filename>menuconfig</filename> launches, use the + interface to navigate through the selections to find the + configuration settings in which you are interested. + For this example, you deselect "CONFIG_SMP" by clearing the + "Symmetric Multi-Processing Support" option. + Using the interface, you can find the option under + "Processor Type and Features". + To deselect "CONFIG_SMP", use the arrow keys to + highlight "Symmetric Multi-Processing Support" and enter "N" + to clear the asterisk. + When you are finished, exit out and save the change. + </para> + + <para> + Saving the selections updates the <filename>.config</filename> + configuration file. + This is the file that the OpenEmbedded build system uses to + configure the kernel during the build. + You can find and examine this file in the Build Directory in + <filename>tmp/work/</filename>. + The actual <filename>.config</filename> is located in the + area where the specific kernel is built. + For example, if you were building a Linux Yocto kernel based + on the <filename>linux-yocto-4.12</filename> kernel and you + were building a QEMU image targeted for + <filename>x86</filename> architecture, the + <filename>.config</filename> file would be: + <literallayout class='monospaced'> + poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18... + ...967-r0/linux-qemux86-standard-build/.config + </literallayout> + <note> + The previous example directory is artificially split and + many of the characters in the actual filename are omitted + in order to make it more readable. + Also, depending on the kernel you are using, the exact + pathname might differ. + </note> + </para> + + <para> + Within the <filename>.config</filename> file, you can see the + kernel settings. + For example, the following entry shows that symmetric + multi-processor support is not set: + <literallayout class='monospaced'> + # CONFIG_SMP is not set + </literallayout> + </para> + + <para> + A good method to isolate changed configurations is to use a + combination of the <filename>menuconfig</filename> tool and + simple shell commands. + Before changing configurations with + <filename>menuconfig</filename>, copy the existing + <filename>.config</filename> and rename it to something else, + use <filename>menuconfig</filename> to make as many changes as + you want and save them, then compare the renamed configuration + file against the newly created file. + You can use the resulting differences as your base to create + configuration fragments to permanently save in your kernel + layer. + <note> + Be sure to make a copy of the <filename>.config</filename> + file and do not just rename it. + The build system needs an existing + <filename>.config</filename> file from which to work. + </note> + </para> + </section> + + <section id='creating-a-defconfig-file'> + <title>Creating a <filename>defconfig</filename> File</title> + + <para> + A <filename>defconfig</filename> file is simply a + <filename>.config</filename> renamed to "defconfig". + You can use a <filename>defconfig</filename> file + to retain a known set of kernel configurations from which the + OpenEmbedded build system can draw to create the final + <filename>.config</filename> file. + <note> + Out-of-the-box, the Yocto Project never ships a + <filename>defconfig</filename> or + <filename>.config</filename> file. + The OpenEmbedded build system creates the final + <filename>.config</filename> file used to configure the + kernel. + </note> + </para> + + <para> + To create a <filename>defconfig</filename>, start with a + complete, working Linux kernel <filename>.config</filename> + file. + Copy that file to the appropriate + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> + directory in your layer's + <filename>recipes-kernel/linux</filename> directory, and rename + the copied file to "defconfig" (e.g. + <filename>~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig</filename>). + 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 + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + 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. + <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 defconfig file configurations. + </note> + For more information on configuring the kernel, see the + "<link linkend='changing-the-configuration'>Changing the Configuration</link>" + section. + </para> + </section> + + <section id='creating-config-fragments'> + <title>Creating Configuration Fragments</title> + + <para> + Configuration fragments are simply kernel options that + appear in a file placed where the OpenEmbedded build system + can find and apply them. + The build system applies configuration fragments after + applying configurations from a <filename>defconfig</filename> + file. + Thus, the final kernel configuration is a combination of the + configurations in the <filename>defconfig</filename> + file and then any configuration fragments you provide. + The build system applies fragments on top of and + after applying the existing defconfig file configurations. + </para> + + <para> + Syntactically, the configuration statement is identical to + what would appear in the <filename>.config</filename> file, + which is in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. + <note> + For more information about where the + <filename>.config</filename> file is located, see the + example in the + "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>" + section. + </note> + </para> + + <para> + It is simple to create a configuration fragment. + One method is to use shell commands. + For example, issuing the following from the shell creates a + configuration fragment file named + <filename>my_smp.cfg</filename> that enables multi-processor + support within the kernel: + <literallayout class='monospaced'> + $ echo "CONFIG_SMP=y" >> my_smp.cfg + </literallayout> + <note> + All configuration fragment files must use the + <filename>.cfg</filename> extension in order for the + OpenEmbedded build system to recognize them as a + configuration fragment. + </note> + </para> + + <para> + Another 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> + <emphasis>Complete a Build Through Kernel Configuration:</emphasis> + 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 create a + <filename>.config</filename> file from a known state. + Because situations exist where your build state might + become unknown, it is best to run this task prior + to starting <filename>menuconfig</filename>. + </para></listitem> + <listitem><para> + <emphasis>Launch <filename>menuconfig</filename>:</emphasis> + Run the <filename>menuconfig</filename> command: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c menuconfig + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create the Configuration Fragment:</emphasis> + Run the <filename>diffconfig</filename> + command to prepare a configuration fragment. + The resulting file <filename>fragment.cfg</filename> + is 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 additional 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> + Where do you put your configuration fragment files? + You can place these files in an area pointed to by + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + as directed by your <filename>bblayers.conf</filename> file, + which is located in your layer. + The OpenEmbedded build system picks up the configuration and + adds it to the kernel's configuration. + For example, suppose you had a set of configuration options + in a file called <filename>myconfig.cfg</filename>. + If you put that file inside a directory named + <filename>linux-yocto</filename> that resides in the same + directory as the kernel's append file within your layer + and then add the following statements to the kernel's append + file, those configuration options will be picked up and applied + when the kernel is built: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + SRC_URI += "file://myconfig.cfg" + </literallayout> + </para> + + <para> + As mentioned earlier, you can group related configurations + into multiple files and name them all in the + <filename>SRC_URI</filename> statement as well. + For example, you could group separate configurations + specifically for Ethernet and graphics into their own files + and add those by using a <filename>SRC_URI</filename> statement + like the following in your append file: + <literallayout class='monospaced'> + SRC_URI += "file://myconfig.cfg \ + file://eth.cfg \ + file://gfx.cfg" + </literallayout> + </para> + </section> + + <section id='validating-configuration'> + <title>Validating Configuration</title> + + <para> + You can use the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink> + task to provide configuration validation: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c kernel_configcheck -f + </literallayout> + Running this task produces 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. + </para> + + <para> + In order to run this task, you must have an existing + <filename>.config</filename> file. + See the + "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>" + section for information on how to create a configuration file. + </para> + + <para> + Following is sample output from the + <filename>do_kernel_configcheck</filename> task: + <literallayout class='monospaced'> + Loading cache: 100% |########################################################| Time: 0:00:00 + Loaded 1275 entries from dependency cache. + NOTE: Resolving any missing task queue dependencies + + Build Configuration: + . + . + . + + NOTE: Executing SetScene Tasks + NOTE: Executing RunQueue Tasks + WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck: + [kernel config]: specified values did not make it into the kernel's final configuration: + + ---------- CONFIG_X86_TSC ----------------- + Config: CONFIG_X86_TSC + From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg + Requested value: CONFIG_X86_TSC=y + Actual value: + + + ---------- CONFIG_X86_BIGSMP ----------------- + Config: CONFIG_X86_BIGSMP + From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg + /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig + Requested value: # CONFIG_X86_BIGSMP is not set + Actual value: + + + ---------- CONFIG_NR_CPUS ----------------- + Config: CONFIG_NR_CPUS + From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg + /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg + /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig + Requested value: CONFIG_NR_CPUS=8 + Actual value: CONFIG_NR_CPUS=1 + + + ---------- CONFIG_SCHED_SMT ----------------- + Config: CONFIG_SCHED_SMT + From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg + /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig + Requested value: CONFIG_SCHED_SMT=y + Actual value: + + + + NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded. + + Summary: There were 3 WARNING messages shown. + </literallayout> + <note> + The previous output example has artificial line breaks + to make it more readable. + </note> + </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 + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink> + tasks until they produce no warnings. + </para> + + <para> + For more information on how to use the + <filename>menuconfig</filename> tool, see the + "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>" + section. + </para> + </section> + + <section id='fine-tuning-the-kernel-configuration-file'> + <title>Fine-Tuning the Kernel Configuration File</title> + + <para> + You can make sure the <filename>.config</filename> file is as + lean or efficient as possible by reading the output of the + kernel configuration fragment audit, noting any issues, making + changes to correct the issues, and then repeating. + </para> + + <para> + As part of the kernel build process, the + <filename>do_kernel_configcheck</filename> task runs. + This task validates the kernel configuration by checking the + final <filename>.config</filename> file against the input + files. + During the check, the task produces warning messages for the + following issues: + <itemizedlist> + <listitem><para> + Requested options that did not make the final + <filename>.config</filename> file. + </para></listitem> + <listitem><para> + Configuration items that appear twice in the same + configuration fragment. + </para></listitem> + <listitem><para> + Configuration items tagged as "required" that were + overridden. + </para></listitem> + <listitem><para> + A board overrides a non-board specific option. + </para></listitem> + <listitem><para> + Listed options not valid for the kernel being + processed. + In other words, the option does not appear anywhere. + </para></listitem> + </itemizedlist> + <note> + The <filename>do_kernel_configcheck</filename> task can + also optionally report if an option is overridden during + processing. + </note> + </para> + + <para> + For each output warning, a message points to the file + that contains a list of the options and a pointer to the + configuration fragment that defines them. + Collectively, the files are the key to streamlining the + configuration. + </para> + + <para> + To streamline the configuration, do the following: + <orderedlist> + <listitem><para> + <emphasis>Use a Working Configuration:</emphasis> + Start with a full configuration that you + know works. + Be sure the configuration builds and boots + successfully. + Use this configuration file as your baseline. + </para></listitem> + <listitem><para> + <emphasis>Run Configure and Check Tasks:</emphasis> + Separately run the + <filename>do_kernel_configme</filename> and + <filename>do_kernel_configcheck</filename> tasks: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c kernel_configme -f + $ bitbake linux-yocto -c kernel_configcheck -f + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Process the Results:</emphasis> + Take the resulting list of files from the + <filename>do_kernel_configcheck</filename> task + warnings and do the following: + <itemizedlist> + <listitem><para> + Drop values that are redefined in the fragment + but do not change the final + <filename>.config</filename> file. + </para></listitem> + <listitem><para> + Analyze and potentially drop values from the + <filename>.config</filename> file that override + required configurations. + </para></listitem> + <listitem><para> + Analyze and potentially remove non-board + specific options. + </para></listitem> + <listitem><para> + Remove repeated and invalid options. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Re-Run Configure and Check Tasks:</emphasis> + After you have worked through the output of the kernel + configuration audit, you can re-run the + <filename>do_kernel_configme</filename> and + <filename>do_kernel_configcheck</filename> tasks to + see the results of your changes. + If you have more issues, you can deal with them as + described in the previous step. + </para></listitem> + </orderedlist> + </para> + + <para> + Iteratively working through steps two through four eventually + yields a minimal, streamlined configuration file. + Once you have the best <filename>.config</filename>, you can + build the Linux Yocto kernel. + </para> + </section> + </section> + + <section id='expanding-variables'> + <title>Expanding Variables</title> + + <para> + Sometimes it is helpful to determine what a variable expands + to during a build. + You can do examine the values of variables by examining the + output of the <filename>bitbake -e</filename> command. + The output is long and is more easily managed in a text file, + which allows for easy searches: + <literallayout class='monospaced'> + $ bitbake -e virtual/kernel > <replaceable>some_text_file</replaceable> + </literallayout> + Within the text file, you can see exactly how each variable is + expanded and used by the OpenEmbedded build system. + </para> + </section> + + <section id='working-with-a-dirty-kernel-version-string'> + <title>Working with a "Dirty" Kernel Version String</title> + + <para> + If you build a kernel image and the version string has a + "+" or a "-dirty" at the end, uncommitted modifications exist + in the kernel's source directory. + Follow these steps to clean up the version string: + <orderedlist> + <listitem><para> + <emphasis>Discover the Uncommitted Changes:</emphasis> + Go to the kernel's locally cloned Git repository + (source directory) and use the following Git command + to list the files that have been changed, added, or + removed: + <literallayout class='monospaced'> + $ git status + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Commit the Changes:</emphasis> + You should commit those changes to the kernel source + tree regardless of whether or not you will save, + export, or use the changes: + <literallayout class='monospaced'> + $ git add + $ git commit -s -a -m "getting rid of -dirty" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Rebuild the Kernel Image:</emphasis> + Once you commit the changes, rebuild the kernel.</para> + + <para>Depending on your particular kernel development + workflow, the commands you use to rebuild the + kernel might differ. + For information on building the kernel image when + using <filename>devtool</filename>, see the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + section. + For information on building the kernel image when + using Bitbake, see the + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + section. + </para></listitem> + </orderedlist> + </para> + </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_REF_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> + <emphasis>Create a Copy of the Kernel Recipe:</emphasis> + 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 Yocto Linux + kernel you are using (e.g. + <filename>linux-yocto-myproject_4.12.bb</filename>, + where "4.12" is the base version of the Linux kernel + with which you would be working). + </para></listitem> + <listitem><para> + <emphasis>Create a Directory for Your Patches:</emphasis> + 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> + <emphasis>Ensure You Have Configurations:</emphasis> + Make sure you have either a <filename>defconfig</filename> + file or configuration fragment files in your layer. + 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> file to the + <filename>files</filename> directory in your layer + 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.</para> + + <para>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> + <emphasis>Edit the Recipe:</emphasis> + 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. + "4.12"). + </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> + <emphasis>Customize Your Recipe as Needed:</emphasis> + 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='&YOCTO_GIT_URL;'></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> + + <section id='adding-recipe-space-kernel-features'> + <title>Adding Recipe-Space Kernel Features</title> + + <para> + You can add kernel features in the + <link linkend='recipe-space-metadata'>recipe-space</link> by + using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> + variable and by specifying the feature's <filename>.scc</filename> + file path in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement. + When you add features using this method, the OpenEmbedded build + system checks to be sure the features are present. + If the features are not present, the build stops. + Kernel features are the last elements processed for configuring + and patching the kernel. + Therefore, adding features in this manner is a way + to enforce specific features are present and enabled + without needing to do a full audit of any other layer's additions + to the <filename>SRC_URI</filename> statement. + </para> + + <para> + You add a kernel feature by providing the feature as part of the + <filename>KERNEL_FEATURES</filename> variable and by providing the + path to the feature's <filename>.scc</filename> file, which is + relative to the root of the kernel Metadata. + The OpenEmbedded build system searches all forms of kernel + Metadata on the <filename>SRC_URI</filename> statement regardless + of whether the Metadata is in the "kernel-cache", system kernel + Metadata, or a recipe-space Metadata (i.e. part of the kernel + recipe). + See the + "<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>" + section for additional information. + </para> + + <para> + When you specify the feature's <filename>.scc</filename> file + on the <filename>SRC_URI</filename> statement, the OpenEmbedded + build system adds the directory of that + <filename>.scc</filename> file along with all its subdirectories + to the kernel feature search path. + Because subdirectories are searched, you can reference a single + <filename>.scc</filename> file in the + <filename>SRC_URI</filename> statement to reference multiple kernel + features. + </para> + + <para> + Consider the following example that adds the "test.scc" feature + to the build. + <orderedlist> + <listitem><para> + <emphasis>Create the Feature File:</emphasis> + Create a <filename>.scc</filename> file and locate it + just as you would any other patch file, + <filename>.cfg</filename> file, or fetcher item + you specify in the <filename>SRC_URI</filename> + statement. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + You must add the directory of the + <filename>.scc</filename> file to the fetcher's + search path in the same manner as you would + add a <filename>.patch</filename> file. + </para></listitem> + <listitem><para> + You can create additional + <filename>.scc</filename> files beneath the + directory that contains the file you are + adding. + All subdirectories are searched during the + build as potential feature directories. + </para></listitem> + </itemizedlist> + </note> + Continuing with the example, suppose the "test.scc" + feature you are adding has a + <filename>test.scc</filename> file in the following + directory: + <literallayout class='monospaced'> + <replaceable>my_recipe</replaceable> + | + +-linux-yocto + | + +-test.cfg + +-test.scc + </literallayout> + In this example, the <filename>linux-yocto</filename> + directory has both the feature + <filename>test.scc</filename> file and a similarly + named configuration fragment file + <filename>test.cfg</filename>. + </para></listitem> + <listitem><para> + <emphasis>Add the Feature File to <filename>SRC_URI</filename>:</emphasis> + Add the <filename>.scc</filename> file to the + recipe's <filename>SRC_URI</filename> statement: + <literallayout class='monospaced'> + SRC_URI_append = " file://test.scc" + </literallayout> + The leading space before the path is important as the + path is appended to the existing path. + </para></listitem> + <listitem><para> + <emphasis>Specify the Feature as a Kernel Feature:</emphasis> + Use the <filename>KERNEL_FEATURES</filename> statement + to specify the feature as a kernel feature: + <literallayout class='monospaced'> + KERNEL_FEATURES_append = " test.scc" + </literallayout> + The OpenEmbedded build system processes the kernel feature + when it builds the kernel. + <note> + If other features are contained below "test.scc", + then their directories are relative to the directory + containing the <filename>test.scc</filename> file. + </note> + </para></listitem> + </orderedlist> + </para> + </section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml new file mode 100644 index 000000000..6d675a6d5 --- /dev/null +++ b/poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml @@ -0,0 +1,622 @@ +<!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 (Yocto Linux kernels), + like other kernels, are based off the Linux kernel releases from + <ulink url='http://www.kernel.org'></ulink>. + At the beginning of a major Linux kernel development cycle, the + Yocto Project team chooses a Linux 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 Linux kernel chosen is in the final stages of + development by the Linux community. + In other words, the Linux kernel is in the release candidate + or "rc" phase and has yet to reach 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 Yocto Project team to deliver the most + up-to-date Yocto Linux kernel possible, while still ensuring that + the team has a stable official release for the baseline Linux + kernel version. + </para> + + <para> + As implied earlier, the ultimate source for Yocto Linux kernels + are released kernels from <filename>kernel.org</filename>. + In addition to a foundational kernel from + <filename>kernel.org</filename>, the available Yocto Linux kernels + contain a mix of important new mainline developments, non-mainline + developments (when no alternative exists), 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> + You can find a web interface to the Yocto Linux kernels in the + <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> + at + <ulink url='&YOCTO_GIT_URL;'></ulink>. + If you look at the interface, you will see to the left a + grouping of Git repositories titled "Yocto Linux Kernel". + Within this group, you will find several Linux Yocto kernels + developed and included with Yocto Project releases: + <itemizedlist> + <listitem><para> + <emphasis><filename>linux-yocto-4.1</filename>:</emphasis> + The stable Yocto Project kernel to use with the Yocto + Project Release 2.0. + This kernel is based on the Linux 4.1 released kernel. + </para></listitem> + <listitem><para> + <emphasis><filename>linux-yocto-4.4</filename>:</emphasis> + The stable Yocto Project kernel to use with the Yocto + Project Release 2.1. + This kernel is based on the Linux 4.4 released kernel. + </para></listitem> + <listitem><para> + <emphasis><filename>linux-yocto-4.6</filename>:</emphasis> + A temporary kernel that is not tied to any Yocto Project + release. + </para></listitem> + <listitem><para> + <emphasis><filename>linux-yocto-4.8</filename>:</emphasis> + The stable yocto Project kernel to use with the Yocto + Project Release 2.2. + </para></listitem> + <listitem><para> + <emphasis><filename>linux-yocto-4.9</filename>:</emphasis> + The stable Yocto Project kernel to use with the Yocto + Project Release 2.3. + This kernel is based on the Linux 4.9 released kernel. + </para></listitem> + <listitem><para> + <emphasis><filename>linux-yocto-4.10</filename>:</emphasis> + The default stable Yocto Project kernel to use with the + Yocto Project Release 2.3. + This kernel is based on the Linux 4.10 released kernel. + </para></listitem> + <listitem><para> + <emphasis><filename>linux-yocto-4.12</filename>:</emphasis> + The default stable Yocto Project kernel to use with the + Yocto Project Release 2.4. + This kernel is based on the Linux 4.12 released kernel. + </para></listitem> + <listitem><para> + <emphasis><filename>yocto-kernel-cache</filename>:</emphasis> + The <filename>linux-yocto-cache</filename> contains + patches and configurations for the linux-yocto kernel + tree. + This repository is useful when working on the linux-yocto + kernel. + For more information on this "Advanced Kernel Metadata", + see the + "<link linkend='kernel-dev-advanced'>Working With Advanced Metadata (<filename>yocto-kernel-cache</filename>)</link>" + Chapter. + </para></listitem> + <listitem><para> + <emphasis><filename>linux-yocto-dev</filename>:</emphasis> + A development kernel based on the latest upstream release + candidate available. + </para></listitem> + </itemizedlist> + <note><title>Notes</title> + Long Term Support Initiative (LTSI) for Yocto Linux + kernels is as follows: + <itemizedlist> + <listitem><para> + For Yocto Project releases 1.7, 1.8, and 2.0, + the LTSI kernel is + <filename>linux-yocto-3.14</filename>. + </para></listitem> + <listitem><para> + For Yocto Project releases 2.1, 2.2, and 2.3, + the LTSI kernel is <filename>linux-yocto-4.1</filename>. + </para></listitem> + <listitem><para> + For Yocto Project release 2.4, the LTSI kernel is + <filename>linux-yocto-4.9</filename> + </para></listitem> + <listitem><para> + <filename>linux-yocto-4.4</filename> is an LTS + kernel. + </para></listitem> + </itemizedlist> + </note> + </para> + + <para> + Once a Yocto Linux 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 Linux kernel development, BSP support, and release + timing to select the best possible <filename>kernel.org</filename> + Linux kernel version on which to base subsequent Yocto Linux + kernel development. + The team continually monitors Linux 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 Linux kernel both adds features and + introduces new bugs. + These consequences are the basic properties of upstream + Linux kernel development and are managed by the Yocto Project + team's Yocto Linux kernel development strategy. + It is the Yocto Project team's policy to not back-port minor + features to the released Yocto Linux 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 Linux kernel can easily + create mismatches, incompatibilities and very subtle errors. + </para> + + <para> + The policies described in this section result in both a stable + and a cutting edge Yocto Linux kernel that mixes forward ports of + existing Linux kernel features and significant and critical new + functionality. + Forward porting Linux kernel functionality into the Yocto Linux + kernels available through the Yocto Project can be thought of as + a "micro uprev." + The many “micro uprevs” produce a Yocto Linux kernel version with + a mix of important new mainline, non-mainline, BSP developments + and feature integrations. + This Yocto Linux 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 Yocto Linux kernels is evolving + and the kernels are used in leading edge feature and BSP + development. + </para> + </section> + + <section id='yocto-linux-kernel-architecture-and-branching-strategies'> + <title>Yocto Linux Kernel Architecture and Branching Strategies</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, in particular the branching + strategies, used achieve that goal in a manner similar to + upstream Linux kernel development in + <filename>kernel.org</filename>. + </para> + + <para> + You can think of a Yocto Linux 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 Yocto Project team using the + Source Code Manager (SCM) Git. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + Git is the obvious SCM for meeting the Yocto Linux + kernel organizational and structural goals described + in this section. + Not only is Git the SCM for Linux kernel development in + <filename>kernel.org</filename> but, Git continues to + grow in popularity and supports many different work + flows, front-ends and management techniques. + </para></listitem> + <listitem><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_OM_URL;#git'>Git</ulink>" + section in the Yocto Project Overview and Concepts + Manual. + The latter reference provides an overview of + Git and presents a minimal set of Git commands + that allows you to be functional using Git. + You can use as much, or as little, of what Git + has to offer to accomplish what you need for your + project. + You do not have to be a "Git Expert" in order to + use it with the Yocto Project. + </para></listitem> + </itemizedlist> + </note> + </para> + + <para> + Using Git's tagging and branching features, 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 "tree-like" architecture results in a structure that has + features organized to be specific for particular functionality, + single kernel types, or a subset of kernel types. + Thus, 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 + Linux kernel. + </para> + + <para> + Another consequence of this strategy 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 features 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 kernel 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 + in Git terms. + The developer does not need to be aware of the existence of any + other branches at all. + Of course, value exists in the having 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> + The following illustration shows the conceptual Yocto + Linux kernel. + <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 Linux kernel release) from which the + Yocto Linux kernel is created. + From this point forward 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 along in the tree. + Placing these common features in the tree this way means + features do not have to be duplicated along individual + branches of the tree structure. + </para> + + <para> + From the "Yocto Project Baseline Kernel", branch points represent + specific functionality for individual Board Support Packages + (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 for a real-time Yocto Linux kernel. + </para> + + <para> + In this example structure, the "Real-time (rt) Kernel" branch has + common features for all real-time Yocto Linux 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 Yocto Linux kernel needed for any given set of + requirements. + <note> + Keep in mind the figure does not take into account all the + supported Yocto Linux kernels, but rather shows a single + generic kernel just for conceptual purposes. + Also keep in mind that this structure represents the Yocto + Project + <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> + that are either pulled from during the build or established + on the host development system prior to the build by either + cloning a particular kernel's Git repository or by + downloading and unpacking a tarball. + </note> + </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 Linux + 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='kernel-build-file-hierarchy'> + <title>Kernel Build File Hierarchy</title> + + <para> + Upstream storage of all the available kernel source code is + one thing, while representing and using the code on your host + development system is another. + Conceptually, you can think of the kernel source repositories + as all the source files necessary for all the supported + Yocto Linux kernels. + As a developer, you are just interested in the source files + for the kernel on which you are working. + And, furthermore, you need them available on your host system. + </para> + + <para> + Kernel source code is available on your host system several + different ways: + <itemizedlist> + <listitem><para> + <emphasis>Files Accessed While using <filename>devtool</filename>:</emphasis> + <filename>devtool</filename>, which is available with the + Yocto Project, is the preferred method by which to + modify the kernel. + See the + "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>" + section. + </para></listitem> + <listitem><para> + <emphasis>Cloned Repository:</emphasis> + If you are working in the kernel all the time, you probably + would want to set up your own local Git repository of the + Yocto Linux kernel tree. + For information on how to clone a Yocto Linux kernel + Git repository, see the + "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>" + section. + </para></listitem> + <listitem><para> + <emphasis>Temporary Source Files from a Build:</emphasis> + If you just need to make some patches to the kernel using + a traditional BitBake workflow (i.e. not using the + <filename>devtool</filename>), you can access temporary + kernel source files that were extracted and used during + a kernel build. + </para></listitem> + </itemizedlist> + </para> + + <para> + The temporary kernel source files resulting from a build using + BitBake have a particular hierarchy. + When you build the kernel on your development system, all files + needed for the build are taken from the source repositories + pointed to by the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable and gathered in a temporary work area where they are + subsequently used to create the unique kernel. + Thus, in a sense, the process constructs a local source tree + specific to your kernel from which to generate the new kernel + image. + </para> + + <para> + The following figure shows the temporary file structure + created on your host system when you build the kernel using + Bitbake. + This + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + contains all the source files used during the build. + <imagedata fileref="figures/kernel-overview-2-generic.png" + width="6in" depth="5in" align="center" scale="100" /> + </para> + + <para> + Again, for additional information on the Yocto Project kernel's + architecture and its branching strategy, see the + "<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>" + section. + You can also reference the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + and + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + sections for detailed example that modifies the kernel. + </para> + </section> + + <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'> + <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title> + + <para> + This section describes part of the kernel configuration audit + phase that most developers can ignore. + For general information on kernel configuration including + <filename>menuconfig</filename>, <filename>defconfig</filename> + files, and configuration fragments, see the + "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" + section. + </para> + + <para> + During this part of the audit phase, the contents of the final + <filename>.config</filename> file are compared against the + fragments specified by the system. + These fragments can be system fragments, distro fragments, + or user-specified configuration elements. + Regardless of their origin, the OpenEmbedded build system + warns the user if a specific option is not included in the + final kernel configuration. + </para> + + <para> + By default, in order to not overwhelm the user with + configuration warnings, the system only reports missing + "hardware" options as they could result in a boot + failure or indicate that important hardware is not available. + </para> + + <para> + To determine whether or not a given option is "hardware" or + "non-hardware", the kernel Metadata in + <filename>yocto-kernel-cache</filename> contains files that + classify individual or groups of options as either hardware + or non-hardware. + To better show this, consider a situation where the + <filename>yocto-kernel-cache</filename> contains the following + files: + <literallayout class='monospaced'> + yocto-kernel-cache/features/drm-psb/hardware.cfg + yocto-kernel-cache/features/kgdb/hardware.cfg + yocto-kernel-cache/ktypes/base/hardware.cfg + yocto-kernel-cache/bsp/mti-malta32/hardware.cfg + yocto-kernel-cache/bsp/fsl-mpc8315e-rdb/hardware.cfg + yocto-kernel-cache/bsp/qemu-ppc32/hardware.cfg + yocto-kernel-cache/bsp/qemuarma9/hardware.cfg + yocto-kernel-cache/bsp/mti-malta64/hardware.cfg + yocto-kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg + yocto-kernel-cache/bsp/common-pc/hardware.cfg + yocto-kernel-cache/bsp/common-pc-64/hardware.cfg + yocto-kernel-cache/features/rfkill/non-hardware.cfg + yocto-kernel-cache/ktypes/base/non-hardware.cfg + yocto-kernel-cache/features/aufs/non-hardware.kcf + yocto-kernel-cache/features/ocf/non-hardware.kcf + yocto-kernel-cache/ktypes/base/non-hardware.kcf + yocto-kernel-cache/ktypes/base/hardware.kcf + yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf + </literallayout> + The following list provides explanations for the various + files: + <itemizedlist> + <listitem><para> + <filename>hardware.kcf</filename>: + Specifies a list of kernel Kconfig files that contain + hardware options only. + </para></listitem> + <listitem><para> + <filename>non-hardware.kcf</filename>: + Specifies a list of kernel Kconfig files that contain + non-hardware options only. + </para></listitem> + <listitem><para> + <filename>hardware.cfg</filename>: + Specifies a list of kernel <filename>CONFIG_</filename> + options that are hardware, regardless of whether or not + they are within a Kconfig file specified by a hardware + or non-hardware Kconfig file (i.e. + <filename>hardware.kcf</filename> or + <filename>non-hardware.kcf</filename>). + </para></listitem> + <listitem><para> + <filename>non-hardware.cfg</filename>: + Specifies a list of kernel <filename>CONFIG_</filename> + options that are not hardware, regardless of whether or + not they are within a Kconfig file specified by a + hardware or non-hardware Kconfig file (i.e. + <filename>hardware.kcf</filename> or + <filename>non-hardware.kcf</filename>). + </para></listitem> + </itemizedlist> + Here is a specific example using the + <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>: + <literallayout class='monospaced'> + CONFIG_SERIAL_8250 + CONFIG_SERIAL_8250_CONSOLE + CONFIG_SERIAL_8250_NR_UARTS + CONFIG_SERIAL_8250_PCI + CONFIG_SERIAL_CORE + CONFIG_SERIAL_CORE_CONSOLE + CONFIG_VGA_ARB + </literallayout> + The kernel configuration audit automatically detects these + files (hence the names must be exactly the ones discussed here), + and uses them as inputs when generating warnings about the + final <filename>.config</filename> file. + </para> + + <para> + A user-specified kernel Metadata repository, or recipe space + feature, can use these same files to classify options that are + found within its <filename>.cfg</filename> files as hardware + or non-hardware, to prevent the OpenEmbedded build system from + producing an error or warning when an option is not in the + final <filename>.config</filename> file. + </para> + </section> +</appendix> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/poky/documentation/kernel-dev/kernel-dev-customization.xsl b/poky/documentation/kernel-dev/kernel-dev-customization.xsl new file mode 100644 index 000000000..325b738e9 --- /dev/null +++ b/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/poky/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl b/poky/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl new file mode 100644 index 000000000..3c56a5a9e --- /dev/null +++ b/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/poky/documentation/kernel-dev/kernel-dev-faq.xml b/poky/documentation/kernel-dev/kernel-dev-faq.xml new file mode 100644 index 000000000..c3a20465a --- /dev/null +++ b/poky/documentation/kernel-dev/kernel-dev-faq.xml @@ -0,0 +1,142 @@ +<!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='creating-config-fragments'>Creating Configuration Fragments</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 in Your Layer</ulink>" + section in the Yocto Project Development Tasks 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/poky/documentation/kernel-dev/kernel-dev-intro.xml b/poky/documentation/kernel-dev/kernel-dev-intro.xml new file mode 100644 index 000000000..4e4fd282a --- /dev/null +++ b/poky/documentation/kernel-dev/kernel-dev-intro.xml @@ -0,0 +1,259 @@ +<!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> + +<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 describes how to set up your build host to support + kernel development, introduces the kernel development process, + provides background information on the Yocto Linux kernel + <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>, + describes common tasks you can perform using the kernel tools, + shows you how to use the kernel Metadata needed to work with + the kernel inside the Yocto Project, and provides insight into how + the Yocto Project team develops and maintains Yocto Linux kernel + Git repositories and Metadata. + </para> + + <para> + Each Yocto Project release has a set of Yocto Linux kernel 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 Linux kernel + upstream developments from + <ulink url='http://www.kernel.org'></ulink> and introduce + newly-supported platforms. + Previous recipes in the release are refreshed and supported for at + least one additional Yocto Project release. + As they align, these previous releases are updated to include the + latest from the Long Term Support Initiative (LTSI) project. + You can learn more about Yocto Linux kernels and LTSI in the + "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>" + section. + </para> + + <para> + Also included is a Yocto Linux kernel development recipe + (<filename>linux-yocto-dev.bb</filename>) should you want to work + with the very latest in upstream Yocto Linux kernel development and + kernel Metadata development. + <note> + For more on Yocto Linux kernels, see the + "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link> + section. + </note> + </para> + + <para> + The Yocto Project also provides a powerful set of kernel + tools for managing Yocto 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 + Yocto Linux kernel <filename>menuconfig</filename> system. + Contrast this against a complete Yocto Linux kernel + <filename>.config</filename> file, 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 Yocto Linux kernel + recipes, an alternative exists by which you can use the Yocto + Project Linux kernel tools with your own kernel sources. + </para> + + <para> + The remainder of this manual provides 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_BRIEF_URL;'>Yocto Project Quick Build</ulink> + document. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink> + as described in the Yocto Project Application Development and + the Extensible Software Development Kit (eSDK) 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 Tasks Manual. + </para></listitem> + <listitem><para> + The + "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>" + section. + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='kernel-modification-workflow'> + <title>Kernel Modification Workflow</title> + + <para> + Kernel modification involves changing the Yocto Project kernel, + which could involve changing configuration options as well as adding + new kernel recipes. + Configuration changes can be added in the form of configuration + fragments, while recipe modification comes through the kernel's + <filename>recipes-kernel</filename> area in a kernel layer you create. + </para> + + <para> + This section presents a high-level overview of the Yocto Project + kernel modification workflow. + The illustration and accompanying list provide general information + and references for further information. + <imagedata fileref="figures/kernel-dev-flow.png" + width="9in" depth="5in" align="center" scalefit="1" /> + </para> + + <para> + <orderedlist> + <listitem><para> + + + <emphasis>Set up Your Host Development System to Support + Development Using the Yocto Project</emphasis>: + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-start'>Setting Up the Development Host to Use the Yocto Project</ulink>" + section in the Yocto Project Development Tasks Manual for + options on how to get a build host ready to use the Yocto + Project. + </para></listitem> + <listitem><para> + <emphasis>Set Up Your Host Development System for Kernel Development:</emphasis> + It is recommended that you use <filename>devtool</filename> + and an extensible SDK for kernel development. + Alternatively, you can use traditional kernel development + methods with the Yocto Project. + Either way, there are steps you need to take to get the + development environment ready.</para> + + <para>Using <filename>devtool</filename> and the eSDK requires + that you have a clean build of the image and that you are + set up with the appropriate eSDK. + For more information, see the + "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" + section.</para> + + <para>Using traditional kernel development requires that you + have the kernel source available in an isolated local Git + repository. + For more information, see the + "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" + section. + </para></listitem> + <listitem><para> + <emphasis>Make Changes to the Kernel Source Code if + applicable:</emphasis> + Modifying the kernel does not always mean directly + changing source files. + However, if you have to do this, you make the changes to the + files in the eSDK's Build Directory if you are using + <filename>devtool</filename>. + For more information, see the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + section.</para> + + <para>If you are using traditional kernel development, you + edit the source files in the kernel's local Git repository. + For more information, see the + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + section. + </para></listitem> + <listitem><para> + <emphasis>Make Kernel Configuration Changes if + Applicable:</emphasis> + If your situation calls for changing the kernel's + configuration, you can use + <link linkend='using-menuconfig'><filename>menuconfig</filename></link>, + which allows you to interactively develop and test the + configuration changes you are making to the kernel. + Saving changes you make with <filename>menuconfig</filename> + updates the kernel's <filename>.config</filename> file. + <note><title>Warning</title> + Try to resist the temptation to directly edit an + existing <filename>.config</filename> file, which is + found in the Build Directory among the source code + used for the build. + Doing so, can produce unexpected results when the + OpenEmbedded build system regenerates the configuration + file. + </note> + Once you are satisfied with the configuration + changes made using <filename>menuconfig</filename> + and you have saved them, you can directly compare the + resulting <filename>.config</filename> file against an + existing original and gather those changes into a + <link linkend='creating-config-fragments'>configuration fragment file</link> + to be referenced from within the kernel's + <filename>.bbappend</filename> file.</para> + + <para>Additionally, if you are working in a BSP layer + and need to modify the BSP's kernel's configuration, + you can use <filename>menuconfig</filename>. + </para></listitem> + <listitem><para> + <emphasis>Rebuild the Kernel Image With Your Changes:</emphasis> + Rebuilding the kernel image applies your changes. + Depending on your target hardware, you can verify your changes + on actual hardware or perhaps QEMU. + </para></listitem> + </orderedlist> + The remainder of this developer's guide covers common tasks typically + used during kernel development, advanced Metadata usage, and Yocto Linux + kernel maintenance concepts. + </para> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/poky/documentation/kernel-dev/kernel-dev-maint-appx.xml b/poky/documentation/kernel-dev/kernel-dev-maint-appx.xml new file mode 100644 index 000000000..b825ae7ea --- /dev/null +++ b/poky/documentation/kernel-dev/kernel-dev-maint-appx.xml @@ -0,0 +1,356 @@ +<!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 Yocto Linux kernel repositories. + These kernel repositories are found under the heading "Yocto Linux + Kernel" at + <ulink url='&YOCTO_GIT_URL;'>&YOCTO_GIT_URL;</ulink> + and are 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, + configurations, branches, tags, and feature divisions found in a + Yocto Linux kernel. + Thus, the Yocto Project Linux kernel repository (or tree) and + accompanying Metadata in the + <filename>yocto-kernel-cache</filename> are built. + </para> + + <para> + The existence of these repositories allow you to access and clone a + particular Yocto Project Linux 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 Linux kernel in any clone of the Yocto + Project Linux kernel source repository and + <filename>yocto-kernel-cache</filename> Git trees. + For example, the following commands clone the Yocto Project + baseline Linux kernel that branches off + <filename>linux.org</filename> version 4.12 and the + <filename>yocto-kernel-cache</filename>, which contains stores of + kernel Metadata: + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/linux-yocto-4.12 + $ git clone git://git.yoctoproject.org/linux-kernel-cache + </literallayout> + For more information on how to set up a local Git repository of + the Yocto Project Linux kernel files, see the + "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>" + section. + </para> + + <para> + Once you have cloned the kernel Git repository and the + cache of Metadata on your local machine, you can discover the + branches that are available in the repository using the following + Git command: + <literallayout class='monospaced'> + $ git branch -a + </literallayout> + Checking out a branch allows you to work with a particular + Yocto Linux kernel. + For example, the following commands check out the + "standard/beagleboard" branch of the Yocto Linux kernel repository + and the "yocto-4.12" branch of the + <filename>yocto-kernel-cache</filename> repository: + <literallayout class='monospaced'> + $ cd ~/linux-yocto-4.12 + $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard + $ cd ~/linux-kernel-cache + $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12 + </literallayout> + <note> + Branches in the <filename>yocto-kernel-cache</filename> + repository correspond to Yocto Linux kernel versions + (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth). + </note> + Once you have checked out and switched to appropriate branches, + you can see a snapshot of all the kernel source files used to + used to build that particular Yocto Linux kernel for a + particular board. + </para> + + <para> + To see the features and configurations for a particular Yocto + Linux kernel, you need to examine the + <filename>yocto-kernel-cache</filename> Git repository. + As mentioned, branches in the + <filename>yocto-kernel-cache</filename> repository correspond to + Yocto Linux kernel versions (e.g. <filename>yocto-4.12</filename>). + Branches contain descriptions in the form of + <filename>.scc</filename> and <filename>.cfg</filename> files. + </para> + + <para> + You should realize, however, that browsing your local + <filename>yocto-kernel-cache</filename> 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;'></ulink> given the + introduction of a new top-level kernel feature or BSP. + The following actions effectively provide the Metadata + and create the tree that includes the new feature, patch, or BSP: + <orderedlist> + <listitem><para> + <emphasis>Pass Feature to the OpenEmbedded Build System:</emphasis> + 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> + <emphasis>Locate Feature:</emphasis> + 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 the + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink> + repository organized under the "Yocto Linux Kernel" + heading in the + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>. + </para></listitem> + <listitem><para> + Areas pointed to by <filename>SRC_URI</filename> + statements found in kernel 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 (e.g. + <filename>beaglebone-standard.scc</filename> and + <filename>beaglebone-preempt-rt.scc</filename>): + <literallayout class='monospaced'> + <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Expand Feature:</emphasis> + Once located, the feature description is either expanded + into a simple script of actions, or into an existing + equivalent script that is already part of the shipped + kernel. + </para></listitem> + <listitem><para> + <emphasis>Append Extra Features:</emphasis> + 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> + <emphasis>Locate, Expand, and Append Each Feature:</emphasis> + Each extra feature is located, expanded and appended to + the script as described in step three. + </para></listitem> + <listitem><para> + <emphasis>Execute the Script:</emphasis> + The script is executed to produce files + <filename>.scc</filename> and <filename>.cfg</filename> + files in appropriate directories of the + <filename>yocto-kernel-cache</filename> repository. + These files 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> + <emphasis>Clone Base Repository:</emphasis> + The base repository is cloned, and the actions + listed in the <filename>yocto-kernel-cache</filename> + directories are applied to the tree. + </para></listitem> + <listitem><para> + <emphasis>Perform Cleanup:</emphasis> + The Git repositories are left with the desired branches + checked out and any required branching, patching and + tagging has been performed. + </para></listitem> + </orderedlist> + </para> + + <para> + The kernel tree and cache are ready for developer consumption to + be locally cloned, configured, and built into a Yocto Project + kernel specific to some target hardware. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + The generated <filename>yocto-kernel-cache</filename> + repository adds to the kernel as shipped with the Yocto + Project release. + Any add-ons and configuration data are applied to the + end of an existing branch. + The full repository generation that is found in the + official Yocto Project kernel repositories at + <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink> + is the combination of all supported boards and + configurations. + </para></listitem> + <listitem><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></listitem> + <listitem><para> + The full kernel tree that you see on + <ulink url='&YOCTO_GIT_URL;'></ulink> is + generated through repeating the above steps for all + valid BSPs. + The end result is a branched, clean history tree that + makes up the kernel for a given release. + You can see the script (<filename>kgit-scc</filename>) + responsible for this in the + <ulink url='&YOCTO_GIT_URL;/cgit.cgi/yocto-kernel-tools/tree/tools'><filename>yocto-kernel-tools</filename></ulink> + repository. + </para></listitem> + <listitem><para> + The steps used to construct the full kernel tree are + the same steps that BitBake uses when it builds a + kernel image. + </para></listitem> + </itemizedlist> + </note> + </para> + </section> + + <section id='build-strategy'> + <title>Build Strategy</title> + + <para> + Once you have cloned a Yocto Linux kernel repository and the + cache repository (<filename>yocto-kernel-cache</filename>) onto + your development system, you can consider the compilation phase + of kernel development, which is 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 with Metadata exists in the + <filename>yocto-kernel-cache</filename> repository. + The branch is based on the Yocto Linux kernel version and + has configurations and features grouped under the + <filename>yocto-kernel-cache/bsp</filename> directory. + For example, features and configurations for the + BeagleBone Board assuming a + <filename>linux-yocto_4.12</filename> kernel reside in the + following area of the <filename>yocto-kernel-cache</filename> + repository: + <literallayout class='monospaced'> + yocto-kernel-cache/bsp/beaglebone + </literallayout> + <note> + In the previous example, the "yocto-4.12" branch is + checked out in the <filename>yocto-kernel-cache</filename> + repository. + </note> + </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 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_REF_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/poky/documentation/kernel-dev/kernel-dev-style.css b/poky/documentation/kernel-dev/kernel-dev-style.css new file mode 100644 index 000000000..9c01aa798 --- /dev/null +++ b/poky/documentation/kernel-dev/kernel-dev-style.css @@ -0,0 +1,988 @@ +/* + 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; +} + +.writernotes { + color: red; +} + + + /*********** / + / 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/poky/documentation/kernel-dev/kernel-dev.xml b/poky/documentation/kernel-dev/kernel-dev.xml new file mode 100644 index 000000000..986c44044 --- /dev/null +++ b/poky/documentation/kernel-dev/kernel-dev.xml @@ -0,0 +1,170 @@ +<!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>Scott</firstname> <surname>Rifenbark</surname> + <affiliation> + <orgname>Scotty's Documentation Services, INC</orgname> + </affiliation> + <email>srifenbark@gmail.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>2.0</revnumber> + <date>October 2015</date> + <revremark>Released with the Yocto Project 2.0 Release.</revremark> + </revision> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.4</revnumber> + <date>October 2017</date> + <revremark>Released with the Yocto Project 2.4 Release.</revremark> + </revision> + <revision> + <revnumber>2.5</revnumber> + <date>May 2018</date> + <revremark>Released with the Yocto Project 2.5 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><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + This version of the + <emphasis>Yocto Project Linux Kernel Development Manual</emphasis> + is for the &YOCTO_DOC_VERSION; release of the + Yocto Project. + To be sure you have the latest version of the manual + for this release, go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and select the manual from that site. + Manuals from the site are more up-to-date than manuals + derived from the Yocto Project released TAR files. + </para></listitem> + <listitem><para> + If you located this manual through a web search, the + version of the manual might not be the one you want + (e.g. the search might have returned a manual much + older than the Yocto Project version with which you + are working). + You can see all Yocto Project major releases by + visiting the + <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink> + page. + If you need a version of this manual for a different + Yocto Project release, visit the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and select the manual set by using the + "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE" + pull-down menus. + </para></listitem> + <listitem><para> + To report any inaccuracies or problems with this + manual, send an email to the Yocto Project + discussion group at + <filename>yocto@yoctoproject.com</filename> or log into + the freenode <filename>#yocto</filename> channel. + </para></listitem> + </itemizedlist> + </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-faq.xml"/> + +<!-- <index id='index'> + <title>Index</title> + </index> +--> + +</book> +<!-- +vim: expandtab tw=80 ts=4 +--> |