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