| <!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; ] > |
| <!--SPDX-License-Identifier: CC-BY-2.0-UK--> |
| |
| <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 |
| --> |