1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3******************************************************* 4Working with Advanced Metadata (``yocto-kernel-cache``) 5******************************************************* 6 7Overview 8======== 9 10In addition to supporting configuration fragments and patches, the Yocto 11Project kernel tools also support rich 12:term:`Metadata` that you can use to define 13complex policies and Board Support Package (BSP) support. The purpose of 14the Metadata and the tools that manage it is to help you manage the 15complexity of the configuration and sources used to support multiple 16BSPs and Linux kernel types. 17 18Kernel Metadata exists in many places. One area in the 19:ref:`overview-manual/development-environment:yocto project source repositories` 20is the ``yocto-kernel-cache`` Git repository. You can find this repository 21grouped under the "Yocto Linux Kernel" heading in the 22:yocto_git:`Yocto Project Source Repositories <>`. 23 24Kernel development tools ("kern-tools") are also available in the Yocto Project 25Source Repositories under the "Yocto Linux Kernel" heading in the 26``yocto-kernel-tools`` Git repository. The recipe that builds these 27tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in 28the :term:`Source Directory` (e.g. 29``poky``). 30 31Using Kernel Metadata in a Recipe 32================================= 33 34As mentioned in the introduction, the Yocto Project contains kernel 35Metadata, which is located in the ``yocto-kernel-cache`` Git repository. 36This Metadata defines Board Support Packages (BSPs) that correspond to 37definitions in linux-yocto recipes for corresponding BSPs. A BSP 38consists of an aggregation of kernel policy and enabled 39hardware-specific features. The BSP can be influenced from within the 40linux-yocto recipe. 41 42.. note:: 43 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. 46 47Every linux-yocto style recipe must define the 48:term:`KMACHINE` variable. This 49variable is typically set to the same value as the :term:`MACHINE` variable, 50which is used by :term:`BitBake`. 51However, in some cases, the variable might instead refer to the 52underlying platform of the :term:`MACHINE`. 53 54Multiple BSPs can reuse the same :term:`KMACHINE` name if they are built 55using the same BSP description. Multiple Corei7-based BSPs could share 56the same "intel-corei7-64" value for :term:`KMACHINE`. It is important to 57realize that :term:`KMACHINE` is just for kernel mapping, while :term:`MACHINE` 58is the machine type within a BSP Layer. Even with this distinction, 59however, these two variables can hold the same value. See the 60":ref:`kernel-dev/advanced:bsp descriptions`" section for more information. 61 62Every linux-yocto style recipe must also indicate the Linux kernel 63source repository branch used to build the Linux kernel. The 64:term:`KBRANCH` variable must be set 65to indicate the branch. 66 67.. note:: 68 69 You can use the :term:`KBRANCH` value to define an alternate branch typically 70 with a machine override as shown here from the ``meta-yocto-bsp`` layer:: 71 72 KBRANCH:edgerouter = "standard/edgerouter" 73 74 75The linux-yocto style recipes can optionally define the following 76variables: 77 78 - :term:`KERNEL_FEATURES` 79 80 - :term:`LINUX_KERNEL_TYPE` 81 82:term:`LINUX_KERNEL_TYPE` 83defines the kernel type to be used in assembling the configuration. If 84you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to "standard". 85Together with :term:`KMACHINE`, :term:`LINUX_KERNEL_TYPE` defines the search 86arguments used by the kernel tools to find the appropriate description 87within the kernel Metadata with which to build out the sources and 88configuration. The linux-yocto recipes define "standard", "tiny", and 89"preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" 90section for more information on kernel types. 91 92During the build, the kern-tools search for the BSP description file 93that most closely matches the :term:`KMACHINE` and :term:`LINUX_KERNEL_TYPE` 94variables passed in from the recipe. The tools use the first BSP 95description they find that matches both variables. If the tools cannot find 96a match, they issue a warning. 97 98The tools first search for the :term:`KMACHINE` and then for the 99:term:`LINUX_KERNEL_TYPE`. If the tools cannot find a partial match, they 100will use the sources from the :term:`KBRANCH` and any configuration 101specified in the :term:`SRC_URI`. 102 103You can use the 104:term:`KERNEL_FEATURES` 105variable to include features (configuration fragments, patches, or both) 106that are not already included by the :term:`KMACHINE` and 107:term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a 108feature specified as "features/netfilter/netfilter.scc", specify:: 109 110 KERNEL_FEATURES += "features/netfilter/netfilter.scc" 111 112To include a 113feature called "cfg/sound.scc" just for the ``qemux86`` machine, 114specify:: 115 116 KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc" 117 118The value of 119the entries in :term:`KERNEL_FEATURES` are dependent on their location 120within the kernel Metadata itself. The examples here are taken from the 121``yocto-kernel-cache`` repository. Each branch of this repository 122contains "features" and "cfg" subdirectories at the top-level. For more 123information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`" 124section. 125 126Kernel Metadata Syntax 127====================== 128 129The kernel Metadata consists of three primary types of files: ``scc`` 130[1]_ description files, configuration fragments, and patches. The 131``scc`` files define variables and include or otherwise reference any of 132the three file types. The description files are used to aggregate all 133types of kernel Metadata into what ultimately describes the sources and 134the configuration required to build a Linux kernel tailored to a 135specific machine. 136 137The ``scc`` description files are used to define two fundamental types 138of kernel Metadata: 139 140- Features 141 142- Board Support Packages (BSPs) 143 144Features aggregate sources in the form of patches and configuration 145fragments into a modular reusable unit. You can use features to 146implement conceptually separate kernel Metadata descriptions such as 147pure configuration fragments, simple patches, complex features, and 148kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel 149features and policy to be reused in the BSPs. 150 151BSPs define hardware-specific features and aggregate them with kernel 152types to form the final description of what will be assembled and built. 153 154While the kernel Metadata syntax does not enforce any logical separation 155of configuration fragments, patches, features or kernel types, best 156practices dictate a logical separation of these types of Metadata. The 157following Metadata file hierarchy is recommended:: 158 159 base/ 160 bsp/ 161 cfg/ 162 features/ 163 ktypes/ 164 patches/ 165 166The ``bsp`` directory contains the :ref:`kernel-dev/advanced:bsp descriptions`. 167The remaining directories all contain "features". Separating ``bsp`` from the 168rest of the structure aids conceptualizing intended usage. 169 170Use these guidelines to help place your ``scc`` description files within 171the structure: 172 173- If your file contains only configuration fragments, place the file in 174 the ``cfg`` directory. 175 176- If your file contains only source-code fixes, place the file in the 177 ``patches`` directory. 178 179- If your file encapsulates a major feature, often combining sources 180 and configurations, place the file in ``features`` directory. 181 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. 185 186These distinctions can easily become blurred --- especially as out-of-tree 187features slowly merge upstream over time. Also, remember that how the 188description files are placed is a purely logical organization and has no 189impact on the functionality of the kernel Metadata. There is no impact 190because all of ``cfg``, ``features``, ``patches``, and ``ktypes``, 191contain "features" as far as the kernel tools are concerned. 192 193Paths used in kernel Metadata files are relative to base, which is 194either 195:term:`FILESEXTRAPATHS` if 196you are creating Metadata in 197:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`, 198or the top level of 199:yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>` 200if you are creating 201:ref:`kernel-dev/advanced:metadata outside the recipe-space`. 202 203.. [1] 204 ``scc`` stands for Series Configuration Control, but the naming has 205 less significance in the current implementation of the tooling than 206 it had in the past. Consider ``scc`` files to be description files. 207 208Configuration 209------------- 210 211The simplest unit of kernel Metadata is the configuration-only feature. 212This feature consists of one or more Linux kernel configuration 213parameters in a configuration fragment file (``.cfg``) and a ``.scc`` 214file that describes the fragment. 215 216As an example, consider the Symmetric Multi-Processing (SMP) fragment 217used with the ``linux-yocto-4.12`` kernel as defined outside of the 218recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of 219two 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:: 222 223 cfg/smp.scc: 224 define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds" 225 define KFEATURE_COMPATIBILITY all 226 227 kconf hardware smp.cfg 228 229 cfg/smp.cfg: 230 CONFIG_SMP=y 231 CONFIG_SCHED_SMT=y 232 # Increase default NR_CPUS from 8 to 64 so that platform with 233 # more than 8 processors can be all activated at boot time 234 CONFIG_NR_CPUS=64 235 # The following is needed when setting NR_CPUS to something 236 # greater than 8 on x86 architectures, it should be automatically 237 # disregarded by Kconfig when using a different arch 238 CONFIG_X86_BIGSMP=y 239 240You can find general information on configuration 241fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section. 242 243Within the ``smp.scc`` file, the 244:term:`KFEATURE_DESCRIPTION` 245statement provides a short description of the fragment. Higher level 246kernel tools use this description. 247 248Also within the ``smp.scc`` file, the ``kconf`` command includes the 249actual configuration fragment in an ``.scc`` file, and the "hardware" 250keyword identifies the fragment as being hardware enabling, as opposed 251to general policy, which would use the "non-hardware" keyword. The 252distinction is made for the benefit of the configuration validation 253tools, which warn you if a hardware fragment overrides a policy set by a 254non-hardware fragment. 255 256.. note:: 257 258 The description file can include multiple ``kconf`` statements, one per 259 fragment. 260 261As described in the 262":ref:`kernel-dev/common:validating configuration`" section, you can 263use the following BitBake command to audit your configuration:: 264 265 $ bitbake linux-yocto -c kernel_configcheck -f 266 267Patches 268------- 269 270Patch descriptions are very similar to configuration fragment 271descriptions, which are described in the previous section. However, 272instead of a ``.cfg`` file, these descriptions work with source patches 273(i.e. ``.patch`` files). 274 275A typical patch includes a description file and the patch itself. As an 276example, consider the build patches used with the ``linux-yocto-4.12`` 277kernel as defined outside of the recipe space (i.e. 278``yocto-kernel-cache``). This Metadata consists of several files: 279``build.scc`` and a set of ``*.patch`` files. You can find these files 280in the ``patches/build`` directory of the ``yocto-4.12`` branch in the 281``yocto-kernel-cache`` Git repository. 282 283The following listings show the ``build.scc`` file and part of the 284``modpost-mask-trivial-warnings.patch`` file:: 285 286 patches/build/build.scc: 287 patch arm-serialize-build-targets.patch 288 patch powerpc-serialize-image-targets.patch 289 patch kbuild-exclude-meta-directory-from-distclean-processi.patch 290 291 # applied by kgit 292 # patch kbuild-add-meta-files-to-the-ignore-li.patch 293 294 patch modpost-mask-trivial-warnings.patch 295 patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch 296 297 patches/build/modpost-mask-trivial-warnings.patch: 298 From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001 299 From: Paul Gortmaker <paul.gortmaker@windriver.com> 300 Date: Sun, 25 Jan 2009 17:58:09 -0500 301 Subject: [PATCH] modpost: mask trivial warnings 302 303 Newer HOSTCC will complain about various stdio fcns because 304 . 305 . 306 . 307 char *dump_write = NULL, *files_source = NULL; 308 int opt; 309 -- 310 2.10.1 311 312 generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT) 313 314The description file can 315include multiple patch statements where each statement handles a single 316patch. In the example ``build.scc`` file, there are five patch statements 317for the five patches in the directory. 318 319You can create a typical ``.patch`` file using ``diff -Nurp`` or 320``git format-patch`` commands. For information on how to create patches, 321see the ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" 322and ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" 323sections. 324 325Features 326-------- 327 328Features are complex kernel Metadata types that consist of configuration 329fragments, patches, and possibly other feature description files. As an 330example, consider the following generic listing:: 331 332 features/myfeature.scc 333 define KFEATURE_DESCRIPTION "Enable myfeature" 334 335 patch 0001-myfeature-core.patch 336 patch 0002-myfeature-interface.patch 337 338 include cfg/myfeature_dependency.scc 339 kconf non-hardware myfeature.cfg 340 341This example shows how the ``patch`` and ``kconf`` commands are used as well 342as how an additional feature description file is included with the 343``include`` command. 344 345Typically, features are less granular than configuration fragments and 346are more likely than configuration fragments and patches to be the types 347of things you want to specify in the :term:`KERNEL_FEATURES` variable of the 348Linux kernel recipe. See the 349":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier 350in the manual. 351 352Kernel Types 353------------ 354 355A kernel type defines a high-level kernel policy by aggregating non-hardware 356configuration fragments with patches you want to use when building a Linux 357kernel of a specific type (e.g. a real-time kernel). Syntactically, kernel 358types are no different than features as described in the 359":ref:`kernel-dev/advanced:features`" section. The :term:`LINUX_KERNEL_TYPE` 360variable in the kernel recipe selects the kernel type. For example, in the 361``linux-yocto_4.12.bb`` kernel recipe found in ``poky/meta/recipes-kernel/linux``, a 362:ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` 363directive includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file, 364which has the following statement that defines the default kernel type:: 365 366 LINUX_KERNEL_TYPE ??= "standard" 367 368Another example would be the real-time kernel (i.e. 369``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel 370type as follows:: 371 372 LINUX_KERNEL_TYPE = "preempt-rt" 373 374.. note:: 375 376 You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory 377 of the :ref:`overview-manual/development-environment:yocto project source repositories` 378 (e.g. ``poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb``). See the 379 ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" 380 section for more information. 381 382Three kernel types ("standard", "tiny", and "preempt-rt") are supported 383for Linux Yocto kernels: 384 385- "standard": Includes the generic Linux kernel policy of the Yocto 386 Project linux-yocto kernel recipes. This policy includes, among other 387 things, which file systems, networking options, core kernel features, 388 and debugging and tracing options are supported. 389 390- "preempt-rt": Applies the ``PREEMPT_RT`` patches and the 391 configuration options required to build a real-time Linux kernel. 392 This kernel type inherits from the "standard" kernel type. 393 394- "tiny": Defines a bare minimum configuration meant to serve as a base 395 for very small Linux kernels. The "tiny" kernel type is independent 396 from the "standard" configuration. Although the "tiny" kernel type 397 does not currently include any source changes, it might in the 398 future. 399 400For any given kernel type, the Metadata is defined by the ``.scc`` (e.g. 401``standard.scc``). Here is a partial listing for the ``standard.scc`` 402file, which is found in the ``ktypes/standard`` directory of the 403``yocto-kernel-cache`` Git repository:: 404 405 # Include this kernel type fragment to get the standard features and 406 # configuration values. 407 408 # Note: if only the features are desired, but not the configuration 409 # then this should be included as: 410 # include ktypes/standard/standard.scc nocfg 411 # if no chained configuration is desired, include it as: 412 # include ktypes/standard/standard.scc nocfg inherit 413 414 415 416 include ktypes/base/base.scc 417 branch standard 418 419 kconf non-hardware standard.cfg 420 421 include features/kgdb/kgdb.scc 422 . 423 . 424 . 425 426 include cfg/net/ip6_nf.scc 427 include cfg/net/bridge.scc 428 429 include cfg/systemd.scc 430 431 include features/rfkill/rfkill.scc 432 433As with any ``.scc`` file, a kernel type definition can aggregate other 434``.scc`` files with ``include`` commands. These definitions can also 435directly pull in configuration fragments and patches with the ``kconf`` 436and ``patch`` commands, respectively. 437 438.. note:: 439 440 It is not strictly necessary to create a kernel type ``.scc`` 441 file. The Board Support Package (BSP) file can implicitly define the 442 kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the 443 ":ref:`kernel-dev/advanced:bsp descriptions`" section for more 444 information. 445 446BSP Descriptions 447---------------- 448 449BSP descriptions (i.e. ``*.scc`` files) combine kernel types with 450hardware-specific features. The hardware-specific Metadata is typically 451defined independently in the BSP layer, and then aggregated with each 452supported kernel type. 453 454.. note:: 455 456 For BSPs supported by the Yocto Project, the BSP description files 457 are located in the ``bsp`` directory of the ``yocto-kernel-cache`` 458 repository organized under the "Yocto Linux Kernel" heading in the 459 :yocto_git:`Yocto Project Source Repositories <>`. 460 461This section overviews the BSP description structure, the aggregation 462concepts, and presents a detailed example using a BSP supported by the 463Yocto Project (i.e. BeagleBone Board). For complete information on BSP 464layer file hierarchy, see the :doc:`/bsp-guide/index`. 465 466Description Overview 467~~~~~~~~~~~~~~~~~~~~ 468 469For simplicity, consider the following root BSP layer description files 470for the BeagleBone board. These files employ both a structure and naming 471convention for consistency. The naming convention for the file is as 472follows:: 473 474 bsp_root_name-kernel_type.scc 475 476Here are some example root layer 477BSP filenames for the BeagleBone Board BSP, which is supported by the 478Yocto Project:: 479 480 beaglebone-standard.scc 481 beaglebone-preempt-rt.scc 482 483Each file uses the root name (i.e "beaglebone") BSP name followed by the 484kernel type. 485 486Examine the ``beaglebone-standard.scc`` file:: 487 488 define KMACHINE beaglebone 489 define KTYPE standard 490 define KARCH arm 491 492 include ktypes/standard/standard.scc 493 branch beaglebone 494 495 include beaglebone.scc 496 497 # default policy for standard kernels 498 include features/latencytop/latencytop.scc 499 include features/profiling/profiling.scc 500 501Every top-level BSP description file 502should define the :term:`KMACHINE`, 503:term:`KTYPE`, and 504:term:`KARCH` variables. These 505variables allow the OpenEmbedded build system to identify the 506description as meeting the criteria set by the recipe being built. This 507example supports the "beaglebone" machine for the "standard" kernel and 508the "arm" architecture. 509 510Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel 511type description file. Thus, if you do not have the 512kernel type defined in your kernel Metadata as it is here, you only need 513to ensure that the 514:term:`LINUX_KERNEL_TYPE` 515variable in the kernel recipe and the :term:`KTYPE` variable in the BSP 516description file match. 517 518To separate your kernel policy from your hardware configuration, you 519include a kernel type (``ktype``), such as "standard". In the previous 520example, this is done using the following:: 521 522 include ktypes/standard/standard.scc 523 524This file aggregates all the configuration 525fragments, patches, and features that make up your standard kernel 526policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more 527information. 528 529To aggregate common configurations and features specific to the kernel 530for `mybsp`, use the following:: 531 532 include mybsp.scc 533 534You can see that in the BeagleBone example with the following:: 535 536 include beaglebone.scc 537 538For information on how to break a complete ``.config`` file into the various 539configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section. 540 541Finally, if you have any configurations specific to the hardware that 542are not in a ``*.scc`` file, you can include them as follows:: 543 544 kconf hardware mybsp-extra.cfg 545 546The BeagleBone example does not include these 547types of configurations. However, the Malta 32-bit board does 548("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file:: 549 550 define KMACHINE mti-malta32-le 551 define KMACHINE qemumipsel 552 define KTYPE standard 553 define KARCH mips 554 555 include ktypes/standard/standard.scc 556 branch mti-malta32 557 558 include mti-malta32.scc 559 kconf hardware mti-malta32-le.cfg 560 561Example 562~~~~~~~ 563 564Many real-world examples are more complex. Like any other ``.scc`` file, 565BSP descriptions can aggregate features. Consider the Minnow BSP 566definition given the ``linux-yocto-4.4`` branch of the 567``yocto-kernel-cache`` (i.e. ``yocto-kernel-cache/bsp/minnow/minnow.scc``):: 568 569 include cfg/x86.scc 570 include features/eg20t/eg20t.scc 571 include cfg/dmaengine.scc 572 include features/power/intel.scc 573 include cfg/efi.scc 574 include features/usb/ehci-hcd.scc 575 include features/usb/ohci-hcd.scc 576 include features/usb/usb-gadgets.scc 577 include features/usb/touchscreen-composite.scc 578 include cfg/timer/hpet.scc 579 include features/leds/leds.scc 580 include features/spi/spidev.scc 581 include features/i2c/i2cdev.scc 582 include features/mei/mei-txe.scc 583 584 # Earlyprintk and port debug requires 8250 585 kconf hardware cfg/8250.cfg 586 587 kconf hardware minnow.cfg 588 kconf hardware minnow-dev.cfg 589 590.. note:: 591 592 Although the Minnow Board BSP is unused, the Metadata remains and is 593 being used here just as an example. 594 595The ``minnow.scc`` description file includes a hardware configuration 596fragment (``minnow.cfg``) specific to the Minnow BSP as well as several 597more general configuration fragments and features enabling hardware 598found on the machine. This ``minnow.scc`` description file is then 599included in each of the three "minnow" description files for the 600supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). 601Consider the "minnow" description for the "standard" kernel type (i.e. 602``minnow-standard.scc``):: 603 604 define KMACHINE minnow 605 define KTYPE standard 606 define KARCH i386 607 608 include ktypes/standard 609 610 include minnow.scc 611 612 # Extra minnow configs above the minimal defined in minnow.scc 613 include cfg/efi-ext.scc 614 include features/media/media-all.scc 615 include features/sound/snd_hda_intel.scc 616 617 # The following should really be in standard.scc 618 # USB live-image support 619 include cfg/usb-mass-storage.scc 620 include cfg/boot-live.scc 621 622 # Basic profiling 623 include features/latencytop/latencytop.scc 624 include features/profiling/profiling.scc 625 626 # Requested drivers that don't have an existing scc 627 kconf hardware minnow-drivers-extra.cfg 628 629The ``include`` command midway through the file includes the ``minnow.scc`` description 630that defines all enabled hardware for the BSP that is common to all 631kernel types. Using this command significantly reduces duplication. 632 633Now consider the "minnow" description for the "tiny" kernel type (i.e. 634``minnow-tiny.scc``):: 635 636 define KMACHINE minnow 637 define KTYPE tiny 638 define KARCH i386 639 640 include ktypes/tiny 641 642 include minnow.scc 643 644As you might expect, 645the "tiny" description includes quite a bit less. In fact, it includes 646only the minimal policy defined by the "tiny" kernel type and the 647hardware-specific configuration required for booting the machine along 648with the most basic functionality of the system as defined in the base 649"minnow" description file. 650 651Notice again the three critical variables: 652:term:`KMACHINE`, 653:term:`KTYPE`, and 654:term:`KARCH`. Of these variables, only 655:term:`KTYPE` has changed to specify the "tiny" kernel type. 656 657Kernel Metadata Location 658======================== 659 660Kernel Metadata always exists outside of the kernel tree either defined 661in a kernel recipe (recipe-space) or outside of the recipe. Where you 662choose to define the Metadata depends on what you want to do and how you 663intend to work. Regardless of where you define the kernel Metadata, the 664syntax used applies equally. 665 666If you are unfamiliar with the Linux kernel and only wish to apply a 667configuration and possibly a couple of patches provided to you by 668others, the recipe-space method is recommended. This method is also a 669good approach if you are working with Linux kernel sources you do not 670control or if you just do not want to maintain a Linux kernel Git 671repository on your own. For partial information on how you can define 672kernel Metadata in the recipe-space, see the 673":ref:`kernel-dev/common:modifying an existing recipe`" section. 674 675Conversely, if you are actively developing a kernel and are already 676maintaining a Linux kernel Git repository of your own, you might find it 677more convenient to work with kernel Metadata kept outside the 678recipe-space. Working with Metadata in this area can make iterative 679development of the Linux kernel more efficient outside of the BitBake 680environment. 681 682Recipe-Space Metadata 683--------------------- 684 685When stored in recipe-space, the kernel Metadata files reside in a 686directory hierarchy below :term:`FILESEXTRAPATHS`. For 687a linux-yocto recipe or for a Linux kernel recipe derived by copying 688:oe_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb 689</openembedded-core/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>` 690into your layer and modifying it, :term:`FILESEXTRAPATHS` is typically set to 691``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. 692See the ":ref:`kernel-dev/common:modifying an existing recipe`" 693section for more information. 694 695Here is an example that shows a trivial tree of kernel Metadata stored 696in recipe-space within a BSP layer:: 697 698 meta-my_bsp_layer/ 699 `-- recipes-kernel 700 `-- linux 701 `-- linux-yocto 702 |-- bsp-standard.scc 703 |-- bsp.cfg 704 `-- standard.cfg 705 706When the Metadata is stored in recipe-space, you must take steps to 707ensure BitBake has the necessary information to decide what files to 708fetch and when they need to be fetched again. It is only necessary to 709specify the ``.scc`` files on the 710:term:`SRC_URI`. BitBake parses them 711and fetches any files referenced in the ``.scc`` files by the 712``include``, ``patch``, or ``kconf`` commands. Because of this, it is 713necessary to bump the recipe :term:`PR` 714value when changing the content of files not explicitly listed in the 715:term:`SRC_URI`. 716 717If the BSP description is in recipe space, you cannot simply list the 718``*.scc`` in the :term:`SRC_URI` statement. You need to use the following 719form from your kernel append file:: 720 721 SRC_URI:append:myplatform = " \ 722 file://myplatform;type=kmeta;destsuffix=myplatform \ 723 " 724 725Metadata Outside the Recipe-Space 726--------------------------------- 727 728When stored outside of the recipe-space, the kernel Metadata files 729reside in a separate repository. The OpenEmbedded build system adds the 730Metadata to the build as a "type=kmeta" repository through the 731:term:`SRC_URI` variable. As an 732example, consider the following :term:`SRC_URI` statement from the 733``linux-yocto_5.15.bb`` kernel recipe:: 734 735 SRC_URI = "git://git.yoctoproject.org/linux-yocto.git;name=machine;branch=${KBRANCH};protocol=https \ 736 git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-5.15;destsuffix=${KMETA};protocol=https" 737 738``${KMETA}``, in this context, is simply used to name the directory into 739which the Git fetcher places the Metadata. This behavior is no different 740than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g. 741see the previous section). 742 743You can keep kernel Metadata in a "kernel-cache", which is a directory 744containing configuration fragments. As with any Metadata kept outside 745the recipe-space, you simply need to use the :term:`SRC_URI` statement with 746the "type=kmeta" attribute. Doing so makes the kernel Metadata available 747during the configuration phase. 748 749If you modify the Metadata, you must not forget to update the :term:`SRCREV` 750statements in the kernel's recipe. In particular, you need to update the 751``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you 752wish to use. Changing the data in these branches and not updating the 753:term:`SRCREV` statements to match will cause the build to fetch an older 754commit. 755 756Organizing Your Source 757====================== 758 759Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux 760kernel sources that have only a single branch. This type of 761repository structure is fine for linear development supporting a single 762machine and architecture. However, if you work with multiple boards and 763architectures, a kernel source repository with multiple branches is more 764efficient. For example, suppose you need a series of patches for one 765board to boot. Sometimes, these patches are works-in-progress or 766fundamentally wrong, yet they are still necessary for specific boards. 767In these situations, you most likely do not want to include these 768patches in every kernel you build (i.e. have the patches as part of the 769default branch). It is situations like these that give rise to 770multiple branches used within a Linux kernel sources Git repository. 771 772Here are repository organization strategies maximizing source reuse, 773removing redundancy, and logically ordering your changes. This section 774presents strategies for the following cases: 775 776- Encapsulating patches in a feature description and only including the 777 patches in the BSP descriptions of the applicable boards. 778 779- Creating a machine branch in your kernel source repository and 780 applying the patches on that branch only. 781 782- Creating a feature branch in your kernel source repository and 783 merging that branch into your BSP when needed. 784 785The approach you take is entirely up to you and depends on what works 786best for your development model. 787 788Encapsulating Patches 789--------------------- 790 791If you are reusing patches from an external tree and are not working on 792the patches, you might find the encapsulated feature to be appropriate. 793Given this scenario, you do not need to create any branches in the 794source repository. Rather, you just take the static patches you need and 795encapsulate them within a feature description. Once you have the feature 796description, you simply include that into the BSP description as 797described in the ":ref:`kernel-dev/advanced:bsp descriptions`" section. 798 799You can find information on how to create patches and BSP descriptions 800in the ":ref:`kernel-dev/advanced:patches`" and 801":ref:`kernel-dev/advanced:bsp descriptions`" sections. 802 803Machine Branches 804---------------- 805 806When you have multiple machines and architectures to support, or you are 807actively working on board support, it is more efficient to create 808branches in the repository based on individual machines. Having machine 809branches allows common source to remain in the development branch with any 810features specific to a machine stored in the appropriate machine branch. 811This organization method frees you from continually reintegrating your 812patches into a feature. 813 814Once you have a new branch, you can set up your kernel Metadata to use 815the branch a couple different ways. In the recipe, you can specify the 816new branch as the :term:`KBRANCH` to use for the board as follows:: 817 818 KBRANCH = "mynewbranch" 819 820Another method is to use the ``branch`` command in the BSP 821description:: 822 823 mybsp.scc: 824 define KMACHINE mybsp 825 define KTYPE standard 826 define KARCH i386 827 include standard.scc 828 829 branch mynewbranch 830 831 include mybsp-hw.scc 832 833If you find yourself with numerous branches, you might consider using a 834hierarchical branching system similar to what the Yocto Linux Kernel Git 835repositories use:: 836 837 common/kernel_type/machine 838 839If you had two kernel types, "standard" and "small" for instance, three 840machines, and common as ``mydir``, the branches in your Git repository 841might look like this:: 842 843 mydir/base 844 mydir/standard/base 845 mydir/standard/machine_a 846 mydir/standard/machine_b 847 mydir/standard/machine_c 848 mydir/small/base 849 mydir/small/machine_a 850 851This organization can help clarify the branch relationships. In this 852case, ``mydir/standard/machine_a`` includes everything in ``mydir/base`` 853and ``mydir/standard/base``. The "standard" and "small" branches add 854sources specific to those kernel types that for whatever reason are not 855appropriate for the other branches. 856 857.. note:: 858 859 The "base" branches are an artifact of the way Git manages its data 860 internally on the filesystem: Git will not allow you to use 861 ``mydir/standard`` and ``mydir/standard/machine_a`` because it would have to 862 create a file and a directory named "standard". 863 864Feature Branches 865---------------- 866 867When you are actively developing new features, it can be more efficient 868to work with that feature as a branch, rather than as a set of patches 869that have to be regularly updated. The Yocto Project Linux kernel tools 870provide for this with the ``git merge`` command. 871 872To merge a feature branch into a BSP, insert the ``git merge`` command 873after any ``branch`` commands:: 874 875 mybsp.scc: 876 define KMACHINE mybsp 877 define KTYPE standard 878 define KARCH i386 879 include standard.scc 880 881 branch mynewbranch 882 git merge myfeature 883 884 include mybsp-hw.scc 885 886SCC Description File Reference 887============================== 888 889This section provides a brief reference for the commands you can use 890within an SCC description file (``.scc``): 891 892- ``branch [ref]``: Creates a new branch relative to the current branch 893 (typically ``${KTYPE}``) using the currently checked-out branch, or 894 "ref" if specified. 895 896- ``define``: Defines variables, such as 897 :term:`KMACHINE`, 898 :term:`KTYPE`, 899 :term:`KARCH`, and 900 :term:`KFEATURE_DESCRIPTION`. 901 902- ``include SCC_FILE``: Includes an SCC file in the current file. The 903 file is parsed as if you had inserted it inline. 904 905- ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration 906 fragment for merging into the final Linux ``.config`` file. 907 908- ``git merge GIT_BRANCH``: Merges the feature branch into the current 909 branch. 910 911- ``patch PATCH_FILE``: Applies the patch to the current Git branch. 912 913 914