documentation/kernel-dev/advanced.rst

4 Working with Advanced Metadata (``yocto-kernel-cache``)
11 Project kernel tools also support rich
16 BSPs and Linux kernel types.
18 Kernel Metadata exists in many places. One area in the
20 is the ``yocto-kernel-cache`` Git repository. You can find this repository
21 grouped under the "Yocto Linux Kernel" heading in the
24 Kernel development tools ("kern-tools") are also available in the Yocto Project
25 Source Repositories under the "Yocto Linux Kernel" heading in the
26 ``yocto-kernel-tools`` Git repository. The recipe that builds these
27 tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in
31 Using Kernel Metadata in a Recipe
34 As mentioned in the introduction, the Yocto Project contains kernel
35 Metadata, which is located in the ``yocto-kernel-cache`` Git repository.
38 consists of an aggregation of kernel policy and enabled
44    A Linux kernel recipe that contains kernel Metadata (e.g. inherits
57 realize that :term:`KMACHINE` is just for kernel mapping, while :term:`MACHINE`
60 ":ref:`kernel-dev/advanced:bsp descriptions`" section for more information.
62 Every linux-yocto style recipe must also indicate the Linux kernel
63 source repository branch used to build the Linux kernel. The
83 defines the kernel type to be used in assembling the configuration. If
86 arguments used by the kernel tools to find the appropriate description
87 within the kernel Metadata with which to build out the sources and
89 "preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
90 section for more information on kernel types.
120 within the kernel Metadata itself. The examples here are taken from the
121 ``yocto-kernel-cache`` repository. Each branch of this repository
123 information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`"
126 Kernel Metadata Syntax
129 The kernel Metadata consists of three primary types of files: ``scc``
133 types of kernel Metadata into what ultimately describes the sources and
134 the configuration required to build a Linux kernel tailored to a
138 of kernel Metadata:
146 implement conceptually separate kernel Metadata descriptions such as
148 kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel
151 BSPs define hardware-specific features and aggregate them with kernel
154 While the kernel Metadata syntax does not enforce any logical separation
155 of configuration fragments, patches, features or kernel types, best
166 The ``bsp`` directory contains the :ref:`kernel-dev/advanced:bsp descriptions`.
183    order to define a base kernel policy or major kernel type to be
189 impact on the functionality of the kernel Metadata. There is no impact
191 contain "features" as far as the kernel tools are concerned.
193 Paths used in kernel Metadata files are relative to base, which is
197 :ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`,
199 :yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>`
201 :ref:`kernel-dev/advanced:metadata outside the recipe-space`.
211 The simplest unit of kernel Metadata is the configuration-only feature.
212 This feature consists of one or more Linux kernel configuration
217 used with the ``linux-yocto-4.12`` kernel as defined outside of the
218 recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
221 ``yocto-kernel-cache`` Git repository::
241 fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section.
246 kernel tools use this description.
262 ":ref:`kernel-dev/common:validating configuration`" section, you can
277 kernel as defined outside of the recipe space (i.e.
278 ``yocto-kernel-cache``). This Metadata consists of several files:
281 ``yocto-kernel-cache`` Git repository.
321 see the ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
322 and ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
328 Features are complex kernel Metadata types that consist of configuration
348 Linux kernel recipe. See the
349 ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier
352 Kernel Types
355 A kernel type defines a high-level kernel policy by aggregating
357 building a Linux kernel of a specific type (e.g. a real-time kernel).
358 Syntactically, kernel types are no different than features as described
359 in the ":ref:`kernel-dev/advanced:features`" section. The
361 variable in the kernel recipe selects the kernel type. For example, in
362 the ``linux-yocto_4.12.bb`` kernel recipe found in
363 ``poky/meta/recipes-kernel/linux``, a
365 includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
366 which has the following statement that defines the default kernel type::
370 Another example would be the real-time kernel (i.e.
371 ``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel
378    You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory
380    (e.g. ``poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb``). See the
381    ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`"
384 Three kernel types ("standard", "tiny", and "preempt-rt") are supported
387 -  "standard": Includes the generic Linux kernel policy of the Yocto
388    Project linux-yocto kernel recipes. This policy includes, among other
389    things, which file systems, networking options, core kernel features,
393    configuration options required to build a real-time Linux kernel.
394    This kernel type inherits from the "standard" kernel type.
397    for very small Linux kernels. The "tiny" kernel type is independent
398    from the "standard" configuration. Although the "tiny" kernel type
402 For any given kernel type, the Metadata is defined by the ``.scc`` (e.g.
405 ``yocto-kernel-cache`` Git repository::
407    # Include this kernel type fragment to get the standard features and
435 As with any ``.scc`` file, a kernel type definition can aggregate other
442    It is not strictly necessary to create a kernel type ``.scc``
444    kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the
445    ":ref:`kernel-dev/advanced:bsp descriptions`" section for more
451 BSP descriptions (i.e. ``*.scc`` files) combine kernel types with
454 supported kernel type.
459    are located in the ``bsp`` directory of the ``yocto-kernel-cache``
460    repository organized under the "Yocto Linux Kernel" heading in the
486 kernel type.
509 example supports the "beaglebone" machine for the "standard" kernel and
512 Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel
514 kernel type defined in your kernel Metadata as it is here, you only need
517 variable in the kernel recipe and the :term:`KTYPE` variable in the BSP
520 To separate your kernel policy from your hardware configuration, you
521 include a kernel type (``ktype``), such as "standard". In the previous
527 fragments, patches, and features that make up your standard kernel
528 policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more
531 To aggregate common configurations and features specific to the kernel
541 configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" sectio…
569 ``yocto-kernel-cache`` (i.e.
570 ``yocto-kernel-cache/bsp/minnow/minnow.scc``):
605 supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
606 Consider the "minnow" description for the "standard" kernel type (i.e.
636 kernel types. Using this command significantly reduces duplication.
638 Now consider the "minnow" description for the "tiny" kernel type (i.e.
651 only the minimal policy defined by the "tiny" kernel type and the
660 :term:`KTYPE` has changed to specify the "tiny" kernel type.
662 Kernel Metadata Location
665 Kernel Metadata always exists outside of the kernel tree either defined
666 in a kernel recipe (recipe-space) or outside of the recipe. Where you
668 intend to work. Regardless of where you define the kernel Metadata, the
671 If you are unfamiliar with the Linux kernel and only wish to apply a
674 good approach if you are working with Linux kernel sources you do not
675 control or if you just do not want to maintain a Linux kernel Git
677 kernel Metadata in the recipe-space, see the
678 ":ref:`kernel-dev/common:modifying an existing recipe`" section.
680 Conversely, if you are actively developing a kernel and are already
681 maintaining a Linux kernel Git repository of your own, you might find it
682 more convenient to work with kernel Metadata kept outside the
684 development of the Linux kernel more efficient outside of the BitBake
690 When stored in recipe-space, the kernel Metadata files reside in a
692 a linux-yocto recipe or for a Linux kernel recipe derived by copying
693 :oe_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
694 </openembedded-core/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`
697 See the ":ref:`kernel-dev/common:modifying an existing recipe`"
700 Here is an example that shows a trivial tree of kernel Metadata stored
704    `-- recipes-kernel
724 form from your kernel append file::
733 When stored outside of the recipe-space, the kernel Metadata files
738 ``linux-yocto_4.12.bb`` kernel recipe::
741 …git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${…
749 You can keep kernel Metadata in a "kernel-cache", which is a directory
752 the "type=kmeta" attribute. Doing so makes the kernel Metadata available
756 statements in the kernel's recipe. In particular, you need to update the
766 kernel sources that have only a single branch. This type of
769 architectures, a kernel source repository with multiple branches is more
774 patches in every kernel you build (i.e. have the patches as part of the
776 multiple branches used within a Linux kernel sources Git repository.
785 -  Creating a machine branch in your kernel source repository and
788 -  Creating a feature branch in your kernel source repository and
803 described in the ":ref:`kernel-dev/advanced:bsp descriptions`" section.
806 in the ":ref:`kernel-dev/advanced:patches`" and
807 ":ref:`kernel-dev/advanced:bsp descriptions`" sections.
820 Once you have a new branch, you can set up your kernel Metadata to use
840 hierarchical branching system similar to what the Yocto Linux Kernel Git
845 If you had two kernel types, "standard" and "small" for instance, three
860 sources specific to those kernel types that for whatever reason are not
875 that have to be regularly updated. The Yocto Project Linux kernel tools