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 356non-hardware configuration fragments with patches you want to use when 357building a Linux kernel of a specific type (e.g. a real-time kernel). 358Syntactically, kernel types are no different than features as described 359in the ":ref:`kernel-dev/advanced:features`" section. The 360:term:`LINUX_KERNEL_TYPE` 361variable in the kernel recipe selects the kernel type. For example, in 362the ``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>` directive 365includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file, 366which has the following statement that defines the default kernel type:: 367 368 LINUX_KERNEL_TYPE ??= "standard" 369 370Another example would be the real-time kernel (i.e. 371``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel 372type as follows:: 373 374 LINUX_KERNEL_TYPE = "preempt-rt" 375 376.. note:: 377 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`" 382 section for more information. 383 384Three kernel types ("standard", "tiny", and "preempt-rt") are supported 385for Linux Yocto kernels: 386 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, 390 and debugging and tracing options are supported. 391 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. 395 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 400 future. 401 402For any given kernel type, the Metadata is defined by the ``.scc`` (e.g. 403``standard.scc``). Here is a partial listing for the ``standard.scc`` 404file, which is found in the ``ktypes/standard`` directory of the 405``yocto-kernel-cache`` Git repository:: 406 407 # Include this kernel type fragment to get the standard features and 408 # configuration values. 409 410 # Note: if only the features are desired, but not the configuration 411 # then this should be included as: 412 # include ktypes/standard/standard.scc nocfg 413 # if no chained configuration is desired, include it as: 414 # include ktypes/standard/standard.scc nocfg inherit 415 416 417 418 include ktypes/base/base.scc 419 branch standard 420 421 kconf non-hardware standard.cfg 422 423 include features/kgdb/kgdb.scc 424 . 425 . 426 . 427 428 include cfg/net/ip6_nf.scc 429 include cfg/net/bridge.scc 430 431 include cfg/systemd.scc 432 433 include features/rfkill/rfkill.scc 434 435As with any ``.scc`` file, a kernel type definition can aggregate other 436``.scc`` files with ``include`` commands. These definitions can also 437directly pull in configuration fragments and patches with the ``kconf`` 438and ``patch`` commands, respectively. 439 440.. note:: 441 442 It is not strictly necessary to create a kernel type ``.scc`` 443 file. The Board Support Package (BSP) file can implicitly define the 444 kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the 445 ":ref:`kernel-dev/advanced:bsp descriptions`" section for more 446 information. 447 448BSP Descriptions 449---------------- 450 451BSP descriptions (i.e. ``*.scc`` files) combine kernel types with 452hardware-specific features. The hardware-specific Metadata is typically 453defined independently in the BSP layer, and then aggregated with each 454supported kernel type. 455 456.. note:: 457 458 For BSPs supported by the Yocto Project, the BSP description files 459 are located in the ``bsp`` directory of the ``yocto-kernel-cache`` 460 repository organized under the "Yocto Linux Kernel" heading in the 461 :yocto_git:`Yocto Project Source Repositories <>`. 462 463This section overviews the BSP description structure, the aggregation 464concepts, and presents a detailed example using a BSP supported by the 465Yocto Project (i.e. BeagleBone Board). For complete information on BSP 466layer file hierarchy, see the :doc:`/bsp-guide/index`. 467 468Description Overview 469~~~~~~~~~~~~~~~~~~~~ 470 471For simplicity, consider the following root BSP layer description files 472for the BeagleBone board. These files employ both a structure and naming 473convention for consistency. The naming convention for the file is as 474follows:: 475 476 bsp_root_name-kernel_type.scc 477 478Here are some example root layer 479BSP filenames for the BeagleBone Board BSP, which is supported by the 480Yocto Project:: 481 482 beaglebone-standard.scc 483 beaglebone-preempt-rt.scc 484 485Each file uses the root name (i.e "beaglebone") BSP name followed by the 486kernel type. 487 488Examine the ``beaglebone-standard.scc`` file:: 489 490 define KMACHINE beaglebone 491 define KTYPE standard 492 define KARCH arm 493 494 include ktypes/standard/standard.scc 495 branch beaglebone 496 497 include beaglebone.scc 498 499 # default policy for standard kernels 500 include features/latencytop/latencytop.scc 501 include features/profiling/profiling.scc 502 503Every top-level BSP description file 504should define the :term:`KMACHINE`, 505:term:`KTYPE`, and 506:term:`KARCH` variables. These 507variables allow the OpenEmbedded build system to identify the 508description as meeting the criteria set by the recipe being built. This 509example supports the "beaglebone" machine for the "standard" kernel and 510the "arm" architecture. 511 512Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel 513type description file. Thus, if you do not have the 514kernel type defined in your kernel Metadata as it is here, you only need 515to ensure that the 516:term:`LINUX_KERNEL_TYPE` 517variable in the kernel recipe and the :term:`KTYPE` variable in the BSP 518description file match. 519 520To separate your kernel policy from your hardware configuration, you 521include a kernel type (``ktype``), such as "standard". In the previous 522example, this is done using the following:: 523 524 include ktypes/standard/standard.scc 525 526This file aggregates all the configuration 527fragments, patches, and features that make up your standard kernel 528policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more 529information. 530 531To aggregate common configurations and features specific to the kernel 532for `mybsp`, use the following:: 533 534 include mybsp.scc 535 536You can see that in the BeagleBone example with the following:: 537 538 include beaglebone.scc 539 540For information on how to break a complete ``.config`` file into the various 541configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section. 542 543Finally, if you have any configurations specific to the hardware that 544are not in a ``*.scc`` file, you can include them as follows:: 545 546 kconf hardware mybsp-extra.cfg 547 548The BeagleBone example does not include these 549types of configurations. However, the Malta 32-bit board does 550("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file:: 551 552 define KMACHINE mti-malta32-le 553 define KMACHINE qemumipsel 554 define KTYPE standard 555 define KARCH mips 556 557 include ktypes/standard/standard.scc 558 branch mti-malta32 559 560 include mti-malta32.scc 561 kconf hardware mti-malta32-le.cfg 562 563Example 564~~~~~~~ 565 566Many real-world examples are more complex. Like any other ``.scc`` file, 567BSP descriptions can aggregate features. Consider the Minnow BSP 568definition given the ``linux-yocto-4.4`` branch of the 569``yocto-kernel-cache`` (i.e. 570``yocto-kernel-cache/bsp/minnow/minnow.scc``): 571 572.. note:: 573 574 Although the Minnow Board BSP is unused, the Metadata remains and is 575 being used here just as an example. 576 577:: 578 579 include cfg/x86.scc 580 include features/eg20t/eg20t.scc 581 include cfg/dmaengine.scc 582 include features/power/intel.scc 583 include cfg/efi.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 588 include cfg/timer/hpet.scc 589 include features/leds/leds.scc 590 include features/spi/spidev.scc 591 include features/i2c/i2cdev.scc 592 include features/mei/mei-txe.scc 593 594 # Earlyprintk and port debug requires 8250 595 kconf hardware cfg/8250.cfg 596 597 kconf hardware minnow.cfg 598 kconf hardware minnow-dev.cfg 599 600The ``minnow.scc`` description file includes a hardware configuration 601fragment (``minnow.cfg``) specific to the Minnow BSP as well as several 602more general configuration fragments and features enabling hardware 603found on the machine. This ``minnow.scc`` description file is then 604included in each of the three "minnow" description files for the 605supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). 606Consider the "minnow" description for the "standard" kernel type (i.e. 607``minnow-standard.scc``):: 608 609 define KMACHINE minnow 610 define KTYPE standard 611 define KARCH i386 612 613 include ktypes/standard 614 615 include minnow.scc 616 617 # Extra minnow configs above the minimal defined in minnow.scc 618 include cfg/efi-ext.scc 619 include features/media/media-all.scc 620 include features/sound/snd_hda_intel.scc 621 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 626 627 # Basic profiling 628 include features/latencytop/latencytop.scc 629 include features/profiling/profiling.scc 630 631 # Requested drivers that don't have an existing scc 632 kconf hardware minnow-drivers-extra.cfg 633 634The ``include`` command midway through the file includes the ``minnow.scc`` description 635that defines all enabled hardware for the BSP that is common to all 636kernel types. Using this command significantly reduces duplication. 637 638Now consider the "minnow" description for the "tiny" kernel type (i.e. 639``minnow-tiny.scc``):: 640 641 define KMACHINE minnow 642 define KTYPE tiny 643 define KARCH i386 644 645 include ktypes/tiny 646 647 include minnow.scc 648 649As you might expect, 650the "tiny" description includes quite a bit less. In fact, it includes 651only the minimal policy defined by the "tiny" kernel type and the 652hardware-specific configuration required for booting the machine along 653with the most basic functionality of the system as defined in the base 654"minnow" description file. 655 656Notice again the three critical variables: 657:term:`KMACHINE`, 658:term:`KTYPE`, and 659:term:`KARCH`. Of these variables, only 660:term:`KTYPE` has changed to specify the "tiny" kernel type. 661 662Kernel Metadata Location 663======================== 664 665Kernel Metadata always exists outside of the kernel tree either defined 666in a kernel recipe (recipe-space) or outside of the recipe. Where you 667choose to define the Metadata depends on what you want to do and how you 668intend to work. Regardless of where you define the kernel Metadata, the 669syntax used applies equally. 670 671If you are unfamiliar with the Linux kernel and only wish to apply a 672configuration and possibly a couple of patches provided to you by 673others, the recipe-space method is recommended. This method is also a 674good approach if you are working with Linux kernel sources you do not 675control or if you just do not want to maintain a Linux kernel Git 676repository on your own. For partial information on how you can define 677kernel Metadata in the recipe-space, see the 678":ref:`kernel-dev/common:modifying an existing recipe`" section. 679 680Conversely, if you are actively developing a kernel and are already 681maintaining a Linux kernel Git repository of your own, you might find it 682more convenient to work with kernel Metadata kept outside the 683recipe-space. Working with Metadata in this area can make iterative 684development of the Linux kernel more efficient outside of the BitBake 685environment. 686 687Recipe-Space Metadata 688--------------------- 689 690When stored in recipe-space, the kernel Metadata files reside in a 691directory hierarchy below :term:`FILESEXTRAPATHS`. For 692a 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>` 695into your layer and modifying it, :term:`FILESEXTRAPATHS` is typically set to 696``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. 697See the ":ref:`kernel-dev/common:modifying an existing recipe`" 698section for more information. 699 700Here is an example that shows a trivial tree of kernel Metadata stored 701in recipe-space within a BSP layer:: 702 703 meta-my_bsp_layer/ 704 `-- recipes-kernel 705 `-- linux 706 `-- linux-yocto 707 |-- bsp-standard.scc 708 |-- bsp.cfg 709 `-- standard.cfg 710 711When the Metadata is stored in recipe-space, you must take steps to 712ensure BitBake has the necessary information to decide what files to 713fetch and when they need to be fetched again. It is only necessary to 714specify the ``.scc`` files on the 715:term:`SRC_URI`. BitBake parses them 716and fetches any files referenced in the ``.scc`` files by the 717``include``, ``patch``, or ``kconf`` commands. Because of this, it is 718necessary to bump the recipe :term:`PR` 719value when changing the content of files not explicitly listed in the 720:term:`SRC_URI`. 721 722If 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 724form from your kernel append file:: 725 726 SRC_URI:append:myplatform = " \ 727 file://myplatform;type=kmeta;destsuffix=myplatform \ 728 " 729 730Metadata Outside the Recipe-Space 731--------------------------------- 732 733When stored outside of the recipe-space, the kernel Metadata files 734reside in a separate repository. The OpenEmbedded build system adds the 735Metadata to the build as a "type=kmeta" repository through the 736:term:`SRC_URI` variable. As an 737example, consider the following :term:`SRC_URI` statement from the 738``linux-yocto_4.12.bb`` kernel recipe:: 739 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=${KMETA}" 742 743 744``${KMETA}``, in this context, is simply used to name the directory into 745which the Git fetcher places the Metadata. This behavior is no different 746than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g. 747see the previous section). 748 749You can keep kernel Metadata in a "kernel-cache", which is a directory 750containing configuration fragments. As with any Metadata kept outside 751the recipe-space, you simply need to use the :term:`SRC_URI` statement with 752the "type=kmeta" attribute. Doing so makes the kernel Metadata available 753during the configuration phase. 754 755If you modify the Metadata, you must not forget to update the :term:`SRCREV` 756statements 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 758wish to use. Changing the data in these branches and not updating the 759:term:`SRCREV` statements to match will cause the build to fetch an older 760commit. 761 762Organizing Your Source 763====================== 764 765Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux 766kernel sources that have only a single branch. This type of 767repository structure is fine for linear development supporting a single 768machine and architecture. However, if you work with multiple boards and 769architectures, a kernel source repository with multiple branches is more 770efficient. For example, suppose you need a series of patches for one 771board to boot. Sometimes, these patches are works-in-progress or 772fundamentally wrong, yet they are still necessary for specific boards. 773In these situations, you most likely do not want to include these 774patches in every kernel you build (i.e. have the patches as part of the 775default branch). It is situations like these that give rise to 776multiple branches used within a Linux kernel sources Git repository. 777 778Here are repository organization strategies maximizing source reuse, 779removing redundancy, and logically ordering your changes. This section 780presents strategies for the following cases: 781 782- Encapsulating patches in a feature description and only including the 783 patches in the BSP descriptions of the applicable boards. 784 785- Creating a machine branch in your kernel source repository and 786 applying the patches on that branch only. 787 788- Creating a feature branch in your kernel source repository and 789 merging that branch into your BSP when needed. 790 791The approach you take is entirely up to you and depends on what works 792best for your development model. 793 794Encapsulating Patches 795--------------------- 796 797If you are reusing patches from an external tree and are not working on 798the patches, you might find the encapsulated feature to be appropriate. 799Given this scenario, you do not need to create any branches in the 800source repository. Rather, you just take the static patches you need and 801encapsulate them within a feature description. Once you have the feature 802description, you simply include that into the BSP description as 803described in the ":ref:`kernel-dev/advanced:bsp descriptions`" section. 804 805You can find information on how to create patches and BSP descriptions 806in the ":ref:`kernel-dev/advanced:patches`" and 807":ref:`kernel-dev/advanced:bsp descriptions`" sections. 808 809Machine Branches 810---------------- 811 812When you have multiple machines and architectures to support, or you are 813actively working on board support, it is more efficient to create 814branches in the repository based on individual machines. Having machine 815branches allows common source to remain in the development branch with any 816features specific to a machine stored in the appropriate machine branch. 817This organization method frees you from continually reintegrating your 818patches into a feature. 819 820Once you have a new branch, you can set up your kernel Metadata to use 821the branch a couple different ways. In the recipe, you can specify the 822new branch as the :term:`KBRANCH` to use for the board as follows:: 823 824 KBRANCH = "mynewbranch" 825 826Another method is to use the ``branch`` command in the BSP 827description:: 828 829 mybsp.scc: 830 define KMACHINE mybsp 831 define KTYPE standard 832 define KARCH i386 833 include standard.scc 834 835 branch mynewbranch 836 837 include mybsp-hw.scc 838 839If you find yourself with numerous branches, you might consider using a 840hierarchical branching system similar to what the Yocto Linux Kernel Git 841repositories use:: 842 843 common/kernel_type/machine 844 845If you had two kernel types, "standard" and "small" for instance, three 846machines, and common as ``mydir``, the branches in your Git repository 847might look like this:: 848 849 mydir/base 850 mydir/standard/base 851 mydir/standard/machine_a 852 mydir/standard/machine_b 853 mydir/standard/machine_c 854 mydir/small/base 855 mydir/small/machine_a 856 857This organization can help clarify the branch relationships. In this 858case, ``mydir/standard/machine_a`` includes everything in ``mydir/base`` 859and ``mydir/standard/base``. The "standard" and "small" branches add 860sources specific to those kernel types that for whatever reason are not 861appropriate for the other branches. 862 863.. note:: 864 865 The "base" branches are an artifact of the way Git manages its data 866 internally on the filesystem: Git will not allow you to use 867 ``mydir/standard`` and ``mydir/standard/machine_a`` because it would have to 868 create a file and a directory named "standard". 869 870Feature Branches 871---------------- 872 873When you are actively developing new features, it can be more efficient 874to work with that feature as a branch, rather than as a set of patches 875that have to be regularly updated. The Yocto Project Linux kernel tools 876provide for this with the ``git merge`` command. 877 878To merge a feature branch into a BSP, insert the ``git merge`` command 879after any ``branch`` commands:: 880 881 mybsp.scc: 882 define KMACHINE mybsp 883 define KTYPE standard 884 define KARCH i386 885 include standard.scc 886 887 branch mynewbranch 888 git merge myfeature 889 890 include mybsp-hw.scc 891 892SCC Description File Reference 893============================== 894 895This section provides a brief reference for the commands you can use 896within an SCC description file (``.scc``): 897 898- ``branch [ref]``: Creates a new branch relative to the current branch 899 (typically ``${KTYPE}``) using the currently checked-out branch, or 900 "ref" if specified. 901 902- ``define``: Defines variables, such as 903 :term:`KMACHINE`, 904 :term:`KTYPE`, 905 :term:`KARCH`, and 906 :term:`KFEATURE_DESCRIPTION`. 907 908- ``include SCC_FILE``: Includes an SCC file in the current file. The 909 file is parsed as if you had inserted it inline. 910 911- ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration 912 fragment for merging into the final Linux ``.config`` file. 913 914- ``git merge GIT_BRANCH``: Merges the feature branch into the current 915 branch. 916 917- ``patch PATCH_FILE``: Applies the patch to the current Git branch. 918 919 920