diff options
Diffstat (limited to 'poky/documentation/kernel-dev/kernel-dev-advanced.xml')
| -rw-r--r-- | poky/documentation/kernel-dev/kernel-dev-advanced.xml | 1256 |
1 files changed, 1256 insertions, 0 deletions
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 +--> |
