blob: 58adcc9b70579ace1bdc37d5978d7bcabb231998 [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
Andrew Geissler09209ee2020-12-13 08:44:15 -060024set up, see the ":doc:`/dev-manual/start`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -050025the 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060028":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050029section 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060037 ":ref:`dev-manual/start:checking out by branch in poky`" and
38 ":ref:`dev-manual/start:checking out by tag in poky`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -050039 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060042:ref:`devtool <sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050043and 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060052":ref:`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 Geissler09209ee2020-12-13 08:44:15 -060066 :ref:`overview-manual/development-environment:yocto project source repositories`
Andrew Geissler4c19ea12020-10-27 13:52:24 -050067 (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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600107 ":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500108 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600113 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500114 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
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600142 ``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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600150 $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh
151 Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500152 ============================================================================
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 Geissler09209ee2020-12-13 08:44:15 -0600210 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600215":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500216section.
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600229source as described in the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500230section:
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600239 ":ref:`dev-manual/start:checking out by branch in poky`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500240 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 Geissler09209ee2020-12-13 08:44:15 -0600252 :ref:`overview-manual/development-environment:yocto project source repositories`
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500253 (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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600292 ":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500293 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600298 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500299 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600381":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500382section 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600389 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500390 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600446 ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500447 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 Geissler09209ee2020-12-13 08:44:15 -0600460- :ref:`kernel-dev/common:creating the append file`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500461
Andrew Geissler09209ee2020-12-13 08:44:15 -0600462- :ref:`kernel-dev/common:applying patches`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500463
Andrew Geissler09209ee2020-12-13 08:44:15 -0600464- :ref:`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 Geissler09209ee2020-12-13 08:44:15 -0600505 sure to refer to the :doc:`/bsp-guide/index`.
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600645":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500646and
Andrew Geissler09209ee2020-12-13 08:44:15 -0600647":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500648sections.
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600772 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500773 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600785the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500786
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600794 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500795 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 Geissler09209ee2020-12-13 08:44:15 -0600865 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600915 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500916 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600938":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500939section).
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600945 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500946 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
Andrew Geissler09209ee2020-12-13 08:44:15 -06001111 ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001112 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
Andrew Geissler09209ee2020-12-13 08:44:15 -06001193 ":ref:`kernel-dev/common:changing the configuration`",
1194 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`",
1195 and ":ref:`kernel-dev/common:creating a \`\`defconfig\`\` file`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001196 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
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001304Creating Configuration Fragments
1305--------------------------------
1306
1307Configuration fragments are simply kernel options that appear in a file
1308placed where the OpenEmbedded build system can find and apply them. The
1309build system applies configuration fragments after applying
1310configurations from a ``defconfig`` file. Thus, the final kernel
1311configuration is a combination of the configurations in the
1312``defconfig`` file and then any configuration fragments you provide. The
1313build system applies fragments on top of and after applying the existing
1314defconfig file configurations.
1315
1316Syntactically, the configuration statement is identical to what would
1317appear in the ``.config`` file, which is in the :term:`Build Directory`.
1318
1319.. note::
1320
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001321 For more information about where the ``.config`` file is located, see the
1322 example in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001323 ":ref:`kernel-dev/common:using \`\`menuconfig\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001324 section.
1325
1326It is simple to create a configuration fragment. One method is to use
1327shell commands. For example, issuing the following from the shell
1328creates a configuration fragment file named ``my_smp.cfg`` that enables
1329multi-processor support within the kernel:
1330::
1331
1332 $ echo "CONFIG_SMP=y" >> my_smp.cfg
1333
1334.. note::
1335
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001336 All configuration fragment files must use the ``.cfg`` extension in order
1337 for the OpenEmbedded build system to recognize them as a configuration
1338 fragment.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001339
1340Another method is to create a configuration fragment using the
1341differences between two configuration files: one previously created and
1342saved, and one freshly created using the ``menuconfig`` tool.
1343
1344To create a configuration fragment using this method, follow these
1345steps:
1346
13471. *Complete a Build Through Kernel Configuration:* Complete a build at
1348 least through the kernel configuration task as follows:
1349 ::
1350
1351 $ bitbake linux-yocto -c kernel_configme -f
1352
1353 This step ensures that you create a
1354 ``.config`` file from a known state. Because situations exist where
1355 your build state might become unknown, it is best to run this task
1356 prior to starting ``menuconfig``.
1357
13582. *Launch menuconfig:* Run the ``menuconfig`` command:
1359 ::
1360
1361 $ bitbake linux-yocto -c menuconfig
1362
13633. *Create the Configuration Fragment:* Run the ``diffconfig`` command
1364 to prepare a configuration fragment. The resulting file
1365 ``fragment.cfg`` is placed in the
1366 ``${``\ :term:`WORKDIR`\ ``}``
1367 directory:
1368 ::
1369
1370 $ bitbake linux-yocto -c diffconfig
1371
1372The ``diffconfig`` command creates a file that is a list of Linux kernel
1373``CONFIG_`` assignments. See the "`Changing the
1374Configuration <#changing-the-configuration>`__" section for additional
1375information on how to use the output as a configuration fragment.
1376
1377.. note::
1378
1379 You can also use this method to create configuration fragments for a
Andrew Geissler09209ee2020-12-13 08:44:15 -06001380 BSP. See the ":ref:`kernel-dev/advanced:bsp descriptions`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001381 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001382
1383Where do you put your configuration fragment files? You can place these
1384files in an area pointed to by
1385:term:`SRC_URI` as directed by your
1386``bblayers.conf`` file, which is located in your layer. The OpenEmbedded
1387build system picks up the configuration and adds it to the kernel's
1388configuration. For example, suppose you had a set of configuration
1389options in a file called ``myconfig.cfg``. If you put that file inside a
1390directory named ``linux-yocto`` that resides in the same directory as
1391the kernel's append file within your layer and then add the following
1392statements to the kernel's append file, those configuration options will
1393be picked up and applied when the kernel is built:
1394::
1395
1396 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1397 SRC_URI += "file://myconfig.cfg"
1398
1399As mentioned earlier, you can group related configurations into multiple
1400files and name them all in the ``SRC_URI`` statement as well. For
1401example, you could group separate configurations specifically for
1402Ethernet and graphics into their own files and add those by using a
1403``SRC_URI`` statement like the following in your append file:
1404::
1405
1406 SRC_URI += "file://myconfig.cfg \
1407 file://eth.cfg \
1408 file://gfx.cfg"
1409
1410Validating Configuration
1411------------------------
1412
1413You can use the
1414:ref:`ref-tasks-kernel_configcheck`
1415task to provide configuration validation:
1416::
1417
1418 $ bitbake linux-yocto -c kernel_configcheck -f
1419
1420Running this task produces warnings for when a
1421requested configuration does not appear in the final ``.config`` file or
1422when you override a policy configuration in a hardware configuration
1423fragment.
1424
1425In order to run this task, you must have an existing ``.config`` file.
Andrew Geissler09209ee2020-12-13 08:44:15 -06001426See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001427information on how to create a configuration file.
1428
1429Following is sample output from the ``do_kernel_configcheck`` task:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001430
1431.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001432
1433 Loading cache: 100% |########################################################| Time: 0:00:00
1434 Loaded 1275 entries from dependency cache.
1435 NOTE: Resolving any missing task queue dependencies
1436
1437 Build Configuration:
1438 .
1439 .
1440 .
1441
1442 NOTE: Executing SetScene Tasks
1443 NOTE: Executing RunQueue Tasks
1444 WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck:
1445 [kernel config]: specified values did not make it into the kernel's final configuration:
1446
1447 ---------- CONFIG_X86_TSC -----------------
1448 Config: CONFIG_X86_TSC
1449 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
1450 Requested value: CONFIG_X86_TSC=y
1451 Actual value:
1452
1453
1454 ---------- CONFIG_X86_BIGSMP -----------------
1455 Config: CONFIG_X86_BIGSMP
1456 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1457 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1458 Requested value: # CONFIG_X86_BIGSMP is not set
1459 Actual value:
1460
1461
1462 ---------- CONFIG_NR_CPUS -----------------
1463 Config: CONFIG_NR_CPUS
1464 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1465 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
1466 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1467 Requested value: CONFIG_NR_CPUS=8
1468 Actual value: CONFIG_NR_CPUS=1
1469
1470
1471 ---------- CONFIG_SCHED_SMT -----------------
1472 Config: CONFIG_SCHED_SMT
1473 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1474 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1475 Requested value: CONFIG_SCHED_SMT=y
1476 Actual value:
1477
1478
1479
1480 NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded.
1481
1482 Summary: There were 3 WARNING messages shown.
1483
1484.. note::
1485
1486 The previous output example has artificial line breaks to make it
1487 more readable.
1488
1489The output describes the various problems that you can encounter along
1490with where to find the offending configuration items. You can use the
1491information in the logs to adjust your configuration files and then
1492repeat the
1493:ref:`ref-tasks-kernel_configme`
1494and
1495:ref:`ref-tasks-kernel_configcheck`
1496tasks until they produce no warnings.
1497
1498For more information on how to use the ``menuconfig`` tool, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001499:ref:`kernel-dev/common:using \`\`menuconfig\`\`` section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001500
1501Fine-Tuning the Kernel Configuration File
1502-----------------------------------------
1503
1504You can make sure the ``.config`` file is as lean or efficient as
1505possible by reading the output of the kernel configuration fragment
1506audit, noting any issues, making changes to correct the issues, and then
1507repeating.
1508
1509As part of the kernel build process, the ``do_kernel_configcheck`` task
1510runs. This task validates the kernel configuration by checking the final
1511``.config`` file against the input files. During the check, the task
1512produces warning messages for the following issues:
1513
1514- Requested options that did not make the final ``.config`` file.
1515
1516- Configuration items that appear twice in the same configuration
1517 fragment.
1518
1519- Configuration items tagged as "required" that were overridden.
1520
1521- A board overrides a non-board specific option.
1522
1523- Listed options not valid for the kernel being processed. In other
1524 words, the option does not appear anywhere.
1525
1526.. note::
1527
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001528 The :ref:`ref-tasks-kernel_configcheck` task can also optionally report if
1529 an option is overridden during processing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001530
1531For each output warning, a message points to the file that contains a
1532list of the options and a pointer to the configuration fragment that
1533defines them. Collectively, the files are the key to streamlining the
1534configuration.
1535
1536To streamline the configuration, do the following:
1537
15381. *Use a Working Configuration:* Start with a full configuration that
1539 you know works. Be sure the configuration builds and boots
1540 successfully. Use this configuration file as your baseline.
1541
15422. *Run Configure and Check Tasks:* Separately run the
1543 ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks:
1544 ::
1545
1546 $ bitbake linux-yocto -c kernel_configme -f
1547 $ bitbake linux-yocto -c kernel_configcheck -f
1548
15493. *Process the Results:* Take the resulting list of files from the
1550 ``do_kernel_configcheck`` task warnings and do the following:
1551
1552 - Drop values that are redefined in the fragment but do not change
1553 the final ``.config`` file.
1554
1555 - Analyze and potentially drop values from the ``.config`` file that
1556 override required configurations.
1557
1558 - Analyze and potentially remove non-board specific options.
1559
1560 - Remove repeated and invalid options.
1561
15624. *Re-Run Configure and Check Tasks:* After you have worked through the
1563 output of the kernel configuration audit, you can re-run the
1564 ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks to see the
1565 results of your changes. If you have more issues, you can deal with
1566 them as described in the previous step.
1567
1568Iteratively working through steps two through four eventually yields a
1569minimal, streamlined configuration file. Once you have the best
1570``.config``, you can build the Linux Yocto kernel.
1571
1572Expanding Variables
1573===================
1574
1575Sometimes it is helpful to determine what a variable expands to during a
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001576build. You can examine the values of variables by examining the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001577output of the ``bitbake -e`` command. The output is long and is more
1578easily managed in a text file, which allows for easy searches:
1579::
1580
1581 $ bitbake -e virtual/kernel > some_text_file
1582
1583Within the text file, you can see
1584exactly how each variable is expanded and used by the OpenEmbedded build
1585system.
1586
1587Working with a "Dirty" Kernel Version String
1588============================================
1589
1590If you build a kernel image and the version string has a "+" or a
1591"-dirty" at the end, uncommitted modifications exist in the kernel's
1592source directory. Follow these steps to clean up the version string:
1593
15941. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned
1595 Git repository (source directory) and use the following Git command
1596 to list the files that have been changed, added, or removed:
1597 ::
1598
1599 $ git status
1600
16012. *Commit the Changes:* You should commit those changes to the kernel
1602 source tree regardless of whether or not you will save, export, or
1603 use the changes:
1604 ::
1605
1606 $ git add
1607 $ git commit -s -a -m "getting rid of -dirty"
1608
16093. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the
1610 kernel.
1611
1612 Depending on your particular kernel development workflow, the
1613 commands you use to rebuild the kernel might differ. For information
1614 on building the kernel image when using ``devtool``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001615 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001616 section. For
1617 information on building the kernel image when using Bitbake, see the
1618 "`Using Traditional Kernel Development to Patch the
1619 Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__"
1620 section.
1621
1622Working With Your Own Sources
1623=============================
1624
1625If you cannot work with one of the Linux kernel versions supported by
1626existing linux-yocto recipes, you can still make use of the Yocto
1627Project Linux kernel tooling by working with your own sources. When you
1628use your own sources, you will not be able to leverage the existing
1629kernel :term:`Metadata` and stabilization
1630work of the linux-yocto sources. However, you will be able to manage
1631your own Metadata in the same format as the linux-yocto sources.
1632Maintaining format compatibility facilitates converging with linux-yocto
1633on a future, mutually-supported kernel version.
1634
1635To help you use your own sources, the Yocto Project provides a
1636linux-yocto custom recipe (``linux-yocto-custom.bb``) that uses
1637``kernel.org`` sources and the Yocto Project Linux kernel tools for
1638managing kernel Metadata. You can find this recipe in the ``poky`` Git
1639repository of the Yocto Project :yocto_git:`Source Repository <>`
1640at:
1641::
1642
1643 poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
1644
1645Here are some basic steps you can use to work with your own sources:
1646
16471. *Create a Copy of the Kernel Recipe:* Copy the
1648 ``linux-yocto-custom.bb`` recipe to your layer and give it a
1649 meaningful name. The name should include the version of the Yocto
1650 Linux kernel you are using (e.g. ``linux-yocto-myproject_4.12.bb``,
1651 where "4.12" is the base version of the Linux kernel with which you
1652 would be working).
1653
16542. *Create a Directory for Your Patches:* In the same directory inside
1655 your layer, create a matching directory to store your patches and
1656 configuration files (e.g. ``linux-yocto-myproject``).
1657
16583. *Ensure You Have Configurations:* Make sure you have either a
1659 ``defconfig`` file or configuration fragment files in your layer.
1660 When you use the ``linux-yocto-custom.bb`` recipe, you must specify a
1661 configuration. If you do not have a ``defconfig`` file, you can run
1662 the following:
1663 ::
1664
1665 $ make defconfig
1666
1667 After running the command, copy the
1668 resulting ``.config`` file to the ``files`` directory in your layer
1669 as "defconfig" and then add it to the
1670 :term:`SRC_URI` variable in the
1671 recipe.
1672
1673 Running the ``make defconfig`` command results in the default
1674 configuration for your architecture as defined by your kernel.
1675 However, no guarantee exists that this configuration is valid for
1676 your use case, or that your board will even boot. This is
1677 particularly true for non-x86 architectures.
1678
1679 To use non-x86 ``defconfig`` files, you need to be more specific and
1680 find one that matches your board (i.e. for arm, you look in
1681 ``arch/arm/configs`` and use the one that is the best starting point
1682 for your board).
1683
16844. *Edit the Recipe:* Edit the following variables in your recipe as
1685 appropriate for your project:
1686
1687 - :term:`SRC_URI`: The
1688 ``SRC_URI`` should specify a Git repository that uses one of the
1689 supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``,
1690 and so forth). The ``SRC_URI`` variable should also specify either
1691 a ``defconfig`` file or some configuration fragment files. The
1692 skeleton recipe provides an example ``SRC_URI`` as a syntax
1693 reference.
1694
1695 - :term:`LINUX_VERSION`:
1696 The Linux kernel version you are using (e.g. "4.12").
1697
1698 - :term:`LINUX_VERSION_EXTENSION`:
1699 The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the
1700 resulting kernel and visible through the ``uname`` command.
1701
1702 - :term:`SRCREV`: The commit ID
1703 from which you want to build.
1704
1705 - :term:`PR`: Treat this variable the
1706 same as you would in any other recipe. Increment the variable to
1707 indicate to the OpenEmbedded build system that the recipe has
1708 changed.
1709
1710 - :term:`PV`: The default ``PV``
1711 assignment is typically adequate. It combines the
1712 ``LINUX_VERSION`` with the Source Control Manager (SCM) revision
1713 as derived from the :term:`SRCPV`
1714 variable. The combined results are a string with the following
1715 form:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001716 ::
1717
1718 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
1719
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001720 While lengthy, the extra verbosity in ``PV`` helps ensure you are
1721 using the exact sources from which you intend to build.
1722
1723 - :term:`COMPATIBLE_MACHINE`:
1724 A list of the machines supported by your new recipe. This variable
1725 in the example recipe is set by default to a regular expression
1726 that matches only the empty string, "(^$)". This default setting
1727 triggers an explicit build failure. You must change it to match a
1728 list of the machines that your new recipe supports. For example,
1729 to support the ``qemux86`` and ``qemux86-64`` machines, use the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001730 following form:
1731 ::
1732
1733 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001734
17355. *Customize Your Recipe as Needed:* Provide further customizations to
1736 your recipe as needed just as you would customize an existing
1737 linux-yocto recipe. See the "`Modifying an Existing
1738 Recipe <#modifying-an-existing-recipe>`__" section for information.
1739
1740Working with Out-of-Tree Modules
1741================================
1742
1743This section describes steps to build out-of-tree modules on your target
1744and describes how to incorporate out-of-tree modules in the build.
1745
1746Building Out-of-Tree Modules on the Target
1747------------------------------------------
1748
1749While the traditional Yocto Project development model would be to
1750include kernel modules as part of the normal build process, you might
1751find it useful to build modules on the target. This could be the case if
1752your target system is capable and powerful enough to handle the
1753necessary compilation. Before deciding to build on your target, however,
1754you should consider the benefits of using a proper cross-development
1755environment from your build host.
1756
1757If you want to be able to build out-of-tree modules on the target, there
1758are some steps you need to take on the target that is running your SDK
1759image. Briefly, the ``kernel-dev`` package is installed by default on
1760all ``*.sdk`` images and the ``kernel-devsrc`` package is installed on
1761many of the ``*.sdk`` images. However, you need to create some scripts
1762prior to attempting to build the out-of-tree modules on the target that
1763is running that image.
1764
1765Prior to attempting to build the out-of-tree modules, you need to be on
1766the target as root and you need to change to the ``/usr/src/kernel``
1767directory. Next, ``make`` the scripts:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001768
1769.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001770
1771 # cd /usr/src/kernel
1772 # make scripts
1773
1774Because all SDK image recipes include ``dev-pkgs``, the
1775``kernel-dev`` packages will be installed as part of the SDK image and
1776the ``kernel-devsrc`` packages will be installed as part of applicable
1777SDK images. The SDK uses the scripts when building out-of-tree modules.
1778Once you have switched to that directory and created the scripts, you
1779should be able to build your out-of-tree modules on the target.
1780
1781Incorporating Out-of-Tree Modules
1782---------------------------------
1783
1784While it is always preferable to work with sources integrated into the
1785Linux kernel sources, if you need an external kernel module, the
1786``hello-mod.bb`` recipe is available as a template from which you can
1787create your own out-of-tree Linux kernel module recipe.
1788
1789This template recipe is located in the ``poky`` Git repository of the
1790Yocto Project :yocto_git:`Source Repository <>` at:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001791
1792.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001793
1794 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
1795
1796To get started, copy this recipe to your layer and give it a meaningful
1797name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new
1798directory named ``files`` where you can store any source files, patches,
1799or other files necessary for building the module that do not come with
1800the sources. Finally, update the recipe as needed for the module.
1801Typically, you will need to set the following variables:
1802
1803- :term:`DESCRIPTION`
1804
1805- :term:`LICENSE* <LICENSE>`
1806
1807- :term:`SRC_URI`
1808
1809- :term:`PV`
1810
1811Depending on the build system used by the module sources, you might need
1812to make some adjustments. For example, a typical module ``Makefile``
1813looks much like the one provided with the ``hello-mod`` template:
1814::
1815
1816 obj-m := hello.o
1817
1818 SRC := $(shell pwd)
1819
1820 all:
1821 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
1822
1823 modules_install:
1824 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
1825 ...
1826
1827The important point to note here is the :term:`KERNEL_SRC` variable. The
1828:ref:`module <ref-classes-module>` class sets this variable and the
1829:term:`KERNEL_PATH` variable to
1830``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build
1831information to build modules. If your module ``Makefile`` uses a
1832different variable, you might want to override the
1833:ref:`ref-tasks-compile` step, or
1834create a patch to the ``Makefile`` to work with the more typical
1835``KERNEL_SRC`` or ``KERNEL_PATH`` variables.
1836
1837After you have prepared your recipe, you will likely want to include the
1838module in your images. To do this, see the documentation for the
1839following variables in the Yocto Project Reference Manual and set one of
1840them appropriately for your machine configuration file:
1841
1842- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
1843
1844- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
1845
1846- :term:`MACHINE_EXTRA_RDEPENDS`
1847
1848- :term:`MACHINE_EXTRA_RRECOMMENDS`
1849
1850Modules are often not required for boot and can be excluded from certain
1851build configurations. The following allows for the most flexibility:
1852::
1853
1854 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
1855
1856The value is
1857derived by appending the module filename without the ``.ko`` extension
1858to the string "kernel-module-".
1859
1860Because the variable is
1861:term:`RRECOMMENDS` and not a
1862:term:`RDEPENDS` variable, the build
1863will not fail if this module is not available to include in the image.
1864
1865Inspecting Changes and Commits
1866==============================
1867
1868A common question when working with a kernel is: "What changes have been
1869applied to this tree?" Rather than using "grep" across directories to
1870see what has changed, you can use Git to inspect or search the kernel
1871tree. Using Git is an efficient way to see what has changed in the tree.
1872
1873What Changed in a Kernel?
1874-------------------------
1875
1876Following are a few examples that show how to use Git commands to
1877examine changes. These examples are by no means the only way to see
1878changes.
1879
1880.. note::
1881
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001882 In the following examples, unless you provide a commit range, ``kernel.org``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001883 history is blended with Yocto Project kernel changes. You can form
1884 ranges by using branch names from the kernel tree as the upper and
1885 lower commit markers with the Git commands. You can see the branch
1886 names through the web interface to the Yocto Project source
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001887 repositories at :yocto_git:`/`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001888
1889To see a full range of the changes, use the ``git whatchanged`` command
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001890and specify a commit range for the branch (`commit`\ ``..``\ `commit`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001891
1892Here is an example that looks at what has changed in the ``emenlow``
1893branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the
1894commit associated with the ``standard/base`` branch, while the upper
1895commit range is the commit associated with the ``standard/emenlow``
1896branch.
1897::
1898
1899 $ git whatchanged origin/standard/base..origin/standard/emenlow
1900
1901To see short, one line summaries of changes use the ``git log`` command:
1902::
1903
1904 $ git log --oneline origin/standard/base..origin/standard/emenlow
1905
1906Use this command to see code differences for the changes:
1907::
1908
1909 $ git diff origin/standard/base..origin/standard/emenlow
1910
1911Use this command to see the commit log messages and the text
1912differences:
1913::
1914
1915 $ git show origin/standard/base..origin/standard/emenlow
1916
1917Use this command to create individual patches for each change. Here is
1918an example that that creates patch files for each commit and places them
1919in your ``Documents`` directory:
1920::
1921
1922 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
1923
1924Showing a Particular Feature or Branch Change
1925---------------------------------------------
1926
1927Tags in the Yocto Project kernel tree divide changes for significant
1928features or branches. The ``git show`` tag command shows changes based
1929on a tag. Here is an example that shows ``systemtap`` changes:
1930::
1931
1932 $ git show systemtap
1933
1934You can use the ``git branch --contains`` tag command to
1935show the branches that contain a particular feature. This command shows
1936the branches that contain the ``systemtap`` feature:
1937::
1938
1939 $ git branch --contains systemtap
1940
1941Adding Recipe-Space Kernel Features
1942===================================
1943
1944You can add kernel features in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001945:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001946by using the :term:`KERNEL_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001947variable and by specifying the feature's ``.scc`` file path in the
1948:term:`SRC_URI` statement. When you
1949add features using this method, the OpenEmbedded build system checks to
1950be sure the features are present. If the features are not present, the
1951build stops. Kernel features are the last elements processed for
1952configuring and patching the kernel. Therefore, adding features in this
1953manner is a way to enforce specific features are present and enabled
1954without needing to do a full audit of any other layer's additions to the
1955``SRC_URI`` statement.
1956
1957You add a kernel feature by providing the feature as part of the
1958``KERNEL_FEATURES`` variable and by providing the path to the feature's
1959``.scc`` file, which is relative to the root of the kernel Metadata. The
1960OpenEmbedded build system searches all forms of kernel Metadata on the
1961``SRC_URI`` statement regardless of whether the Metadata is in the
1962"kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e.
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001963part of the kernel recipe). See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001964":ref:`kernel-dev/advanced:kernel metadata location`" section for
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001965additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001966
1967When you specify the feature's ``.scc`` file on the ``SRC_URI``
1968statement, the OpenEmbedded build system adds the directory of that
1969``.scc`` file along with all its subdirectories to the kernel feature
1970search path. Because subdirectories are searched, you can reference a
1971single ``.scc`` file in the ``SRC_URI`` statement to reference multiple
1972kernel features.
1973
1974Consider the following example that adds the "test.scc" feature to the
1975build.
1976
19771. *Create the Feature File:* Create a ``.scc`` file and locate it just
1978 as you would any other patch file, ``.cfg`` file, or fetcher item you
1979 specify in the ``SRC_URI`` statement.
1980
1981 .. note::
1982
1983 - You must add the directory of the ``.scc`` file to the
1984 fetcher's search path in the same manner as you would add a
1985 ``.patch`` file.
1986
1987 - You can create additional ``.scc`` files beneath the directory
1988 that contains the file you are adding. All subdirectories are
1989 searched during the build as potential feature directories.
1990
1991 Continuing with the example, suppose the "test.scc" feature you are
1992 adding has a ``test.scc`` file in the following directory:
1993 ::
1994
1995 my_recipe
1996 |
1997 +-linux-yocto
1998 |
1999 +-test.cfg
2000 +-test.scc
2001
2002 In this example, the
2003 ``linux-yocto`` directory has both the feature ``test.scc`` file and
2004 a similarly named configuration fragment file ``test.cfg``.
2005
20062. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
2007 recipe's ``SRC_URI`` statement:
2008 ::
2009
2010 SRC_URI_append = " file://test.scc"
2011
2012 The leading space before the path is important as the path is
2013 appended to the existing path.
2014
20153. *Specify the Feature as a Kernel Feature:* Use the
2016 ``KERNEL_FEATURES`` statement to specify the feature as a kernel
2017 feature:
2018 ::
2019
2020 KERNEL_FEATURES_append = " test.scc"
2021
2022 The OpenEmbedded build
2023 system processes the kernel feature when it builds the kernel.
2024
2025 .. note::
2026
2027 If other features are contained below "test.scc", then their
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002028 directories are relative to the directory containing the ``test.scc``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002029 file.