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