summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
authorQuentin Schulz <foss@0leil.net>2020-10-26 18:50:27 +0100
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-27 13:23:00 +0000
commit08d7d5c2433c9f54567c558e551771a3d08e272f (patch)
treeacac016c9cad680d4a0bed52661f3add9aa8bf57 /documentation/kernel-dev
parent5d75168a13d00253460020e536b2a87833ec67d2 (diff)
downloadpoky-08d7d5c2433c9f54567c558e551771a3d08e272f.tar.gz
docs: kernel-dev: fix typos, highlights and links
(From yocto-docs rev: a69247321ff34cb0a2b9a8cc62020ec7f3aad834) Signed-off-by: Quentin Schulz <foss@0leil.net> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev')
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.rst96
-rw-r--r--documentation/kernel-dev/kernel-dev-common.rst333
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.rst15
-rw-r--r--documentation/kernel-dev/kernel-dev-faq.rst17
-rw-r--r--documentation/kernel-dev/kernel-dev-intro.rst17
-rw-r--r--documentation/kernel-dev/kernel-dev-maint-appx.rst20
6 files changed, 211 insertions, 287 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.rst b/documentation/kernel-dev/kernel-dev-advanced.rst
index eeb8f87924..444037c3a7 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.rst
+++ b/documentation/kernel-dev/kernel-dev-advanced.rst
@@ -44,9 +44,7 @@ linux-yocto recipe.
44.. note:: 44.. note::
45 45
46 A Linux kernel recipe that contains kernel Metadata (e.g. inherits 46 A Linux kernel recipe that contains kernel Metadata (e.g. inherits
47 from the 47 from the ``linux-yocto.inc`` file) is said to be a "linux-yocto style" recipe.
48 linux-yocto.inc
49 file) is said to be a "linux-yocto style" recipe.
50 48
51Every linux-yocto style recipe must define the 49Every linux-yocto style recipe must define the
52:term:`KMACHINE` variable. This 50:term:`KMACHINE` variable. This
@@ -70,12 +68,8 @@ to indicate the branch.
70 68
71.. note:: 69.. note::
72 70
73 You can use the 71 You can use the ``KBRANCH`` value to define an alternate branch typically
74 KBRANCH 72 with a machine override as shown here from the ``meta-yocto-bsp`` layer:
75 value to define an alternate branch typically with a machine override
76 as shown here from the
77 meta-yocto-bsp
78 layer:
79 :: 73 ::
80 74
81 KBRANCH_edgerouter = "standard/edgerouter" 75 KBRANCH_edgerouter = "standard/edgerouter"
@@ -101,7 +95,7 @@ section for more information on kernel types.
101During the build, the kern-tools search for the BSP description file 95During the build, the kern-tools search for the BSP description file
102that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE`` 96that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE``
103variables passed in from the recipe. The tools use the first BSP 97variables passed in from the recipe. The tools use the first BSP
104description it finds that match both variables. If the tools cannot find 98description they find that matches both variables. If the tools cannot find
105a match, they issue a warning. 99a match, they issue a warning.
106 100
107The tools first search for the ``KMACHINE`` and then for the 101The tools first search for the ``KMACHINE`` and then for the
@@ -251,8 +245,7 @@ two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
251 CONFIG_X86_BIGSMP=y 245 CONFIG_X86_BIGSMP=y
252 246
253You can find general information on configuration 247You can find general information on configuration
254fragment files in the "`Creating Configuration 248fragment files in the ":ref:`creating-config-fragments`" section.
255Fragments <#creating-config-fragments>`__" section.
256 249
257Within the ``smp.scc`` file, the 250Within the ``smp.scc`` file, the
258:term:`KFEATURE_DESCRIPTION` 251:term:`KFEATURE_DESCRIPTION`
@@ -269,13 +262,12 @@ non-hardware fragment.
269 262
270.. note:: 263.. note::
271 264
272 The description file can include multiple 265 The description file can include multiple ``kconf`` statements, one per
273 kconf 266 fragment.
274 statements, one per fragment.
275 267
276As described in the "`Validating 268As described in the
277Configuration <#validating-configuration>`__" section, you can use the 269":ref:`kernel-dev/kernel-dev-common:validating configuration`" section, you can
278following BitBake command to audit your configuration: 270use the following BitBake command to audit your configuration:
279:: 271::
280 272
281 $ bitbake linux-yocto -c kernel_configcheck -f 273 $ bitbake linux-yocto -c kernel_configcheck -f
@@ -335,10 +327,8 @@ for the five patches in the directory.
335 327
336You can create a typical ``.patch`` file using ``diff -Nurp`` or 328You can create a typical ``.patch`` file using ``diff -Nurp`` or
337``git format-patch`` commands. For information on how to create patches, 329``git format-patch`` commands. For information on how to create patches,
338see the "`Using ``devtool`` to Patch the 330see the ":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`"
339Kernel <#using-devtool-to-patch-the-kernel>`__" and "`Using Traditional 331and ":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`"
340Kernel Development to Patch the
341Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__"
342sections. 332sections.
343 333
344Features 334Features
@@ -397,15 +387,11 @@ type as follows:
397 387
398.. note:: 388.. note::
399 389
400 You can find kernel recipes in the 390 You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory
401 meta/recipes-kernel/linux 391 of the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`
402 directory of the 392 (e.g. ``poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb``). See the
403 Source Directory 393 ":ref:`kernel-dev/kernel-dev-advanced:using kernel metadata in a recipe`"
404 (e.g. 394 section for more information.
405 poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb
406 ). See the "
407 Using Kernel Metadata in a Recipe
408 " section for more information.
409 395
410Three kernel types ("standard", "tiny", and "preempt-rt") are supported 396Three kernel types ("standard", "tiny", and "preempt-rt") are supported
411for Linux Yocto kernels: 397for Linux Yocto kernels:
@@ -466,16 +452,11 @@ and ``patch`` commands, respectively.
466 452
467.. note:: 453.. note::
468 454
469 It is not strictly necessary to create a kernel type 455 It is not strictly necessary to create a kernel type ``.scc``
470 .scc
471 file. The Board Support Package (BSP) file can implicitly define the 456 file. The Board Support Package (BSP) file can implicitly define the
472 kernel type using a 457 kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the
473 define 458 ":ref:`kernel-dev/kernel-dev-advanced:bsp descriptions`" section for more
474 KTYPE 459 information.
475 myktype
476 line. See the "
477 BSP Descriptions
478 " section for more information.
479 460
480BSP Descriptions 461BSP Descriptions
481---------------- 462----------------
@@ -488,13 +469,9 @@ supported kernel type.
488.. note:: 469.. note::
489 470
490 For BSPs supported by the Yocto Project, the BSP description files 471 For BSPs supported by the Yocto Project, the BSP description files
491 are located in the 472 are located in the ``bsp`` directory of the ``yocto-kernel-cache``
492 bsp
493 directory of the
494 yocto-kernel-cache
495 repository organized under the "Yocto Linux Kernel" heading in the 473 repository organized under the "Yocto Linux Kernel" heading in the
496 Yocto Project Source Repositories 474 :yocto_git:`Yocto Project Source Repositories </>`.
497 .
498 475
499This section overviews the BSP description structure, the aggregation 476This section overviews the BSP description structure, the aggregation
500concepts, and presents a detailed example using a BSP supported by the 477concepts, and presents a detailed example using a BSP supported by the
@@ -571,7 +548,7 @@ policy. See the "`Kernel Types <#kernel-types>`__" section for more
571information. 548information.
572 549
573To aggregate common configurations and features specific to the kernel 550To aggregate common configurations and features specific to the kernel
574for mybsp, use the following: 551for `mybsp`, use the following:
575:: 552::
576 553
577 include mybsp.scc 554 include mybsp.scc
@@ -582,8 +559,7 @@ You can see that in the BeagleBone example with the following:
582 include beaglebone.scc 559 include beaglebone.scc
583 560
584For information on how to break a complete ``.config`` file into the various 561For information on how to break a complete ``.config`` file into the various
585configuration fragments, see the "`Creating Configuration 562configuration fragments, see the ":ref:`creating-config-fragments`" section.
586Fragments <#creating-config-fragments>`__" section.
587 563
588Finally, if you have any configurations specific to the hardware that 564Finally, if you have any configurations specific to the hardware that
589are not in a ``*.scc`` file, you can include them as follows: 565are not in a ``*.scc`` file, you can include them as follows:
@@ -653,7 +629,7 @@ found on the machine. This ``minnow.scc`` description file is then
653included in each of the three "minnow" description files for the 629included in each of the three "minnow" description files for the
654supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). 630supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
655Consider the "minnow" description for the "standard" kernel type (i.e. 631Consider the "minnow" description for the "standard" kernel type (i.e.
656``minnow-standard.scc``: 632``minnow-standard.scc``):
657:: 633::
658 634
659 define KMACHINE minnow 635 define KMACHINE minnow
@@ -725,8 +701,8 @@ others, the recipe-space method is recommended. This method is also a
725good approach if you are working with Linux kernel sources you do not 701good approach if you are working with Linux kernel sources you do not
726control or if you just do not want to maintain a Linux kernel Git 702control or if you just do not want to maintain a Linux kernel Git
727repository on your own. For partial information on how you can define 703repository on your own. For partial information on how you can define
728kernel Metadata in the recipe-space, see the "`Modifying an Existing 704kernel Metadata in the recipe-space, see the
729Recipe <#modifying-an-existing-recipe>`__" section. 705":ref:`kernel-dev/kernel-dev-common:modifying an existing recipe`" section.
730 706
731Conversely, if you are actively developing a kernel and are already 707Conversely, if you are actively developing a kernel and are already
732maintaining a Linux kernel Git repository of your own, you might find it 708maintaining a Linux kernel Git repository of your own, you might find it
@@ -746,8 +722,8 @@ modifying
746``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to 722``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to
747a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to 723a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to
748``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. 724``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``.
749See the "`Modifying an Existing 725See the ":ref:`kernel-dev/kernel-dev-common:modifying an existing recipe`"
750Recipe <#modifying-an-existing-recipe>`__" section for more information. 726section for more information.
751 727
752Here is an example that shows a trivial tree of kernel Metadata stored 728Here is an example that shows a trivial tree of kernel Metadata stored
753in recipe-space within a BSP layer: 729in recipe-space within a BSP layer:
@@ -849,7 +825,7 @@ best for your development model.
849Encapsulating Patches 825Encapsulating Patches
850--------------------- 826---------------------
851 827
852if you are reusing patches from an external tree and are not working on 828If you are reusing patches from an external tree and are not working on
853the patches, you might find the encapsulated feature to be appropriate. 829the patches, you might find the encapsulated feature to be appropriate.
854Given this scenario, you do not need to create any branches in the 830Given this scenario, you do not need to create any branches in the
855source repository. Rather, you just take the static patches you need and 831source repository. Rather, you just take the static patches you need and
@@ -881,6 +857,7 @@ new branch as the ``KBRANCH`` to use for the board as follows:
881 857
882Another method is to use the ``branch`` command in the BSP 858Another method is to use the ``branch`` command in the BSP
883description: 859description:
860::
884 861
885 mybsp.scc: 862 mybsp.scc:
886 define KMACHINE mybsp 863 define KMACHINE mybsp
@@ -902,7 +879,7 @@ repositories use:
902If you had two kernel types, "standard" and "small" for instance, three 879If you had two kernel types, "standard" and "small" for instance, three
903machines, and common as ``mydir``, the branches in your Git repository 880machines, and common as ``mydir``, the branches in your Git repository
904might look like this: 881might look like this:
905: 882::
906 883
907 mydir/base 884 mydir/base
908 mydir/standard/base 885 mydir/standard/base
@@ -922,11 +899,8 @@ appropriate for the other branches.
922 899
923 The "base" branches are an artifact of the way Git manages its data 900 The "base" branches are an artifact of the way Git manages its data
924 internally on the filesystem: Git will not allow you to use 901 internally on the filesystem: Git will not allow you to use
925 mydir/standard 902 ``mydir/standard`` and ``mydir/standard/machine_a`` because it would have to
926 and 903 create a file and a directory named "standard".
927 mydir/standard/machine_a
928 because it would have to create a file and a directory named
929 "standard".
930 904
931Feature Branches 905Feature Branches
932---------------- 906----------------
diff --git a/documentation/kernel-dev/kernel-dev-common.rst b/documentation/kernel-dev/kernel-dev-common.rst
index 64235f3803..370acf1388 100644
--- a/documentation/kernel-dev/kernel-dev-common.rst
+++ b/documentation/kernel-dev/kernel-dev-common.rst
@@ -33,12 +33,10 @@ Source Directory.
33 33
34 Be sure you check out the appropriate development branch or you 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 35 create your local branch by checking out a specific tag to get the
36 desired version of Yocto Project. See the " 36 desired version of Yocto Project. See the
37 Checking Out by Branch in Poky 37 ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" and
38 " and " 38 ":ref:`dev-manual/dev-manual-start:checking out by tag in poky`"
39 Checking Out by Tag in Poky 39 sections in the Yocto Project Development Tasks Manual for more information.
40 " sections in the Yocto Project Development Tasks Manual for more
41 information.
42 40
43Kernel development is best accomplished using 41Kernel development is best accomplished using
44:ref:`devtool <sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow>` 42:ref:`devtool <sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow>`
@@ -50,8 +48,8 @@ Getting Ready to Develop Using ``devtool``
50 48
51Follow these steps to prepare to update the kernel image using 49Follow these steps to prepare to update the kernel image using
52``devtool``. Completing this procedure leaves you with a clean kernel 50``devtool``. Completing this procedure leaves you with a clean kernel
53image and ready to make modifications as described in the " 51image and ready to make modifications as described in the
54:ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`" 52":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`"
55section: 53section:
56 54
571. *Initialize the BitBake Environment:* Before building an extensible 551. *Initialize the BitBake Environment:* Before building an extensible
@@ -65,10 +63,8 @@ section:
65 .. note:: 63 .. note::
66 64
67 The previous commands assume the 65 The previous commands assume the
68 Source Repositories 66 :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`
69 (i.e. 67 (i.e. ``poky``) have been cloned using Git and the local repository is named
70 poky
71 ) have been cloned using Git and the local repository is named
72 "poky". 68 "poky".
73 69
742. *Prepare Your local.conf File:* By default, the 702. *Prepare Your local.conf File:* By default, the
@@ -107,18 +103,15 @@ section:
107 .. note:: 103 .. note::
108 104
109 For background information on working with common and BSP layers, 105 For background information on working with common and BSP layers,
110 see the " 106 see the
111 Understanding and Creating Layers 107 ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
112 " section in the Yocto Project Development Tasks Manual and the " 108 section in the Yocto Project Development Tasks Manual and the
113 BSP Layers 109 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board
114 " section in the Yocto Project Board Support (BSP) Developer's 110 Support (BSP) Developer's Guide, respectively. For information on how to
115 Guide, respectively. For information on how to use the 111 use the ``bitbake-layers create-layer`` command to quickly set up a layer,
116 bitbake-layers create-layer 112 see the
117 command to quickly set up a layer, see the " 113 ":ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
118 Creating a General Layer Using the 114 section in the Yocto Project Development Tasks Manual.
119 bitbake-layers
120 Script
121 " section in the Yocto Project Development Tasks Manual.
122 115
1234. *Inform the BitBake Build Environment About Your Layer:* As directed 1164. *Inform the BitBake Build Environment About Your Layer:* As directed
124 when you created your layer, you need to add the layer to the 117 when you created your layer, you need to add the layer to the
@@ -141,9 +134,12 @@ section:
141 Once 134 Once
142 the build finishes, you can find the SDK installer file (i.e. 135 the build finishes, you can find the SDK installer file (i.e.
143 ``*.sh`` file) in the following directory: 136 ``*.sh`` file) in the following directory:
144 ~/poky/build/tmp/deploy/sdk For this example, the installer file is 137 ::
145 named 138
146 ``poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-DISTRO.sh`` 139 ~/poky/build/tmp/deploy/sdk
140
141 For this example, the installer file is named
142 ``poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-DISTRO.sh``.
147 143
1486. *Install the Extensible SDK:* Use the following command to install 1446. *Install the Extensible SDK:* Use the following command to install
149 the SDK. For this example, install the SDK in the default 145 the SDK. For this example, install the SDK in the default
@@ -211,7 +207,7 @@ section:
211 building for actual hardware and not for emulation, you could flash 207 building for actual hardware and not for emulation, you could flash
212 the image to a USB stick on ``/dev/sdd`` and boot your device. For an 208 the image to a USB stick on ``/dev/sdd`` and boot your device. For an
213 example that uses a Minnowboard, see the 209 example that uses a Minnowboard, see the
214 `TipsAndTricks/KernelDevelopmentWithEsdk <https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk>`__ 210 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </wiki/TipsAndTricks/KernelDevelopmentWithEsdk>`
215 Wiki page. 211 Wiki page.
216 212
217At this point you have set up to start making modifications to the 213At this point you have set up to start making modifications to the
@@ -247,16 +243,14 @@ section:
247 $ cd ~/poky 243 $ cd ~/poky
248 $ git branch 244 $ git branch
249 master 245 master
250 * &DISTRO_NAME; 246 * &DISTRO_NAME_NO_CAP;
251 $ source oe-init-build-env 247 $ source oe-init-build-env
252 248
253 .. note:: 249 .. note::
254 250
255 The previous commands assume the 251 The previous commands assume the
256 Source Repositories 252 :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`
257 (i.e. 253 (i.e. ``poky``) have been cloned using Git and the local repository is named
258 poky
259 ) have been cloned using Git and the local repository is named
260 "poky". 254 "poky".
261 255
2622. *Prepare Your local.conf File:* By default, the 2562. *Prepare Your local.conf File:* By default, the
@@ -294,18 +288,15 @@ section:
294 .. note:: 288 .. note::
295 289
296 For background information on working with common and BSP layers, 290 For background information on working with common and BSP layers,
297 see the " 291 see the
298 Understanding and Creating Layers 292 ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
299 " section in the Yocto Project Development Tasks Manual and the " 293 section in the Yocto Project Development Tasks Manual and the
300 BSP Layers 294 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board
301 " section in the Yocto Project Board Support (BSP) Developer's 295 Support (BSP) Developer's Guide, respectively. For information on how to
302 Guide, respectively. For information on how to use the 296 use the ``bitbake-layers create-layer`` command to quickly set up a layer,
303 bitbake-layers create-layer 297 see the
304 command to quickly set up a layer, see the " 298 ":ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
305 Creating a General Layer Using the 299 section in the Yocto Project Development Tasks Manual.
306 bitbake-layers
307 Script
308 " section in the Yocto Project Development Tasks Manual.
309 300
3104. *Inform the BitBake Build Environment About Your Layer:* As directed 3014. *Inform the BitBake Build Environment About Your Layer:* As directed
311 when you created your layer, you need to add the layer to the 302 when you created your layer, you need to add the layer to the
@@ -334,12 +325,10 @@ section:
334 325
335 .. note:: 326 .. note::
336 327
337 The 328 The ``linux-yocto-4.12`` kernel can be used with the Yocto Project 2.4
338 linux-yocto-4.12 329 release and forward.
339 kernel can be used with the Yocto Project 2.4 release and forward. 330 You cannot use the ``linux-yocto-4.12`` kernel with releases prior to
340 You cannot use the 331 Yocto Project 2.4.
341 linux-yocto-4.12
342 kernel with releases prior to Yocto Project 2.4:
343 332
344 :: 333 ::
345 334
@@ -351,7 +340,7 @@ section:
351 remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256) 340 remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256)
352 Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done. 341 Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done.
353 Resolving deltas: 100% (5152604/5152604), done. Checking connectivity... done. 342 Resolving deltas: 100% (5152604/5152604), done. Checking connectivity... done.
354 Checking out files: 100% (59846/59846), done. 343 Checking out files: 100% (59846/59846), done.
355 344
3566. *Create a Local Copy of the Kernel Cache Git Repository:* For 3456. *Create a Local Copy of the Kernel Cache Git Repository:* For
357 simplicity, it is recommended that you create your copy of the kernel 346 simplicity, it is recommended that you create your copy of the kernel
@@ -395,13 +384,10 @@ section in the Yocto Project Development Tasks Manual.
395.. note:: 384.. note::
396 385
397 The Yocto Project comes with many tools that simplify tasks you need 386 The Yocto Project comes with many tools that simplify tasks you need
398 to perform. One such tool is the 387 to perform. One such tool is the ``bitbake-layers create-layer``
399 bitbake-layers create-layer 388 command, which simplifies creating a new layer. See the
400 command, which simplifies creating a new layer. See the " 389 ":ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
401 Creating a General Layer Using the 390 section in the Yocto Project Development Tasks Manual for
402 bitbake-layers
403 Script
404 " section in the Yocto Project Development Tasks Manual for
405 information on how to use this script to quick set up a new layer. 391 information on how to use this script to quick set up a new layer.
406 392
407To better understand the layer you create for kernel development, the 393To better understand the layer you create for kernel development, the
@@ -471,11 +457,11 @@ the :term:`Source Directory` in
471 457
472Modifying an existing recipe can consist of the following: 458Modifying an existing recipe can consist of the following:
473 459
474- Creating the append file 460- :ref:`kernel-dev/kernel-dev-common:creating the append file`
475 461
476- Applying patches 462- :ref:`kernel-dev/kernel-dev-common:applying patches`
477 463
478- Changing the configuration 464- :ref:`kernel-dev/kernel-dev-common:changing the configuration`
479 465
480Before modifying an existing recipe, be sure that you have created a 466Before modifying an existing recipe, be sure that you have created a
481minimal, custom layer from which you can work. See the "`Creating and 467minimal, custom layer from which you can work. See the "`Creating and
@@ -490,7 +476,8 @@ based on the linux-yocto recipe you are using. For example, if you are
490modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe, 476modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe,
491the append file will typically be located as follows within your custom 477the append file will typically be located as follows within your custom
492layer: 478layer:
493:: 479
480.. code-block:: none
494 481
495 your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend 482 your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend
496 483
@@ -515,13 +502,12 @@ your layer in the following area:
515.. note:: 502.. note::
516 503
517 If you are working on a new machine Board Support Package (BSP), be 504 If you are working on a new machine Board Support Package (BSP), be
518 sure to refer to the 505 sure to refer to the :doc:`../bsp-guide/bsp-guide`.
519 Yocto Project Board Support Package (BSP) Developer's Guide
520 .
521 506
522As an example, consider the following append file used by the BSPs in 507As an example, consider the following append file used by the BSPs in
523``meta-yocto-bsp``: 508``meta-yocto-bsp``:
524:: 509
510.. code-block:: none
525 511
526 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend 512 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend
527 513
@@ -689,17 +675,13 @@ created to hold the configuration changes.
689 675
690.. note:: 676.. note::
691 677
692 The build system applies the configurations from the 678 The build system applies the configurations from the ``defconfig``
693 defconfig
694 file before applying any subsequent configuration fragments. The 679 file before applying any subsequent configuration fragments. The
695 final kernel configuration is a combination of the configurations in 680 final kernel configuration is a combination of the configurations in
696 the 681 the ``defconfig`` file and any configuration fragments you provide. You need
697 defconfig 682 to realize that if you have any configuration fragments, the build system
698 file and any configuration fragments you provide. You need to realize 683 applies these on top of and after applying the existing ``defconfig`` file
699 that if you have any configuration fragments, the build system 684 configurations.
700 applies these on top of and after applying the existing
701 defconfig
702 file configurations.
703 685
704Generally speaking, the preferred approach is to determine the 686Generally speaking, the preferred approach is to determine the
705incremental change you want to make and add that as a configuration 687incremental change you want to make and add that as a configuration
@@ -755,7 +737,7 @@ To specify an "in-tree" ``defconfig`` file, use the following statement
755form: 737form:
756:: 738::
757 739
758 KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file 740 KBUILD_DEFCONFIG_KMACHINE ?= "defconfig_file"
759 741
760Here is an example 742Here is an example
761that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2" 743that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2"
@@ -768,7 +750,7 @@ a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset:
768Aside from modifying your kernel recipe and providing your own 750Aside from modifying your kernel recipe and providing your own
769``defconfig`` file, you need to be sure no files or statements set 751``defconfig`` file, you need to be sure no files or statements set
770``SRC_URI`` to use a ``defconfig`` other than your "in-tree" file (e.g. 752``SRC_URI`` to use a ``defconfig`` other than your "in-tree" file (e.g.
771a kernel's ``linux-``\ machine\ ``.inc`` file). In other words, if the 753a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the
772build system detects a statement that identifies an "out-of-tree" 754build system detects a statement that identifies an "out-of-tree"
773``defconfig`` file, that statement will override your 755``defconfig`` file, that statement will override your
774``KBUILD_DEFCONFIG`` variable. 756``KBUILD_DEFCONFIG`` variable.
@@ -786,10 +768,9 @@ the extensible SDK and ``devtool``.
786.. note:: 768.. note::
787 769
788 Before attempting this procedure, be sure you have performed the 770 Before attempting this procedure, be sure you have performed the
789 steps to get ready for updating the kernel as described in the " 771 steps to get ready for updating the kernel as described in the
790 Getting Ready to Develop Using 772 ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devtool\`\``"
791 devtool 773 section.
792 " section.
793 774
794Patching the kernel involves changing or adding configurations to an 775Patching the kernel involves changing or adding configurations to an
795existing kernel, changing or adding recipes to the kernel that are 776existing kernel, changing or adding recipes to the kernel that are
@@ -809,12 +790,9 @@ the ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devto
809 790
810 .. note:: 791 .. note::
811 792
812 See this 793 See this step in the
813 step 794 ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devtool\`\``"
814 in the " 795 section for more information.
815 Getting Ready to Develop Using
816 devtool
817 " section for more information.
818 796
819 Use the following ``devtool`` command to check out the code: 797 Use the following ``devtool`` command to check out the code:
820 :: 798 ::
@@ -825,7 +803,8 @@ the ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devto
825 803
826 During the checkout operation, a bug exists that could cause 804 During the checkout operation, a bug exists that could cause
827 errors such as the following to appear: 805 errors such as the following to appear:
828 :: 806
807 .. code-block:: none
829 808
830 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus 809 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
831 be3a89ce7c47178880ba7bf6293d7404 for 810 be3a89ce7c47178880ba7bf6293d7404 for
@@ -883,7 +862,7 @@ the ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devto
883 If the image you originally created resulted in a Wic file, you 862 If the image you originally created resulted in a Wic file, you
884 can use an alternate method to create the new image with the 863 can use an alternate method to create the new image with the
885 updated kernel. For an example, see the steps in the 864 updated kernel. For an example, see the steps in the
886 TipsAndTricks/KernelDevelopmentWithEsdk 865 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </wiki/TipsAndTricks/KernelDevelopmentWithEsdk>`
887 Wiki Page. 866 Wiki Page.
888 867
889 :: 868 ::
@@ -903,7 +882,8 @@ the ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devto
903 2. *Verify the changes*: Log into the machine using ``root`` with no 882 2. *Verify the changes*: Log into the machine using ``root`` with no
904 password and then use the following shell command to scroll 883 password and then use the following shell command to scroll
905 through the console's boot output. 884 through the console's boot output.
906 :: 885
886 .. code-block:: none
907 887
908 # dmesg | less 888 # dmesg | less
909 889
@@ -925,14 +905,15 @@ the ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devto
925 commits as patches and create a ``.bbappend`` file, use the following 905 commits as patches and create a ``.bbappend`` file, use the following
926 command in the terminal used to work with the extensible SDK. This 906 command in the terminal used to work with the extensible SDK. This
927 example uses the previously established layer named ``meta-mylayer``. 907 example uses the previously established layer named ``meta-mylayer``.
908 ::
928 909
929 .. note:: 910 $ devtool finish linux-yocto ~/meta-mylayer
930 911
931 See Step 3 of the " 912 .. note::
932 Getting Ready to Develop Using devtool
933 " section for information on setting up this layer.
934 913
935 $ devtool finish linux-yocto ~/meta-mylayer 914 See Step 3 of the
915 ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devtool\`\``"
916 section for information on setting up this layer.
936 917
937 Once the command 918 Once the command
938 finishes, the patches and the ``.bbappend`` file are located in the 919 finishes, the patches and the ``.bbappend`` file are located in the
@@ -960,9 +941,9 @@ section).
960.. note:: 941.. note::
961 942
962 Before attempting this procedure, be sure you have performed the 943 Before attempting this procedure, be sure you have performed the
963 steps to get ready for updating the kernel as described in the " 944 steps to get ready for updating the kernel as described in the
964 Getting Ready for Traditional Kernel Development 945 ":ref:`kernel-dev/kernel-dev-common:getting ready for traditional kernel development`"
965 " section. 946 section.
966 947
967Patching the kernel involves changing or adding configurations to an 948Patching the kernel involves changing or adding configurations to an
968existing kernel, changing or adding recipes to the kernel that are 949existing kernel, changing or adding recipes to the kernel that are
@@ -986,7 +967,7 @@ Section.
986 section, use the following commands to edit the ``calibrate.c`` file: 967 section, use the following commands to edit the ``calibrate.c`` file:
987 968
988 1. *Change the working directory*: You need to locate the source 969 1. *Change the working directory*: You need to locate the source
989 files in the local copy of the kernel Git repository: Change to 970 files in the local copy of the kernel Git repository. Change to
990 where the kernel source code is before making your edits to the 971 where the kernel source code is before making your edits to the
991 ``calibrate.c`` file: 972 ``calibrate.c`` file:
992 :: 973 ::
@@ -1046,13 +1027,10 @@ Section.
1046 1027
1047 .. note:: 1028 .. note::
1048 1029
1049 Be sure to replace 1030 Be sure to replace `path-to`
1050 path-to
1051 with the pathname to your local Git repositories. Also, you must 1031 with the pathname to your local Git repositories. Also, you must
1052 be sure to specify the correct branch and machine types. For this 1032 be sure to specify the correct branch and machine types. For this
1053 example, the branch is 1033 example, the branch is ``standard/base`` and the machine is ``qemux86``.
1054 standard/base
1055 and the machine is "qemux86".
1056 1034
10574. *Build the Image:* With the source modified, your changes staged and 10354. *Build the Image:* With the source modified, your changes staged and
1058 committed, and the ``local.conf`` file pointing to the kernel files, 1036 committed, and the ``local.conf`` file pointing to the kernel files,
@@ -1073,7 +1051,8 @@ Section.
10736. *Look for Your Changes:* As QEMU booted, you might have seen your 10516. *Look for Your Changes:* As QEMU booted, you might have seen your
1074 changes rapidly scroll by. If not, use these commands to see your 1052 changes rapidly scroll by. If not, use these commands to see your
1075 changes: 1053 changes:
1076 :: 1054
1055 .. code-block:: none
1077 1056
1078 # dmesg | less 1057 # dmesg | less
1079 1058
@@ -1134,13 +1113,10 @@ Section.
1134 1113
1135 .. note:: 1114 .. note::
1136 1115
1137 To build 1116 To build ``core-image-minimal`` again and see the effects of your patch,
1138 core-image-minimal 1117 you can essentially eliminate the temporary source files saved in
1139 again and see the effects of your patch, you can essentially 1118 ``poky/build/tmp/work/...`` and residual effects of the build by entering
1140 eliminate the temporary source files saved in 1119 the following sequence of commands:
1141 poky/build/tmp/work/...
1142 and residual effects of the build by entering the following
1143 sequence of commands:
1144 :: 1120 ::
1145 1121
1146 $ cd ~/poky/build 1122 $ cd ~/poky/build
@@ -1174,7 +1150,7 @@ Using  ``menuconfig``
1174The easiest way to define kernel configurations is to set them through 1150The easiest way to define kernel configurations is to set them through
1175the ``menuconfig`` tool. This tool provides an interactive method with 1151the ``menuconfig`` tool. This tool provides an interactive method with
1176which to set kernel configurations. For general information on 1152which to set kernel configurations. For general information on
1177``menuconfig``, see http://en.wikipedia.org/wiki/Menuconfig. 1153``menuconfig``, see https://en.wikipedia.org/wiki/Menuconfig.
1178 1154
1179To use the ``menuconfig`` tool in the Yocto Project development 1155To use the ``menuconfig`` tool in the Yocto Project development
1180environment, you must do the following: 1156environment, you must do the following:
@@ -1212,35 +1188,20 @@ the tool and save your changes to create an updated version of the
1212 1188
1213.. note:: 1189.. note::
1214 1190
1215 You can use the entire 1191 You can use the entire ``.config`` file as the ``defconfig`` file. For
1216 .config 1192 information on ``defconfig`` files, see the
1217 file as the 1193 ":ref:`kernel-dev/kernel-dev-common:changing the configuration`",
1218 defconfig 1194 ":ref:`kernel-dev/kernel-dev-common:using an "in-tree" \`\`defconfig\`\` file`",
1219 file. For information on 1195 and ":ref:`kernel-dev/kernel-dev-common:creating a \`\`defconfig\`\` file`"
1220 defconfig 1196 sections.
1221 files, see the "
1222 Changing the Configuration
1223 ", "
1224 Using an In-Tree
1225 defconfig
1226 File
1227 , and "
1228 Creating a
1229 defconfig
1230 File
1231 " sections.
1232 1197
1233Consider an example that configures the "CONFIG_SMP" setting for the 1198Consider an example that configures the "CONFIG_SMP" setting for the
1234``linux-yocto-4.12`` kernel. 1199``linux-yocto-4.12`` kernel.
1235 1200
1236.. note:: 1201.. note::
1237 1202
1238 The OpenEmbedded build system recognizes this kernel as 1203 The OpenEmbedded build system recognizes this kernel as ``linux-yocto``
1239 linux-yocto 1204 through Metadata (e.g. :term:`PREFERRED_VERSION`\ ``_linux-yocto ?= "12.4%"``).
1240 through Metadata (e.g.
1241 PREFERRED_VERSION
1242 \_linux-yocto ?= "12.4%"
1243 ).
1244 1205
1245Once ``menuconfig`` launches, use the interface to navigate through the 1206Once ``menuconfig`` launches, use the interface to navigate through the
1246selections to find the configuration settings in which you are 1207selections to find the configuration settings in which you are
@@ -1259,7 +1220,8 @@ area where the specific kernel is built. For example, if you were
1259building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel 1220building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel
1260and you were building a QEMU image targeted for ``x86`` architecture, 1221and you were building a QEMU image targeted for ``x86`` architecture,
1261the ``.config`` file would be: 1222the ``.config`` file would be:
1262:: 1223
1224.. code-block:: none
1263 1225
1264 poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18... 1226 poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
1265 ...967-r0/linux-qemux86-standard-build/.config 1227 ...967-r0/linux-qemux86-standard-build/.config
@@ -1289,11 +1251,8 @@ kernel layer.
1289 1251
1290.. note:: 1252.. note::
1291 1253
1292 Be sure to make a copy of the 1254 Be sure to make a copy of the ``.config`` file and do not just rename it.
1293 .config 1255 The build system needs an existing ``.config`` file from which to work.
1294 file and do not just rename it. The build system needs an existing
1295 .config
1296 file from which to work.
1297 1256
1298Creating a  ``defconfig`` File 1257Creating a  ``defconfig`` File
1299------------------------------ 1258------------------------------
@@ -1307,13 +1266,9 @@ which the OpenEmbedded build system can draw to create the final
1307 1266
1308.. note:: 1267.. note::
1309 1268
1310 Out-of-the-box, the Yocto Project never ships a 1269 Out-of-the-box, the Yocto Project never ships a ``defconfig`` or ``.config``
1311 defconfig 1270 file. The OpenEmbedded build system creates the final ``.config`` file used
1312 or 1271 to configure the kernel.
1313 .config
1314 file. The OpenEmbedded build system creates the final
1315 .config
1316 file used to configure the kernel.
1317 1272
1318To create a ``defconfig``, start with a complete, working Linux kernel 1273To create a ``defconfig``, start with a complete, working Linux kernel
1319``.config`` file. Copy that file to the appropriate 1274``.config`` file. Copy that file to the appropriate
@@ -1335,16 +1290,13 @@ created to hold the configuration changes.
1335 1290
1336.. note:: 1291.. note::
1337 1292
1338 The build system applies the configurations from the 1293 The build system applies the configurations from the ``defconfig``
1339 defconfig
1340 file before applying any subsequent configuration fragments. The 1294 file before applying any subsequent configuration fragments. The
1341 final kernel configuration is a combination of the configurations in 1295 final kernel configuration is a combination of the configurations in
1342 the 1296 the ``defconfig`` file and any configuration fragments you provide. You need
1343 defconfig 1297 to realize that if you have any configuration fragments, the build system
1344 file and any configuration fragments you provide. You need to realize 1298 applies these on top of and after applying the existing ``defconfig`` file
1345 that if you have any configuration fragments, the build system 1299 configurations.
1346 applies these on top of and after applying the existing defconfig
1347 file configurations.
1348 1300
1349For more information on configuring the kernel, see the "`Changing the 1301For more information on configuring the kernel, see the "`Changing the
1350Configuration <#changing-the-configuration>`__" section. 1302Configuration <#changing-the-configuration>`__" section.
@@ -1368,9 +1320,8 @@ appear in the ``.config`` file, which is in the :term:`Build Directory`.
1368 1320
1369.. note:: 1321.. note::
1370 1322
1371 For more information about where the 1323 For more information about where the ``.config`` file is located, see the
1372 .config 1324 example in the
1373 file is located, see the example in the
1374 ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``" 1325 ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``"
1375 section. 1326 section.
1376 1327
@@ -1384,10 +1335,9 @@ multi-processor support within the kernel:
1384 1335
1385.. note:: 1336.. note::
1386 1337
1387 All configuration fragment files must use the 1338 All configuration fragment files must use the ``.cfg`` extension in order
1388 .cfg 1339 for the OpenEmbedded build system to recognize them as a configuration
1389 extension in order for the OpenEmbedded build system to recognize 1340 fragment.
1390 them as a configuration fragment.
1391 1341
1392Another method is to create a configuration fragment using the 1342Another method is to create a configuration fragment using the
1393differences between two configuration files: one previously created and 1343differences between two configuration files: one previously created and
@@ -1429,9 +1379,8 @@ information on how to use the output as a configuration fragment.
1429.. note:: 1379.. note::
1430 1380
1431 You can also use this method to create configuration fragments for a 1381 You can also use this method to create configuration fragments for a
1432 BSP. See the " 1382 BSP. See the ":ref:`kernel-dev/kernel-dev-advanced:bsp descriptions`"
1433 BSP Descriptions 1383 section for more information.
1434 " section for more information.
1435 1384
1436Where do you put your configuration fragment files? You can place these 1385Where do you put your configuration fragment files? You can place these
1437files in an area pointed to by 1386files in an area pointed to by
@@ -1480,7 +1429,8 @@ See the ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``" section f
1480information on how to create a configuration file. 1429information on how to create a configuration file.
1481 1430
1482Following is sample output from the ``do_kernel_configcheck`` task: 1431Following is sample output from the ``do_kernel_configcheck`` task:
1483:: 1432
1433.. code-block:: none
1484 1434
1485 Loading cache: 100% |########################################################| Time: 0:00:00 1435 Loading cache: 100% |########################################################| Time: 0:00:00
1486 Loaded 1275 entries from dependency cache. 1436 Loaded 1275 entries from dependency cache.
@@ -1577,10 +1527,8 @@ produces warning messages for the following issues:
1577 1527
1578.. note:: 1528.. note::
1579 1529
1580 The 1530 The :ref:`ref-tasks-kernel_configcheck` task can also optionally report if
1581 do_kernel_configcheck 1531 an option is overridden during processing.
1582 task can also optionally report if an option is overridden during
1583 processing.
1584 1532
1585For each output warning, a message points to the file that contains a 1533For each output warning, a message points to the file that contains a
1586list of the options and a pointer to the configuration fragment that 1534list of the options and a pointer to the configuration fragment that
@@ -1627,7 +1575,7 @@ Expanding Variables
1627=================== 1575===================
1628 1576
1629Sometimes it is helpful to determine what a variable expands to during a 1577Sometimes it is helpful to determine what a variable expands to during a
1630build. You can do examine the values of variables by examining the 1578build. You can examine the values of variables by examining the
1631output of the ``bitbake -e`` command. The output is long and is more 1579output of the ``bitbake -e`` command. The output is long and is more
1632easily managed in a text file, which allows for easy searches: 1580easily managed in a text file, which allows for easy searches:
1633:: 1581::
@@ -1767,7 +1715,10 @@ Here are some basic steps you can use to work with your own sources:
1767 as derived from the :term:`SRCPV` 1715 as derived from the :term:`SRCPV`
1768 variable. The combined results are a string with the following 1716 variable. The combined results are a string with the following
1769 form: 1717 form:
1770 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 1718 ::
1719
1720 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
1721
1771 While lengthy, the extra verbosity in ``PV`` helps ensure you are 1722 While lengthy, the extra verbosity in ``PV`` helps ensure you are
1772 using the exact sources from which you intend to build. 1723 using the exact sources from which you intend to build.
1773 1724
@@ -1778,7 +1729,10 @@ Here are some basic steps you can use to work with your own sources:
1778 triggers an explicit build failure. You must change it to match a 1729 triggers an explicit build failure. You must change it to match a
1779 list of the machines that your new recipe supports. For example, 1730 list of the machines that your new recipe supports. For example,
1780 to support the ``qemux86`` and ``qemux86-64`` machines, use the 1731 to support the ``qemux86`` and ``qemux86-64`` machines, use the
1781 following form: COMPATIBLE_MACHINE = "qemux86|qemux86-64" 1732 following form:
1733 ::
1734
1735 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
1782 1736
17835. *Customize Your Recipe as Needed:* Provide further customizations to 17375. *Customize Your Recipe as Needed:* Provide further customizations to
1784 your recipe as needed just as you would customize an existing 1738 your recipe as needed just as you would customize an existing
@@ -1813,7 +1767,8 @@ is running that image.
1813Prior to attempting to build the out-of-tree modules, you need to be on 1767Prior to attempting to build the out-of-tree modules, you need to be on
1814the target as root and you need to change to the ``/usr/src/kernel`` 1768the target as root and you need to change to the ``/usr/src/kernel``
1815directory. Next, ``make`` the scripts: 1769directory. Next, ``make`` the scripts:
1816:: 1770
1771.. code-block:: none
1817 1772
1818 # cd /usr/src/kernel 1773 # cd /usr/src/kernel
1819 # make scripts 1774 # make scripts
@@ -1835,7 +1790,8 @@ create your own out-of-tree Linux kernel module recipe.
1835 1790
1836This template recipe is located in the ``poky`` Git repository of the 1791This template recipe is located in the ``poky`` Git repository of the
1837Yocto Project :yocto_git:`Source Repository <>` at: 1792Yocto Project :yocto_git:`Source Repository <>` at:
1838:: 1793
1794.. code-block:: none
1839 1795
1840 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb 1796 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
1841 1797
@@ -1925,17 +1881,15 @@ changes.
1925 1881
1926.. note:: 1882.. note::
1927 1883
1928 In the following examples, unless you provide a commit range, 1884 In the following examples, unless you provide a commit range, ``kernel.org``
1929 kernel.org
1930 history is blended with Yocto Project kernel changes. You can form 1885 history is blended with Yocto Project kernel changes. You can form
1931 ranges by using branch names from the kernel tree as the upper and 1886 ranges by using branch names from the kernel tree as the upper and
1932 lower commit markers with the Git commands. You can see the branch 1887 lower commit markers with the Git commands. You can see the branch
1933 names through the web interface to the Yocto Project source 1888 names through the web interface to the Yocto Project source
1934 repositories at 1889 repositories at :yocto_git:`/`.
1935 .
1936 1890
1937To see a full range of the changes, use the ``git whatchanged`` command 1891To see a full range of the changes, use the ``git whatchanged`` command
1938and specify a commit range for the branch (commit\ ``..``\ commit). 1892and specify a commit range for the branch (`commit`\ ``..``\ `commit`).
1939 1893
1940Here is an example that looks at what has changed in the ``emenlow`` 1894Here is an example that looks at what has changed in the ``emenlow``
1941branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the 1895branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the
@@ -1990,8 +1944,8 @@ Adding Recipe-Space Kernel Features
1990=================================== 1944===================================
1991 1945
1992You can add kernel features in the 1946You can add kernel features in the
1993`recipe-space <#recipe-space-metadata>`__ by using the 1947:ref:`recipe-space <kernel-dev/kernel-dev-advanced:recipe-space metadata>`
1994:term:`KERNEL_FEATURES` 1948by using the :term:`KERNEL_FEATURES`
1995variable and by specifying the feature's ``.scc`` file path in the 1949variable and by specifying the feature's ``.scc`` file path in the
1996:term:`SRC_URI` statement. When you 1950:term:`SRC_URI` statement. When you
1997add features using this method, the OpenEmbedded build system checks to 1951add features using this method, the OpenEmbedded build system checks to
@@ -2008,9 +1962,9 @@ You add a kernel feature by providing the feature as part of the
2008OpenEmbedded build system searches all forms of kernel Metadata on the 1962OpenEmbedded build system searches all forms of kernel Metadata on the
2009``SRC_URI`` statement regardless of whether the Metadata is in the 1963``SRC_URI`` statement regardless of whether the Metadata is in the
2010"kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e. 1964"kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e.
2011part of the kernel recipe). See the "`Kernel Metadata 1965part of the kernel recipe). See the
2012Location <#kernel-metadata-location>`__" section for additional 1966":ref:`kernel-dev/kernel-dev-advanced:kernel metadata location`" section for
2013information. 1967additional information.
2014 1968
2015When you specify the feature's ``.scc`` file on the ``SRC_URI`` 1969When you specify the feature's ``.scc`` file on the ``SRC_URI``
2016statement, the OpenEmbedded build system adds the directory of that 1970statement, the OpenEmbedded build system adds the directory of that
@@ -2073,6 +2027,5 @@ build.
2073 .. note:: 2027 .. note::
2074 2028
2075 If other features are contained below "test.scc", then their 2029 If other features are contained below "test.scc", then their
2076 directories are relative to the directory containing the 2030 directories are relative to the directory containing the ``test.scc``
2077 test.scc
2078 file. 2031 file.
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.rst b/documentation/kernel-dev/kernel-dev-concepts-appx.rst
index 5b6ebef5a8..681faee522 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.rst
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.rst
@@ -11,7 +11,7 @@ Yocto Project Kernel Development and Maintenance
11 11
12Kernels available through the Yocto Project (Yocto Linux kernels), like 12Kernels available through the Yocto Project (Yocto Linux kernels), like
13other kernels, are based off the Linux kernel releases from 13other kernels, are based off the Linux kernel releases from
14http://www.kernel.org. At the beginning of a major Linux kernel 14https://www.kernel.org. At the beginning of a major Linux kernel
15development cycle, the Yocto Project team chooses a Linux kernel based 15development cycle, the Yocto Project team chooses a Linux kernel based
16on factors such as release timing, the anticipated release timing of 16on factors such as release timing, the anticipated release timing of
17final upstream ``kernel.org`` versions, and Yocto Project feature 17final upstream ``kernel.org`` versions, and Yocto Project feature
@@ -119,7 +119,7 @@ upstream Linux kernel development and are managed by the Yocto Project
119team's Yocto Linux kernel development strategy. It is the Yocto Project 119team's Yocto Linux kernel development strategy. It is the Yocto Project
120team's policy to not back-port minor features to the released Yocto 120team's policy to not back-port minor features to the released Yocto
121Linux kernel. They only consider back-porting significant technological 121Linux kernel. They only consider back-porting significant technological
122jumps DASH and, that is done after a complete gap analysis. The reason 122jumps - and, that is done after a complete gap analysis. The reason
123for this policy is that back-porting any small to medium sized change 123for this policy is that back-porting any small to medium sized change
124from an evolving Linux kernel can easily create mismatches, 124from an evolving Linux kernel can easily create mismatches,
125incompatibilities and very subtle errors. 125incompatibilities and very subtle errors.
@@ -129,7 +129,7 @@ cutting edge Yocto Linux kernel that mixes forward ports of existing
129Linux kernel features and significant and critical new functionality. 129Linux kernel features and significant and critical new functionality.
130Forward porting Linux kernel functionality into the Yocto Linux kernels 130Forward porting Linux kernel functionality into the Yocto Linux kernels
131available through the Yocto Project can be thought of as a "micro 131available through the Yocto Project can be thought of as a "micro
132uprev." The many "micro uprevs" produce a Yocto Linux kernel version 132uprev". The many "micro uprevs" produce a Yocto Linux kernel version
133with a mix of important new mainline, non-mainline, BSP developments and 133with a mix of important new mainline, non-mainline, BSP developments and
134feature integrations. This Yocto Linux kernel gives insight into new 134feature integrations. This Yocto Linux kernel gives insight into new
135features and allows focused amounts of testing to be done on the kernel, 135features and allows focused amounts of testing to be done on the kernel,
@@ -160,9 +160,8 @@ implemented by the Yocto Project team using the Source Code Manager
160 but, Git continues to grow in popularity and supports many 160 but, Git continues to grow in popularity and supports many
161 different work flows, front-ends and management techniques. 161 different work flows, front-ends and management techniques.
162 162
163 - You can find documentation on Git at 163 - You can find documentation on Git at https://git-scm.com/doc. You can
164 http://git-scm.com/documentation. You can also get an 164 also get an introduction to Git as it applies to the Yocto Project in the
165 introduction to Git as it applies to the Yocto Project in the
166 ":ref:`overview-manual/overview-manual-development-environment:git`" section in the Yocto Project 165 ":ref:`overview-manual/overview-manual-development-environment:git`" section in the Yocto Project
167 Overview and Concepts Manual. The latter reference provides an 166 Overview and Concepts Manual. The latter reference provides an
168 overview of Git and presents a minimal set of Git commands that 167 overview of Git and presents a minimal set of Git commands that
@@ -260,8 +259,8 @@ Yocto Linux kernel needed for any given set of requirements.
260 Keep in mind the figure does not take into account all the supported 259 Keep in mind the figure does not take into account all the supported
261 Yocto Linux kernels, but rather shows a single generic kernel just 260 Yocto Linux kernels, but rather shows a single generic kernel just
262 for conceptual purposes. Also keep in mind that this structure 261 for conceptual purposes. Also keep in mind that this structure
263 represents the Yocto Project 262 represents the
264 Source Repositories 263 :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`
265 that are either pulled from during the build or established on the 264 that are either pulled from during the build or established on the
266 host development system prior to the build by either cloning a 265 host development system prior to the build by either cloning a
267 particular kernel's Git repository or by downloading and unpacking a 266 particular kernel's Git repository or by downloading and unpacking a
diff --git a/documentation/kernel-dev/kernel-dev-faq.rst b/documentation/kernel-dev/kernel-dev-faq.rst
index 70bf4a2d4b..c9f2102c7d 100644
--- a/documentation/kernel-dev/kernel-dev-faq.rst
+++ b/documentation/kernel-dev/kernel-dev-faq.rst
@@ -50,13 +50,13 @@ How do I install a specific kernel module?
50 50
51Linux kernel modules are packaged individually. To ensure a 51Linux kernel modules are packaged individually. To ensure a
52specific kernel module is included in an image, include it in the 52specific kernel module is included in an image, include it in the
53appropriate machine 53appropriate machine :term:`RRECOMMENDS` variable.
54:term:`RRECOMMENDS` variable.
55These other variables are useful for installing specific modules: 54These other variables are useful for installing specific modules:
56:term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` 55- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
57:term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` 56- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
58:term:`MACHINE_EXTRA_RDEPENDS` 57- :term:`MACHINE_EXTRA_RDEPENDS`
59:term:`MACHINE_EXTRA_RRECOMMENDS` 58- :term:`MACHINE_EXTRA_RRECOMMENDS`
59
60For example, set the following in the ``qemux86.conf`` file to include 60For example, set the following in the ``qemux86.conf`` file to include
61the ``ab123`` kernel modules with images built for the ``qemux86`` 61the ``ab123`` kernel modules with images built for the ``qemux86``
62machine: 62machine:
@@ -64,9 +64,8 @@ machine:
64 64
65 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" 65 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123"
66 66
67For more 67For more information, see the
68information, see the "`Incorporating Out-of-Tree 68":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`" section.
69Modules <#incorporating-out-of-tree-modules>`__" section.
70 69
71How do I change the Linux kernel command line? 70How do I change the Linux kernel command line?
72---------------------------------------------- 71----------------------------------------------
diff --git a/documentation/kernel-dev/kernel-dev-intro.rst b/documentation/kernel-dev/kernel-dev-intro.rst
index 447cddba20..5679a0ab80 100644
--- a/documentation/kernel-dev/kernel-dev-intro.rst
+++ b/documentation/kernel-dev/kernel-dev-intro.rst
@@ -23,7 +23,7 @@ Each Yocto Project release has a set of Yocto Linux kernel recipes,
23whose Git repositories you can view in the Yocto 23whose Git repositories you can view in the Yocto
24:yocto_git:`Source Repositories <>` under the "Yocto Linux Kernel" 24:yocto_git:`Source Repositories <>` under the "Yocto Linux Kernel"
25heading. New recipes for the release track the latest Linux kernel 25heading. New recipes for the release track the latest Linux kernel
26upstream developments from http://www.kernel.org> and introduce 26upstream developments from https://www.kernel.org and introduce
27newly-supported platforms. Previous recipes in the release are refreshed 27newly-supported platforms. Previous recipes in the release are refreshed
28and supported for at least one additional Yocto Project release. As they 28and supported for at least one additional Yocto Project release. As they
29align, these previous releases are updated to include the latest from 29align, these previous releases are updated to include the latest from
@@ -37,8 +37,8 @@ upstream Yocto Linux kernel development and kernel Metadata development.
37 37
38.. note:: 38.. note::
39 39
40 For more on Yocto Linux kernels, see the " 40 For more on Yocto Linux kernels, see the
41 Yocto Project Kernel Development and Maintenance 41 ":ref:`Yocto Project Kernel Development and Maintenance <kernel-big-picture>`"
42 section. 42 section.
43 43
44The Yocto Project also provides a powerful set of kernel tools for 44The Yocto Project also provides a powerful set of kernel tools for
@@ -75,7 +75,7 @@ tools with your own kernel sources.
75The remainder of this manual provides instructions for completing 75The remainder of this manual provides instructions for completing
76specific Linux kernel development tasks. These instructions assume you 76specific Linux kernel development tasks. These instructions assume you
77are comfortable working with 77are comfortable working with
78`BitBake <http://openembedded.org/wiki/Bitbake>`__ recipes and basic 78`BitBake <https://openembedded.org/wiki/Bitbake>`__ recipes and basic
79open-source development tools. Understanding these concepts will 79open-source development tools. Understanding these concepts will
80facilitate the process of working with the kernel recipes. If you find 80facilitate the process of working with the kernel recipes. If you find
81you need some additional background, please be sure to review and 81you need some additional background, please be sure to review and
@@ -158,8 +158,7 @@ general information and references for further information.
158 158
159 .. note:: 159 .. note::
160 160
161 Try to resist the temptation to directly edit an existing 161 Try to resist the temptation to directly edit an existing ``.config``
162 .config
163 file, which is found in the Build Directory among the source code 162 file, which is found in the Build Directory among the source code
164 used for the build. Doing so, can produce unexpected results when 163 used for the build. Doing so, can produce unexpected results when
165 the OpenEmbedded build system regenerates the configuration file. 164 the OpenEmbedded build system regenerates the configuration file.
@@ -167,9 +166,9 @@ general information and references for further information.
167 Once you are satisfied with the configuration changes made using 166 Once you are satisfied with the configuration changes made using
168 ``menuconfig`` and you have saved them, you can directly compare the 167 ``menuconfig`` and you have saved them, you can directly compare the
169 resulting ``.config`` file against an existing original and gather 168 resulting ``.config`` file against an existing original and gather
170 those changes into a `configuration fragment 169 those changes into a
171 file <#creating-config-fragments>`__ to be referenced from within the 170 :ref:`configuration fragment file <creating-config-fragments>` to be
172 kernel's ``.bbappend`` file. 171 referenced from within the kernel's ``.bbappend`` file.
173 172
174 Additionally, if you are working in a BSP layer and need to modify 173 Additionally, if you are working in a BSP layer and need to modify
175 the BSP's kernel's configuration, you can use ``menuconfig``. 174 the BSP's kernel's configuration, you can use ``menuconfig``.
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.rst b/documentation/kernel-dev/kernel-dev-maint-appx.rst
index 17883327d5..69f680688f 100644
--- a/documentation/kernel-dev/kernel-dev-maint-appx.rst
+++ b/documentation/kernel-dev/kernel-dev-maint-appx.rst
@@ -42,7 +42,11 @@ section.
42 42
43Once you have cloned the kernel Git repository and the cache of Metadata 43Once you have cloned the kernel Git repository and the cache of Metadata
44on your local machine, you can discover the branches that are available 44on your local machine, you can discover the branches that are available
45in the repository using the following Git command: $ git branch -a 45in the repository using the following Git command:
46::
47
48 $ git branch -a
49
46Checking out a branch allows you to work with a particular Yocto Linux 50Checking out a branch allows you to work with a particular Yocto Linux
47kernel. For example, the following commands check out the 51kernel. For example, the following commands check out the
48"standard/beagleboard" branch of the Yocto Linux kernel repository and 52"standard/beagleboard" branch of the Yocto Linux kernel repository and
@@ -56,10 +60,8 @@ the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository:
56 60
57.. note:: 61.. note::
58 62
59 Branches in the 63 Branches in the ``yocto-kernel-cache`` repository correspond to Yocto Linux
60 yocto-kernel-cache 64 kernel versions (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth).
61 repository correspond to Yocto Linux kernel versions (e.g.
62 "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth).
63 65
64Once you have checked out and switched to appropriate branches, you can 66Once you have checked out and switched to appropriate branches, you can
65see a snapshot of all the kernel source files used to used to build that 67see a snapshot of all the kernel source files used to used to build that
@@ -105,7 +107,7 @@ patch, or BSP:
105 repository organized under the "Yocto Linux Kernel" heading in the 107 repository organized under the "Yocto Linux Kernel" heading in the
106 :yocto_git:`Yocto Project Source Repositories <>`. 108 :yocto_git:`Yocto Project Source Repositories <>`.
107 109
108 - Areas pointed to by ``SRC_URI`` statements found in kernel recipes 110 - Areas pointed to by ``SRC_URI`` statements found in kernel recipes.
109 111
110 For a typical build, the target of the search is a feature 112 For a typical build, the target of the search is a feature
111 description in an ``.scc`` file whose name follows this format (e.g. 113 description in an ``.scc`` file whose name follows this format (e.g.
@@ -194,12 +196,10 @@ the build process before compilation starts:
194 .. note:: 196 .. note::
195 197
196 In the previous example, the "yocto-4.12" branch is checked out in 198 In the previous example, the "yocto-4.12" branch is checked out in
197 the 199 the ``yocto-kernel-cache`` repository.
198 yocto-kernel-cache
199 repository.
200 200
201The OpenEmbedded build system makes sure these conditions exist before 201The OpenEmbedded build system makes sure these conditions exist before
202attempting compilation. Other means, however, do exist, such as as 202attempting compilation. Other means, however, do exist, such as
203bootstrapping a BSP. 203bootstrapping a BSP.
204 204
205Before building a kernel, the build process verifies the tree and 205Before building a kernel, the build process verifies the tree and