documentation/kernel-dev/advanced.rst

1 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
4 Working with Advanced Metadata (``yocto-kernel-cache``)
19 :ref:`overview-manual/development-environment:yocto project source repositories`
20 is the ``yocto-kernel-cache`` Git repository. You can find this repository
24 Kernel development tools ("kern-tools") are also available in the Yocto Project
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
35 Metadata, which is located in the ``yocto-kernel-cache`` Git repository.
37 definitions in linux-yocto recipes for corresponding BSPs. A BSP
39 hardware-specific features. The BSP can be influenced from within the
40 linux-yocto recipe.
45    from the ``linux-yocto.inc`` file) is said to be a "linux-yocto style" recipe.
47 Every linux-yocto style recipe must define the
55 using the same BSP description. Multiple Corei7-based BSPs could share
56 the same "intel-corei7-64" value for :term:`KMACHINE`. It is important to
60 ":ref:`kernel-dev/advanced:bsp descriptions`" section for more information.
62 Every linux-yocto style recipe must also indicate the Linux kernel
70    with a machine override as shown here from the ``meta-yocto-bsp`` layer::
75 The linux-yocto style recipes can optionally define the following
78   - :term:`KERNEL_FEATURES`
80   - :term:`LINUX_KERNEL_TYPE`
88 configuration. The linux-yocto recipes define "standard", "tiny", and
89 "preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
92 During the build, the kern-tools search for the BSP description file
121 ``yocto-kernel-cache`` repository. Each branch of this repository
122 contains "features" and "cfg" subdirectories at the top-level. For more
123 information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`"
140 -  Features
142 -  Board Support Packages (BSPs)
148 kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel
151 BSPs define hardware-specific features and aggregate them with kernel
166 The ``bsp`` directory contains the :ref:`kernel-dev/advanced:bsp descriptions`.
173 -  If your file contains only configuration fragments, place the file in
176 -  If your file contains only source-code fixes, place the file in the
179 -  If your file encapsulates a major feature, often combining sources
182 -  If your file aggregates non-hardware configuration and patches in
186 These distinctions can easily become blurred - especially as out-of-tree
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`.
209 -------------
211 The simplest unit of kernel Metadata is the configuration-only feature.
216 As an example, consider the Symmetric Multi-Processing (SMP) fragment
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
220 ``cfg`` directory of the ``yocto-4.12`` branch in the
221 ``yocto-kernel-cache`` Git repository::
241 fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section.
251 to general policy, which would use the "non-hardware" keyword. The
254 non-hardware fragment.
262 ":ref:`kernel-dev/common:validating configuration`" section, you can
265    $ bitbake linux-yocto -c kernel_configcheck -f
268 -------
276 example, consider the build patches used with the ``linux-yocto-4.12``
278 ``yocto-kernel-cache``). This Metadata consists of several files:
280 in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
281 ``yocto-kernel-cache`` Git repository.
284 ``modpost-mask-trivial-warnings.patch`` file::
287       patch arm-serialize-build-targets.patch
288       patch powerpc-serialize-image-targets.patch
289       patch kbuild-exclude-meta-directory-from-distclean-processi.patch
292       # patch kbuild-add-meta-files-to-the-ignore-li.patch
294       patch modpost-mask-trivial-warnings.patch
295       patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
297    patches/build/modpost-mask-trivial-warnings.patch:
300       Date: Sun, 25 Jan 2009 17:58:09 -0500
309       --
312       generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
319 You can create a typical ``.patch`` file using ``diff -Nurp`` or
320 ``git format-patch`` commands. For information on how to create patches,
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`"
326 --------
335       patch 0001-myfeature-core.patch
336       patch 0002-myfeature-interface.patch
339       kconf non-hardware myfeature.cfg
345 Typically, features are less granular than configuration fragments and
349 ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier
353 ------------
355 A kernel type defines a high-level kernel policy by aggregating
356 non-hardware configuration fragments with patches you want to use when
357 building a Linux kernel of a specific type (e.g. a real-time kernel).
359 in the ":ref:`kernel-dev/advanced:features`" section. The
362 the ``linux-yocto_4.12.bb`` kernel recipe found in
363 ``poky/meta/recipes-kernel/linux``, a
364 :ref:`require <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`…
365 includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
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
374    LINUX_KERNEL_TYPE = "preempt-rt"
378    You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory
379    of the :ref:`overview-manual/development-environment:yocto project source repositories`
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
392 -  "preempt-rt": Applies the ``PREEMPT_RT`` patches and the
393    configuration options required to build a real-time Linux kernel.
396 -  "tiny": Defines a bare minimum configuration meant to serve as a base
405 ``yocto-kernel-cache`` Git repository::
421    kconf non-hardware standard.cfg
445    ":ref:`kernel-dev/advanced:bsp descriptions`" section for more
449 ----------------
452 hardware-specific features. The hardware-specific Metadata is typically
459    are located in the ``bsp`` directory of the ``yocto-kernel-cache``
466 layer file hierarchy, see the :doc:`/bsp-guide/index`.
476    bsp_root_name-kernel_type.scc
482    beaglebone-standard.scc
483    beaglebone-preempt-rt.scc
488 Examine the ``beaglebone-standard.scc`` file::
503 Every top-level BSP description file
528 policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more
541 configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" sectio…
546    kconf hardware mybsp-extra.cfg
549 types of configurations. However, the Malta 32-bit board does
550 ("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file::
552    define KMACHINE mti-malta32-le
558    branch mti-malta32
560    include mti-malta32.scc
561    kconf hardware mti-malta32-le.cfg
566 Many real-world examples are more complex. Like any other ``.scc`` file,
568 definition given the ``linux-yocto-4.4`` branch of the
569 ``yocto-kernel-cache`` (i.e.
570 ``yocto-kernel-cache/bsp/minnow/minnow.scc``):
584    include features/usb/ehci-hcd.scc
585    include features/usb/ohci-hcd.scc
586    include features/usb/usb-gadgets.scc
587    include features/usb/touchscreen-composite.scc
592    include features/mei/mei-txe.scc
598    kconf hardware minnow-dev.cfg
605 supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
607 ``minnow-standard.scc``)::
618    include cfg/efi-ext.scc
619    include features/media/media-all.scc
623    # USB live-image support
624    include cfg/usb-mass-storage.scc
625    include cfg/boot-live.scc
632    kconf hardware minnow-drivers-extra.cfg
639 ``minnow-tiny.scc``)::
652 hardware-specific configuration required for booting the machine along
666 in a kernel recipe (recipe-space) or outside of the recipe. Where you
673 others, the recipe-space method is recommended. This method is also a
677 kernel Metadata in the recipe-space, see the
678 ":ref:`kernel-dev/common:modifying an existing recipe`" section.
683 recipe-space. Working with Metadata in this area can make iterative
687 Recipe-Space Metadata
688 ---------------------
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`"
701 in recipe-space within a BSP layer::
703    meta-my_bsp_layer/
704    `-- recipes-kernel
705        `-- linux
706            `-- linux-yocto
707                |-- bsp-standard.scc
708                |-- bsp.cfg
709                `-- standard.cfg
711 When the Metadata is stored in recipe-space, you must take steps to
730 Metadata Outside the Recipe-Space
731 ---------------------------------
733 When stored outside of the recipe-space, the kernel Metadata files
738 ``linux-yocto_4.12.bb`` kernel recipe::
740    SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \
741 …git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${…
746 than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g.
749 You can keep kernel Metadata in a "kernel-cache", which is a directory
751 the recipe-space, you simply need to use the :term:`SRC_URI` statement with
765 Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux
767 repository structure is fine for linear development supporting a single
771 board to boot. Sometimes, these patches are works-in-progress or
782 -  Encapsulating patches in a feature description and only including the
785 -  Creating a machine branch in your kernel source repository and
788 -  Creating a feature branch in your kernel source repository and
795 ---------------------
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.
810 ----------------
837       include mybsp-hw.scc
871 ----------------
890       include mybsp-hw.scc
898 -  ``branch [ref]``: Creates a new branch relative to the current branch
899    (typically ``${KTYPE}``) using the currently checked-out branch, or
902 -  ``define``: Defines variables, such as
908 -  ``include SCC_FILE``: Includes an SCC file in the current file. The
911 -  ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration
914 -  ``git merge GIT_BRANCH``: Merges the feature branch into the current
917 -  ``patch PATCH_FILE``: Applies the patch to the current Git branch.