diff options
Diffstat (limited to 'yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml')
| -rw-r--r-- | yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml | 1101 |
1 files changed, 0 insertions, 1101 deletions
diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml deleted file mode 100644 index 9e15f178a..000000000 --- a/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml +++ /dev/null @@ -1,1101 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > - -<chapter id='kernel-dev-advanced'> -<title>Working with Advanced Metadata</title> - -<section id='kernel-dev-advanced-overview'> - <title>Overview</title> - - <para> - In addition to supporting configuration fragments and patches, the - Yocto Project kernel tools also support rich - <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> that you can - use to define complex policies and Board Support Package (BSP) support. - The purpose of the Metadata and the tools that manage it, known as - the kern-tools (<filename>kern-tools-native_git.bb</filename>), is - to help you manage the complexity of the configuration and sources - used to support multiple BSPs and Linux kernel types. - </para> -</section> - -<section id='using-kernel-metadata-in-a-recipe'> - <title>Using Kernel Metadata in a Recipe</title> - - <para> - The kernel sources in the Yocto Project contain kernel Metadata, which - is located in the <filename>meta</filename> branches of the kernel - source Git repositories. - This Metadata defines Board Support Packages (BSPs) that - correspond to definitions in linux-yocto recipes for the same BSPs. - A BSP consists of an aggregation of kernel policy and enabled - hardware-specific features. - The BSP can be influenced from within the linux-yocto recipe. - <note> - Linux kernel source that contains kernel Metadata is said to be - "linux-yocto style" kernel source. - A Linux kernel recipe that inherits from the - <filename>linux-yocto.inc</filename> include file is said to be a - "linux-yocto style" recipe. - </note> - </para> - - <para> - Every linux-yocto style recipe must define the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> - variable. - This variable is typically set to the same value as the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable, which is used by - <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>. - However, in some cases, the variable might instead refer to the - underlying platform of the <filename>MACHINE</filename>. - </para> - - <para> - Multiple BSPs can reuse the same <filename>KMACHINE</filename> - name if they are built using the same BSP description. - The "ep108-zynqmp" and "qemuzynqmp" BSP combination - in the <filename>meta-xilinx</filename> - layer is a good example of two BSPs using the same - <filename>KMACHINE</filename> value (i.e. "zynqmp"). - See the <link linkend='bsp-descriptions'>BSP Descriptions</link> section - for more information. - </para> - - <para> - Every linux-yocto style recipe must also indicate the Linux kernel - source repository branch used to build the Linux kernel. - The <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> - variable must be set to indicate the branch. - <note> - You can use the <filename>KBRANCH</filename> value to define an - alternate branch typically with a machine override as shown here - from the <filename>meta-emenlow</filename> layer: - <literallayout class='monospaced'> - KBRANCH_emenlow-noemgd = "standard/base" - </literallayout> - </note> - </para> - - <para> - The linux-yocto style recipes can optionally define the following - variables: - <literallayout class='monospaced'> - <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink> - <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink> - </literallayout> - </para> - - <para> - <filename>LINUX_KERNEL_TYPE</filename> defines the kernel type to be - used in assembling the configuration. - If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>, - it defaults to "standard". - Together with - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, - <filename>LINUX_KERNEL_TYPE</filename> defines the search - arguments used by the kernel tools to find the - appropriate description within the kernel Metadata with which to - build out the sources and configuration. - The linux-yocto recipes define "standard", "tiny", and "preempt-rt" - kernel types. - See the "<link linkend='kernel-types'>Kernel Types</link>" section - for more information on kernel types. - </para> - - <para> - During the build, the kern-tools search for the BSP description - file that most closely matches the <filename>KMACHINE</filename> - and <filename>LINUX_KERNEL_TYPE</filename> variables passed in from the - recipe. - The tools use the first BSP description it finds that match - both variables. - If the tools cannot find a match, they issue a warning such as - the following: - <literallayout class='monospaced'> - WARNING: Can't find any BSP hardware or required configuration fragments. - WARNING: Looked at meta/cfg/broken/emenlow-broken/hdw_frags.txt and - meta/cfg/broken/emenlow-broken/required_frags.txt in directory: - meta/cfg/broken/emenlow-broken - </literallayout> - In this example, <filename>KMACHINE</filename> was set to "emenlow-broken" - and <filename>LINUX_KERNEL_TYPE</filename> was set to "broken". - </para> - - <para> - The tools first search for the <filename>KMACHINE</filename> and - then for the <filename>LINUX_KERNEL_TYPE</filename>. - If the tools cannot find a partial match, they will use the - sources from the <filename>KBRANCH</filename> and any configuration - specified in the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. - </para> - - <para> - You can use the <filename>KERNEL_FEATURES</filename> variable - to include features (configuration fragments, patches, or both) that - are not already included by the <filename>KMACHINE</filename> and - <filename>LINUX_KERNEL_TYPE</filename> variable combination. - For example, to include a feature specified as - "features/netfilter/netfilter.scc", - specify: - <literallayout class='monospaced'> - KERNEL_FEATURES += "features/netfilter/netfilter.scc" - </literallayout> - To include a feature called "cfg/sound.scc" just for the - <filename>qemux86</filename> machine, specify: - <literallayout class='monospaced'> - KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" - </literallayout> - The value of the entries in <filename>KERNEL_FEATURES</filename> - are dependent on their location within the kernel Metadata itself. - The examples here are taken from the <filename>meta</filename> - branch of the <filename>linux-yocto-3.19</filename> repository. - Within that branch, "features" and "cfg" are subdirectories of the - <filename>meta/cfg/kernel-cache</filename> directory. - For more information, see the - "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section. - <note> - The processing of the these variables has evolved some between the - 0.9 and 1.3 releases of the Yocto Project and associated - kern-tools sources. - The descriptions in this section are accurate for 1.3 and later - releases of the Yocto Project. - </note> - </para> -</section> - -<section id='kernel-metadata-location'> - <title>Kernel Metadata Location</title> - - <para> - Kernel Metadata 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> - </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 "ktype=meta" 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.4.bb</filename> - kernel recipe: - <literallayout class='monospaced'> - SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.4.git;name=machine;branch=${KBRANCH}; \ - git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.4;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. - </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> - Following is an example that shows how a trivial tree of Metadata - is stored in a custom Linux kernel Git repository: - <literallayout class='monospaced'> - meta/ - `‐‐ cfg - `‐‐ kernel-cache - |‐‐ bsp-standard.scc - |‐‐ bsp.cfg - `‐‐ standard.cfg - </literallayout> - </para> - - <para> - To use a branch different from where the sources reside, - specify the branch in the <filename>KMETA</filename> variable - in your Linux kernel recipe. - Here is an example: - <literallayout class='monospaced'> - KMETA = "meta" - </literallayout> - To use the same branch as the sources, set - <filename>KMETA</filename> to an empty string: - <literallayout class='monospaced'> - KMETA = "" - </literallayout> - If you are working with your own sources and want to create an - orphan <filename>meta</filename> branch, use these commands - from within your Linux kernel Git repository: - <literallayout class='monospaced'> - $ git checkout ‐‐orphan meta - $ git rm -rf . - $ git commit ‐‐allow-empty -m "Create orphan meta branch" - </literallayout> - </para> ---> - - <para> - If you modify the Metadata, you must not forget to update the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> - statements in the kernel's recipe. - In particular, you need to update the - <filename>SRCREV_meta</filename> variable to match the commit in - the <filename>KMETA</filename> branch you wish to use. - Changing the data in these branches and not updating the - <filename>SRCREV</filename> statements to match will cause the - build to fetch an older commit. - </para> - </section> -</section> - -<section id='kernel-metadata-syntax'> - <title>Kernel Metadata Syntax</title> - - <para> - The kernel Metadata consists of three primary types of files: - <filename>scc</filename> - <footnote> - <para> - <filename>scc</filename> stands for Series Configuration - Control, but the naming has less significance in the - current implementation of the tooling than it had in the - past. - Consider <filename>scc</filename> files to be description files. - </para> - </footnote> - description files, configuration fragments, and patches. - The <filename>scc</filename> files define variables and include or - otherwise reference any of the three file types. - The description files are used to aggregate all types of kernel - Metadata into - what ultimately describes the sources and the configuration required - to build a Linux kernel tailored to a specific machine. - </para> - - <para> - The <filename>scc</filename> description files are used to define two - fundamental types of kernel Metadata: - <itemizedlist> - <listitem><para>Features</para></listitem> - <listitem><para>Board Support Packages (BSPs)</para></listitem> - </itemizedlist> - </para> - - <para> - Features aggregate sources in the form of patches and configuration - fragments into a modular reusable unit. - You can use features to implement conceptually separate kernel - Metadata descriptions such as pure configuration fragments, - simple patches, complex features, and kernel types. - <link linkend='kernel-types'>Kernel types</link> define general - kernel features and policy to be reused in the BSPs. - </para> - - <para> - BSPs define hardware-specific features and aggregate them with kernel - types to form the final description of what will be assembled and built. - </para> - - <para> - While the kernel Metadata syntax does not enforce any logical - separation of configuration fragments, patches, features or kernel - types, best practices dictate a logical separation of these types - of Metadata. - The following Metadata file hierarchy is recommended: - <literallayout class='monospaced'> - <replaceable>base</replaceable>/ - bsp/ - cfg/ - features/ - ktypes/ - patches/ - </literallayout> - </para> - - <para> - The <filename>bsp</filename> directory contains the - <link linkend='bsp-descriptions'>BSP descriptions</link>. - The remaining directories all contain "features". - Separating <filename>bsp</filename> from the rest of the structure - aids conceptualizing intended usage. - </para> - - <para> - Use these guidelines to help place your <filename>scc</filename> - description files within the structure: - <itemizedlist> - <listitem><para>If your file contains - only configuration fragments, place the file in the - <filename>cfg</filename> directory.</para></listitem> - <listitem><para>If your file contains - only source-code fixes, place the file in the - <filename>patches</filename> directory.</para></listitem> - <listitem><para>If your file encapsulates - a major feature, often combining sources and configurations, - place the file in <filename>features</filename> directory. - </para></listitem> - <listitem><para>If your file aggregates - non-hardware configuration and patches in order to define a - base kernel policy or major kernel type to be reused across - multiple BSPs, place the file in <filename>ktypes</filename> - directory. - </para></listitem> - </itemizedlist> - </para> - - <para> - These distinctions can easily become blurred - especially as - out-of-tree features slowly merge upstream over time. - Also, remember that how the description files are placed is - a purely logical organization and has no impact on the functionality - of the kernel Metadata. - There is no impact because all of <filename>cfg</filename>, - <filename>features</filename>, <filename>patches</filename>, and - <filename>ktypes</filename>, contain "features" as far as the kernel - tools are concerned. - </para> - - <para> - Paths used in kernel Metadata files are relative to - <filename><base></filename>, which is either - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - if you are creating Metadata in - <link linkend='recipe-space-metadata'>recipe-space</link>, - or <filename>meta/cfg/kernel-cache/</filename> if you are creating - <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> - The Symmetric Multi-Processing (SMP) fragment included in the - <filename>linux-yocto-3.19</filename> Git repository - consists of the following two files: - <literallayout class='monospaced'> - cfg/smp.scc: - define KFEATURE_DESCRIPTION "Enable SMP" - define KFEATURE_COMPATIBILITY all - - kconf hardware smp.cfg - - cfg/smp.cfg: - CONFIG_SMP=y - CONFIG_SCHED_SMT=y - # Increase default NR_CPUS from 8 to 64 so that platform with - # more than 8 processors can be all activated at boot time - CONFIG_NR_CPUS=64 - </literallayout> - You can find information on configuration fragment files in the - "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>" - section of the Yocto Project Development Manual and in - the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" - section earlier in this manual. - </para> - - <para> - <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink> - provides a short description of the fragment. - Higher level kernel tools use this description. - </para> - - <para> - The <filename>kconf</filename> command is used to include the - actual configuration fragment in an <filename>.scc</filename> - file, and the "hardware" keyword identifies the fragment as - being hardware enabling, as opposed to general policy, - which would use the "non-hardware" keyword. - The distinction is made for the benefit of the configuration - validation tools, which warn you if a hardware fragment - overrides a policy set by a non-hardware fragment. - <note> - The description file can include multiple - <filename>kconf</filename> statements, one per fragment. - </note> - </para> - - <para> - As described in the - "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" - section, you can use the following BitBake command to audit your - configuration: - <literallayout class='monospaced'> - $ bitbake linux-yocto -c kernel_configcheck -f - </literallayout> - </para> - </section> - - <section id='patches'> - <title>Patches</title> - - <para> - Patch descriptions are very similar to configuration fragment - descriptions, which are described in the previous section. - However, instead of a <filename>.cfg</filename> file, these - descriptions work with source patches. - </para> - - <para> - A typical patch includes a description file and the patch itself: - <literallayout class='monospaced'> - patches/mypatch.scc: - patch mypatch.patch - - patches/mypatch.patch: - <replaceable>typical-patch</replaceable> - </literallayout> - You can create the typical <filename>.patch</filename> - file using <filename>diff -Nurp</filename> or - <filename>git format-patch</filename>. - </para> - - <para> - The description file can include multiple patch statements, - one per patch. - </para> - </section> - - <section id='features'> - <title>Features</title> - - <para> - Features are complex kernel Metadata types that consist - of configuration fragments (<filename>kconf</filename>), patches - (<filename>patch</filename>), and possibly other feature - description files (<filename>include</filename>). - </para> - - <para> - Here is an example that shows a feature description file: - <literallayout class='monospaced'> - features/myfeature.scc - define KFEATURE_DESCRIPTION "Enable myfeature" - - patch 0001-myfeature-core.patch - patch 0002-myfeature-interface.patch - - include cfg/myfeature_dependency.scc - kconf non-hardware myfeature.cfg - </literallayout> - This example shows how the <filename>patch</filename> and - <filename>kconf</filename> commands are used as well as - how an additional feature description file is included. - </para> - - <para> - Typically, features are less granular than configuration - fragments and are more likely than configuration fragments - and patches to be the types of things you want to specify - in the <filename>KERNEL_FEATURES</filename> variable of the - Linux kernel recipe. - See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>" - section earlier in the manual. - </para> - </section> - - <section id='kernel-types'> - <title>Kernel Types</title> - - <para> - A kernel type defines a high-level kernel policy by - aggregating non-hardware configuration fragments with - patches you want to use when building a Linux kernels of a - specific type. - Syntactically, kernel types are no different than features - as described in the "<link linkend='features'>Features</link>" - section. - The <filename>LINUX_KERNEL_TYPE</filename> variable in the kernel - recipe selects the kernel type. - See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>" - section for more information. - </para> - - <para> - As an example, the <filename>linux-yocto-3.19</filename> - tree defines three kernel types: "standard", - "tiny", and "preempt-rt": - <itemizedlist> - <listitem><para>"standard": - Includes the generic Linux kernel policy of the Yocto - Project linux-yocto kernel recipes. - This policy includes, among other things, which file - systems, networking options, core kernel features, and - debugging and tracing options are supported. - </para></listitem> - <listitem><para>"preempt-rt": - Applies the <filename>PREEMPT_RT</filename> - patches and the configuration options required to - build a real-time Linux kernel. - This kernel type inherits from the "standard" kernel type. - </para></listitem> - <listitem><para>"tiny": - Defines a bare minimum configuration meant to serve as a - base for very small Linux kernels. - The "tiny" kernel type is independent from the "standard" - configuration. - Although the "tiny" kernel type does not currently include - any source changes, it might in the future. - </para></listitem> - </itemizedlist> - </para> - - <para> - The "standard" kernel type is defined by - <filename>standard.scc</filename>: - <literallayout class='monospaced'> - # Include this kernel type fragment to get the standard features and - # configuration values. - - # Include all standard features - include standard-nocfg.scc - - kconf non-hardware standard.cfg - - # individual cfg block section - include cfg/fs/devtmpfs.scc - include cfg/fs/debugfs.scc - include cfg/fs/btrfs.scc - include cfg/fs/ext2.scc - include cfg/fs/ext3.scc - include cfg/fs/ext4.scc - - include cfg/net/ipv6.scc - include cfg/net/ip_nf.scc - include cfg/net/ip6_nf.scc - include cfg/net/bridge.scc - </literallayout> - </para> - - <para> - As with any <filename>.scc</filename> file, a - kernel type definition can aggregate other - <filename>.scc</filename> files with - <filename>include</filename> commands. - These definitions can also directly pull in - configuration fragments and patches with the - <filename>kconf</filename> and <filename>patch</filename> - commands, respectively. - </para> - - <note> - It is not strictly necessary to create a kernel type - <filename>.scc</filename> file. - The Board Support Package (BSP) file can implicitly define - the kernel type using a <filename>define - <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'>KTYPE</ulink> myktype</filename> - line. - See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>" - section for more information. - </note> - </section> - - <section id='bsp-descriptions'> - <title>BSP Descriptions</title> - - <para> - BSP descriptions combine kernel types with hardware-specific - features. - The hardware-specific portion is typically defined - independently, and then aggregated with each supported kernel - type. - Consider this simple BSP description that supports the - <replaceable>mybsp</replaceable> machine: - <literallayout class='monospaced'> - <replaceable>mybsp</replaceable>.scc: - define KMACHINE <replaceable>mybsp</replaceable> - define KTYPE standard - define KARCH i386 - - kconf <replaceable>mybsp</replaceable>.cfg - </literallayout> - Every BSP description should define the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>, - and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink> - variables. - These variables allow the OpenEmbedded build system to identify - the description as meeting the criteria set by the recipe being - built. - This simple example supports the "mybsp" machine for the "standard" - kernel and the "i386" architecture. - </para> - - <para> - Be aware that a hard link between the - <filename>KTYPE</filename> variable and a kernel type - description file does not exist. - Thus, if you do not have kernel types defined in your kernel - Metadata, you only need to ensure that the kernel recipe's - <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> - variable and the <filename>KTYPE</filename> variable in the - BSP description file match. - <note> - Future versions of the tooling make the specification of - <filename>KTYPE</filename> in the BSP optional. - </note> - </para> - - <para> - If you did want to separate your kernel policy from your - hardware configuration, you could do so by specifying a kernel - type, such as "standard" and including that description file - in the BSP description file. - See the "<link linkend='kernel-types'>Kernel Types</link>" section - for more information. - </para> - - <para> - You might also have multiple hardware configurations that you - aggregate into a single hardware description file that you - could include in the BSP description file, rather than referencing - a single <filename>.cfg</filename> file. - Consider the following: - <literallayout class='monospaced'> - <replaceable>mybsp</replaceable>.scc: - define KMACHINE mybsp - define KTYPE standard - define KARCH i386 - - include standard.scc - include <replaceable>mybsp</replaceable>-hw.scc - </literallayout> - </para> - - <para> - In the above example, <filename>standard.scc</filename> - aggregates all the configuration fragments, patches, and - features that make up your standard kernel policy whereas - <replaceable>mybsp</replaceable><filename>-hw.scc</filename> - aggregates all those necessary - to support the hardware available on the - <replaceable>mybsp</replaceable> machine. - For information on how to break a complete - <filename>.config</filename> file into the various - configuration fragments, see the - "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" - section. - </para> - - <para> - Many real-world examples are more complex. - Like any other <filename>.scc</filename> file, BSP - descriptions can aggregate features. - Consider the Minnow BSP definition from the - <filename>linux-yocto-3.19</filename> - Git repository: - <literallayout class='monospaced'> - minnow.scc: - include cfg/x86.scc - include features/eg20t/eg20t.scc - include cfg/dmaengine.scc - include features/power/intel.scc - include cfg/efi.scc - include features/usb/ehci-hcd.scc - include features/usb/ohci-hcd.scc - include features/usb/usb-gadgets.scc - include features/usb/touchscreen-composite.scc - include cfg/timer/hpet.scc - include cfg/timer/rtc.scc - include features/leds/leds.scc - include features/spi/spidev.scc - include features/i2c/i2cdev.scc - - # Earlyprintk and port debug requires 8250 - kconf hardware cfg/8250.cfg - - kconf hardware minnow.cfg - kconf hardware minnow-dev.cfg - </literallayout> - </para> - - <para> - The <filename>minnow.scc</filename> description file includes - a hardware configuration fragment - (<filename>minnow.cfg</filename>) specific to the Minnow - BSP as well as several more general configuration - fragments and features enabling hardware found on the - machine. - This description file is then included in each of the three - "minnow" description files for the supported kernel types - (i.e. "standard", "preempt-rt", and "tiny"). - Consider the "minnow" description for the "standard" kernel - type: - <literallayout class='monospaced'> - minnow-standard.scc: - define KMACHINE minnow - define KTYPE standard - define KARCH i386 - - include ktypes/standard - - include minnow.scc - - # Extra minnow configs above the minimal defined in minnow.scc - include cfg/efi-ext.scc - include features/media/media-all.scc - include features/sound/snd_hda_intel.scc - - # The following should really be in standard.scc - # USB live-image support - include cfg/usb-mass-storage.scc - include cfg/boot-live.scc - - # Basic profiling - include features/latencytop/latencytop.scc - include features/profiling/profiling.scc - - # Requested drivers that don't have an existing scc - kconf hardware minnow-drivers-extra.cfg - </literallayout> - The <filename>include</filename> command midway through the file - includes the <filename>minnow.scc</filename> description that - defines all hardware enablements for the BSP that is common to all - kernel types. - Using this command significantly reduces duplication. - </para> - - <para> - Now consider the "minnow" description for the "tiny" kernel type: - <literallayout class='monospaced'> - minnow-tiny.scc: - define KMACHINE minnow - define KTYPE tiny - define KARCH i386 - - include ktypes/tiny - - include minnow.scc - </literallayout> - As you might expect, the "tiny" description includes quite a - bit less. - In fact, it includes only the minimal policy defined by the - "tiny" kernel type and the hardware-specific configuration required - for booting the machine along with the most basic functionality of - the system as defined in the base "minnow" description file. - </para> - - <para> - Notice again the three critical variables: - <filename>KMACHINE</filename>, <filename>KTYPE</filename>, - and <filename>KARCH</filename>. - Of these variables, only the <filename>KTYPE</filename> has changed. - It is now set to "tiny". - </para> - </section> -</section> - -<section id='organizing-your-source'> - <title>Organizing Your Source</title> - - <para> - Many recipes based on the <filename>linux-yocto-custom.bb</filename> - recipe use Linux kernel sources that have only a single - branch - "master". - This type of repository structure is fine for linear development - supporting a single machine and architecture. - However, if you work with multiple boards and architectures, - a kernel source repository with multiple branches is more - efficient. - For example, suppose you need a series of patches for one board to boot. - Sometimes, these patches are works-in-progress or fundamentally wrong, - yet they are still necessary for specific boards. - In these situations, you most likely do not want to include these - patches in every kernel you build (i.e. have the patches as part of - the lone "master" branch). - It is situations like these that give rise to multiple branches used - within a Linux kernel sources Git repository. - </para> - - <para> - Repository organization strategies exist that maximize source reuse, - remove redundancy, and logically order your changes. - This section presents strategies for the following cases: - <itemizedlist> - <listitem><para>Encapsulating patches in a feature description - and only including the patches in the BSP descriptions of - the applicable boards.</para></listitem> - <listitem><para>Creating a machine branch in your - kernel source repository and applying the patches on that - branch only.</para></listitem> - <listitem><para>Creating a feature branch in your - kernel source repository and merging that branch into your - BSP when needed.</para></listitem> - </itemizedlist> - </para> - - <para> - The approach you take is entirely up to you - and depends on what works best for your development model. - </para> - - <section id='encapsulating-patches'> - <title>Encapsulating Patches</title> - - <para> - if you are reusing patches from an external tree and are not - working on the patches, you might find the encapsulated feature - to be appropriate. - Given this scenario, you do not need to create any branches in the - source repository. - Rather, you just take the static patches you need and encapsulate - them within a feature description. - Once you have the feature description, you simply include that into - the BSP description as described in the - "<link linkend='bsp-descriptions'>BSP Descriptions</link>" - section. - </para> - - <para> - You can find information on how to create patches and BSP - descriptions in the "<link linkend='patches'>Patches</link>" and - "<link linkend='bsp-descriptions'>BSP Descriptions</link>" - sections. - </para> - </section> - - <section id='machine-branches'> - <title>Machine Branches</title> - - <para> - When you have multiple machines and architectures to support, - or you are actively working on board support, it is more - efficient to create branches in the repository based on - individual machines. - Having machine branches allows common source to remain in the - "master" branch with any features specific to a machine stored - in the appropriate machine branch. - This organization method frees you from continually reintegrating - your patches into a feature. - </para> - - <para> - Once you have a new branch, you can set up your kernel Metadata - to use the branch a couple different ways. - In the recipe, you can specify the new branch as the - <filename>KBRANCH</filename> to use for the board as - follows: - <literallayout class='monospaced'> - KBRANCH = "mynewbranch" - </literallayout> - Another method is to use the <filename>branch</filename> command - in the BSP description: - <literallayout class='monospaced'> - mybsp.scc: - define KMACHINE mybsp - define KTYPE standard - define KARCH i386 - include standard.scc - - branch mynewbranch - - include mybsp-hw.scc - </literallayout> - </para> - - <para> - If you find - yourself with numerous branches, you might consider using a - hierarchical branching system similar to what the linux-yocto Linux - kernel repositories use: - <literallayout class='monospaced'> - <replaceable>common</replaceable>/<replaceable>kernel_type</replaceable>/<replaceable>machine</replaceable> - </literallayout> - </para> - - <para> - If you had two kernel types, "standard" and "small" for - instance, three machines, and <replaceable>common</replaceable> - as <filename>mydir</filename>, the branches in your - Git repository might look like this: - <literallayout class='monospaced'> - mydir/base - mydir/standard/base - mydir/standard/machine_a - mydir/standard/machine_b - mydir/standard/machine_c - mydir/small/base - mydir/small/machine_a - </literallayout> - </para> - - <para> - This organization can help clarify the branch relationships. - In this case, <filename>mydir/standard/machine_a</filename> - includes everything in <filename>mydir/base</filename> and - <filename>mydir/standard/base</filename>. - The "standard" and "small" branches add sources specific to those - kernel types that for whatever reason are not appropriate for the - other branches. - <note>The "base" branches are an artifact of the way Git manages - its data internally on the filesystem: Git will not allow you - to use <filename>mydir/standard</filename> and - <filename>mydir/standard/machine_a</filename> because it - would have to create a file and a directory named "standard". - </note> - </para> - </section> - - <section id='feature-branches'> - <title>Feature Branches</title> - - <para> - When you are actively developing new features, it can be more - efficient to work with that feature as a branch, rather than - as a set of patches that have to be regularly updated. - The Yocto Project Linux kernel tools provide for this with - the <filename>git merge</filename> command. - </para> - - <para> - To merge a feature branch into a BSP, insert the - <filename>git merge</filename> command after any - <filename>branch</filename> commands: - <literallayout class='monospaced'> - mybsp.scc: - define KMACHINE mybsp - define KTYPE standard - define KARCH i386 - include standard.scc - - branch mynewbranch - git merge myfeature - - include mybsp-hw.scc - </literallayout> - </para> - </section> -</section> - -<section id='scc-reference'> - <title>SCC Description File Reference</title> - - <para> - This section provides a brief reference for the commands you can use - within an SCC description file (<filename>.scc</filename>): - <itemizedlist> - <listitem><para><filename>branch [ref]</filename>: - Creates a new branch relative to the current branch - (typically <filename>${KTYPE}</filename>) using - the currently checked-out branch, or "ref" if specified. - </para></listitem> - <listitem><para><filename>define</filename>: - Defines variables, such as <filename>KMACHINE</filename>, - <filename>KTYPE</filename>, <filename>KARCH</filename>, - and <filename>KFEATURE_DESCRIPTION</filename>.</para></listitem> - <listitem><para><filename>include SCC_FILE</filename>: - Includes an SCC file in the current file. - The file is parsed as if you had inserted it inline. - </para></listitem> - <listitem><para><filename>kconf [hardware|non-hardware] CFG_FILE</filename>: - Queues a configuration fragment for merging into the final - Linux <filename>.config</filename> file.</para></listitem> - <listitem><para><filename>git merge GIT_BRANCH</filename>: - Merges the feature branch into the current branch. - </para></listitem> - <listitem><para><filename>patch PATCH_FILE</filename>: - Applies the patch to the current Git branch.</para></listitem> - </itemizedlist> - </para> -</section> - -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> |