1 files changed, 0 insertions, 912 deletions
diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst
deleted file mode 100644
index 4c463503f6..0000000000
--- a/documentation/kernel-dev/advanced.rst
+++ /dev/null
@@ -1,912 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
-*******************************************************
-Working with Advanced Metadata (``yocto-kernel-cache``)
-*******************************************************
-Overview
-========
-In addition to supporting configuration fragments and patches, the Yocto
-Project kernel tools also support rich
-:term:`Metadata` 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.
-Kernel Metadata exists in many places. One area in the
-:ref:`overview-manual/development-environment:yocto project source repositories`
-is the ``yocto-kernel-cache`` Git repository. You can find this repository
-grouped under the "Yocto Linux Kernel" heading in the
-:yocto_git:`Yocto Project Source Repositories <>`.
-Kernel development tools ("kern-tools") are also available in the Yocto Project
-Source Repositories under the "Yocto Linux Kernel" heading in the
-``yocto-kernel-tools`` Git repository. The recipe that builds these
-tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in
-the :term:`Source Directory` (e.g.
-``poky``).
-Using Kernel Metadata in a Recipe
-=================================
-As mentioned in the introduction, the Yocto Project contains kernel
-Metadata, which is located in the ``yocto-kernel-cache`` 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 ``linux-yocto.inc`` file) is said to be a "linux-yocto style" recipe.
-Every linux-yocto style recipe must define the
-:term:`KMACHINE` variable. This
-variable is typically set to the same value as the :term:`MACHINE` variable,
-which is used by :term:`BitBake`.
-However, in some cases, the variable might instead refer to the
-underlying platform of the :term:`MACHINE`.
-Multiple BSPs can reuse the same :term:`KMACHINE` name if they are built
-using the same BSP description. Multiple Corei7-based BSPs could share
-the same "intel-corei7-64" value for :term:`KMACHINE`. It is important to
-realize that :term:`KMACHINE` is just for kernel mapping, while :term:`MACHINE`
-is the machine type within a BSP Layer. Even with this distinction,
-however, these two variables can hold the same value. See the
-":ref:`kernel-dev/advanced:bsp descriptions`" section for more information.
-Every linux-yocto style recipe must also indicate the Linux kernel
-source repository branch used to build the Linux kernel. The
-:term:`KBRANCH` variable must be set
-to indicate the branch.
-.. note::
-   You can use the :term:`KBRANCH` value to define an alternate branch typically
-   with a machine override as shown here from the ``meta-yocto-bsp`` layer::
-      KBRANCH:beaglebone-yocto = "standard/beaglebone"
-The linux-yocto style recipes can optionally define the following
-variables:
-  - :term:`KERNEL_FEATURES`
-  - :term:`LINUX_KERNEL_TYPE`
-:term:`LINUX_KERNEL_TYPE`
-defines the kernel type to be used in assembling the configuration. If
-you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to "standard".
-Together with :term:`KMACHINE`, :term:`LINUX_KERNEL_TYPE` 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 ":ref:`kernel-dev/advanced:kernel types`"
-section for more information on kernel types.
-During the build, the kern-tools search for the BSP description file
-that most closely matches the :term:`KMACHINE` and :term:`LINUX_KERNEL_TYPE`
-variables passed in from the recipe. The tools use the first BSP
-description they find that matches both variables. If the tools cannot find
-a match, they issue a warning.
-The tools first search for the :term:`KMACHINE` and then for the
-:term:`LINUX_KERNEL_TYPE`. If the tools cannot find a partial match, they
-will use the sources from the :term:`KBRANCH` and any configuration
-specified in the :term:`SRC_URI`.
-You can use the
-:term:`KERNEL_FEATURES`
-variable to include features (configuration fragments, patches, or both)
-that are not already included by the :term:`KMACHINE` and
-:term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a
-feature specified as "features/netfilter/netfilter.scc", specify::
-   KERNEL_FEATURES += "features/netfilter/netfilter.scc"
-To include a
-feature called "cfg/sound.scc" just for the ``qemux86`` machine,
-specify::
-   KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc"
-The value of
-the entries in :term:`KERNEL_FEATURES` are dependent on their location
-within the kernel Metadata itself. The examples here are taken from the
-``yocto-kernel-cache`` repository. Each branch of this repository
-contains "features" and "cfg" subdirectories at the top-level. For more
-information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`"
-section.
-Kernel Metadata Syntax
-======================
-The kernel Metadata consists of three primary types of files: ``scc``
-[1]_ description files, configuration fragments, and patches. The
-``scc`` 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.
-The ``scc`` description files are used to define two fundamental types
-of kernel Metadata:
-  Features
-  Board Support Packages (BSPs)
-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. :ref:`kernel-dev/advanced:kernel types` define general kernel
-features and policy to be reused in the BSPs.
-BSPs define hardware-specific features and aggregate them with kernel
-types to form the final description of what will be assembled and built.
-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::
-   base/
-      bsp/
-      cfg/
-      features/
-      ktypes/
-      patches/
-The ``bsp`` directory contains the :ref:`kernel-dev/advanced:bsp descriptions`.
-The remaining directories all contain "features". Separating ``bsp`` from the
-rest of the structure aids conceptualizing intended usage.
-Use these guidelines to help place your ``scc`` description files within
-the structure:
-  If your file contains only configuration fragments, place the file in
-   the ``cfg`` directory.
-  If your file contains only source-code fixes, place the file in the
-   ``patches`` directory.
-  If your file encapsulates a major feature, often combining sources
-   and configurations, place the file in ``features`` directory.
-  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 ``ktypes`` directory.
-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 ``cfg``, ``features``, ``patches``, and ``ktypes``,
-contain "features" as far as the kernel tools are concerned.
-Paths used in kernel Metadata files are relative to base, which is
-either
-:term:`FILESEXTRAPATHS` if
-you are creating Metadata in
-:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`,
-or the top level of
-:yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>`
-if you are creating
-:ref:`kernel-dev/advanced:metadata outside the recipe-space`.
-.. [1]
-   ``scc`` 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 ``scc`` files to be description files.
-Configuration
-------------
-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 (``.cfg``) and a ``.scc``
-file that describes the fragment.
-As an example, consider the Symmetric Multi-Processing (SMP) fragment
-used with the ``linux-yocto-4.12`` kernel as defined outside of the
-recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
-two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
-``cfg`` directory of the ``yocto-4.12`` branch in the
-``yocto-kernel-cache`` Git repository::
-   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
-You can find general information on configuration
-fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section.
-Within the ``smp.scc`` file, the
-:term:`KFEATURE_DESCRIPTION`
-statement provides a short description of the fragment. Higher level
-kernel tools use this description.
-Also within the ``smp.scc`` file, the ``kconf`` command includes the
-actual configuration fragment in an ``.scc`` 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 ``kconf`` statements, one per
-   fragment.
-As described in the
-":ref:`kernel-dev/common:validating configuration`" section, you can
-use the following BitBake command to audit your configuration::
-   $ bitbake linux-yocto -c kernel_configcheck -f
-Patches
-------
-Patch descriptions are very similar to configuration fragment
-descriptions, which are described in the previous section. However,
-instead of a ``.cfg`` file, these descriptions work with source patches
-(i.e. ``.patch`` files).
-A typical patch includes a description file and the patch itself. As an
-example, consider the build patches used with the ``linux-yocto-4.12``
-kernel as defined outside of the recipe space (i.e.
-``yocto-kernel-cache``). This Metadata consists of several files:
-``build.scc`` and a set of ``*.patch`` files. You can find these files
-in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
-``yocto-kernel-cache`` Git repository.
-The following listings show the ``build.scc`` file and part of the
-``modpost-mask-trivial-warnings.patch`` file::
-   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)
-The description file can
-include multiple patch statements where each statement handles a single
-patch. In the example ``build.scc`` file, there are five patch statements
-for the five patches in the directory.
-You can create a typical ``.patch`` file using ``diff -Nurp`` or
-``git format-patch`` commands. For information on how to create patches,
-see the ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
-and ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
-sections.
-Features
--------
-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::
-   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
-This example shows how the ``patch`` and ``kconf`` commands are used as well
-as how an additional feature description file is included with the
-``include`` command.
-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 :term:`KERNEL_FEATURES` variable of the
-Linux kernel recipe. See the
-":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier
-in the manual.
-Kernel Types
------------
-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
-":ref:`kernel-dev/advanced:features`" section. The :term:`LINUX_KERNEL_TYPE`
-variable in the kernel recipe selects the kernel type. For example, in the
-``linux-yocto_4.12.bb`` kernel recipe found in ``poky/meta/recipes-kernel/linux``, a
-:ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
-directive includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
-which has the following statement that defines the default kernel type::
-   LINUX_KERNEL_TYPE ??= "standard"
-Another example would be the real-time kernel (i.e.
-``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel
-type as follows::
-   LINUX_KERNEL_TYPE = "preempt-rt"
-.. note::
-   You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory
-   of the :ref:`overview-manual/development-environment:yocto project source repositories`
-   (e.g. ``poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb``). See the
-   ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`"
-   section for more information.
-Three kernel types ("standard", "tiny", and "preempt-rt") are supported
-for Linux Yocto kernels:
-  "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.
-  "preempt-rt": Applies the ``PREEMPT_RT`` patches and the
-   configuration options required to build a real-time Linux kernel.
-   This kernel type inherits from the "standard" kernel type.
-  "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.
-For any given kernel type, the Metadata is defined by the ``.scc`` (e.g.
-``standard.scc``). Here is a partial listing for the ``standard.scc``
-file, which is found in the ``ktypes/standard`` directory of the
-``yocto-kernel-cache`` Git repository::
-   # 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
-As with any ``.scc`` file, a kernel type definition can aggregate other
-``.scc`` files with ``include`` commands. These definitions can also
-directly pull in configuration fragments and patches with the ``kconf``
-and ``patch`` commands, respectively.
-.. note::
-   It is not strictly necessary to create a kernel type ``.scc``
-   file. The Board Support Package (BSP) file can implicitly define the
-   kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the
-   ":ref:`kernel-dev/advanced:bsp descriptions`" section for more
-   information.
-BSP Descriptions
----------------
-BSP descriptions (i.e. ``*.scc`` 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 ``bsp`` directory of the ``yocto-kernel-cache``
-   repository organized under the "Yocto Linux Kernel" heading in the
-   :yocto_git:`Yocto Project Source Repositories <>`.
-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 :doc:`/bsp-guide/index`.
-Description Overview
-~~~~~~~~~~~~~~~~~~~~
-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::
-   bsp_root_name-kernel_type.scc
-Here are some example root layer
-BSP filenames for the BeagleBone Board BSP, which is supported by the
-Yocto Project::
-   beaglebone-standard.scc
-   beaglebone-preempt-rt.scc
-Each file uses the root name (i.e "beaglebone") BSP name followed by the
-kernel type.
-Examine the ``beaglebone-standard.scc`` file::
-   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
-Every top-level BSP description file
-should define the :term:`KMACHINE`,
-:term:`KTYPE`, and
-:term:`KARCH` 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.
-Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel
-type description file. 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
-:term:`LINUX_KERNEL_TYPE`
-variable in the kernel recipe and the :term:`KTYPE` variable in the BSP
-description file match.
-To separate your kernel policy from your hardware configuration, you
-include a kernel type (``ktype``), such as "standard". In the previous
-example, this is done using the following::
-   include ktypes/standard/standard.scc
-This file aggregates all the configuration
-fragments, patches, and features that make up your standard kernel
-policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more
-information.
-To aggregate common configurations and features specific to the kernel
-for `mybsp`, use the following::
-   include mybsp.scc
-You can see that in the BeagleBone example with the following::
-   include beaglebone.scc
-For information on how to break a complete ``.config`` file into the various
-configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section.
-Finally, if you have any configurations specific to the hardware that
-are not in a ``*.scc`` file, you can include them as follows::
-   kconf hardware mybsp-extra.cfg
-The BeagleBone example does not include these
-types of configurations. However, the Malta 32-bit board does
-("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file::
-   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
-Example
-~~~~~~~
-Many real-world examples are more complex. Like any other ``.scc`` file,
-BSP descriptions can aggregate features. Consider the Minnow BSP
-definition given the ``linux-yocto-4.4`` branch of the
-``yocto-kernel-cache`` (i.e. ``yocto-kernel-cache/bsp/minnow/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 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
-.. note::
-   Although the Minnow Board BSP is unused, the Metadata remains and is
-   being used here just as an example.
-The ``minnow.scc`` description file includes a hardware configuration
-fragment (``minnow.cfg``) specific to the Minnow BSP as well as several
-more general configuration fragments and features enabling hardware
-found on the machine. This ``minnow.scc`` 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.
-``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
-The ``include`` command midway through the file includes the ``minnow.scc`` description
-that defines all enabled hardware for the BSP that is common to all
-kernel types. Using this command significantly reduces duplication.
-Now consider the "minnow" description for the "tiny" kernel type (i.e.
-``minnow-tiny.scc``)::
-   define KMACHINE minnow
-   define KTYPE tiny
-   define KARCH i386
-   include ktypes/tiny
-   include minnow.scc
-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.
-Notice again the three critical variables:
-:term:`KMACHINE`,
-:term:`KTYPE`, and
-:term:`KARCH`. Of these variables, only
-:term:`KTYPE` has changed to specify the "tiny" kernel type.
-Kernel Metadata Location
-========================
-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.
-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
-":ref:`kernel-dev/common:modifying an existing recipe`" section.
-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.
-Recipe-Space Metadata
---------------------
-When stored in recipe-space, the kernel Metadata files reside in a
-directory hierarchy below :term:`FILESEXTRAPATHS`. For
-a linux-yocto recipe or for a Linux kernel recipe derived by copying
-:oe_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
-</openembedded-core/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`
-into your layer and modifying it, :term:`FILESEXTRAPATHS` is typically set to
-``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``.
-See the ":ref:`kernel-dev/common:modifying an existing recipe`"
-section for more information.
-Here is an example that shows a trivial tree of kernel Metadata stored
-in recipe-space within a BSP layer::
-   meta-my_bsp_layer/
-   `-- recipes-kernel
-       `-- linux
-           `-- linux-yocto
-               |-- bsp-standard.scc
-               |-- bsp.cfg
-               `-- standard.cfg
-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 ``.scc`` files on the
-:term:`SRC_URI`. BitBake parses them
-and fetches any files referenced in the ``.scc`` files by the
-``include``, ``patch``, or ``kconf`` commands. Because of this, it is
-necessary to bump the recipe :term:`PR`
-value when changing the content of files not explicitly listed in the
-:term:`SRC_URI`.
-If the BSP description is in recipe space, you cannot simply list the
-``*.scc`` in the :term:`SRC_URI` statement. You need to use the following
-form from your kernel append file::
-   SRC_URI:append:myplatform = " \
-       file://myplatform;type=kmeta;destsuffix=myplatform \
-       "
-Metadata Outside the Recipe-Space
---------------------------------
-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
-:term:`SRC_URI` variable. As an
-example, consider the following :term:`SRC_URI` statement from the
-``linux-yocto_5.15.bb`` kernel recipe::
-   SRC_URI = "git://git.yoctoproject.org/linux-yocto.git;name=machine;branch=${KBRANCH};protocol=https \
-              git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-5.15;destsuffix=${KMETA};protocol=https"
-``${KMETA}``, 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 :term:`SRC_URI` statement used in a recipe (e.g.
-see the previous section).
-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 :term:`SRC_URI` statement with
-the "type=kmeta" attribute. Doing so makes the kernel Metadata available
-during the configuration phase.
-If you modify the Metadata, you must not forget to update the :term:`SRCREV`
-statements in the kernel's recipe. In particular, you need to update the
-``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you
-wish to use. Changing the data in these branches and not updating the
-:term:`SRCREV` statements to match will cause the build to fetch an older
-commit.
-Organizing Your Source
-======================
-Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux
-kernel sources that have only a single branch. 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
-default branch). It is situations like these that give rise to
-multiple branches used within a Linux kernel sources Git repository.
-Here are repository organization strategies maximizing source reuse,
-removing redundancy, and logically ordering your changes. This section
-presents strategies for the following cases:
-  Encapsulating patches in a feature description and only including the
-   patches in the BSP descriptions of the applicable boards.
-  Creating a machine branch in your kernel source repository and
-   applying the patches on that branch only.
-  Creating a feature branch in your kernel source repository and
-   merging that branch into your BSP when needed.
-The approach you take is entirely up to you and depends on what works
-best for your development model.
-Encapsulating Patches
---------------------
-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 ":ref:`kernel-dev/advanced:bsp descriptions`" section.
-You can find information on how to create patches and BSP descriptions
-in the ":ref:`kernel-dev/advanced:patches`" and
-":ref:`kernel-dev/advanced:bsp descriptions`" sections.
-Machine Branches
----------------
-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 development 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.
-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 :term:`KBRANCH` to use for the board as follows::
-   KBRANCH = "mynewbranch"
-Another method is to use the ``branch`` command in the BSP
-description::
-   mybsp.scc:
-      define KMACHINE mybsp
-      define KTYPE standard
-      define KARCH i386
-      include standard.scc
-      branch mynewbranch
-      include mybsp-hw.scc
-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::
-   common/kernel_type/machine
-If you had two kernel types, "standard" and "small" for instance, three
-machines, and common as ``mydir``, the branches in your Git repository
-might look like this::
-   mydir/base
-   mydir/standard/base
-   mydir/standard/machine_a
-   mydir/standard/machine_b
-   mydir/standard/machine_c
-   mydir/small/base
-   mydir/small/machine_a
-This organization can help clarify the branch relationships. In this
-case, ``mydir/standard/machine_a`` includes everything in ``mydir/base``
-and ``mydir/standard/base``. 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
-   ``mydir/standard`` and ``mydir/standard/machine_a`` because it would have to
-   create a file and a directory named "standard".
-Feature Branches
----------------
-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 ``git merge`` command.
-To merge a feature branch into a BSP, insert the ``git merge`` command
-after any ``branch`` commands::
-   mybsp.scc:
-      define KMACHINE mybsp
-      define KTYPE standard
-      define KARCH i386
-      include standard.scc
-      branch mynewbranch
-      git merge myfeature
-      include mybsp-hw.scc
-SCC Description File Reference
-==============================
-This section provides a brief reference for the commands you can use
-within an SCC description file (``.scc``):
-  ``branch [ref]``: Creates a new branch relative to the current branch
-   (typically ``${KTYPE}``) using the currently checked-out branch, or
-   "ref" if specified.
-  ``define``: Defines variables, such as
-   :term:`KMACHINE`,
-   :term:`KTYPE`,
-   :term:`KARCH`, and
-   :term:`KFEATURE_DESCRIPTION`.
-  ``include SCC_FILE``: Includes an SCC file in the current file. The
-   file is parsed as if you had inserted it inline.
-  ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration
-   fragment for merging into the final Linux ``.config`` file.
-  ``git merge GIT_BRANCH``: Merges the feature branch into the current
-   branch.
-  ``patch PATCH_FILE``: Applies the patch to the current Git branch.