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