Lines Matching +full:in +full:- +full:kernel
1 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
4 Working with Advanced Metadata (``yocto-kernel-cache``)
10 In addition to supporting configuration fragments and patches, the Yocto
11 Project kernel tools also support rich
16 BSPs and Linux kernel types.
18 Kernel Metadata exists in many places. One area in the
19 :ref:`overview-manual/development-environment:yocto project source repositories`
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.
37 definitions in linux-yocto recipes for corresponding BSPs. A BSP
38 consists of an aggregation of kernel policy and enabled
39 hardware-specific features. The BSP can be influenced from within the
40 linux-yocto recipe.
44 A Linux kernel recipe that contains kernel Metadata (e.g. inherits
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
51 However, in some cases, the variable might instead refer to 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
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
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`
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
88 configuration. The linux-yocto recipes define "standard", "tiny", and
89 "preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
90 section for more information on kernel types.
92 During the build, the kern-tools search for the BSP description file
94 variables passed in from the recipe. The tools use the first BSP
101 specified in the :term:`SRC_URI`.
119 the entries in :term:`KERNEL_FEATURES` are dependent on their location
120 within the kernel Metadata itself. The examples here are taken from the
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`"
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:
140 - Features
142 - Board Support Packages (BSPs)
144 Features aggregate sources in the form of patches and configuration
146 implement conceptually separate kernel Metadata descriptions such as
148 kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel
149 features and policy to be reused in the BSPs.
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`.
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
180 and configurations, place the file in ``features`` directory.
182 - If your file aggregates non-hardware configuration and patches in
183 order to define a base kernel policy or major kernel type to be
184 reused across multiple BSPs, place the file in ``ktypes`` directory.
186 These distinctions can easily become blurred - especially as out-of-tree
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
196 you are creating Metadata in
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`.
205 less significance in the current implementation of the tooling than
206 it had in the past. Consider ``scc`` files to be description files.
209 -------------
211 The simplest unit of kernel Metadata is the configuration-only feature.
212 This feature consists of one or more Linux kernel configuration
213 parameters in a configuration fragment file (``.cfg``) and a ``.scc``
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
219 two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
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.
246 kernel tools use this description.
249 actual configuration fragment in an ``.scc`` file, and the "hardware"
251 to general policy, which would use the "non-hardware" keyword. The
254 non-hardware fragment.
261 As described in the
262 ":ref:`kernel-dev/common:validating configuration`" section, you can
265 $ bitbake linux-yocto -c kernel_configcheck -f
268 -------
271 descriptions, which are described in the previous section. However,
276 example, consider the build patches used with the ``linux-yocto-4.12``
277 kernel as defined outside of the recipe space (i.e.
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)
316 patch. In the example ``build.scc`` file, there are five patch statements
317 for the five patches in the directory.
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 --------
328 Features are complex kernel Metadata types that consist of configuration
335 patch 0001-myfeature-core.patch
336 patch 0002-myfeature-interface.patch
339 kconf non-hardware myfeature.cfg
347 of things you want to specify in the :term:`KERNEL_FEATURES` variable of the
348 Linux kernel recipe. See the
349 ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier
350 in the manual.
352 Kernel Types
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).
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
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,
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
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
389 things, which file systems, networking options, core kernel features,
392 - "preempt-rt": Applies the ``PREEMPT_RT`` patches and the
393 configuration options required to build a real-time Linux kernel.
394 This kernel type inherits from the "standard" kernel type.
396 - "tiny": Defines a bare minimum configuration meant to serve as a base
397 for very small Linux kernels. The "tiny" kernel type is independent
398 from the "standard" configuration. Although the "tiny" kernel type
399 does not currently include any source changes, it might in the
402 For any given kernel type, the Metadata is defined by the ``.scc`` (e.g.
404 file, which is found in the ``ktypes/standard`` directory of the
405 ``yocto-kernel-cache`` Git repository::
407 # Include this kernel type fragment to get the standard features and
421 kconf non-hardware standard.cfg
435 As with any ``.scc`` file, a kernel type definition can aggregate other
437 directly pull in configuration fragments and patches with the ``kconf``
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
449 ----------------
451 BSP descriptions (i.e. ``*.scc`` files) combine kernel types with
452 hardware-specific features. The hardware-specific Metadata is typically
453 defined independently in the BSP layer, and then aggregated with each
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
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
486 kernel type.
488 Examine the ``beaglebone-standard.scc`` file::
503 Every top-level BSP description file
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
536 You can see that in the BeagleBone example with the following::
541 configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" sectio…
544 are not in a ``*.scc`` file, you can include them as follows::
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
604 included in each of the three "minnow" description files for the
605 supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
606 Consider the "minnow" description for the "standard" kernel type (i.e.
607 ``minnow-standard.scc``)::
617 # Extra minnow configs above the minimal defined in minnow.scc
618 include cfg/efi-ext.scc
619 include features/media/media-all.scc
622 # The following should really be in standard.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
636 kernel types. Using this command significantly reduces duplication.
638 Now consider the "minnow" description for the "tiny" kernel type (i.e.
639 ``minnow-tiny.scc``)::
650 the "tiny" description includes quite a bit less. In fact, it includes
651 only the minimal policy defined by the "tiny" kernel type and the
652 hardware-specific configuration required for booting the machine along
653 with the most basic functionality of the system as defined in the base
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
673 others, the recipe-space method is recommended. This method is also 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
683 recipe-space. Working with Metadata in this area can make iterative
684 development of the Linux kernel more efficient outside of the BitBake
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`"
700 Here is an example that shows a trivial tree of kernel Metadata stored
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
716 and fetches any files referenced in the ``.scc`` files by the
719 value when changing the content of files not explicitly listed in the
722 If the BSP description is in recipe space, you cannot simply list the
723 ``*.scc`` in the :term:`SRC_URI` statement. You need to use the following
724 form from your kernel append file::
730 Metadata Outside the Recipe-Space
731 ---------------------------------
733 When stored outside of the recipe-space, the kernel Metadata files
734 reside in a separate repository. The OpenEmbedded build system adds the
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=${…
744 ``${KMETA}``, in this context, is simply used to name the directory into
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
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
757 ``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you
758 wish to use. Changing the data in these branches and not updating the
765 Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux
766 kernel sources that have only a single branch. This type of
769 architectures, a kernel source repository with multiple branches is more
771 board to boot. Sometimes, these patches are works-in-progress or
773 In these situations, you most likely do not want to include these
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.
782 - Encapsulating patches in a feature description and only including the
783 patches in the BSP descriptions of the applicable boards.
785 - Creating a machine branch in your kernel source repository and
788 - Creating a feature branch in your kernel source repository and
795 ---------------------
799 Given this scenario, you do not need to create any branches in the
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 ----------------
814 branches in the repository based on individual machines. Having machine
815 branches allows common source to remain in the development branch with any
816 features specific to a machine stored in the appropriate machine branch.
820 Once you have a new branch, you can set up your kernel Metadata to use
821 the branch a couple different ways. In the recipe, you can specify the
826 Another method is to use the ``branch`` command in the BSP
837 include mybsp-hw.scc
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
846 machines, and common as ``mydir``, the branches in your Git repository
857 This organization can help clarify the branch relationships. In this
858 case, ``mydir/standard/machine_a`` includes everything in ``mydir/base``
860 sources specific to those kernel types that for whatever reason are not
871 ----------------
875 that have to be regularly updated. The Yocto Project Linux kernel tools
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.