blob: 16ef6453bd78c86b4e289dda24ecded2b1165232 [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
Patrick Williams92b42cb2022-09-03 06:53:57 -0500551. *Initialize the BitBake Environment:*
56 you need to initialize the BitBake build environment by sourcing
Andrew Geisslerc926e172021-05-07 16:11:35 -050057 the build environment script (i.e. :ref:`structure-core-script`)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050058
Andrew Geissler95ac1b82021-03-31 14:34:31 -050059 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -050060 $ source oe-init-build-env
61
62 .. note::
63
64 The previous commands assume the
Andrew Geissler09209ee2020-12-13 08:44:15 -060065 :ref:`overview-manual/development-environment:yocto project source repositories`
Andrew Geissler4c19ea12020-10-27 13:52:24 -050066 (i.e. ``poky``) have been cloned using Git and the local repository is named
Andrew Geisslerc9f78652020-09-18 14:11:35 -050067 "poky".
68
692. *Prepare Your local.conf File:* By default, the
70 :term:`MACHINE` variable is set to
71 "qemux86-64", which is fine if you are building for the QEMU emulator
72 in 64-bit mode. However, if you are not, you need to set the
Andrew Geissler09036742021-06-25 14:25:14 -050073 :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
Andrew Geisslerc9f78652020-09-18 14:11:35 -050074 found in the
75 :term:`Build Directory` (i.e.
Andrew Geissler95ac1b82021-03-31 14:34:31 -050076 ``poky/build`` in this example).
Andrew Geisslerc9f78652020-09-18 14:11:35 -050077
78 Also, since you are preparing to work on the kernel image, you need
79 to set the
80 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
81 variable to include kernel modules.
82
83 In this example we wish to build for qemux86 so we must set the
Andrew Geissler5f350902021-07-23 13:09:54 -040084 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
Andrew Geisslerc926e172021-05-07 16:11:35 -050085 As described we do this by appending to ``conf/local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050086
87 MACHINE = "qemux86"
88 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
89
903. *Create a Layer for Patches:* You need to create a layer to hold
91 patches created for the kernel image. You can use the
Andrew Geisslerc926e172021-05-07 16:11:35 -050092 ``bitbake-layers create-layer`` command as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050093
Andrew Geissler95ac1b82021-03-31 14:34:31 -050094 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -050095 $ bitbake-layers create-layer ../../meta-mylayer
96 NOTE: Starting bitbake server...
97 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
98 $
99
100 .. note::
101
102 For background information on working with common and BSP layers,
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500103 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600104 ":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500105 section in the Yocto Project Development Tasks Manual and the
106 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board
107 Support (BSP) Developer's Guide, respectively. For information on how to
108 use the ``bitbake-layers create-layer`` command to quickly set up a layer,
109 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600110 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500111 section in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112
1134. *Inform the BitBake Build Environment About Your Layer:* As directed
114 when you created your layer, you need to add the layer to the
115 :term:`BBLAYERS` variable in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500116 ``bblayers.conf`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500118 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500119 $ bitbake-layers add-layer ../../meta-mylayer
120 NOTE: Starting bitbake server...
121 $
122
Patrick Williams92b42cb2022-09-03 06:53:57 -05001235. *Build the Clean Image:* The final step in preparing to work on the
124 kernel is to build an initial image using ``bitbake``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500125
Patrick Williams92b42cb2022-09-03 06:53:57 -0500126 $ bitbake core-image-minimal
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500127 Parsing recipes: 100% |##########################################| Time: 0:00:05
128 Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors.
129 WARNING: No packages to add, building image core-image-minimal unmodified
130 Loading cache: 100% |############################################| Time: 0:00:00
131 Loaded 1299 entries from dependency cache.
132 NOTE: Resolving any missing task queue dependencies
133 Initializing tasks: 100% |#######################################| Time: 0:00:07
134 Checking sstate mirror object availability: 100% |###############| Time: 0:00:00
135 NOTE: Executing SetScene Tasks
136 NOTE: Executing RunQueue Tasks
137 NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500138
139 If you were
140 building for actual hardware and not for emulation, you could flash
141 the image to a USB stick on ``/dev/sdd`` and boot your device. For an
142 example that uses a Minnowboard, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600143 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500144 Wiki page.
145
146At this point you have set up to start making modifications to the
Patrick Williams92b42cb2022-09-03 06:53:57 -0500147kernel. For a continued example, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600148":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500149section.
150
151Getting Ready for Traditional Kernel Development
152------------------------------------------------
153
154Getting ready for traditional kernel development using the Yocto Project
155involves many of the same steps as described in the previous section.
156However, you need to establish a local copy of the kernel source since
157you will be editing these files.
158
159Follow these steps to prepare to update the kernel image using
160traditional kernel development flow with the Yocto Project. Completing
161this procedure leaves you ready to make modifications to the kernel
Andrew Geissler09209ee2020-12-13 08:44:15 -0600162source as described in the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500163section:
164
1651. *Initialize the BitBake Environment:* Before you can do anything
166 using BitBake, you need to initialize the BitBake build environment
167 by sourcing the build environment script (i.e.
168 :ref:`structure-core-script`).
169 Also, for this example, be sure that the local branch you have
170 checked out for ``poky`` is the Yocto Project &DISTRO_NAME; branch. If
171 you need to checkout out the &DISTRO_NAME; branch, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600172 ":ref:`dev-manual/start:checking out by branch in poky`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173 section in the Yocto Project Development Tasks Manual.
174 ::
175
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500176 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500177 $ git branch
178 master
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500179 * &DISTRO_NAME_NO_CAP;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500180 $ source oe-init-build-env
181
182 .. note::
183
184 The previous commands assume the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600185 :ref:`overview-manual/development-environment:yocto project source repositories`
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500186 (i.e. ``poky``) have been cloned using Git and the local repository is named
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500187 "poky".
188
1892. *Prepare Your local.conf File:* By default, the
190 :term:`MACHINE` variable is set to
191 "qemux86-64", which is fine if you are building for the QEMU emulator
192 in 64-bit mode. However, if you are not, you need to set the
Andrew Geissler09036742021-06-25 14:25:14 -0500193 :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500194 found in the
195 :term:`Build Directory` (i.e.
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500196 ``poky/build`` in this example).
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500197
198 Also, since you are preparing to work on the kernel image, you need
199 to set the
200 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
201 variable to include kernel modules.
202
203 In this example we wish to build for qemux86 so we must set the
Andrew Geissler5f350902021-07-23 13:09:54 -0400204 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
Andrew Geisslerc926e172021-05-07 16:11:35 -0500205 As described we do this by appending to ``conf/local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500206
207 MACHINE = "qemux86"
208 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
209
2103. *Create a Layer for Patches:* You need to create a layer to hold
211 patches created for the kernel image. You can use the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500212 ``bitbake-layers create-layer`` command as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500213
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500214 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500215 $ bitbake-layers create-layer ../../meta-mylayer
216 NOTE: Starting bitbake server...
217 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
218
219 .. note::
220
221 For background information on working with common and BSP layers,
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500222 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600223 ":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500224 section in the Yocto Project Development Tasks Manual and the
225 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board
226 Support (BSP) Developer's Guide, respectively. For information on how to
227 use the ``bitbake-layers create-layer`` command to quickly set up a layer,
228 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600229 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500230 section in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500231
2324. *Inform the BitBake Build Environment About Your Layer:* As directed
233 when you created your layer, you need to add the layer to the
234 :term:`BBLAYERS` variable in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500235 ``bblayers.conf`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500236
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500237 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500238 $ bitbake-layers add-layer ../../meta-mylayer
239 NOTE: Starting bitbake server ...
240 $
241
2425. *Create a Local Copy of the Kernel Git Repository:* You can find Git
243 repositories of supported Yocto Project kernels organized under
244 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
245 :yocto_git:`/`.
246
247 For simplicity, it is recommended that you create your copy of the
248 kernel Git repository outside of the
249 :term:`Source Directory`, which is
250 usually named ``poky``. Also, be sure you are in the
251 ``standard/base`` branch.
252
253 The following commands show how to create a local copy of the
254 ``linux-yocto-4.12`` kernel and be in the ``standard/base`` branch.
255
256 .. note::
257
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500258 The ``linux-yocto-4.12`` kernel can be used with the Yocto Project 2.4
259 release and forward.
260 You cannot use the ``linux-yocto-4.12`` kernel with releases prior to
261 Yocto Project 2.4.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500262
263 ::
264
265 $ cd ~
266 $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base
267 Cloning into 'linux-yocto-4.12'...
268 remote: Counting objects: 6097195, done.
269 remote: Compressing objects: 100% (901026/901026), done.
270 remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256)
271 Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done.
272 Resolving deltas: 100% (5152604/5152604), done. Checking connectivity... done.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500273 Checking out files: 100% (59846/59846), done.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500274
2756. *Create a Local Copy of the Kernel Cache Git Repository:* For
276 simplicity, it is recommended that you create your copy of the kernel
277 cache Git repository outside of the
278 :term:`Source Directory`, which is
279 usually named ``poky``. Also, for this example, be sure you are in
280 the ``yocto-4.12`` branch.
281
282 The following commands show how to create a local copy of the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700283 ``yocto-kernel-cache`` and switch to the ``yocto-4.12`` branch::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500284
285 $ cd ~
286 $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12
287 Cloning into 'yocto-kernel-cache'...
288 remote: Counting objects: 22639, done.
289 remote: Compressing objects: 100% (9761/9761), done.
290 remote: Total 22639 (delta 12400), reused 22586 (delta 12347)
291 Receiving objects: 100% (22639/22639), 22.34 MiB | 6.27 MiB/s, done.
292 Resolving deltas: 100% (12400/12400), done.
293 Checking connectivity... done.
294
295At this point, you are ready to start making modifications to the kernel
296using traditional kernel development steps. For a continued example, see
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500297the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500298section.
299
300Creating and Preparing a Layer
301==============================
302
303If you are going to be modifying kernel recipes, it is recommended that
304you create and prepare your own layer in which to do your work. Your
305layer contains its own :term:`BitBake`
306append files (``.bbappend``) and provides a convenient mechanism to
307create your own recipe files (``.bb``) as well as store and use kernel
308patch files. For background information on working with layers, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600309":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500310section in the Yocto Project Development Tasks Manual.
311
312.. note::
313
314 The Yocto Project comes with many tools that simplify tasks you need
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500315 to perform. One such tool is the ``bitbake-layers create-layer``
316 command, which simplifies creating a new layer. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600317 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500318 section in the Yocto Project Development Tasks Manual for
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500319 information on how to use this script to quick set up a new layer.
320
321To better understand the layer you create for kernel development, the
322following section describes how to create a layer without the aid of
323tools. These steps assume creation of a layer named ``mylayer`` in your
324home directory:
325
Andrew Geisslerc926e172021-05-07 16:11:35 -05003261. *Create Structure*: Create the layer's structure::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500327
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500328 $ mkdir meta-mylayer
329 $ mkdir meta-mylayer/conf
330 $ mkdir meta-mylayer/recipes-kernel
331 $ mkdir meta-mylayer/recipes-kernel/linux
332 $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto
333
334 The ``conf`` directory holds your configuration files, while the
335 ``recipes-kernel`` directory holds your append file and eventual
336 patch files.
337
3382. *Create the Layer Configuration File*: Move to the
339 ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500340 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500341
342 # We have a conf and classes directory, add to BBPATH
343 BBPATH .= ":${LAYERDIR}"
344
345 # We have recipes-* directories, add to BBFILES
346 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
347 ${LAYERDIR}/recipes-*/*/*.bbappend"
348
349 BBFILE_COLLECTIONS += "mylayer"
350 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
351 BBFILE_PRIORITY_mylayer = "5"
352
353 Notice ``mylayer`` as part of the last three statements.
354
3553. *Create the Kernel Recipe Append File*: Move to the
356 ``meta-mylayer/recipes-kernel/linux`` directory and create the
357 kernel's append file. This example uses the ``linux-yocto-4.12``
358 kernel. Thus, the name of the append file is
Andrew Geisslerc926e172021-05-07 16:11:35 -0500359 ``linux-yocto_4.12.bbappend``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500360
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500361 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500362
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500363 SRC_URI:append = " file://patch-file-one.patch"
364 SRC_URI:append = " file://patch-file-two.patch"
365 SRC_URI:append = " file://patch-file-three.patch"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500366
367 The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
368 enable the OpenEmbedded build system to find patch files. For more
369 information on using append files, see the
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500370 ":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500371 section in the Yocto Project Development Tasks Manual.
372
373Modifying an Existing Recipe
374============================
375
376In many cases, you can customize an existing linux-yocto recipe to meet
377the needs of your project. Each release of the Yocto Project provides a
378few Linux kernel recipes from which you can choose. These are located in
379the :term:`Source Directory` in
380``meta/recipes-kernel/linux``.
381
382Modifying an existing recipe can consist of the following:
383
Andrew Geissler09209ee2020-12-13 08:44:15 -0600384- :ref:`kernel-dev/common:creating the append file`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500385
Andrew Geissler09209ee2020-12-13 08:44:15 -0600386- :ref:`kernel-dev/common:applying patches`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500387
Andrew Geissler09209ee2020-12-13 08:44:15 -0600388- :ref:`kernel-dev/common:changing the configuration`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500389
390Before modifying an existing recipe, be sure that you have created a
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500391minimal, custom layer from which you can work. See the
392":ref:`kernel-dev/common:creating and preparing a layer`" section for
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500393information.
394
395Creating the Append File
396------------------------
397
398You create this file in your custom layer. You also name it accordingly
399based on the linux-yocto recipe you are using. For example, if you are
400modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe,
401the append file will typically be located as follows within your custom
402layer:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500403
404.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500405
406 your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend
407
408The append file should initially extend the
409:term:`FILESPATH` search path by
410prepending the directory that contains your files to the
411:term:`FILESEXTRAPATHS`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500412variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500413
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500414 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500415
416The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``
417expands to "linux-yocto" in the current directory for this example. If
418you add any new files that modify the kernel recipe and you have
Andrew Geissler09036742021-06-25 14:25:14 -0500419extended :term:`FILESPATH` as described above, you must place the files in
Andrew Geisslerc926e172021-05-07 16:11:35 -0500420your layer in the following area::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500421
422 your-layer/recipes-kernel/linux/linux-yocto/
423
424.. note::
425
426 If you are working on a new machine Board Support Package (BSP), be
Andrew Geissler09209ee2020-12-13 08:44:15 -0600427 sure to refer to the :doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500428
429As an example, consider the following append file used by the BSPs in
430``meta-yocto-bsp``:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500431
432.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500433
434 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend
435
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700436Here are the contents of this file. Be aware that the actual commit ID
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500437strings in this example listing might be different than the actual
438strings in the file from the ``meta-yocto-bsp`` layer upstream.
439::
440
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500441 KBRANCH:genericx86 = "standard/base"
442 KBRANCH:genericx86-64 = "standard/base"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500443
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500444 KMACHINE:genericx86 ?= "common-pc"
445 KMACHINE:genericx86-64 ?= "common-pc-64"
446 KBRANCH:edgerouter = "standard/edgerouter"
447 KBRANCH:beaglebone = "standard/beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500448
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500449 SRCREV_machine:genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
450 SRCREV_machine:genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
451 SRCREV_machine:edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
452 SRCREV_machine:beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500453
454
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500455 COMPATIBLE_MACHINE:genericx86 = "genericx86"
456 COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64"
457 COMPATIBLE_MACHINE:edgerouter = "edgerouter"
458 COMPATIBLE_MACHINE:beaglebone = "beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500459
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500460 LINUX_VERSION:genericx86 = "4.12.7"
461 LINUX_VERSION:genericx86-64 = "4.12.7"
462 LINUX_VERSION:edgerouter = "4.12.10"
463 LINUX_VERSION:beaglebone = "4.12.10"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500464
465This append file
466contains statements used to support several BSPs that ship with the
467Yocto Project. The file defines machines using the
468:term:`COMPATIBLE_MACHINE`
469variable and uses the
470:term:`KMACHINE` variable to ensure
471the machine name used by the OpenEmbedded build system maps to the
472machine name used by the Linux Yocto kernel. The file also uses the
473optional :term:`KBRANCH` variable to
474ensure the build process uses the appropriate kernel branch.
475
476Although this particular example does not use it, the
477:term:`KERNEL_FEATURES`
478variable could be used to enable features specific to the kernel. The
479append file points to specific commits in the
480:term:`Source Directory` Git repository and
481the ``meta`` Git repository branches to identify the exact kernel needed
482to build the BSP.
483
484One thing missing in this particular BSP, which you will typically need
485when developing a BSP, is the kernel configuration file (``.config``)
486for your BSP. When developing a BSP, you probably have a kernel
487configuration file or a set of kernel configuration files that, when
488taken together, define the kernel configuration for your BSP. You can
489accomplish this definition by putting the configurations in a file or a
490set of files inside a directory located at the same level as your
491kernel's append file and having the same name as the kernel's main
492recipe file. With all these conditions met, simply reference those files
493in the :term:`SRC_URI` statement in
494the append file.
495
496For example, suppose you had some configuration options in a file called
497``network_configs.cfg``. You can place that file inside a directory
Andrew Geissler09036742021-06-25 14:25:14 -0500498named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500499following to the append file. When the OpenEmbedded build system builds
500the kernel, the configuration options are picked up and applied.
501::
502
503 SRC_URI += "file://network_configs.cfg"
504
505To group related configurations into multiple files, you perform a
506similar procedure. Here is an example that groups separate
507configurations specifically for Ethernet and graphics into their own
Andrew Geissler09036742021-06-25 14:25:14 -0500508files and adds the configurations by using a :term:`SRC_URI` statement like
Andrew Geisslerc926e172021-05-07 16:11:35 -0500509the following in your append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500510
511 SRC_URI += "file://myconfig.cfg \
512 file://eth.cfg \
513 file://gfx.cfg"
514
515Another variable you can use in your kernel recipe append file is the
516:term:`FILESEXTRAPATHS`
517variable. When you use this statement, you are extending the locations
518used by the OpenEmbedded system to look for files and patches as the
519recipe is processed.
520
521.. note::
522
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700523 There are other ways of grouping and defining configuration
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500524 options. For example, if you are working with a local clone of the
525 kernel repository, you could checkout the kernel's ``meta`` branch,
526 make your changes, and then push the changes to the local bare clone
527 of the kernel. The result is that you directly add configuration
528 options to the ``meta`` branch for your BSP. The configuration
529 options will likely end up in that location anyway if the BSP gets
530 added to the Yocto Project.
531
532 In general, however, the Yocto Project maintainers take care of
Andrew Geissler5f350902021-07-23 13:09:54 -0400533 moving the :term:`SRC_URI`-specified configuration options to the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700534 kernel's ``meta`` branch. Not only is it easier for BSP developers
535 not to have to put those configurations in the branch,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500536 but having the maintainers do it allows them to apply 'global'
537 knowledge about the kinds of common configuration options multiple
538 BSPs in the tree are typically using. This allows for promotion of
539 common configurations into common features.
540
541Applying Patches
542----------------
543
544If you have a single patch or a small series of patches that you want to
545apply to the Linux kernel source, you can do so just as you would with
546any other recipe. You first copy the patches to the path added to
547:term:`FILESEXTRAPATHS` in
548your ``.bbappend`` file as described in the previous section, and then
549reference them in :term:`SRC_URI`
550statements.
551
552For example, you can apply a three-patch series by adding the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500553lines to your linux-yocto ``.bbappend`` file in your layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500554
555 SRC_URI += "file://0001-first-change.patch"
556 SRC_URI += "file://0002-second-change.patch"
557 SRC_URI += "file://0003-third-change.patch"
558
559The next time you run BitBake to build
560the Linux kernel, BitBake detects the change in the recipe and fetches
561and applies the patches before building the kernel.
562
563For a detailed example showing how to patch the kernel using
564``devtool``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600565":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500566and
Andrew Geissler09209ee2020-12-13 08:44:15 -0600567":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500568sections.
569
570Changing the Configuration
571--------------------------
572
573You can make wholesale or incremental changes to the final ``.config``
574file used for the eventual Linux kernel configuration by including a
575``defconfig`` file and by specifying configuration fragments in the
576:term:`SRC_URI` to be applied to that
577file.
578
579If you have a complete, working Linux kernel ``.config`` file you want
580to use for the configuration, as before, copy that file to the
581appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux``
582directory, and rename the copied file to "defconfig". Then, add the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500583following lines to the linux-yocto ``.bbappend`` file in your layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500584
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500585 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500586 SRC_URI += "file://defconfig"
587
Andrew Geissler09036742021-06-25 14:25:14 -0500588The :term:`SRC_URI` tells the build system how to search
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500589for the file, while the
590:term:`FILESEXTRAPATHS`
591extends the :term:`FILESPATH`
592variable (search directories) to include the ``${PN}`` directory you
593created to hold the configuration changes.
594
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700595You can also use a regular ``defconfig`` file, as generated by the
596:ref:`ref-tasks-savedefconfig`
597task instead of a complete ``.config`` file. This only specifies the
598non-default configuration values. You need to additionally set
599:term:`KCONFIG_MODE`
600in the linux-yocto ``.bbappend`` file in your layer::
601
602 KCONFIG_MODE = "alldefconfig"
603
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500604.. note::
605
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500606 The build system applies the configurations from the ``defconfig``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500607 file before applying any subsequent configuration fragments. The
608 final kernel configuration is a combination of the configurations in
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500609 the ``defconfig`` file and any configuration fragments you provide. You need
610 to realize that if you have any configuration fragments, the build system
611 applies these on top of and after applying the existing ``defconfig`` file
612 configurations.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500613
614Generally speaking, the preferred approach is to determine the
615incremental change you want to make and add that as a configuration
616fragment. For example, if you want to add support for a basic serial
617console, create a file named ``8250.cfg`` in the ``${PN}`` directory
Andrew Geisslerc926e172021-05-07 16:11:35 -0500618with the following content (without indentation)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500619
620 CONFIG_SERIAL_8250=y
621 CONFIG_SERIAL_8250_CONSOLE=y
622 CONFIG_SERIAL_8250_PCI=y
623 CONFIG_SERIAL_8250_NR_UARTS=4
624 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
625 CONFIG_SERIAL_CORE=y
626 CONFIG_SERIAL_CORE_CONSOLE=y
627
628Next, include this
Andrew Geissler09036742021-06-25 14:25:14 -0500629configuration fragment and extend the :term:`FILESPATH` variable in your
Andrew Geisslerc926e172021-05-07 16:11:35 -0500630``.bbappend`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500631
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500632 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500633 SRC_URI += "file://8250.cfg"
634
635The next time you run BitBake to build the
636Linux kernel, BitBake detects the change in the recipe and fetches and
637applies the new configuration before building the kernel.
638
639For a detailed example showing how to configure the kernel, see the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500640":ref:`kernel-dev/common:configuring the kernel`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500641
642Using an "In-Tree"  ``defconfig`` File
643--------------------------------------
644
645It might be desirable to have kernel configuration fragment support
646through a ``defconfig`` file that is pulled from the kernel source tree
647for the configured machine. By default, the OpenEmbedded build system
648looks for ``defconfig`` files in the layer used for Metadata, which is
Andrew Geisslerc926e172021-05-07 16:11:35 -0500649"out-of-tree", and then configures them using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500650
651 SRC_URI += "file://defconfig"
652
653If you do not want to maintain copies of
654``defconfig`` files in your layer but would rather allow users to use
655the default configuration from the kernel tree and still be able to add
656configuration fragments to the
657:term:`SRC_URI` through, for example,
658append files, you can direct the OpenEmbedded build system to use a
659``defconfig`` file that is "in-tree".
660
661To specify an "in-tree" ``defconfig`` file, use the following statement
Andrew Geisslerc926e172021-05-07 16:11:35 -0500662form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500663
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500664 KBUILD_DEFCONFIG_KMACHINE ?= "defconfig_file"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500665
666Here is an example
Andrew Geissler09036742021-06-25 14:25:14 -0500667that assigns the :term:`KBUILD_DEFCONFIG` variable based on "raspberrypi2"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500668and provides the path to the "in-tree" ``defconfig`` file to be used for
Andrew Geisslerc926e172021-05-07 16:11:35 -0500669a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500670
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500671 KBUILD_DEFCONFIG:raspberrypi2 ?= "bcm2709_defconfig"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500672
673Aside from modifying your kernel recipe and providing your own
674``defconfig`` file, you need to be sure no files or statements set
Andrew Geissler5f350902021-07-23 13:09:54 -0400675:term:`SRC_URI` to use a ``defconfig`` other than your "in-tree" file (e.g.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500676a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500677build system detects a statement that identifies an "out-of-tree"
678``defconfig`` file, that statement will override your
Andrew Geissler09036742021-06-25 14:25:14 -0500679:term:`KBUILD_DEFCONFIG` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500680
681See the
682:term:`KBUILD_DEFCONFIG`
683variable description for more information.
684
685Using ``devtool`` to Patch the Kernel
686=====================================
687
688The steps in this procedure show you how you can patch the kernel using
Patrick Williams92b42cb2022-09-03 06:53:57 -0500689``devtool``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500690
691.. note::
692
693 Before attempting this procedure, be sure you have performed the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500694 steps to get ready for updating the kernel as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600695 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500696 section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500697
698Patching the kernel involves changing or adding configurations to an
699existing kernel, changing or adding recipes to the kernel that are
700needed to support specific hardware features, or even altering the
701source code itself.
702
703This example creates a simple patch by adding some QEMU emulator console
704output at boot time through ``printk`` statements in the kernel's
705``calibrate.c`` source code file. Applying the patch and booting the
706modified image causes the added messages to appear on the emulator's
707console. The example is a continuation of the setup procedure found in
Andrew Geissler09209ee2020-12-13 08:44:15 -0600708the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500709
7101. *Check Out the Kernel Source Files:* First you must use ``devtool``
Patrick Williams92b42cb2022-09-03 06:53:57 -0500711 to checkout the kernel source code in its workspace.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500712
713 .. note::
714
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500715 See this step in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600716 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500717 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500718
Andrew Geisslerc926e172021-05-07 16:11:35 -0500719 Use the following ``devtool`` command to check out the code::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500720
721 $ devtool modify linux-yocto
722
723 .. note::
724
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700725 During the checkout operation, there is a bug that could cause
726 errors such as the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500727
728 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500729
730 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
731 be3a89ce7c47178880ba7bf6293d7404 for
732 /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
733
734
735 You can safely ignore these messages. The source code is correctly
736 checked out.
737
7382. *Edit the Source Files* Follow these steps to make some simple
739 changes to the source files:
740
741 1. *Change the working directory*: In the previous step, the output
742 noted where you can find the source files (e.g.
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500743 ``poky_sdk/workspace/sources/linux-yocto``). Change to where the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500744 kernel source code is before making your edits to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500745 ``calibrate.c`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500746
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500747 $ cd poky_sdk/workspace/sources/linux-yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500748
749 2. *Edit the source file*: Edit the ``init/calibrate.c`` file to have
Andrew Geisslerc926e172021-05-07 16:11:35 -0500750 the following changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500751
752 void calibrate_delay(void)
753 {
754 unsigned long lpj;
755 static bool printed;
756 int this_cpu = smp_processor_id();
757
758 printk("*************************************\n");
759 printk("* *\n");
760 printk("* HELLO YOCTO KERNEL *\n");
761 printk("* *\n");
762 printk("*************************************\n");
763
764 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
765 .
766 .
767 .
768
7693. *Build the Updated Kernel Source:* To build the updated kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -0500770 source, use ``devtool``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500771
772 $ devtool build linux-yocto
773
7744. *Create the Image With the New Kernel:* Use the
775 ``devtool build-image`` command to create a new image that has the
776 new kernel.
777
778 .. note::
779
780 If the image you originally created resulted in a Wic file, you
781 can use an alternate method to create the new image with the
782 updated kernel. For an example, see the steps in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600783 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500784 Wiki Page.
785
786 ::
787
788 $ cd ~
789 $ devtool build-image core-image-minimal
790
7915. *Test the New Image:* For this example, you can run the new image
792 using QEMU to verify your changes:
793
794 1. *Boot the image*: Boot the modified image in the QEMU emulator
Andrew Geisslerc926e172021-05-07 16:11:35 -0500795 using this command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500796
797 $ runqemu qemux86
798
799 2. *Verify the changes*: Log into the machine using ``root`` with no
800 password and then use the following shell command to scroll
801 through the console's boot output.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500802
803 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500804
805 # dmesg | less
806
807 You should see
808 the results of your ``printk`` statements as part of the output
809 when you scroll down the console window.
810
Patrick Williams92b42cb2022-09-03 06:53:57 -05008116. *Stage and commit your changes*: Change
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500812 your working directory to where you modified the ``calibrate.c`` file
Andrew Geisslerc926e172021-05-07 16:11:35 -0500813 and use these Git commands to stage and commit your changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500814
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500815 $ cd poky_sdk/workspace/sources/linux-yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500816 $ git status
817 $ git add init/calibrate.c
818 $ git commit -m "calibrate: Add printk example"
819
8207. *Export the Patches and Create an Append File:* To export your
821 commits as patches and create a ``.bbappend`` file, use the following
Patrick Williams92b42cb2022-09-03 06:53:57 -0500822 command. This example uses the previously established layer named ``meta-mylayer``.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500823 ::
824
825 $ devtool finish linux-yocto ~/meta-mylayer
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500826
827 .. note::
828
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500829 See Step 3 of the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600830 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500831 section for information on setting up this layer.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500832
833 Once the command
834 finishes, the patches and the ``.bbappend`` file are located in the
835 ``~/meta-mylayer/recipes-kernel/linux`` directory.
836
8378. *Build the Image With Your Modified Kernel:* You can now build an
838 image that includes your kernel patches. Execute the following
839 command from your
840 :term:`Build Directory` in the terminal
Andrew Geisslerc926e172021-05-07 16:11:35 -0500841 set up to run BitBake::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500842
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500843 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500844 $ bitbake core-image-minimal
845
846Using Traditional Kernel Development to Patch the Kernel
847========================================================
848
849The steps in this procedure show you how you can patch the kernel using
Patrick Williams92b42cb2022-09-03 06:53:57 -0500850traditional kernel development (i.e. not using ``devtool``
851as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600852":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500853section).
854
855.. note::
856
857 Before attempting this procedure, be sure you have performed the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500858 steps to get ready for updating the kernel as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600859 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500860 section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500861
862Patching the kernel involves changing or adding configurations to an
863existing kernel, changing or adding recipes to the kernel that are
864needed to support specific hardware features, or even altering the
865source code itself.
866
867The example in this section creates a simple patch by adding some QEMU
868emulator console output at boot time through ``printk`` statements in
869the kernel's ``calibrate.c`` source code file. Applying the patch and
870booting the modified image causes the added messages to appear on the
871emulator's console. The example is a continuation of the setup procedure
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500872found in the
873":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500874Section.
875
8761. *Edit the Source Files* Prior to this step, you should have used Git
877 to create a local copy of the repository for your kernel. Assuming
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500878 you created the repository as directed in the
879 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500880 section, use the following commands to edit the ``calibrate.c`` file:
881
882 1. *Change the working directory*: You need to locate the source
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500883 files in the local copy of the kernel Git repository. Change to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500884 where the kernel source code is before making your edits to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500885 ``calibrate.c`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500886
887 $ cd ~/linux-yocto-4.12/init
888
889 2. *Edit the source file*: Edit the ``calibrate.c`` file to have the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500890 following changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500891
892 void calibrate_delay(void)
893 {
894 unsigned long lpj;
895 static bool printed;
896 int this_cpu = smp_processor_id();
897
898 printk("*************************************\n");
899 printk("* *\n");
900 printk("* HELLO YOCTO KERNEL *\n");
901 printk("* *\n");
902 printk("*************************************\n");
903
904 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
905 .
906 .
907 .
908
9092. *Stage and Commit Your Changes:* Use standard Git commands to stage
Andrew Geisslerc926e172021-05-07 16:11:35 -0500910 and commit the changes you just made::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500911
912 $ git add calibrate.c
913 $ git commit -m "calibrate.c - Added some printk statements"
914
915 If you do not
916 stage and commit your changes, the OpenEmbedded Build System will not
917 pick up the changes.
918
9193. *Update Your local.conf File to Point to Your Source Files:* In
920 addition to your ``local.conf`` file specifying to use
921 "kernel-modules" and the "qemux86" machine, it must also point to the
922 updated kernel source files. Add
923 :term:`SRC_URI` and
924 :term:`SRCREV` statements similar
Andrew Geisslerc926e172021-05-07 16:11:35 -0500925 to the following to your ``local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500926
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500927 $ cd poky/build/conf
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500928
Andrew Geisslerc926e172021-05-07 16:11:35 -0500929 Add the following to the ``local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500930
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500931 SRC_URI:pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500932 git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500933 SRCREV_meta:qemux86 = "${AUTOREV}"
934 SRCREV_machine:qemux86 = "${AUTOREV}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500935
936 .. note::
937
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500938 Be sure to replace `path-to`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500939 with the pathname to your local Git repositories. Also, you must
940 be sure to specify the correct branch and machine types. For this
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500941 example, the branch is ``standard/base`` and the machine is ``qemux86``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500942
9434. *Build the Image:* With the source modified, your changes staged and
944 committed, and the ``local.conf`` file pointing to the kernel files,
Andrew Geisslerc926e172021-05-07 16:11:35 -0500945 you can now use BitBake to build the image::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500946
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500947 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500948 $ bitbake core-image-minimal
949
9505. *Boot the image*: Boot the modified image in the QEMU emulator using
951 this command. When prompted to login to the QEMU console, use "root"
Andrew Geisslerc926e172021-05-07 16:11:35 -0500952 with no password::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500953
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500954 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500955 $ runqemu qemux86
956
9576. *Look for Your Changes:* As QEMU booted, you might have seen your
958 changes rapidly scroll by. If not, use these commands to see your
959 changes:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500960
961 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500962
963 # dmesg | less
964
965 You should see the results of your
966 ``printk`` statements as part of the output when you scroll down the
967 console window.
968
9697. *Generate the Patch File:* Once you are sure that your patch works
970 correctly, you can generate a ``*.patch`` file in the kernel source
Andrew Geisslerc926e172021-05-07 16:11:35 -0500971 repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500972
973 $ cd ~/linux-yocto-4.12/init
974 $ git format-patch -1
975 0001-calibrate.c-Added-some-printk-statements.patch
976
9778. *Move the Patch File to Your Layer:* In order for subsequent builds
978 to pick up patches, you need to move the patch file you created in
979 the previous step to your layer ``meta-mylayer``. For this example,
980 the layer created earlier is located in your home directory as
981 ``meta-mylayer``. When the layer was created using the
982 ``yocto-create`` script, no additional hierarchy was created to
983 support patches. Before moving the patch file, you need to add
Andrew Geisslerc926e172021-05-07 16:11:35 -0500984 additional structure to your layer using the following commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500985
986 $ cd ~/meta-mylayer
987 $ mkdir recipes-kernel
988 $ mkdir recipes-kernel/linux
989 $ mkdir recipes-kernel/linux/linux-yocto
990
991 Once you have created this
992 hierarchy in your layer, you can move the patch file using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500993 following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500994
995 $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto
996
9979. *Create the Append File:* Finally, you need to create the
998 ``linux-yocto_4.12.bbappend`` file and insert statements that allow
999 the OpenEmbedded build system to find the patch. The append file
1000 needs to be in your layer's ``recipes-kernel/linux`` directory and it
1001 must be named ``linux-yocto_4.12.bbappend`` and have the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001002 contents::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001003
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001004 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerd5838332022-05-27 11:33:10 -05001005 SRC_URI:append = " file://0001-calibrate.c-Added-some-printk-statements.patch"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001006
1007 The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
1008 enable the OpenEmbedded build system to find the patch file.
1009
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001010 For more information on append files and patches, see the
1011 ":ref:`kernel-dev/common:creating the append file`" and
1012 ":ref:`kernel-dev/common:applying patches`" sections. You can also see the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001013 ":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001014 section in the Yocto Project Development Tasks Manual.
1015
1016 .. note::
1017
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001018 To build ``core-image-minimal`` again and see the effects of your patch,
1019 you can essentially eliminate the temporary source files saved in
1020 ``poky/build/tmp/work/...`` and residual effects of the build by entering
Andrew Geisslerc926e172021-05-07 16:11:35 -05001021 the following sequence of commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001022
Andrew Geissler95ac1b82021-03-31 14:34:31 -05001023 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001024 $ bitbake -c cleanall yocto-linux
1025 $ bitbake core-image-minimal -c cleanall
1026 $ bitbake core-image-minimal
1027 $ runqemu qemux86
1028
1029
1030Configuring the Kernel
1031======================
1032
1033Configuring the Yocto Project kernel consists of making sure the
1034``.config`` file has all the right information in it for the image you
1035are building. You can use the ``menuconfig`` tool and configuration
1036fragments to make sure your ``.config`` file is just how you need it.
1037You can also save known configurations in a ``defconfig`` file that the
1038build system can use for kernel configuration.
1039
1040This section describes how to use ``menuconfig``, create and use
1041configuration fragments, and how to interactively modify your
1042``.config`` file to create the leanest kernel configuration file
1043possible.
1044
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001045For more information on kernel configuration, see the
1046":ref:`kernel-dev/common:changing the configuration`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001047
1048Using  ``menuconfig``
1049---------------------
1050
1051The easiest way to define kernel configurations is to set them through
1052the ``menuconfig`` tool. This tool provides an interactive method with
1053which to set kernel configurations. For general information on
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001054``menuconfig``, see https://en.wikipedia.org/wiki/Menuconfig.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001055
1056To use the ``menuconfig`` tool in the Yocto Project development
1057environment, you must do the following:
1058
1059- Because you launch ``menuconfig`` using BitBake, you must be sure to
1060 set up your environment by running the
1061 :ref:`structure-core-script` script found in
1062 the :term:`Build Directory`.
1063
1064- You must be sure of the state of your build's configuration in the
1065 :term:`Source Directory`.
1066
Andrew Geisslerc926e172021-05-07 16:11:35 -05001067- Your build host must have the following two packages installed::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001068
1069 libncurses5-dev
1070 libtinfo-dev
1071
1072The following commands initialize the BitBake environment, run the
1073:ref:`ref-tasks-kernel_configme`
1074task, and launch ``menuconfig``. These commands assume the Source
Andrew Geisslerc926e172021-05-07 16:11:35 -05001075Directory's top-level folder is ``poky``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001076
1077 $ cd poky
1078 $ source oe-init-build-env
1079 $ bitbake linux-yocto -c kernel_configme -f
1080 $ bitbake linux-yocto -c menuconfig
1081
1082Once ``menuconfig`` comes up, its standard
1083interface allows you to interactively examine and configure all the
1084kernel configuration parameters. After making your changes, simply exit
1085the tool and save your changes to create an updated version of the
1086``.config`` configuration file.
1087
1088.. note::
1089
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001090 You can use the entire ``.config`` file as the ``defconfig`` file. For
1091 information on ``defconfig`` files, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001092 ":ref:`kernel-dev/common:changing the configuration`",
1093 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`",
1094 and ":ref:`kernel-dev/common:creating a \`\`defconfig\`\` file`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001095 sections.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001096
1097Consider an example that configures the "CONFIG_SMP" setting for the
1098``linux-yocto-4.12`` kernel.
1099
1100.. note::
1101
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001102 The OpenEmbedded build system recognizes this kernel as ``linux-yocto``
1103 through Metadata (e.g. :term:`PREFERRED_VERSION`\ ``_linux-yocto ?= "12.4%"``).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001104
1105Once ``menuconfig`` launches, use the interface to navigate through the
1106selections to find the configuration settings in which you are
1107interested. For this example, you deselect "CONFIG_SMP" by clearing the
1108"Symmetric Multi-Processing Support" option. Using the interface, you
1109can find the option under "Processor Type and Features". To deselect
1110"CONFIG_SMP", use the arrow keys to highlight "Symmetric
1111Multi-Processing Support" and enter "N" to clear the asterisk. When you
1112are finished, exit out and save the change.
1113
1114Saving the selections updates the ``.config`` configuration file. This
1115is the file that the OpenEmbedded build system uses to configure the
1116kernel during the build. You can find and examine this file in the Build
1117Directory in ``tmp/work/``. The actual ``.config`` is located in the
1118area where the specific kernel is built. For example, if you were
1119building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel
1120and you were building a QEMU image targeted for ``x86`` architecture,
1121the ``.config`` file would be:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001122
1123.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001124
1125 poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
1126 ...967-r0/linux-qemux86-standard-build/.config
1127
1128.. note::
1129
1130 The previous example directory is artificially split and many of the
1131 characters in the actual filename are omitted in order to make it
1132 more readable. Also, depending on the kernel you are using, the exact
1133 pathname might differ.
1134
1135Within the ``.config`` file, you can see the kernel settings. For
1136example, the following entry shows that symmetric multi-processor
Andrew Geisslerc926e172021-05-07 16:11:35 -05001137support is not set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001138
1139 # CONFIG_SMP is not set
1140
1141A good method to isolate changed configurations is to use a combination
1142of the ``menuconfig`` tool and simple shell commands. Before changing
1143configurations with ``menuconfig``, copy the existing ``.config`` and
1144rename it to something else, use ``menuconfig`` to make as many changes
1145as you want and save them, then compare the renamed configuration file
1146against the newly created file. You can use the resulting differences as
1147your base to create configuration fragments to permanently save in your
1148kernel layer.
1149
1150.. note::
1151
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001152 Be sure to make a copy of the ``.config`` file and do not just rename it.
1153 The build system needs an existing ``.config`` file from which to work.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001154
1155Creating a  ``defconfig`` File
1156------------------------------
1157
1158A ``defconfig`` file in the context of the Yocto Project is often a
1159``.config`` file that is copied from a build or a ``defconfig`` taken
1160from the kernel tree and moved into recipe space. You can use a
1161``defconfig`` file to retain a known set of kernel configurations from
1162which the OpenEmbedded build system can draw to create the final
1163``.config`` file.
1164
1165.. note::
1166
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001167 Out-of-the-box, the Yocto Project never ships a ``defconfig`` or ``.config``
1168 file. The OpenEmbedded build system creates the final ``.config`` file used
1169 to configure the kernel.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001170
1171To create a ``defconfig``, start with a complete, working Linux kernel
1172``.config`` file. Copy that file to the appropriate
1173``${``\ :term:`PN`\ ``}`` directory in
1174your layer's ``recipes-kernel/linux`` directory, and rename the copied
1175file to "defconfig" (e.g.
1176``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then,
1177add the following lines to the linux-yocto ``.bbappend`` file in your
Andrew Geisslerc926e172021-05-07 16:11:35 -05001178layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001179
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001180 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001181 SRC_URI += "file://defconfig"
1182
1183The :term:`SRC_URI` tells the build system how to search for the file, while the
1184:term:`FILESEXTRAPATHS` extends the :term:`FILESPATH`
1185variable (search directories) to include the ``${PN}`` directory you
1186created to hold the configuration changes.
1187
1188.. note::
1189
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001190 The build system applies the configurations from the ``defconfig``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001191 file before applying any subsequent configuration fragments. The
1192 final kernel configuration is a combination of the configurations in
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001193 the ``defconfig`` file and any configuration fragments you provide. You need
1194 to realize that if you have any configuration fragments, the build system
1195 applies these on top of and after applying the existing ``defconfig`` file
1196 configurations.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001197
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001198For more information on configuring the kernel, see the
1199":ref:`kernel-dev/common:changing the configuration`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001200
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001201Creating Configuration Fragments
1202--------------------------------
1203
1204Configuration fragments are simply kernel options that appear in a file
1205placed where the OpenEmbedded build system can find and apply them. The
1206build system applies configuration fragments after applying
1207configurations from a ``defconfig`` file. Thus, the final kernel
1208configuration is a combination of the configurations in the
1209``defconfig`` file and then any configuration fragments you provide. The
1210build system applies fragments on top of and after applying the existing
1211defconfig file configurations.
1212
1213Syntactically, the configuration statement is identical to what would
1214appear in the ``.config`` file, which is in the :term:`Build Directory`.
1215
1216.. note::
1217
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001218 For more information about where the ``.config`` file is located, see the
1219 example in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001220 ":ref:`kernel-dev/common:using \`\`menuconfig\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001221 section.
1222
1223It is simple to create a configuration fragment. One method is to use
1224shell commands. For example, issuing the following from the shell
1225creates a configuration fragment file named ``my_smp.cfg`` that enables
Andrew Geisslerc926e172021-05-07 16:11:35 -05001226multi-processor support within the kernel::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001227
1228 $ echo "CONFIG_SMP=y" >> my_smp.cfg
1229
1230.. note::
1231
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001232 All configuration fragment files must use the ``.cfg`` extension in order
1233 for the OpenEmbedded build system to recognize them as a configuration
1234 fragment.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001235
1236Another method is to create a configuration fragment using the
1237differences between two configuration files: one previously created and
1238saved, and one freshly created using the ``menuconfig`` tool.
1239
1240To create a configuration fragment using this method, follow these
1241steps:
1242
12431. *Complete a Build Through Kernel Configuration:* Complete a build at
Andrew Geisslerc926e172021-05-07 16:11:35 -05001244 least through the kernel configuration task as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001245
1246 $ bitbake linux-yocto -c kernel_configme -f
1247
1248 This step ensures that you create a
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001249 ``.config`` file from a known state. Because there are situations where
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001250 your build state might become unknown, it is best to run this task
1251 prior to starting ``menuconfig``.
1252
Andrew Geisslerc926e172021-05-07 16:11:35 -050012532. *Launch menuconfig:* Run the ``menuconfig`` command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001254
1255 $ bitbake linux-yocto -c menuconfig
1256
12573. *Create the Configuration Fragment:* Run the ``diffconfig`` command
1258 to prepare a configuration fragment. The resulting file
1259 ``fragment.cfg`` is placed in the
1260 ``${``\ :term:`WORKDIR`\ ``}``
Andrew Geisslerc926e172021-05-07 16:11:35 -05001261 directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001262
1263 $ bitbake linux-yocto -c diffconfig
1264
1265The ``diffconfig`` command creates a file that is a list of Linux kernel
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001266``CONFIG_`` assignments. See the
1267":ref:`kernel-dev/common:changing the configuration`" section for additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001268information on how to use the output as a configuration fragment.
1269
1270.. note::
1271
1272 You can also use this method to create configuration fragments for a
Andrew Geissler09209ee2020-12-13 08:44:15 -06001273 BSP. See the ":ref:`kernel-dev/advanced:bsp descriptions`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001274 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001275
1276Where do you put your configuration fragment files? You can place these
1277files in an area pointed to by
1278:term:`SRC_URI` as directed by your
1279``bblayers.conf`` file, which is located in your layer. The OpenEmbedded
1280build system picks up the configuration and adds it to the kernel's
1281configuration. For example, suppose you had a set of configuration
1282options in a file called ``myconfig.cfg``. If you put that file inside a
1283directory named ``linux-yocto`` that resides in the same directory as
1284the kernel's append file within your layer and then add the following
1285statements to the kernel's append file, those configuration options will
Andrew Geisslerc926e172021-05-07 16:11:35 -05001286be picked up and applied when the kernel is built::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001287
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001288 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001289 SRC_URI += "file://myconfig.cfg"
1290
1291As mentioned earlier, you can group related configurations into multiple
Andrew Geissler09036742021-06-25 14:25:14 -05001292files and name them all in the :term:`SRC_URI` statement as well. For
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001293example, you could group separate configurations specifically for
1294Ethernet and graphics into their own files and add those by using a
Andrew Geissler09036742021-06-25 14:25:14 -05001295:term:`SRC_URI` statement like the following in your append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001296
1297 SRC_URI += "file://myconfig.cfg \
1298 file://eth.cfg \
1299 file://gfx.cfg"
1300
1301Validating Configuration
1302------------------------
1303
1304You can use the
1305:ref:`ref-tasks-kernel_configcheck`
Andrew Geisslerc926e172021-05-07 16:11:35 -05001306task to provide configuration validation::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001307
1308 $ bitbake linux-yocto -c kernel_configcheck -f
1309
1310Running this task produces warnings for when a
1311requested configuration does not appear in the final ``.config`` file or
1312when you override a policy configuration in a hardware configuration
1313fragment.
1314
1315In order to run this task, you must have an existing ``.config`` file.
Andrew Geissler09209ee2020-12-13 08:44:15 -06001316See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001317information on how to create a configuration file.
1318
1319Following is sample output from the ``do_kernel_configcheck`` task:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001320
1321.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001322
1323 Loading cache: 100% |########################################################| Time: 0:00:00
1324 Loaded 1275 entries from dependency cache.
1325 NOTE: Resolving any missing task queue dependencies
1326
1327 Build Configuration:
1328 .
1329 .
1330 .
1331
1332 NOTE: Executing SetScene Tasks
1333 NOTE: Executing RunQueue Tasks
1334 WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck:
1335 [kernel config]: specified values did not make it into the kernel's final configuration:
1336
1337 ---------- CONFIG_X86_TSC -----------------
1338 Config: CONFIG_X86_TSC
1339 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
1340 Requested value: CONFIG_X86_TSC=y
1341 Actual value:
1342
1343
1344 ---------- CONFIG_X86_BIGSMP -----------------
1345 Config: CONFIG_X86_BIGSMP
1346 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1347 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1348 Requested value: # CONFIG_X86_BIGSMP is not set
1349 Actual value:
1350
1351
1352 ---------- CONFIG_NR_CPUS -----------------
1353 Config: CONFIG_NR_CPUS
1354 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1355 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
1356 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1357 Requested value: CONFIG_NR_CPUS=8
1358 Actual value: CONFIG_NR_CPUS=1
1359
1360
1361 ---------- CONFIG_SCHED_SMT -----------------
1362 Config: CONFIG_SCHED_SMT
1363 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1364 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1365 Requested value: CONFIG_SCHED_SMT=y
1366 Actual value:
1367
1368
1369
1370 NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded.
1371
1372 Summary: There were 3 WARNING messages shown.
1373
1374.. note::
1375
1376 The previous output example has artificial line breaks to make it
1377 more readable.
1378
1379The output describes the various problems that you can encounter along
1380with where to find the offending configuration items. You can use the
1381information in the logs to adjust your configuration files and then
1382repeat the
1383:ref:`ref-tasks-kernel_configme`
1384and
1385:ref:`ref-tasks-kernel_configcheck`
1386tasks until they produce no warnings.
1387
1388For more information on how to use the ``menuconfig`` tool, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001389:ref:`kernel-dev/common:using \`\`menuconfig\`\`` section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001390
1391Fine-Tuning the Kernel Configuration File
1392-----------------------------------------
1393
1394You can make sure the ``.config`` file is as lean or efficient as
1395possible by reading the output of the kernel configuration fragment
1396audit, noting any issues, making changes to correct the issues, and then
1397repeating.
1398
1399As part of the kernel build process, the ``do_kernel_configcheck`` task
1400runs. This task validates the kernel configuration by checking the final
1401``.config`` file against the input files. During the check, the task
1402produces warning messages for the following issues:
1403
1404- Requested options that did not make the final ``.config`` file.
1405
1406- Configuration items that appear twice in the same configuration
1407 fragment.
1408
1409- Configuration items tagged as "required" that were overridden.
1410
1411- A board overrides a non-board specific option.
1412
1413- Listed options not valid for the kernel being processed. In other
1414 words, the option does not appear anywhere.
1415
1416.. note::
1417
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001418 The :ref:`ref-tasks-kernel_configcheck` task can also optionally report if
1419 an option is overridden during processing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001420
1421For each output warning, a message points to the file that contains a
1422list of the options and a pointer to the configuration fragment that
1423defines them. Collectively, the files are the key to streamlining the
1424configuration.
1425
1426To streamline the configuration, do the following:
1427
14281. *Use a Working Configuration:* Start with a full configuration that
1429 you know works. Be sure the configuration builds and boots
1430 successfully. Use this configuration file as your baseline.
1431
14322. *Run Configure and Check Tasks:* Separately run the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001433 ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001434
1435 $ bitbake linux-yocto -c kernel_configme -f
1436 $ bitbake linux-yocto -c kernel_configcheck -f
1437
14383. *Process the Results:* Take the resulting list of files from the
1439 ``do_kernel_configcheck`` task warnings and do the following:
1440
1441 - Drop values that are redefined in the fragment but do not change
1442 the final ``.config`` file.
1443
1444 - Analyze and potentially drop values from the ``.config`` file that
1445 override required configurations.
1446
1447 - Analyze and potentially remove non-board specific options.
1448
1449 - Remove repeated and invalid options.
1450
14514. *Re-Run Configure and Check Tasks:* After you have worked through the
1452 output of the kernel configuration audit, you can re-run the
1453 ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks to see the
1454 results of your changes. If you have more issues, you can deal with
1455 them as described in the previous step.
1456
1457Iteratively working through steps two through four eventually yields a
1458minimal, streamlined configuration file. Once you have the best
1459``.config``, you can build the Linux Yocto kernel.
1460
1461Expanding Variables
1462===================
1463
1464Sometimes it is helpful to determine what a variable expands to during a
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001465build. You can examine the values of variables by examining the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001466output of the ``bitbake -e`` command. The output is long and is more
Andrew Geisslerc926e172021-05-07 16:11:35 -05001467easily managed in a text file, which allows for easy searches::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001468
1469 $ bitbake -e virtual/kernel > some_text_file
1470
1471Within the text file, you can see
1472exactly how each variable is expanded and used by the OpenEmbedded build
1473system.
1474
1475Working with a "Dirty" Kernel Version String
1476============================================
1477
1478If you build a kernel image and the version string has a "+" or a
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001479"-dirty" at the end, it means there are uncommitted modifications in the kernel's
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001480source directory. Follow these steps to clean up the version string:
1481
14821. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned
1483 Git repository (source directory) and use the following Git command
Andrew Geisslerc926e172021-05-07 16:11:35 -05001484 to list the files that have been changed, added, or removed::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001485
1486 $ git status
1487
14882. *Commit the Changes:* You should commit those changes to the kernel
1489 source tree regardless of whether or not you will save, export, or
Andrew Geisslerc926e172021-05-07 16:11:35 -05001490 use the changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001491
1492 $ git add
1493 $ git commit -s -a -m "getting rid of -dirty"
1494
14953. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the
1496 kernel.
1497
1498 Depending on your particular kernel development workflow, the
1499 commands you use to rebuild the kernel might differ. For information
1500 on building the kernel image when using ``devtool``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001501 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001502 section. For
Andrew Geisslerd5838332022-05-27 11:33:10 -05001503 information on building the kernel image when using BitBake, see the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001504 ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001505 section.
1506
1507Working With Your Own Sources
1508=============================
1509
1510If you cannot work with one of the Linux kernel versions supported by
1511existing linux-yocto recipes, you can still make use of the Yocto
1512Project Linux kernel tooling by working with your own sources. When you
1513use your own sources, you will not be able to leverage the existing
1514kernel :term:`Metadata` and stabilization
1515work of the linux-yocto sources. However, you will be able to manage
1516your own Metadata in the same format as the linux-yocto sources.
1517Maintaining format compatibility facilitates converging with linux-yocto
1518on a future, mutually-supported kernel version.
1519
1520To help you use your own sources, the Yocto Project provides a
Andrew Geissler595f6302022-01-24 19:11:47 +00001521linux-yocto custom recipe that uses ``kernel.org`` sources and
1522the Yocto Project Linux kernel tools for managing kernel Metadata.
1523You can find this recipe in the ``poky`` Git repository:
1524:yocto_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
1525</poky/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001526
1527Here are some basic steps you can use to work with your own sources:
1528
15291. *Create a Copy of the Kernel Recipe:* Copy the
1530 ``linux-yocto-custom.bb`` recipe to your layer and give it a
1531 meaningful name. The name should include the version of the Yocto
1532 Linux kernel you are using (e.g. ``linux-yocto-myproject_4.12.bb``,
1533 where "4.12" is the base version of the Linux kernel with which you
1534 would be working).
1535
15362. *Create a Directory for Your Patches:* In the same directory inside
1537 your layer, create a matching directory to store your patches and
1538 configuration files (e.g. ``linux-yocto-myproject``).
1539
15403. *Ensure You Have Configurations:* Make sure you have either a
1541 ``defconfig`` file or configuration fragment files in your layer.
1542 When you use the ``linux-yocto-custom.bb`` recipe, you must specify a
1543 configuration. If you do not have a ``defconfig`` file, you can run
Andrew Geisslerc926e172021-05-07 16:11:35 -05001544 the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001545
1546 $ make defconfig
1547
1548 After running the command, copy the
1549 resulting ``.config`` file to the ``files`` directory in your layer
1550 as "defconfig" and then add it to the
1551 :term:`SRC_URI` variable in the
1552 recipe.
1553
1554 Running the ``make defconfig`` command results in the default
1555 configuration for your architecture as defined by your kernel.
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001556 However, there is no guarantee that this configuration is valid for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001557 your use case, or that your board will even boot. This is
1558 particularly true for non-x86 architectures.
1559
1560 To use non-x86 ``defconfig`` files, you need to be more specific and
1561 find one that matches your board (i.e. for arm, you look in
1562 ``arch/arm/configs`` and use the one that is the best starting point
1563 for your board).
1564
15654. *Edit the Recipe:* Edit the following variables in your recipe as
1566 appropriate for your project:
1567
1568 - :term:`SRC_URI`: The
Andrew Geissler09036742021-06-25 14:25:14 -05001569 :term:`SRC_URI` should specify a Git repository that uses one of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001570 supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``,
Andrew Geissler09036742021-06-25 14:25:14 -05001571 and so forth). The :term:`SRC_URI` variable should also specify either
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001572 a ``defconfig`` file or some configuration fragment files. The
Andrew Geissler09036742021-06-25 14:25:14 -05001573 skeleton recipe provides an example :term:`SRC_URI` as a syntax
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001574 reference.
1575
1576 - :term:`LINUX_VERSION`:
1577 The Linux kernel version you are using (e.g. "4.12").
1578
1579 - :term:`LINUX_VERSION_EXTENSION`:
1580 The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the
1581 resulting kernel and visible through the ``uname`` command.
1582
1583 - :term:`SRCREV`: The commit ID
1584 from which you want to build.
1585
1586 - :term:`PR`: Treat this variable the
1587 same as you would in any other recipe. Increment the variable to
1588 indicate to the OpenEmbedded build system that the recipe has
1589 changed.
1590
Andrew Geissler09036742021-06-25 14:25:14 -05001591 - :term:`PV`: The default :term:`PV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001592 assignment is typically adequate. It combines the
Andrew Geissler09036742021-06-25 14:25:14 -05001593 :term:`LINUX_VERSION` with the Source Control Manager (SCM) revision
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001594 as derived from the :term:`SRCPV`
1595 variable. The combined results are a string with the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001596 form::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001597
1598 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
1599
Andrew Geissler09036742021-06-25 14:25:14 -05001600 While lengthy, the extra verbosity in :term:`PV` helps ensure you are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001601 using the exact sources from which you intend to build.
1602
1603 - :term:`COMPATIBLE_MACHINE`:
1604 A list of the machines supported by your new recipe. This variable
1605 in the example recipe is set by default to a regular expression
1606 that matches only the empty string, "(^$)". This default setting
1607 triggers an explicit build failure. You must change it to match a
1608 list of the machines that your new recipe supports. For example,
1609 to support the ``qemux86`` and ``qemux86-64`` machines, use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001610 following form::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001611
1612 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001613
16145. *Customize Your Recipe as Needed:* Provide further customizations to
1615 your recipe as needed just as you would customize an existing
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001616 linux-yocto recipe. See the
1617 ":ref:`ref-manual/devtool-reference:modifying an existing recipe`" section
1618 for information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001619
1620Working with Out-of-Tree Modules
1621================================
1622
1623This section describes steps to build out-of-tree modules on your target
1624and describes how to incorporate out-of-tree modules in the build.
1625
1626Building Out-of-Tree Modules on the Target
1627------------------------------------------
1628
1629While the traditional Yocto Project development model would be to
1630include kernel modules as part of the normal build process, you might
1631find it useful to build modules on the target. This could be the case if
1632your target system is capable and powerful enough to handle the
1633necessary compilation. Before deciding to build on your target, however,
1634you should consider the benefits of using a proper cross-development
1635environment from your build host.
1636
1637If you want to be able to build out-of-tree modules on the target, there
1638are some steps you need to take on the target that is running your SDK
1639image. Briefly, the ``kernel-dev`` package is installed by default on
1640all ``*.sdk`` images and the ``kernel-devsrc`` package is installed on
1641many of the ``*.sdk`` images. However, you need to create some scripts
1642prior to attempting to build the out-of-tree modules on the target that
1643is running that image.
1644
1645Prior to attempting to build the out-of-tree modules, you need to be on
1646the target as root and you need to change to the ``/usr/src/kernel``
1647directory. Next, ``make`` the scripts:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001648
1649.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001650
1651 # cd /usr/src/kernel
1652 # make scripts
1653
1654Because all SDK image recipes include ``dev-pkgs``, the
1655``kernel-dev`` packages will be installed as part of the SDK image and
1656the ``kernel-devsrc`` packages will be installed as part of applicable
1657SDK images. The SDK uses the scripts when building out-of-tree modules.
1658Once you have switched to that directory and created the scripts, you
1659should be able to build your out-of-tree modules on the target.
1660
1661Incorporating Out-of-Tree Modules
1662---------------------------------
1663
1664While it is always preferable to work with sources integrated into the
1665Linux kernel sources, if you need an external kernel module, the
1666``hello-mod.bb`` recipe is available as a template from which you can
1667create your own out-of-tree Linux kernel module recipe.
1668
1669This template recipe is located in the ``poky`` Git repository of the
Andrew Geissler595f6302022-01-24 19:11:47 +00001670Yocto Project:
1671:yocto_git:`meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
1672</poky/tree/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001673
1674To get started, copy this recipe to your layer and give it a meaningful
1675name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new
1676directory named ``files`` where you can store any source files, patches,
1677or other files necessary for building the module that do not come with
1678the sources. Finally, update the recipe as needed for the module.
1679Typically, you will need to set the following variables:
1680
1681- :term:`DESCRIPTION`
1682
1683- :term:`LICENSE* <LICENSE>`
1684
1685- :term:`SRC_URI`
1686
1687- :term:`PV`
1688
1689Depending on the build system used by the module sources, you might need
1690to make some adjustments. For example, a typical module ``Makefile``
Andrew Geisslerc926e172021-05-07 16:11:35 -05001691looks much like the one provided with the ``hello-mod`` template::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001692
1693 obj-m := hello.o
1694
1695 SRC := $(shell pwd)
1696
1697 all:
1698 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
1699
1700 modules_install:
1701 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
1702 ...
1703
1704The important point to note here is the :term:`KERNEL_SRC` variable. The
1705:ref:`module <ref-classes-module>` class sets this variable and the
1706:term:`KERNEL_PATH` variable to
1707``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build
1708information to build modules. If your module ``Makefile`` uses a
1709different variable, you might want to override the
1710:ref:`ref-tasks-compile` step, or
1711create a patch to the ``Makefile`` to work with the more typical
Andrew Geissler09036742021-06-25 14:25:14 -05001712:term:`KERNEL_SRC` or :term:`KERNEL_PATH` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001713
1714After you have prepared your recipe, you will likely want to include the
1715module in your images. To do this, see the documentation for the
1716following variables in the Yocto Project Reference Manual and set one of
1717them appropriately for your machine configuration file:
1718
1719- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
1720
1721- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
1722
1723- :term:`MACHINE_EXTRA_RDEPENDS`
1724
1725- :term:`MACHINE_EXTRA_RRECOMMENDS`
1726
1727Modules are often not required for boot and can be excluded from certain
Andrew Geisslerc926e172021-05-07 16:11:35 -05001728build configurations. The following allows for the most flexibility::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001729
1730 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
1731
1732The value is
1733derived by appending the module filename without the ``.ko`` extension
1734to the string "kernel-module-".
1735
1736Because the variable is
1737:term:`RRECOMMENDS` and not a
1738:term:`RDEPENDS` variable, the build
1739will not fail if this module is not available to include in the image.
1740
1741Inspecting Changes and Commits
1742==============================
1743
1744A common question when working with a kernel is: "What changes have been
1745applied to this tree?" Rather than using "grep" across directories to
1746see what has changed, you can use Git to inspect or search the kernel
1747tree. Using Git is an efficient way to see what has changed in the tree.
1748
1749What Changed in a Kernel?
1750-------------------------
1751
1752Following are a few examples that show how to use Git commands to
1753examine changes. These examples are by no means the only way to see
1754changes.
1755
1756.. note::
1757
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001758 In the following examples, unless you provide a commit range, ``kernel.org``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001759 history is blended with Yocto Project kernel changes. You can form
1760 ranges by using branch names from the kernel tree as the upper and
1761 lower commit markers with the Git commands. You can see the branch
1762 names through the web interface to the Yocto Project source
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001763 repositories at :yocto_git:`/`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001764
1765To see a full range of the changes, use the ``git whatchanged`` command
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001766and specify a commit range for the branch (`commit`\ ``..``\ `commit`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001767
1768Here is an example that looks at what has changed in the ``emenlow``
1769branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the
1770commit associated with the ``standard/base`` branch, while the upper
1771commit range is the commit associated with the ``standard/emenlow``
1772branch.
1773::
1774
1775 $ git whatchanged origin/standard/base..origin/standard/emenlow
1776
Andrew Geisslerc926e172021-05-07 16:11:35 -05001777To see short, one line summaries of changes use the ``git log`` command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001778
1779 $ git log --oneline origin/standard/base..origin/standard/emenlow
1780
Andrew Geisslerc926e172021-05-07 16:11:35 -05001781Use this command to see code differences for the changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001782
1783 $ git diff origin/standard/base..origin/standard/emenlow
1784
1785Use this command to see the commit log messages and the text
Andrew Geisslerc926e172021-05-07 16:11:35 -05001786differences::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001787
1788 $ git show origin/standard/base..origin/standard/emenlow
1789
1790Use this command to create individual patches for each change. Here is
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001791an example that creates patch files for each commit and places them
Andrew Geisslerc926e172021-05-07 16:11:35 -05001792in your ``Documents`` directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001793
1794 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
1795
1796Showing a Particular Feature or Branch Change
1797---------------------------------------------
1798
1799Tags in the Yocto Project kernel tree divide changes for significant
1800features or branches. The ``git show`` tag command shows changes based
Andrew Geisslerc926e172021-05-07 16:11:35 -05001801on a tag. Here is an example that shows ``systemtap`` changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001802
1803 $ git show systemtap
1804
1805You can use the ``git branch --contains`` tag command to
1806show the branches that contain a particular feature. This command shows
Andrew Geisslerc926e172021-05-07 16:11:35 -05001807the branches that contain the ``systemtap`` feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001808
1809 $ git branch --contains systemtap
1810
1811Adding Recipe-Space Kernel Features
1812===================================
1813
1814You can add kernel features in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001815:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001816by using the :term:`KERNEL_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001817variable and by specifying the feature's ``.scc`` file path in the
1818:term:`SRC_URI` statement. When you
1819add features using this method, the OpenEmbedded build system checks to
1820be sure the features are present. If the features are not present, the
1821build stops. Kernel features are the last elements processed for
1822configuring and patching the kernel. Therefore, adding features in this
1823manner is a way to enforce specific features are present and enabled
1824without needing to do a full audit of any other layer's additions to the
Andrew Geissler09036742021-06-25 14:25:14 -05001825:term:`SRC_URI` statement.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001826
1827You add a kernel feature by providing the feature as part of the
Andrew Geissler09036742021-06-25 14:25:14 -05001828:term:`KERNEL_FEATURES` variable and by providing the path to the feature's
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001829``.scc`` file, which is relative to the root of the kernel Metadata. The
1830OpenEmbedded build system searches all forms of kernel Metadata on the
Andrew Geissler09036742021-06-25 14:25:14 -05001831:term:`SRC_URI` statement regardless of whether the Metadata is in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001832"kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e.
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001833part of the kernel recipe). See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001834":ref:`kernel-dev/advanced:kernel metadata location`" section for
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001835additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001836
Andrew Geissler09036742021-06-25 14:25:14 -05001837When you specify the feature's ``.scc`` file on the :term:`SRC_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001838statement, the OpenEmbedded build system adds the directory of that
1839``.scc`` file along with all its subdirectories to the kernel feature
1840search path. Because subdirectories are searched, you can reference a
Andrew Geissler09036742021-06-25 14:25:14 -05001841single ``.scc`` file in the :term:`SRC_URI` statement to reference multiple
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001842kernel features.
1843
1844Consider the following example that adds the "test.scc" feature to the
1845build.
1846
18471. *Create the Feature File:* Create a ``.scc`` file and locate it just
1848 as you would any other patch file, ``.cfg`` file, or fetcher item you
Andrew Geissler09036742021-06-25 14:25:14 -05001849 specify in the :term:`SRC_URI` statement.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001850
1851 .. note::
1852
1853 - You must add the directory of the ``.scc`` file to the
1854 fetcher's search path in the same manner as you would add a
1855 ``.patch`` file.
1856
1857 - You can create additional ``.scc`` files beneath the directory
1858 that contains the file you are adding. All subdirectories are
1859 searched during the build as potential feature directories.
1860
1861 Continuing with the example, suppose the "test.scc" feature you are
Andrew Geisslerc926e172021-05-07 16:11:35 -05001862 adding has a ``test.scc`` file in the following directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001863
1864 my_recipe
1865 |
1866 +-linux-yocto
1867 |
1868 +-test.cfg
1869 +-test.scc
1870
1871 In this example, the
1872 ``linux-yocto`` directory has both the feature ``test.scc`` file and
1873 a similarly named configuration fragment file ``test.cfg``.
1874
18752. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
Andrew Geissler09036742021-06-25 14:25:14 -05001876 recipe's :term:`SRC_URI` statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001877
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001878 SRC_URI:append = " file://test.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001879
1880 The leading space before the path is important as the path is
1881 appended to the existing path.
1882
18833. *Specify the Feature as a Kernel Feature:* Use the
Andrew Geissler09036742021-06-25 14:25:14 -05001884 :term:`KERNEL_FEATURES` statement to specify the feature as a kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -05001885 feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001886
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001887 KERNEL_FEATURES:append = " test.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001888
1889 The OpenEmbedded build
1890 system processes the kernel feature when it builds the kernel.
1891
1892 .. note::
1893
1894 If other features are contained below "test.scc", then their
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001895 directories are relative to the directory containing the ``test.scc``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001896 file.