1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3************ 4Common Tasks 5************ 6 7This chapter presents several common tasks you perform when you work 8with the Yocto Project Linux kernel. These tasks include preparing your 9host development system for kernel development, preparing a layer, 10modifying an existing recipe, patching the kernel, configuring the 11kernel, iterative development, working with your own sources, and 12incorporating out-of-tree modules. 13 14.. note:: 15 16 The examples presented in this chapter work with the Yocto Project 17 2.4 Release and forward. 18 19Preparing the Build Host to Work on the Kernel 20============================================== 21 22Before you can do any kernel development, you need to be sure your build 23host is set up to use the Yocto Project. For information on how to get 24set up, see the ":doc:`/dev-manual/start`" section in 25the Yocto Project Development Tasks Manual. Part of preparing the system 26is creating a local Git repository of the 27:term:`Source Directory` (``poky``) on your system. Follow the steps in the 28":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" 29section in the Yocto Project Development Tasks Manual to set up your 30Source Directory. 31 32.. note:: 33 34 Be sure you check out the appropriate development branch or you 35 create your local branch by checking out a specific tag to get the 36 desired version of Yocto Project. See the 37 ":ref:`dev-manual/start:checking out by branch in poky`" and 38 ":ref:`dev-manual/start:checking out by tag in poky`" 39 sections in the Yocto Project Development Tasks Manual for more information. 40 41Kernel development is best accomplished using 42:ref:`devtool <sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow>` 43and not through traditional kernel workflow methods. The remainder of 44this section provides information for both scenarios. 45 46Getting Ready to Develop Using ``devtool`` 47------------------------------------------ 48 49Follow these steps to prepare to update the kernel image using 50``devtool``. Completing this procedure leaves you with a clean kernel 51image and ready to make modifications as described in the 52":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" 53section: 54 55#. *Initialize the BitBake Environment:* 56 you need to initialize the BitBake build environment by sourcing 57 the build environment script (i.e. :ref:`structure-core-script`):: 58 59 $ cd poky 60 $ source oe-init-build-env 61 62 .. note:: 63 64 The previous commands assume the 65 :ref:`overview-manual/development-environment:yocto project source repositories` 66 (i.e. ``poky``) have been cloned using Git and the local repository is named 67 "poky". 68 69#. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable 70 is set to "qemux86-64", which is fine if you are building for the QEMU 71 emulator in 64-bit mode. However, if you are not, you need to set the 72 :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file 73 found in the :term:`Build Directory` (i.e. ``poky/build`` in this example). 74 75 Also, since you are preparing to work on the kernel image, you need 76 to set the :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable to include 77 kernel modules. 78 79 In this example we wish to build for qemux86 so we must set the 80 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules". 81 As described we do this by appending to ``conf/local.conf``:: 82 83 MACHINE = "qemux86" 84 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" 85 86#. *Create a Layer for Patches:* You need to create a layer to hold 87 patches created for the kernel image. You can use the 88 ``bitbake-layers create-layer`` command as follows:: 89 90 $ cd poky/build 91 $ bitbake-layers create-layer ../../meta-mylayer 92 NOTE: Starting bitbake server... 93 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' 94 $ 95 96 .. note:: 97 98 For background information on working with common and BSP layers, 99 see the 100 ":ref:`dev-manual/layers:understanding and creating layers`" 101 section in the Yocto Project Development Tasks Manual and the 102 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board 103 Support (BSP) Developer's Guide, respectively. For information on how to 104 use the ``bitbake-layers create-layer`` command to quickly set up a layer, 105 see the 106 ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" 107 section in the Yocto Project Development Tasks Manual. 108 109#. *Inform the BitBake Build Environment About Your Layer:* As directed 110 when you created your layer, you need to add the layer to the 111 :term:`BBLAYERS` variable in the 112 ``bblayers.conf`` file as follows:: 113 114 $ cd poky/build 115 $ bitbake-layers add-layer ../../meta-mylayer 116 NOTE: Starting bitbake server... 117 $ 118 119#. *Build the Clean Image:* The final step in preparing to work on the 120 kernel is to build an initial image using ``bitbake``:: 121 122 $ bitbake core-image-minimal 123 Parsing recipes: 100% |##########################################| Time: 0:00:05 124 Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors. 125 WARNING: No packages to add, building image core-image-minimal unmodified 126 Loading cache: 100% |############################################| Time: 0:00:00 127 Loaded 1299 entries from dependency cache. 128 NOTE: Resolving any missing task queue dependencies 129 Initializing tasks: 100% |#######################################| Time: 0:00:07 130 Checking sstate mirror object availability: 100% |###############| Time: 0:00:00 131 NOTE: Executing SetScene Tasks 132 NOTE: Executing RunQueue Tasks 133 NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded. 134 135 If you were 136 building for actual hardware and not for emulation, you could flash 137 the image to a USB stick on ``/dev/sdd`` and boot your device. For an 138 example that uses a Minnowboard, see the 139 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>` 140 Wiki page. 141 142At this point you have set up to start making modifications to the 143kernel. For a continued example, see the 144":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" 145section. 146 147Getting Ready for Traditional Kernel Development 148------------------------------------------------ 149 150Getting ready for traditional kernel development using the Yocto Project 151involves many of the same steps as described in the previous section. 152However, you need to establish a local copy of the kernel source since 153you will be editing these files. 154 155Follow these steps to prepare to update the kernel image using 156traditional kernel development flow with the Yocto Project. Completing 157this procedure leaves you ready to make modifications to the kernel 158source as described in the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" 159section: 160 161#. *Initialize the BitBake Environment:* Before you can do anything 162 using BitBake, you need to initialize the BitBake build environment 163 by sourcing the build environment script (i.e. 164 :ref:`structure-core-script`). 165 Also, for this example, be sure that the local branch you have 166 checked out for ``poky`` is the Yocto Project &DISTRO_NAME; branch. If 167 you need to checkout out the &DISTRO_NAME; branch, see the 168 ":ref:`dev-manual/start:checking out by branch in poky`" 169 section in the Yocto Project Development Tasks Manual:: 170 171 $ cd poky 172 $ git branch 173 master 174 * &DISTRO_NAME_NO_CAP; 175 $ source oe-init-build-env 176 177 .. note:: 178 179 The previous commands assume the 180 :ref:`overview-manual/development-environment:yocto project source repositories` 181 (i.e. ``poky``) have been cloned using Git and the local repository is named 182 "poky". 183 184#. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable is 185 set to "qemux86-64", which is fine if you are building for the QEMU emulator 186 in 64-bit mode. However, if you are not, you need to set the :term:`MACHINE` 187 variable appropriately in your ``conf/local.conf`` file found in the 188 :term:`Build Directory` (i.e. ``poky/build`` in this example). 189 190 Also, since you are preparing to work on the kernel image, you need 191 to set the 192 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` 193 variable to include kernel modules. 194 195 In this example we wish to build for qemux86 so we must set the 196 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules". 197 As described we do this by appending to ``conf/local.conf``:: 198 199 MACHINE = "qemux86" 200 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" 201 202#. *Create a Layer for Patches:* You need to create a layer to hold 203 patches created for the kernel image. You can use the 204 ``bitbake-layers create-layer`` command as follows:: 205 206 $ cd poky/build 207 $ bitbake-layers create-layer ../../meta-mylayer 208 NOTE: Starting bitbake server... 209 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' 210 211 .. note:: 212 213 For background information on working with common and BSP layers, 214 see the 215 ":ref:`dev-manual/layers:understanding and creating layers`" 216 section in the Yocto Project Development Tasks Manual and the 217 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board 218 Support (BSP) Developer's Guide, respectively. For information on how to 219 use the ``bitbake-layers create-layer`` command to quickly set up a layer, 220 see the 221 ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" 222 section in the Yocto Project Development Tasks Manual. 223 224#. *Inform the BitBake Build Environment About Your Layer:* As directed 225 when you created your layer, you need to add the layer to the 226 :term:`BBLAYERS` variable in the 227 ``bblayers.conf`` file as follows:: 228 229 $ cd poky/build 230 $ bitbake-layers add-layer ../../meta-mylayer 231 NOTE: Starting bitbake server ... 232 $ 233 234#. *Create a Local Copy of the Kernel Git Repository:* You can find Git 235 repositories of supported Yocto Project kernels organized under 236 "Yocto Linux Kernel" in the Yocto Project Source Repositories at 237 :yocto_git:`/`. 238 239 For simplicity, it is recommended that you create your copy of the 240 kernel Git repository outside of the 241 :term:`Source Directory`, which is 242 usually named ``poky``. Also, be sure you are in the 243 ``standard/base`` branch. 244 245 The following commands show how to create a local copy of the 246 ``linux-yocto-4.12`` kernel and be in the ``standard/base`` branch:: 247 248 $ cd ~ 249 $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base 250 Cloning into 'linux-yocto-4.12'... 251 remote: Counting objects: 6097195, done. 252 remote: Compressing objects: 100% (901026/901026), done. 253 remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256) 254 Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done. 255 Resolving deltas: 100% (5152604/5152604), done. Checking connectivity... done. 256 Checking out files: 100% (59846/59846), done. 257 258 .. note:: 259 260 The ``linux-yocto-4.12`` kernel can be used with the Yocto Project 2.4 261 release and forward. 262 You cannot use the ``linux-yocto-4.12`` kernel with releases prior to 263 Yocto Project 2.4. 264 265#. *Create a Local Copy of the Kernel Cache Git Repository:* For 266 simplicity, it is recommended that you create your copy of the kernel 267 cache Git repository outside of the 268 :term:`Source Directory`, which is 269 usually named ``poky``. Also, for this example, be sure you are in 270 the ``yocto-4.12`` branch. 271 272 The following commands show how to create a local copy of the 273 ``yocto-kernel-cache`` and switch to the ``yocto-4.12`` branch:: 274 275 $ cd ~ 276 $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12 277 Cloning into 'yocto-kernel-cache'... 278 remote: Counting objects: 22639, done. 279 remote: Compressing objects: 100% (9761/9761), done. 280 remote: Total 22639 (delta 12400), reused 22586 (delta 12347) 281 Receiving objects: 100% (22639/22639), 22.34 MiB | 6.27 MiB/s, done. 282 Resolving deltas: 100% (12400/12400), done. 283 Checking connectivity... done. 284 285At this point, you are ready to start making modifications to the kernel 286using traditional kernel development steps. For a continued example, see 287the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" 288section. 289 290Creating and Preparing a Layer 291============================== 292 293If you are going to be modifying kernel recipes, it is recommended that 294you create and prepare your own layer in which to do your work. Your 295layer contains its own :term:`BitBake` 296append files (``.bbappend``) and provides a convenient mechanism to 297create your own recipe files (``.bb``) as well as store and use kernel 298patch files. For background information on working with layers, see the 299":ref:`dev-manual/layers:understanding and creating layers`" 300section in the Yocto Project Development Tasks Manual. 301 302.. note:: 303 304 The Yocto Project comes with many tools that simplify tasks you need 305 to perform. One such tool is the ``bitbake-layers create-layer`` 306 command, which simplifies creating a new layer. See the 307 ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" 308 section in the Yocto Project Development Tasks Manual for 309 information on how to use this script to quick set up a new layer. 310 311To better understand the layer you create for kernel development, the 312following section describes how to create a layer without the aid of 313tools. These steps assume creation of a layer named ``mylayer`` in your 314home directory: 315 316#. *Create Structure*: Create the layer's structure:: 317 318 $ mkdir meta-mylayer 319 $ mkdir meta-mylayer/conf 320 $ mkdir meta-mylayer/recipes-kernel 321 $ mkdir meta-mylayer/recipes-kernel/linux 322 $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto 323 324 The ``conf`` directory holds your configuration files, while the 325 ``recipes-kernel`` directory holds your append file and eventual 326 patch files. 327 328#. *Create the Layer Configuration File*: Move to the 329 ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as 330 follows:: 331 332 # We have a conf and classes directory, add to BBPATH 333 BBPATH .= ":${LAYERDIR}" 334 335 # We have recipes-* directories, add to BBFILES 336 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ 337 ${LAYERDIR}/recipes-*/*/*.bbappend" 338 339 BBFILE_COLLECTIONS += "mylayer" 340 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" 341 BBFILE_PRIORITY_mylayer = "5" 342 343 Notice ``mylayer`` as part of the last three statements. 344 345#. *Create the Kernel Recipe Append File*: Move to the 346 ``meta-mylayer/recipes-kernel/linux`` directory and create the 347 kernel's append file. This example uses the ``linux-yocto-4.12`` 348 kernel. Thus, the name of the append file is 349 ``linux-yocto_4.12.bbappend``:: 350 351 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 352 353 SRC_URI += "file://patch-file-one.patch" 354 SRC_URI += "file://patch-file-two.patch" 355 SRC_URI += "file://patch-file-three.patch" 356 357 The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements 358 enable the OpenEmbedded build system to find patch files. For more 359 information on using append files, see the 360 ":ref:`dev-manual/layers:appending other layers metadata with your layer`" 361 section in the Yocto Project Development Tasks Manual. 362 363Modifying an Existing Recipe 364============================ 365 366In many cases, you can customize an existing linux-yocto recipe to meet 367the needs of your project. Each release of the Yocto Project provides a 368few Linux kernel recipes from which you can choose. These are located in 369the :term:`Source Directory` in 370``meta/recipes-kernel/linux``. 371 372Modifying an existing recipe can consist of the following: 373 374- :ref:`kernel-dev/common:creating the append file` 375 376- :ref:`kernel-dev/common:applying patches` 377 378- :ref:`kernel-dev/common:changing the configuration` 379 380Before modifying an existing recipe, be sure that you have created a 381minimal, custom layer from which you can work. See the 382":ref:`kernel-dev/common:creating and preparing a layer`" section for 383information. 384 385Creating the Append File 386------------------------ 387 388You create this file in your custom layer. You also name it accordingly 389based on the linux-yocto recipe you are using. For example, if you are 390modifying the ``meta/recipes-kernel/linux/linux-yocto_6.1.bb`` recipe, 391the append file will typically be located as follows within your custom 392layer: 393 394.. code-block:: none 395 396 your-layer/recipes-kernel/linux/linux-yocto_6.1.bbappend 397 398The append file should initially extend the 399:term:`FILESPATH` search path by 400prepending the directory that contains your files to the 401:term:`FILESEXTRAPATHS` 402variable as follows:: 403 404 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 405 406The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}`` 407expands to "linux-yocto" in the current directory for this example. If 408you add any new files that modify the kernel recipe and you have 409extended :term:`FILESPATH` as described above, you must place the files in 410your layer in the following area:: 411 412 your-layer/recipes-kernel/linux/linux-yocto/ 413 414.. note:: 415 416 If you are working on a new machine Board Support Package (BSP), be 417 sure to refer to the :doc:`/bsp-guide/index`. 418 419As an example, consider the following append file used by the BSPs in 420``meta-yocto-bsp``: 421 422.. code-block:: none 423 424 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend 425 426Here are the contents of this file. Be aware that the actual commit ID 427strings in this example listing might be different than the actual 428strings in the file from the ``meta-yocto-bsp`` layer upstream:: 429 430 KBRANCH:genericx86 = "v6.1/standard/base" 431 KBRANCH:genericx86-64 = "v6.1/standard/base" 432 KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone" 433 434 KMACHINE:genericx86 ?= "common-pc" 435 KMACHINE:genericx86-64 ?= "common-pc-64" 436 KMACHINE:beaglebone-yocto ?= "beaglebone" 437 438 SRCREV_machine:genericx86 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" 439 SRCREV_machine:genericx86-64 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" 440 SRCREV_machine:beaglebone-yocto ?= "423e1996694b61fbfc8ec3bf062fc6461d64fde1" 441 442 COMPATIBLE_MACHINE:genericx86 = "genericx86" 443 COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64" 444 COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto" 445 446 LINUX_VERSION:genericx86 = "6.1.30" 447 LINUX_VERSION:genericx86-64 = "6.1.30" 448 LINUX_VERSION:beaglebone-yocto = "6.1.20" 449 450This append file 451contains statements used to support several BSPs that ship with the 452Yocto Project. The file defines machines using the 453:term:`COMPATIBLE_MACHINE` 454variable and uses the 455:term:`KMACHINE` variable to ensure 456the machine name used by the OpenEmbedded build system maps to the 457machine name used by the Linux Yocto kernel. The file also uses the 458optional :term:`KBRANCH` variable to 459ensure the build process uses the appropriate kernel branch. 460 461Although this particular example does not use it, the 462:term:`KERNEL_FEATURES` 463variable could be used to enable features specific to the kernel. The 464append file points to specific commits in the 465:term:`Source Directory` Git repository and 466the ``meta`` Git repository branches to identify the exact kernel needed 467to build the BSP. 468 469One thing missing in this particular BSP, which you will typically need 470when developing a BSP, is the kernel configuration file (``.config``) 471for your BSP. When developing a BSP, you probably have a kernel 472configuration file or a set of kernel configuration files that, when 473taken together, define the kernel configuration for your BSP. You can 474accomplish this definition by putting the configurations in a file or a 475set of files inside a directory located at the same level as your 476kernel's append file and having the same name as the kernel's main 477recipe file. With all these conditions met, simply reference those files 478in the :term:`SRC_URI` statement in 479the append file. 480 481For example, suppose you had some configuration options in a file called 482``network_configs.cfg``. You can place that file inside a directory 483named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the 484following to the append file. When the OpenEmbedded build system builds 485the kernel, the configuration options are picked up and applied:: 486 487 SRC_URI += "file://network_configs.cfg" 488 489To group related configurations into multiple files, you perform a 490similar procedure. Here is an example that groups separate 491configurations specifically for Ethernet and graphics into their own 492files and adds the configurations by using a :term:`SRC_URI` statement like 493the following in your append file:: 494 495 SRC_URI += "file://myconfig.cfg \ 496 file://eth.cfg \ 497 file://gfx.cfg" 498 499Another variable you can use in your kernel recipe append file is the 500:term:`FILESEXTRAPATHS` 501variable. When you use this statement, you are extending the locations 502used by the OpenEmbedded system to look for files and patches as the 503recipe is processed. 504 505.. note:: 506 507 There are other ways of grouping and defining configuration 508 options. For example, if you are working with a local clone of the 509 kernel repository, you could checkout the kernel's ``meta`` branch, 510 make your changes, and then push the changes to the local bare clone 511 of the kernel. The result is that you directly add configuration 512 options to the ``meta`` branch for your BSP. The configuration 513 options will likely end up in that location anyway if the BSP gets 514 added to the Yocto Project. 515 516 In general, however, the Yocto Project maintainers take care of 517 moving the :term:`SRC_URI`-specified configuration options to the 518 kernel's ``meta`` branch. Not only is it easier for BSP developers 519 not to have to put those configurations in the branch, 520 but having the maintainers do it allows them to apply 'global' 521 knowledge about the kinds of common configuration options multiple 522 BSPs in the tree are typically using. This allows for promotion of 523 common configurations into common features. 524 525Applying Patches 526---------------- 527 528If you have a single patch or a small series of patches that you want to 529apply to the Linux kernel source, you can do so just as you would with 530any other recipe. You first copy the patches to the path added to 531:term:`FILESEXTRAPATHS` in 532your ``.bbappend`` file as described in the previous section, and then 533reference them in :term:`SRC_URI` 534statements. 535 536For example, you can apply a three-patch series by adding the following 537lines to your linux-yocto ``.bbappend`` file in your layer:: 538 539 SRC_URI += "file://0001-first-change.patch" 540 SRC_URI += "file://0002-second-change.patch" 541 SRC_URI += "file://0003-third-change.patch" 542 543The next time you run BitBake to build 544the Linux kernel, BitBake detects the change in the recipe and fetches 545and applies the patches before building the kernel. 546 547For a detailed example showing how to patch the kernel using 548``devtool``, see the 549":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" 550and 551":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" 552sections. 553 554Changing the Configuration 555-------------------------- 556 557You can make wholesale or incremental changes to the final ``.config`` 558file used for the eventual Linux kernel configuration by including a 559``defconfig`` file and by specifying configuration fragments in the 560:term:`SRC_URI` to be applied to that 561file. 562 563If you have a complete, working Linux kernel ``.config`` file you want 564to use for the configuration, as before, copy that file to the 565appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux`` 566directory, and rename the copied file to "defconfig". Then, add the 567following lines to the linux-yocto ``.bbappend`` file in your layer:: 568 569 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 570 SRC_URI += "file://defconfig" 571 572The :term:`SRC_URI` tells the build system how to search 573for the file, while the 574:term:`FILESEXTRAPATHS` 575extends the :term:`FILESPATH` 576variable (search directories) to include the ``${PN}`` directory you 577created to hold the configuration changes. 578 579You can also use a regular ``defconfig`` file, as generated by the 580:ref:`ref-tasks-savedefconfig` 581task instead of a complete ``.config`` file. This only specifies the 582non-default configuration values. You need to additionally set 583:term:`KCONFIG_MODE` 584in the linux-yocto ``.bbappend`` file in your layer:: 585 586 KCONFIG_MODE = "alldefconfig" 587 588.. note:: 589 590 The build system applies the configurations from the ``defconfig`` 591 file before applying any subsequent configuration fragments. The 592 final kernel configuration is a combination of the configurations in 593 the ``defconfig`` file and any configuration fragments you provide. You need 594 to realize that if you have any configuration fragments, the build system 595 applies these on top of and after applying the existing ``defconfig`` file 596 configurations. 597 598Generally speaking, the preferred approach is to determine the 599incremental change you want to make and add that as a configuration 600fragment. For example, if you want to add support for a basic serial 601console, create a file named ``8250.cfg`` in the ``${PN}`` directory 602with the following content (without indentation):: 603 604 CONFIG_SERIAL_8250=y 605 CONFIG_SERIAL_8250_CONSOLE=y 606 CONFIG_SERIAL_8250_PCI=y 607 CONFIG_SERIAL_8250_NR_UARTS=4 608 CONFIG_SERIAL_8250_RUNTIME_UARTS=4 609 CONFIG_SERIAL_CORE=y 610 CONFIG_SERIAL_CORE_CONSOLE=y 611 612Next, include this 613configuration fragment and extend the :term:`FILESPATH` variable in your 614``.bbappend`` file:: 615 616 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 617 SRC_URI += "file://8250.cfg" 618 619The next time you run BitBake to build the 620Linux kernel, BitBake detects the change in the recipe and fetches and 621applies the new configuration before building the kernel. 622 623For a detailed example showing how to configure the kernel, see the 624":ref:`kernel-dev/common:configuring the kernel`" section. 625 626Using an "In-Tree" ``defconfig`` File 627-------------------------------------- 628 629It might be desirable to have kernel configuration fragment support 630through a ``defconfig`` file that is pulled from the kernel source tree 631for the configured machine. By default, the OpenEmbedded build system 632looks for ``defconfig`` files in the layer used for Metadata, which is 633"out-of-tree", and then configures them using the following:: 634 635 SRC_URI += "file://defconfig" 636 637If you do not want to maintain copies of 638``defconfig`` files in your layer but would rather allow users to use 639the default configuration from the kernel tree and still be able to add 640configuration fragments to the 641:term:`SRC_URI` through, for example, 642append files, you can direct the OpenEmbedded build system to use a 643``defconfig`` file that is "in-tree". 644 645To specify an "in-tree" ``defconfig`` file, use the following statement 646form:: 647 648 KBUILD_DEFCONFIG:<machine> ?= "defconfig_file" 649 650Here is an example that assigns the :term:`KBUILD_DEFCONFIG` variable utilizing 651an override for the "raspberrypi2" :term:`MACHINE` and provides the path to the 652"in-tree" ``defconfig`` file to be used for a Raspberry Pi 2, which is based on 653the Broadcom 2708/2709 chipset:: 654 655 KBUILD_DEFCONFIG:raspberrypi2 ?= "bcm2709_defconfig" 656 657Aside from modifying your kernel recipe and providing your own 658``defconfig`` file, you need to be sure no files or statements set 659:term:`SRC_URI` to use a ``defconfig`` other than your "in-tree" file (e.g. 660a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the 661build system detects a statement that identifies an "out-of-tree" 662``defconfig`` file, that statement will override your 663:term:`KBUILD_DEFCONFIG` variable. 664 665See the 666:term:`KBUILD_DEFCONFIG` 667variable description for more information. 668 669Using ``devtool`` to Patch the Kernel 670===================================== 671 672The steps in this procedure show you how you can patch the kernel using 673``devtool``. 674 675.. note:: 676 677 Before attempting this procedure, be sure you have performed the 678 steps to get ready for updating the kernel as described in the 679 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" 680 section. 681 682Patching the kernel involves changing or adding configurations to an 683existing kernel, changing or adding recipes to the kernel that are 684needed to support specific hardware features, or even altering the 685source code itself. 686 687This example creates a simple patch by adding some QEMU emulator console 688output at boot time through ``printk`` statements in the kernel's 689``calibrate.c`` source code file. Applying the patch and booting the 690modified image causes the added messages to appear on the emulator's 691console. The example is a continuation of the setup procedure found in 692the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Section. 693 694#. *Check Out the Kernel Source Files:* First you must use ``devtool`` 695 to checkout the kernel source code in its workspace. 696 697 .. note:: 698 699 See this step in the 700 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" 701 section for more information. 702 703 Use the following ``devtool`` command to check out the code:: 704 705 $ devtool modify linux-yocto 706 707 .. note:: 708 709 During the checkout operation, there is a bug that could cause 710 errors such as the following: 711 712 .. code-block:: none 713 714 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus 715 be3a89ce7c47178880ba7bf6293d7404 for 716 /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack 717 718 719 You can safely ignore these messages. The source code is correctly 720 checked out. 721 722#. *Edit the Source Files* Follow these steps to make some simple 723 changes to the source files: 724 725 #. *Change the working directory*: In the previous step, the output 726 noted where you can find the source files (e.g. 727 ``poky_sdk/workspace/sources/linux-yocto``). Change to where the 728 kernel source code is before making your edits to the 729 ``calibrate.c`` file:: 730 731 $ cd poky_sdk/workspace/sources/linux-yocto 732 733 #. *Edit the source file*: Edit the ``init/calibrate.c`` file to have 734 the following changes:: 735 736 void calibrate_delay(void) 737 { 738 unsigned long lpj; 739 static bool printed; 740 int this_cpu = smp_processor_id(); 741 742 printk("*************************************\n"); 743 printk("* *\n"); 744 printk("* HELLO YOCTO KERNEL *\n"); 745 printk("* *\n"); 746 printk("*************************************\n"); 747 748 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { 749 . 750 . 751 . 752 753#. *Build the Updated Kernel Source:* To build the updated kernel 754 source, use ``devtool``:: 755 756 $ devtool build linux-yocto 757 758#. *Create the Image With the New Kernel:* Use the 759 ``devtool build-image`` command to create a new image that has the 760 new kernel:: 761 762 $ cd ~ 763 $ devtool build-image core-image-minimal 764 765 .. note:: 766 767 If the image you originally created resulted in a Wic file, you 768 can use an alternate method to create the new image with the 769 updated kernel. For an example, see the steps in the 770 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>` 771 Wiki Page. 772 773#. *Test the New Image:* For this example, you can run the new image 774 using QEMU to verify your changes: 775 776 #. *Boot the image*: Boot the modified image in the QEMU emulator 777 using this command:: 778 779 $ runqemu qemux86 780 781 #. *Verify the changes*: Log into the machine using ``root`` with no 782 password and then use the following shell command to scroll 783 through the console's boot output. 784 785 .. code-block:: none 786 787 # dmesg | less 788 789 You should see 790 the results of your ``printk`` statements as part of the output 791 when you scroll down the console window. 792 793#. *Stage and commit your changes*: Change 794 your working directory to where you modified the ``calibrate.c`` file 795 and use these Git commands to stage and commit your changes:: 796 797 $ cd poky_sdk/workspace/sources/linux-yocto 798 $ git status 799 $ git add init/calibrate.c 800 $ git commit -m "calibrate: Add printk example" 801 802#. *Export the Patches and Create an Append File:* To export your 803 commits as patches and create a ``.bbappend`` file, use the following 804 command. This example uses the previously established layer named ``meta-mylayer``:: 805 806 $ devtool finish linux-yocto ~/meta-mylayer 807 808 .. note:: 809 810 See Step 3 of the 811 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" 812 section for information on setting up this layer. 813 814 Once the command 815 finishes, the patches and the ``.bbappend`` file are located in the 816 ``~/meta-mylayer/recipes-kernel/linux`` directory. 817 818#. *Build the Image With Your Modified Kernel:* You can now build an 819 image that includes your kernel patches. Execute the following 820 command from your :term:`Build Directory` in the terminal 821 set up to run BitBake:: 822 823 $ cd poky/build 824 $ bitbake core-image-minimal 825 826Using Traditional Kernel Development to Patch the Kernel 827======================================================== 828 829The steps in this procedure show you how you can patch the kernel using 830traditional kernel development (i.e. not using ``devtool`` 831as described in the 832":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" 833section). 834 835.. note:: 836 837 Before attempting this procedure, be sure you have performed the 838 steps to get ready for updating the kernel as described in the 839 ":ref:`kernel-dev/common:getting ready for traditional kernel development`" 840 section. 841 842Patching the kernel involves changing or adding configurations to an 843existing kernel, changing or adding recipes to the kernel that are 844needed to support specific hardware features, or even altering the 845source code itself. 846 847The example in this section creates a simple patch by adding some QEMU 848emulator console output at boot time through ``printk`` statements in 849the kernel's ``calibrate.c`` source code file. Applying the patch and 850booting the modified image causes the added messages to appear on the 851emulator's console. The example is a continuation of the setup procedure 852found in the 853":ref:`kernel-dev/common:getting ready for traditional kernel development`" 854Section. 855 856#. *Edit the Source Files* Prior to this step, you should have used Git 857 to create a local copy of the repository for your kernel. Assuming 858 you created the repository as directed in the 859 ":ref:`kernel-dev/common:getting ready for traditional kernel development`" 860 section, use the following commands to edit the ``calibrate.c`` file: 861 862 #. *Change the working directory*: You need to locate the source 863 files in the local copy of the kernel Git repository. Change to 864 where the kernel source code is before making your edits to the 865 ``calibrate.c`` file:: 866 867 $ cd ~/linux-yocto-4.12/init 868 869 #. *Edit the source file*: Edit the ``calibrate.c`` file to have the 870 following changes:: 871 872 void calibrate_delay(void) 873 { 874 unsigned long lpj; 875 static bool printed; 876 int this_cpu = smp_processor_id(); 877 878 printk("*************************************\n"); 879 printk("* *\n"); 880 printk("* HELLO YOCTO KERNEL *\n"); 881 printk("* *\n"); 882 printk("*************************************\n"); 883 884 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { 885 . 886 . 887 . 888 889#. *Stage and Commit Your Changes:* Use standard Git commands to stage 890 and commit the changes you just made:: 891 892 $ git add calibrate.c 893 $ git commit -m "calibrate.c - Added some printk statements" 894 895 If you do not 896 stage and commit your changes, the OpenEmbedded Build System will not 897 pick up the changes. 898 899#. *Update Your local.conf File to Point to Your Source Files:* In 900 addition to your ``local.conf`` file specifying to use 901 "kernel-modules" and the "qemux86" machine, it must also point to the 902 updated kernel source files. Add 903 :term:`SRC_URI` and 904 :term:`SRCREV` statements similar 905 to the following to your ``local.conf``:: 906 907 $ cd poky/build/conf 908 909 Add the following to the ``local.conf``:: 910 911 SRC_URI:pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ 912 git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" 913 SRCREV_meta:qemux86 = "${AUTOREV}" 914 SRCREV_machine:qemux86 = "${AUTOREV}" 915 916 .. note:: 917 918 Be sure to replace `path-to` 919 with the pathname to your local Git repositories. Also, you must 920 be sure to specify the correct branch and machine types. For this 921 example, the branch is ``standard/base`` and the machine is ``qemux86``. 922 923#. *Build the Image:* With the source modified, your changes staged and 924 committed, and the ``local.conf`` file pointing to the kernel files, 925 you can now use BitBake to build the image:: 926 927 $ cd poky/build 928 $ bitbake core-image-minimal 929 930#. *Boot the image*: Boot the modified image in the QEMU emulator using 931 this command. When prompted to login to the QEMU console, use "root" 932 with no password:: 933 934 $ cd poky/build 935 $ runqemu qemux86 936 937#. *Look for Your Changes:* As QEMU booted, you might have seen your 938 changes rapidly scroll by. If not, use these commands to see your 939 changes: 940 941 .. code-block:: none 942 943 # dmesg | less 944 945 You should see the results of your 946 ``printk`` statements as part of the output when you scroll down the 947 console window. 948 949#. *Generate the Patch File:* Once you are sure that your patch works 950 correctly, you can generate a ``*.patch`` file in the kernel source 951 repository:: 952 953 $ cd ~/linux-yocto-4.12/init 954 $ git format-patch -1 955 0001-calibrate.c-Added-some-printk-statements.patch 956 957#. *Move the Patch File to Your Layer:* In order for subsequent builds 958 to pick up patches, you need to move the patch file you created in 959 the previous step to your layer ``meta-mylayer``. For this example, 960 the layer created earlier is located in your home directory as 961 ``meta-mylayer``. When the layer was created using the 962 ``yocto-create`` script, no additional hierarchy was created to 963 support patches. Before moving the patch file, you need to add 964 additional structure to your layer using the following commands:: 965 966 $ cd ~/meta-mylayer 967 $ mkdir recipes-kernel 968 $ mkdir recipes-kernel/linux 969 $ mkdir recipes-kernel/linux/linux-yocto 970 971 Once you have created this 972 hierarchy in your layer, you can move the patch file using the 973 following command:: 974 975 $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto 976 977#. *Create the Append File:* Finally, you need to create the 978 ``linux-yocto_4.12.bbappend`` file and insert statements that allow 979 the OpenEmbedded build system to find the patch. The append file 980 needs to be in your layer's ``recipes-kernel/linux`` directory and it 981 must be named ``linux-yocto_4.12.bbappend`` and have the following 982 contents:: 983 984 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 985 SRC_URI += "file://0001-calibrate.c-Added-some-printk-statements.patch" 986 987 The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements 988 enable the OpenEmbedded build system to find the patch file. 989 990 For more information on append files and patches, see the 991 ":ref:`kernel-dev/common:creating the append file`" and 992 ":ref:`kernel-dev/common:applying patches`" sections. You can also see the 993 ":ref:`dev-manual/layers:appending other layers metadata with your layer`" 994 section in the Yocto Project Development Tasks Manual. 995 996 .. note:: 997 998 To build ``core-image-minimal`` again and see the effects of your patch, 999 you can essentially eliminate the temporary source files saved in 1000 ``poky/build/tmp/work/...`` and residual effects of the build by entering 1001 the following sequence of commands:: 1002 1003 $ cd poky/build 1004 $ bitbake -c cleanall linux-yocto 1005 $ bitbake core-image-minimal -c cleanall 1006 $ bitbake core-image-minimal 1007 $ runqemu qemux86 1008 1009 1010Configuring the Kernel 1011====================== 1012 1013Configuring the Yocto Project kernel consists of making sure the 1014``.config`` file has all the right information in it for the image you 1015are building. You can use the ``menuconfig`` tool and configuration 1016fragments to make sure your ``.config`` file is just how you need it. 1017You can also save known configurations in a ``defconfig`` file that the 1018build system can use for kernel configuration. 1019 1020This section describes how to use ``menuconfig``, create and use 1021configuration fragments, and how to interactively modify your 1022``.config`` file to create the leanest kernel configuration file 1023possible. 1024 1025For more information on kernel configuration, see the 1026":ref:`kernel-dev/common:changing the configuration`" section. 1027 1028Using ``menuconfig`` 1029--------------------- 1030 1031The easiest way to define kernel configurations is to set them through 1032the ``menuconfig`` tool. This tool provides an interactive method with 1033which to set kernel configurations. For general information on 1034``menuconfig``, see :wikipedia:`Menuconfig`. 1035 1036To use the ``menuconfig`` tool in the Yocto Project development 1037environment, you must do the following: 1038 1039- Because you launch ``menuconfig`` using BitBake, you must be sure to 1040 set up your environment by running the :ref:`structure-core-script` script 1041 found in the :term:`Build Directory`. 1042 1043- You must be sure of the state of your build's configuration in the 1044 :term:`Source Directory`. 1045 1046- Your build host must have the following two packages installed:: 1047 1048 libncurses5-dev 1049 libtinfo-dev 1050 1051The following commands initialize the BitBake environment, run the 1052:ref:`ref-tasks-kernel_configme` 1053task, and launch ``menuconfig``. These commands assume the Source 1054Directory's top-level folder is ``poky``:: 1055 1056 $ cd poky 1057 $ source oe-init-build-env 1058 $ bitbake linux-yocto -c kernel_configme -f 1059 $ bitbake linux-yocto -c menuconfig 1060 1061Once ``menuconfig`` comes up, its standard 1062interface allows you to interactively examine and configure all the 1063kernel configuration parameters. After making your changes, simply exit 1064the tool and save your changes to create an updated version of the 1065``.config`` configuration file. 1066 1067.. note:: 1068 1069 You can use the entire ``.config`` file as the ``defconfig`` file. For 1070 information on ``defconfig`` files, see the 1071 ":ref:`kernel-dev/common:changing the configuration`", 1072 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`", 1073 and ":ref:`kernel-dev/common:creating a \`\`defconfig\`\` file`" 1074 sections. 1075 1076Consider an example that configures the "CONFIG_SMP" setting for the 1077``linux-yocto-4.12`` kernel. 1078 1079.. note:: 1080 1081 The OpenEmbedded build system recognizes this kernel as ``linux-yocto`` 1082 through Metadata (e.g. :term:`PREFERRED_VERSION`\ ``_linux-yocto ?= "4.12%"``). 1083 1084Once ``menuconfig`` launches, use the interface to navigate through the 1085selections to find the configuration settings in which you are 1086interested. For this example, you deselect "CONFIG_SMP" by clearing the 1087"Symmetric Multi-Processing Support" option. Using the interface, you 1088can find the option under "Processor Type and Features". To deselect 1089"CONFIG_SMP", use the arrow keys to highlight "Symmetric 1090Multi-Processing Support" and enter "N" to clear the asterisk. When you 1091are finished, exit out and save the change. 1092 1093Saving the selections updates the ``.config`` configuration file. This is the 1094file that the OpenEmbedded build system uses to configure the kernel during 1095the build. You can find and examine this file in the :term:`Build Directory` 1096in ``tmp/work/``. The actual ``.config`` is located in the 1097area where the specific kernel is built. For example, if you were 1098building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel 1099and you were building a QEMU image targeted for ``x86`` architecture, 1100the ``.config`` file would be: 1101 1102.. code-block:: none 1103 1104 poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18... 1105 ...967-r0/linux-qemux86-standard-build/.config 1106 1107.. note:: 1108 1109 The previous example directory is artificially split and many of the 1110 characters in the actual filename are omitted in order to make it 1111 more readable. Also, depending on the kernel you are using, the exact 1112 pathname might differ. 1113 1114Within the ``.config`` file, you can see the kernel settings. For 1115example, the following entry shows that symmetric multi-processor 1116support is not set:: 1117 1118 # CONFIG_SMP is not set 1119 1120A good method to isolate changed configurations is to use a combination 1121of the ``menuconfig`` tool and simple shell commands. Before changing 1122configurations with ``menuconfig``, copy the existing ``.config`` and 1123rename it to something else, use ``menuconfig`` to make as many changes 1124as you want and save them, then compare the renamed configuration file 1125against the newly created file. You can use the resulting differences as 1126your base to create configuration fragments to permanently save in your 1127kernel layer. 1128 1129.. note:: 1130 1131 Be sure to make a copy of the ``.config`` file and do not just rename it. 1132 The build system needs an existing ``.config`` file from which to work. 1133 1134Creating a ``defconfig`` File 1135------------------------------ 1136 1137A ``defconfig`` file in the context of the Yocto Project is often a 1138``.config`` file that is copied from a build or a ``defconfig`` taken 1139from the kernel tree and moved into recipe space. You can use a 1140``defconfig`` file to retain a known set of kernel configurations from 1141which the OpenEmbedded build system can draw to create the final 1142``.config`` file. 1143 1144.. note:: 1145 1146 Out-of-the-box, the Yocto Project never ships a ``defconfig`` or ``.config`` 1147 file. The OpenEmbedded build system creates the final ``.config`` file used 1148 to configure the kernel. 1149 1150To create a ``defconfig``, start with a complete, working Linux kernel 1151``.config`` file. Copy that file to the appropriate 1152``${``\ :term:`PN`\ ``}`` directory in 1153your layer's ``recipes-kernel/linux`` directory, and rename the copied 1154file to "defconfig" (e.g. 1155``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then, 1156add the following lines to the linux-yocto ``.bbappend`` file in your 1157layer:: 1158 1159 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 1160 SRC_URI += "file://defconfig" 1161 1162The :term:`SRC_URI` tells the build system how to search for the file, while the 1163:term:`FILESEXTRAPATHS` extends the :term:`FILESPATH` 1164variable (search directories) to include the ``${PN}`` directory you 1165created to hold the configuration changes. 1166 1167.. note:: 1168 1169 The build system applies the configurations from the ``defconfig`` 1170 file before applying any subsequent configuration fragments. The 1171 final kernel configuration is a combination of the configurations in 1172 the ``defconfig`` file and any configuration fragments you provide. You need 1173 to realize that if you have any configuration fragments, the build system 1174 applies these on top of and after applying the existing ``defconfig`` file 1175 configurations. 1176 1177For more information on configuring the kernel, see the 1178":ref:`kernel-dev/common:changing the configuration`" section. 1179 1180Creating Configuration Fragments 1181-------------------------------- 1182 1183Configuration fragments are simply kernel options that appear in a file 1184placed where the OpenEmbedded build system can find and apply them. The 1185build system applies configuration fragments after applying 1186configurations from a ``defconfig`` file. Thus, the final kernel 1187configuration is a combination of the configurations in the 1188``defconfig`` file and then any configuration fragments you provide. The 1189build system applies fragments on top of and after applying the existing 1190defconfig file configurations. 1191 1192Syntactically, the configuration statement is identical to what would 1193appear in the ``.config`` file, which is in the :term:`Build Directory`. 1194 1195.. note:: 1196 1197 For more information about where the ``.config`` file is located, see the 1198 example in the 1199 ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" 1200 section. 1201 1202It is simple to create a configuration fragment. One method is to use 1203shell commands. For example, issuing the following from the shell 1204creates a configuration fragment file named ``my_smp.cfg`` that enables 1205multi-processor support within the kernel:: 1206 1207 $ echo "CONFIG_SMP=y" >> my_smp.cfg 1208 1209.. note:: 1210 1211 All configuration fragment files must use the ``.cfg`` extension in order 1212 for the OpenEmbedded build system to recognize them as a configuration 1213 fragment. 1214 1215Another method is to create a configuration fragment using the 1216differences between two configuration files: one previously created and 1217saved, and one freshly created using the ``menuconfig`` tool. 1218 1219To create a configuration fragment using this method, follow these 1220steps: 1221 1222#. *Complete a Build Through Kernel Configuration:* Complete a build at 1223 least through the kernel configuration task as follows:: 1224 1225 $ bitbake linux-yocto -c kernel_configme -f 1226 1227 This step ensures that you create a 1228 ``.config`` file from a known state. Because there are situations where 1229 your build state might become unknown, it is best to run this task 1230 prior to starting ``menuconfig``. 1231 1232#. *Launch menuconfig:* Run the ``menuconfig`` command:: 1233 1234 $ bitbake linux-yocto -c menuconfig 1235 1236#. *Create the Configuration Fragment:* Run the ``diffconfig`` command 1237 to prepare a configuration fragment. The resulting file 1238 ``fragment.cfg`` is placed in the 1239 ``${``\ :term:`WORKDIR`\ ``}`` 1240 directory:: 1241 1242 $ bitbake linux-yocto -c diffconfig 1243 1244The ``diffconfig`` command creates a file that is a list of Linux kernel 1245``CONFIG_`` assignments. See the 1246":ref:`kernel-dev/common:changing the configuration`" section for additional 1247information on how to use the output as a configuration fragment. 1248 1249.. note:: 1250 1251 You can also use this method to create configuration fragments for a 1252 BSP. See the ":ref:`kernel-dev/advanced:bsp descriptions`" 1253 section for more information. 1254 1255Where do you put your configuration fragment files? You can place these 1256files in an area pointed to by 1257:term:`SRC_URI` as directed by your 1258``bblayers.conf`` file, which is located in your layer. The OpenEmbedded 1259build system picks up the configuration and adds it to the kernel's 1260configuration. For example, suppose you had a set of configuration 1261options in a file called ``myconfig.cfg``. If you put that file inside a 1262directory named ``linux-yocto`` that resides in the same directory as 1263the kernel's append file within your layer and then add the following 1264statements to the kernel's append file, those configuration options will 1265be picked up and applied when the kernel is built:: 1266 1267 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 1268 SRC_URI += "file://myconfig.cfg" 1269 1270As mentioned earlier, you can group related configurations into multiple 1271files and name them all in the :term:`SRC_URI` statement as well. For 1272example, you could group separate configurations specifically for 1273Ethernet and graphics into their own files and add those by using a 1274:term:`SRC_URI` statement like the following in your append file:: 1275 1276 SRC_URI += "file://myconfig.cfg \ 1277 file://eth.cfg \ 1278 file://gfx.cfg" 1279 1280Validating Configuration 1281------------------------ 1282 1283You can use the 1284:ref:`ref-tasks-kernel_configcheck` 1285task to provide configuration validation:: 1286 1287 $ bitbake linux-yocto -c kernel_configcheck -f 1288 1289Running this task produces warnings for when a 1290requested configuration does not appear in the final ``.config`` file or 1291when you override a policy configuration in a hardware configuration 1292fragment. 1293 1294In order to run this task, you must have an existing ``.config`` file. 1295See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for 1296information on how to create a configuration file. 1297 1298Here is sample output from the :ref:`ref-tasks-kernel_configcheck` task: 1299 1300.. code-block:: none 1301 1302 Loading cache: 100% |########################################################| Time: 0:00:00 1303 Loaded 1275 entries from dependency cache. 1304 NOTE: Resolving any missing task queue dependencies 1305 1306 Build Configuration: 1307 . 1308 . 1309 . 1310 1311 NOTE: Executing SetScene Tasks 1312 NOTE: Executing RunQueue Tasks 1313 WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck: 1314 [kernel config]: specified values did not make it into the kernel's final configuration: 1315 1316 ---------- CONFIG_X86_TSC ----------------- 1317 Config: CONFIG_X86_TSC 1318 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg 1319 Requested value: CONFIG_X86_TSC=y 1320 Actual value: 1321 1322 1323 ---------- CONFIG_X86_BIGSMP ----------------- 1324 Config: CONFIG_X86_BIGSMP 1325 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg 1326 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig 1327 Requested value: # CONFIG_X86_BIGSMP is not set 1328 Actual value: 1329 1330 1331 ---------- CONFIG_NR_CPUS ----------------- 1332 Config: CONFIG_NR_CPUS 1333 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg 1334 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg 1335 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig 1336 Requested value: CONFIG_NR_CPUS=8 1337 Actual value: CONFIG_NR_CPUS=1 1338 1339 1340 ---------- CONFIG_SCHED_SMT ----------------- 1341 Config: CONFIG_SCHED_SMT 1342 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg 1343 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig 1344 Requested value: CONFIG_SCHED_SMT=y 1345 Actual value: 1346 1347 1348 1349 NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded. 1350 1351 Summary: There were 3 WARNING messages shown. 1352 1353.. note:: 1354 1355 The previous output example has artificial line breaks to make it 1356 more readable. 1357 1358The output describes the various problems that you can encounter along 1359with where to find the offending configuration items. You can use the 1360information in the logs to adjust your configuration files and then 1361repeat the 1362:ref:`ref-tasks-kernel_configme` 1363and 1364:ref:`ref-tasks-kernel_configcheck` 1365tasks until they produce no warnings. 1366 1367For more information on how to use the ``menuconfig`` tool, see the 1368:ref:`kernel-dev/common:using \`\`menuconfig\`\`` section. 1369 1370Fine-Tuning the Kernel Configuration File 1371----------------------------------------- 1372 1373You can make sure the ``.config`` file is as lean or efficient as 1374possible by reading the output of the kernel configuration fragment 1375audit, noting any issues, making changes to correct the issues, and then 1376repeating. 1377 1378As part of the kernel build process, the :ref:`ref-tasks-kernel_configcheck` task 1379runs. This task validates the kernel configuration by checking the final 1380``.config`` file against the input files. During the check, the task 1381produces warning messages for the following issues: 1382 1383- Requested options that did not make it into the final ``.config`` file. 1384 1385- Configuration items that appear twice in the same configuration 1386 fragment. 1387 1388- Configuration items tagged as "required" that were overridden. 1389 1390- A board overrides a non-board specific option. 1391 1392- Listed options not valid for the kernel being processed. In other 1393 words, the option does not appear anywhere. 1394 1395.. note:: 1396 1397 The :ref:`ref-tasks-kernel_configcheck` task can also optionally report if 1398 an option is overridden during processing. 1399 1400For each output warning, a message points to the file that contains a 1401list of the options and a pointer to the configuration fragment that 1402defines them. Collectively, the files are the key to streamlining the 1403configuration. 1404 1405To streamline the configuration, do the following: 1406 1407#. *Use a Working Configuration:* Start with a full configuration that 1408 you know works. Be sure the configuration builds and boots 1409 successfully. Use this configuration file as your baseline. 1410 1411#. *Run Configure and Check Tasks:* Separately run the 1412 :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks:: 1413 1414 $ bitbake linux-yocto -c kernel_configme -f 1415 $ bitbake linux-yocto -c kernel_configcheck -f 1416 1417#. *Process the Results:* Take the resulting list of files from the 1418 :ref:`ref-tasks-kernel_configcheck` task warnings and do the following: 1419 1420 - Drop values that are redefined in the fragment but do not change 1421 the final ``.config`` file. 1422 1423 - Analyze and potentially drop values from the ``.config`` file that 1424 override required configurations. 1425 1426 - Analyze and potentially remove non-board specific options. 1427 1428 - Remove repeated and invalid options. 1429 1430#. *Re-Run Configure and Check Tasks:* After you have worked through the 1431 output of the kernel configuration audit, you can re-run the 1432 :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks to see the 1433 results of your changes. If you have more issues, you can deal with 1434 them as described in the previous step. 1435 1436Iteratively working through steps two through four eventually yields a 1437minimal, streamlined configuration file. Once you have the best 1438``.config``, you can build the Linux Yocto kernel. 1439 1440Expanding Variables 1441=================== 1442 1443Sometimes it is helpful to determine what a variable expands to during a 1444build. You can examine the values of variables by examining the 1445output of the ``bitbake -e`` command. The output is long and is more 1446easily managed in a text file, which allows for easy searches:: 1447 1448 $ bitbake -e virtual/kernel > some_text_file 1449 1450Within the text file, you can see 1451exactly how each variable is expanded and used by the OpenEmbedded build 1452system. 1453 1454Working with a "Dirty" Kernel Version String 1455============================================ 1456 1457If you build a kernel image and the version string has a "+" or a 1458"-dirty" at the end, it means there are uncommitted modifications in the kernel's 1459source directory. Follow these steps to clean up the version string: 1460 1461#. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned 1462 Git repository (source directory) and use the following Git command 1463 to list the files that have been changed, added, or removed:: 1464 1465 $ git status 1466 1467#. *Commit the Changes:* You should commit those changes to the kernel 1468 source tree regardless of whether or not you will save, export, or 1469 use the changes:: 1470 1471 $ git add 1472 $ git commit -s -a -m "getting rid of -dirty" 1473 1474#. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the 1475 kernel. 1476 1477 Depending on your particular kernel development workflow, the 1478 commands you use to rebuild the kernel might differ. For information 1479 on building the kernel image when using ``devtool``, see the 1480 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" 1481 section. For 1482 information on building the kernel image when using BitBake, see the 1483 ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" 1484 section. 1485 1486Working With Your Own Sources 1487============================= 1488 1489If you cannot work with one of the Linux kernel versions supported by 1490existing linux-yocto recipes, you can still make use of the Yocto 1491Project Linux kernel tooling by working with your own sources. When you 1492use your own sources, you will not be able to leverage the existing 1493kernel :term:`Metadata` and stabilization 1494work of the linux-yocto sources. However, you will be able to manage 1495your own Metadata in the same format as the linux-yocto sources. 1496Maintaining format compatibility facilitates converging with linux-yocto 1497on a future, mutually-supported kernel version. 1498 1499To help you use your own sources, the Yocto Project provides a 1500linux-yocto custom recipe that uses ``kernel.org`` sources and 1501the Yocto Project Linux kernel tools for managing kernel Metadata. 1502You can find this recipe in the ``poky`` Git repository: 1503:yocto_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb 1504</poky/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`. 1505 1506Here are some basic steps you can use to work with your own sources: 1507 1508#. *Create a Copy of the Kernel Recipe:* Copy the 1509 ``linux-yocto-custom.bb`` recipe to your layer and give it a 1510 meaningful name. The name should include the version of the Yocto 1511 Linux kernel you are using (e.g. ``linux-yocto-myproject_4.12.bb``, 1512 where "4.12" is the base version of the Linux kernel with which you 1513 would be working). 1514 1515#. *Create a Directory for Your Patches:* In the same directory inside 1516 your layer, create a matching directory to store your patches and 1517 configuration files (e.g. ``linux-yocto-myproject``). 1518 1519#. *Ensure You Have Configurations:* Make sure you have either a 1520 ``defconfig`` file or configuration fragment files in your layer. 1521 When you use the ``linux-yocto-custom.bb`` recipe, you must specify a 1522 configuration. If you do not have a ``defconfig`` file, you can run 1523 the following:: 1524 1525 $ make defconfig 1526 1527 After running the command, copy the 1528 resulting ``.config`` file to the ``files`` directory in your layer 1529 as "defconfig" and then add it to the 1530 :term:`SRC_URI` variable in the 1531 recipe. 1532 1533 Running the ``make defconfig`` command results in the default 1534 configuration for your architecture as defined by your kernel. 1535 However, there is no guarantee that this configuration is valid for 1536 your use case, or that your board will even boot. This is 1537 particularly true for non-x86 architectures. 1538 1539 To use non-x86 ``defconfig`` files, you need to be more specific and 1540 find one that matches your board (i.e. for arm, you look in 1541 ``arch/arm/configs`` and use the one that is the best starting point 1542 for your board). 1543 1544#. *Edit the Recipe:* Edit the following variables in your recipe as 1545 appropriate for your project: 1546 1547 - :term:`SRC_URI`: The 1548 :term:`SRC_URI` should specify a Git repository that uses one of the 1549 supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``, 1550 and so forth). The :term:`SRC_URI` variable should also specify either 1551 a ``defconfig`` file or some configuration fragment files. The 1552 skeleton recipe provides an example :term:`SRC_URI` as a syntax 1553 reference. 1554 1555 - :term:`LINUX_VERSION`: 1556 The Linux kernel version you are using (e.g. "4.12"). 1557 1558 - :term:`LINUX_VERSION_EXTENSION`: 1559 The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the 1560 resulting kernel and visible through the ``uname`` command. 1561 1562 - :term:`SRCREV`: The commit ID 1563 from which you want to build. 1564 1565 - :term:`PR`: Treat this variable the 1566 same as you would in any other recipe. Increment the variable to 1567 indicate to the OpenEmbedded build system that the recipe has 1568 changed. 1569 1570 - :term:`PV`: The default :term:`PV` 1571 assignment is typically adequate. It combines the 1572 :term:`LINUX_VERSION` with the Source Control Manager (SCM) revision 1573 as derived from the :term:`SRCPV` 1574 variable. The combined results are a string with the following 1575 form:: 1576 1577 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 1578 1579 While lengthy, the extra verbosity in :term:`PV` helps ensure you are 1580 using the exact sources from which you intend to build. 1581 1582 - :term:`COMPATIBLE_MACHINE`: 1583 A list of the machines supported by your new recipe. This variable 1584 in the example recipe is set by default to a regular expression 1585 that matches only the empty string, "(^$)". This default setting 1586 triggers an explicit build failure. You must change it to match a 1587 list of the machines that your new recipe supports. For example, 1588 to support the ``qemux86`` and ``qemux86-64`` machines, use the 1589 following form:: 1590 1591 COMPATIBLE_MACHINE = "qemux86|qemux86-64" 1592 1593#. *Customize Your Recipe as Needed:* Provide further customizations to 1594 your recipe as needed just as you would customize an existing 1595 linux-yocto recipe. See the 1596 ":ref:`ref-manual/devtool-reference:modifying an existing recipe`" section 1597 for information. 1598 1599Working with Out-of-Tree Modules 1600================================ 1601 1602This section describes steps to build out-of-tree modules on your target 1603and describes how to incorporate out-of-tree modules in the build. 1604 1605Building Out-of-Tree Modules on the Target 1606------------------------------------------ 1607 1608While the traditional Yocto Project development model would be to 1609include kernel modules as part of the normal build process, you might 1610find it useful to build modules on the target. This could be the case if 1611your target system is capable and powerful enough to handle the 1612necessary compilation. Before deciding to build on your target, however, 1613you should consider the benefits of using a proper cross-development 1614environment from your build host. 1615 1616If you want to be able to build out-of-tree modules on the target, there 1617are some steps you need to take on the target that is running your SDK 1618image. Briefly, the ``kernel-dev`` package is installed by default on 1619all ``*.sdk`` images and the ``kernel-devsrc`` package is installed on 1620many of the ``*.sdk`` images. However, you need to create some scripts 1621prior to attempting to build the out-of-tree modules on the target that 1622is running that image. 1623 1624Prior to attempting to build the out-of-tree modules, you need to be on 1625the target as root and you need to change to the ``/usr/src/kernel`` 1626directory. Next, ``make`` the scripts: 1627 1628.. code-block:: none 1629 1630 # cd /usr/src/kernel 1631 # make scripts 1632 1633Because all SDK image recipes include ``dev-pkgs``, the 1634``kernel-dev`` packages will be installed as part of the SDK image and 1635the ``kernel-devsrc`` packages will be installed as part of applicable 1636SDK images. The SDK uses the scripts when building out-of-tree modules. 1637Once you have switched to that directory and created the scripts, you 1638should be able to build your out-of-tree modules on the target. 1639 1640Incorporating Out-of-Tree Modules 1641--------------------------------- 1642 1643While it is always preferable to work with sources integrated into the 1644Linux kernel sources, if you need an external kernel module, the 1645``hello-mod.bb`` recipe is available as a template from which you can 1646create your own out-of-tree Linux kernel module recipe. 1647 1648This template recipe is located in the ``poky`` Git repository of the 1649Yocto Project: 1650:yocto_git:`meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb 1651</poky/tree/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb>`. 1652 1653To get started, copy this recipe to your layer and give it a meaningful 1654name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new 1655directory named ``files`` where you can store any source files, patches, 1656or other files necessary for building the module that do not come with 1657the sources. Finally, update the recipe as needed for the module. 1658Typically, you will need to set the following variables: 1659 1660- :term:`DESCRIPTION` 1661 1662- :term:`LICENSE* <LICENSE>` 1663 1664- :term:`SRC_URI` 1665 1666- :term:`PV` 1667 1668Depending on the build system used by the module sources, you might need 1669to make some adjustments. For example, a typical module ``Makefile`` 1670looks much like the one provided with the ``hello-mod`` template:: 1671 1672 obj-m := hello.o 1673 1674 SRC := $(shell pwd) 1675 1676 all: 1677 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) 1678 1679 modules_install: 1680 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install 1681 ... 1682 1683The important point to note here is the :term:`KERNEL_SRC` variable. The 1684:ref:`ref-classes-module` class sets this variable and the :term:`KERNEL_PATH` 1685variable to ``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build 1686information to build modules. If your module ``Makefile`` uses a different 1687variable, you might want to override the :ref:`ref-tasks-compile` step, or 1688create a patch to the ``Makefile`` to work with the more typical 1689:term:`KERNEL_SRC` or :term:`KERNEL_PATH` variables. 1690 1691After you have prepared your recipe, you will likely want to include the 1692module in your images. To do this, see the documentation for the 1693following variables in the Yocto Project Reference Manual and set one of 1694them appropriately for your machine configuration file: 1695 1696- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` 1697 1698- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` 1699 1700- :term:`MACHINE_EXTRA_RDEPENDS` 1701 1702- :term:`MACHINE_EXTRA_RRECOMMENDS` 1703 1704Modules are often not required for boot and can be excluded from certain 1705build configurations. The following allows for the most flexibility:: 1706 1707 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" 1708 1709The value is 1710derived by appending the module filename without the ``.ko`` extension 1711to the string "kernel-module-". 1712 1713Because the variable is 1714:term:`RRECOMMENDS` and not a 1715:term:`RDEPENDS` variable, the build 1716will not fail if this module is not available to include in the image. 1717 1718Inspecting Changes and Commits 1719============================== 1720 1721A common question when working with a kernel is: "What changes have been 1722applied to this tree?" Rather than using "grep" across directories to 1723see what has changed, you can use Git to inspect or search the kernel 1724tree. Using Git is an efficient way to see what has changed in the tree. 1725 1726What Changed in a Kernel? 1727------------------------- 1728 1729Here are a few examples that show how to use Git commands to 1730examine changes. These examples are by no means the only way to see 1731changes. 1732 1733.. note:: 1734 1735 In the following examples, unless you provide a commit range, ``kernel.org`` 1736 history is blended with Yocto Project kernel changes. You can form 1737 ranges by using branch names from the kernel tree as the upper and 1738 lower commit markers with the Git commands. You can see the branch 1739 names through the web interface to the Yocto Project source 1740 repositories at :yocto_git:`/`. 1741 1742To see a full range of the changes, use the ``git whatchanged`` command 1743and specify a commit range for the branch (`commit`\ ``..``\ `commit`). 1744 1745Here is an example that looks at what has changed in the ``emenlow`` 1746branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the 1747commit associated with the ``standard/base`` branch, while the upper 1748commit range is the commit associated with the ``standard/emenlow`` 1749branch:: 1750 1751 $ git whatchanged origin/standard/base..origin/standard/emenlow 1752 1753To see short, one line summaries of changes use the ``git log`` command:: 1754 1755 $ git log --oneline origin/standard/base..origin/standard/emenlow 1756 1757Use this command to see code differences for the changes:: 1758 1759 $ git diff origin/standard/base..origin/standard/emenlow 1760 1761Use this command to see the commit log messages and the text 1762differences:: 1763 1764 $ git show origin/standard/base..origin/standard/emenlow 1765 1766Use this command to create individual patches for each change. Here is 1767an example that creates patch files for each commit and places them 1768in your ``Documents`` directory:: 1769 1770 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow 1771 1772Showing a Particular Feature or Branch Change 1773--------------------------------------------- 1774 1775Tags in the Yocto Project kernel tree divide changes for significant 1776features or branches. The ``git show`` tag command shows changes based 1777on a tag. Here is an example that shows ``systemtap`` changes:: 1778 1779 $ git show systemtap 1780 1781You can use the ``git branch --contains`` tag command to 1782show the branches that contain a particular feature. This command shows 1783the branches that contain the ``systemtap`` feature:: 1784 1785 $ git branch --contains systemtap 1786 1787Adding Recipe-Space Kernel Features 1788=================================== 1789 1790You can add kernel features in the 1791:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>` 1792by using the :term:`KERNEL_FEATURES` 1793variable and by specifying the feature's ``.scc`` file path in the 1794:term:`SRC_URI` statement. When you 1795add features using this method, the OpenEmbedded build system checks to 1796be sure the features are present. If the features are not present, the 1797build stops. Kernel features are the last elements processed for 1798configuring and patching the kernel. Therefore, adding features in this 1799manner is a way to enforce specific features are present and enabled 1800without needing to do a full audit of any other layer's additions to the 1801:term:`SRC_URI` statement. 1802 1803You add a kernel feature by providing the feature as part of the 1804:term:`KERNEL_FEATURES` variable and by providing the path to the feature's 1805``.scc`` file, which is relative to the root of the kernel Metadata. The 1806OpenEmbedded build system searches all forms of kernel Metadata on the 1807:term:`SRC_URI` statement regardless of whether the Metadata is in the 1808"kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e. 1809part of the kernel recipe). See the 1810":ref:`kernel-dev/advanced:kernel metadata location`" section for 1811additional information. 1812 1813When you specify the feature's ``.scc`` file on the :term:`SRC_URI` 1814statement, the OpenEmbedded build system adds the directory of that 1815``.scc`` file along with all its subdirectories to the kernel feature 1816search path. Because subdirectories are searched, you can reference a 1817single ``.scc`` file in the :term:`SRC_URI` statement to reference multiple 1818kernel features. 1819 1820Consider the following example that adds the "test.scc" feature to the 1821build. 1822 1823#. *Create the Feature File:* Create a ``.scc`` file and locate it just 1824 as you would any other patch file, ``.cfg`` file, or fetcher item you 1825 specify in the :term:`SRC_URI` statement. 1826 1827 .. note:: 1828 1829 - You must add the directory of the ``.scc`` file to the 1830 fetcher's search path in the same manner as you would add a 1831 ``.patch`` file. 1832 1833 - You can create additional ``.scc`` files beneath the directory 1834 that contains the file you are adding. All subdirectories are 1835 searched during the build as potential feature directories. 1836 1837 Continuing with the example, suppose the "test.scc" feature you are 1838 adding has a ``test.scc`` file in the following directory:: 1839 1840 my_recipe 1841 | 1842 +-linux-yocto 1843 | 1844 +-test.cfg 1845 +-test.scc 1846 1847 In this example, the 1848 ``linux-yocto`` directory has both the feature ``test.scc`` file and 1849 a similarly named configuration fragment file ``test.cfg``. 1850 1851#. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the 1852 recipe's :term:`SRC_URI` statement:: 1853 1854 SRC_URI += "file://test.scc" 1855 1856 The leading space before the path is important as the path is 1857 appended to the existing path. 1858 1859#. *Specify the Feature as a Kernel Feature:* Use the 1860 :term:`KERNEL_FEATURES` statement to specify the feature as a kernel 1861 feature:: 1862 1863 KERNEL_FEATURES += "test.scc" 1864 1865 The OpenEmbedded build 1866 system processes the kernel feature when it builds the kernel. 1867 1868 .. note:: 1869 1870 If other features are contained below "test.scc", then their 1871 directories are relative to the directory containing the ``test.scc`` 1872 file. 1873