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