blob: 0cee503346f275807decf4b4ad954337e2984b7a [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
Andrew Geissler517393d2023-01-13 08:55:19 -060055#. *Initialize the BitBake Environment:*
Patrick Williams92b42cb2022-09-03 06:53:57 -050056 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
Andrew Geissler517393d2023-01-13 08:55:19 -060069#. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable
Patrick Williams2390b1b2022-11-03 13:47:49 -050070 is set to "qemux86-64", which is fine if you are building for the QEMU
71 emulator in 64-bit mode. However, if you are not, you need to set the
Andrew Geissler09036742021-06-25 14:25:14 -050072 :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
Patrick Williams2390b1b2022-11-03 13:47:49 -050073 found in the :term:`Build Directory` (i.e. ``poky/build`` in this example).
Andrew Geisslerc9f78652020-09-18 14:11:35 -050074
75 Also, since you are preparing to work on the kernel image, you need
Patrick Williams2390b1b2022-11-03 13:47:49 -050076 to set the :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable to include
77 kernel modules.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050078
79 In this example we wish to build for qemux86 so we must set the
Andrew Geissler5f350902021-07-23 13:09:54 -040080 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
Andrew Geisslerc926e172021-05-07 16:11:35 -050081 As described we do this by appending to ``conf/local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050082
83 MACHINE = "qemux86"
84 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
85
Andrew Geissler517393d2023-01-13 08:55:19 -060086#. *Create a Layer for Patches:* You need to create a layer to hold
Andrew Geisslerc9f78652020-09-18 14:11:35 -050087 patches created for the kernel image. You can use the
Andrew Geisslerc926e172021-05-07 16:11:35 -050088 ``bitbake-layers create-layer`` command as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050089
Andrew Geissler95ac1b82021-03-31 14:34:31 -050090 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -050091 $ bitbake-layers create-layer ../../meta-mylayer
92 NOTE: Starting bitbake server...
93 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
94 $
95
96 .. note::
97
98 For background information on working with common and BSP layers,
Andrew Geissler4c19ea12020-10-27 13:52:24 -050099 see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600100 ":ref:`dev-manual/layers:understanding and creating layers`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500101 section in the Yocto Project Development Tasks Manual and the
102 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board
103 Support (BSP) Developer's Guide, respectively. For information on how to
104 use the ``bitbake-layers create-layer`` command to quickly set up a layer,
105 see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600106 ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500107 section in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500108
Andrew Geissler517393d2023-01-13 08:55:19 -0600109#. *Inform the BitBake Build Environment About Your Layer:* As directed
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500110 when you created your layer, you need to add the layer to the
111 :term:`BBLAYERS` variable in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500112 ``bblayers.conf`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500113
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500114 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500115 $ bitbake-layers add-layer ../../meta-mylayer
116 NOTE: Starting bitbake server...
117 $
118
Andrew Geissler517393d2023-01-13 08:55:19 -0600119#. *Build the Clean Image:* The final step in preparing to work on the
Patrick Williams92b42cb2022-09-03 06:53:57 -0500120 kernel is to build an initial image using ``bitbake``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500121
Patrick Williams92b42cb2022-09-03 06:53:57 -0500122 $ bitbake core-image-minimal
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500123 Parsing recipes: 100% |##########################################| Time: 0:00:05
124 Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors.
125 WARNING: No packages to add, building image core-image-minimal unmodified
126 Loading cache: 100% |############################################| Time: 0:00:00
127 Loaded 1299 entries from dependency cache.
128 NOTE: Resolving any missing task queue dependencies
129 Initializing tasks: 100% |#######################################| Time: 0:00:07
130 Checking sstate mirror object availability: 100% |###############| Time: 0:00:00
131 NOTE: Executing SetScene Tasks
132 NOTE: Executing RunQueue Tasks
133 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 -0500134
135 If you were
136 building for actual hardware and not for emulation, you could flash
137 the image to a USB stick on ``/dev/sdd`` and boot your device. For an
138 example that uses a Minnowboard, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600139 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500140 Wiki page.
141
142At this point you have set up to start making modifications to the
Patrick Williams92b42cb2022-09-03 06:53:57 -0500143kernel. For a continued example, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600144":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500145section.
146
147Getting Ready for Traditional Kernel Development
148------------------------------------------------
149
150Getting ready for traditional kernel development using the Yocto Project
151involves many of the same steps as described in the previous section.
152However, you need to establish a local copy of the kernel source since
153you will be editing these files.
154
155Follow these steps to prepare to update the kernel image using
156traditional kernel development flow with the Yocto Project. Completing
157this procedure leaves you ready to make modifications to the kernel
Andrew Geissler09209ee2020-12-13 08:44:15 -0600158source as described in the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500159section:
160
Andrew Geissler517393d2023-01-13 08:55:19 -0600161#. *Initialize the BitBake Environment:* Before you can do anything
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500162 using BitBake, you need to initialize the BitBake build environment
163 by sourcing the build environment script (i.e.
164 :ref:`structure-core-script`).
165 Also, for this example, be sure that the local branch you have
166 checked out for ``poky`` is the Yocto Project &DISTRO_NAME; branch. If
167 you need to checkout out the &DISTRO_NAME; branch, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600168 ":ref:`dev-manual/start:checking out by branch in poky`"
Andrew Geissler517393d2023-01-13 08:55:19 -0600169 section in the Yocto Project Development Tasks Manual::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500170
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500171 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500172 $ git branch
173 master
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500174 * &DISTRO_NAME_NO_CAP;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500175 $ source oe-init-build-env
176
177 .. note::
178
179 The previous commands assume the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600180 :ref:`overview-manual/development-environment:yocto project source repositories`
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500181 (i.e. ``poky``) have been cloned using Git and the local repository is named
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500182 "poky".
183
Andrew Geissler517393d2023-01-13 08:55:19 -0600184#. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable is
Patrick Williams2390b1b2022-11-03 13:47:49 -0500185 set to "qemux86-64", which is fine if you are building for the QEMU emulator
186 in 64-bit mode. However, if you are not, you need to set the :term:`MACHINE`
187 variable appropriately in your ``conf/local.conf`` file found in the
188 :term:`Build Directory` (i.e. ``poky/build`` in this example).
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500189
190 Also, since you are preparing to work on the kernel image, you need
191 to set the
192 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
193 variable to include kernel modules.
194
195 In this example we wish to build for qemux86 so we must set the
Andrew Geissler5f350902021-07-23 13:09:54 -0400196 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
Andrew Geisslerc926e172021-05-07 16:11:35 -0500197 As described we do this by appending to ``conf/local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500198
199 MACHINE = "qemux86"
200 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
201
Andrew Geissler517393d2023-01-13 08:55:19 -0600202#. *Create a Layer for Patches:* You need to create a layer to hold
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500203 patches created for the kernel image. You can use the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500204 ``bitbake-layers create-layer`` command as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500205
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500206 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500207 $ bitbake-layers create-layer ../../meta-mylayer
208 NOTE: Starting bitbake server...
209 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
210
211 .. note::
212
213 For background information on working with common and BSP layers,
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500214 see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600215 ":ref:`dev-manual/layers:understanding and creating layers`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500216 section in the Yocto Project Development Tasks Manual and the
217 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board
218 Support (BSP) Developer's Guide, respectively. For information on how to
219 use the ``bitbake-layers create-layer`` command to quickly set up a layer,
220 see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600221 ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500222 section in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500223
Andrew Geissler517393d2023-01-13 08:55:19 -0600224#. *Inform the BitBake Build Environment About Your Layer:* As directed
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500225 when you created your layer, you need to add the layer to the
226 :term:`BBLAYERS` variable in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500227 ``bblayers.conf`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500228
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500229 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500230 $ bitbake-layers add-layer ../../meta-mylayer
231 NOTE: Starting bitbake server ...
232 $
233
Andrew Geissler517393d2023-01-13 08:55:19 -0600234#. *Create a Local Copy of the Kernel Git Repository:* You can find Git
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500235 repositories of supported Yocto Project kernels organized under
236 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
237 :yocto_git:`/`.
238
239 For simplicity, it is recommended that you create your copy of the
240 kernel Git repository outside of the
241 :term:`Source Directory`, which is
242 usually named ``poky``. Also, be sure you are in the
243 ``standard/base`` branch.
244
245 The following commands show how to create a local copy of the
Andrew Geissler517393d2023-01-13 08:55:19 -0600246 ``linux-yocto-4.12`` kernel and be in the ``standard/base`` branch::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500247
248 $ cd ~
249 $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base
250 Cloning into 'linux-yocto-4.12'...
251 remote: Counting objects: 6097195, done.
252 remote: Compressing objects: 100% (901026/901026), done.
253 remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256)
254 Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done.
255 Resolving deltas: 100% (5152604/5152604), done. Checking connectivity... done.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500256 Checking out files: 100% (59846/59846), done.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500257
Andrew Geissler517393d2023-01-13 08:55:19 -0600258 .. note::
259
260 The ``linux-yocto-4.12`` kernel can be used with the Yocto Project 2.4
261 release and forward.
262 You cannot use the ``linux-yocto-4.12`` kernel with releases prior to
263 Yocto Project 2.4.
264
265#. *Create a Local Copy of the Kernel Cache Git Repository:* For
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500266 simplicity, it is recommended that you create your copy of the kernel
267 cache Git repository outside of the
268 :term:`Source Directory`, which is
269 usually named ``poky``. Also, for this example, be sure you are in
270 the ``yocto-4.12`` branch.
271
272 The following commands show how to create a local copy of the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700273 ``yocto-kernel-cache`` and switch to the ``yocto-4.12`` branch::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500274
275 $ cd ~
276 $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12
277 Cloning into 'yocto-kernel-cache'...
278 remote: Counting objects: 22639, done.
279 remote: Compressing objects: 100% (9761/9761), done.
280 remote: Total 22639 (delta 12400), reused 22586 (delta 12347)
281 Receiving objects: 100% (22639/22639), 22.34 MiB | 6.27 MiB/s, done.
282 Resolving deltas: 100% (12400/12400), done.
283 Checking connectivity... done.
284
285At this point, you are ready to start making modifications to the kernel
286using traditional kernel development steps. For a continued example, see
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500287the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500288section.
289
290Creating and Preparing a Layer
291==============================
292
293If you are going to be modifying kernel recipes, it is recommended that
294you create and prepare your own layer in which to do your work. Your
295layer contains its own :term:`BitBake`
296append files (``.bbappend``) and provides a convenient mechanism to
297create your own recipe files (``.bb``) as well as store and use kernel
298patch files. For background information on working with layers, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600299":ref:`dev-manual/layers:understanding and creating layers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500300section in the Yocto Project Development Tasks Manual.
301
302.. note::
303
304 The Yocto Project comes with many tools that simplify tasks you need
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500305 to perform. One such tool is the ``bitbake-layers create-layer``
306 command, which simplifies creating a new layer. See the
Andrew Geissler517393d2023-01-13 08:55:19 -0600307 ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500308 section in the Yocto Project Development Tasks Manual for
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500309 information on how to use this script to quick set up a new layer.
310
311To better understand the layer you create for kernel development, the
312following section describes how to create a layer without the aid of
313tools. These steps assume creation of a layer named ``mylayer`` in your
314home directory:
315
Andrew Geissler517393d2023-01-13 08:55:19 -0600316#. *Create Structure*: Create the layer's structure::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500317
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500318 $ mkdir meta-mylayer
319 $ mkdir meta-mylayer/conf
320 $ mkdir meta-mylayer/recipes-kernel
321 $ mkdir meta-mylayer/recipes-kernel/linux
322 $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto
323
324 The ``conf`` directory holds your configuration files, while the
325 ``recipes-kernel`` directory holds your append file and eventual
326 patch files.
327
Andrew Geissler517393d2023-01-13 08:55:19 -0600328#. *Create the Layer Configuration File*: Move to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500329 ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500330 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500331
332 # We have a conf and classes directory, add to BBPATH
333 BBPATH .= ":${LAYERDIR}"
334
335 # We have recipes-* directories, add to BBFILES
336 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
337 ${LAYERDIR}/recipes-*/*/*.bbappend"
338
339 BBFILE_COLLECTIONS += "mylayer"
340 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
341 BBFILE_PRIORITY_mylayer = "5"
342
343 Notice ``mylayer`` as part of the last three statements.
344
Andrew Geissler517393d2023-01-13 08:55:19 -0600345#. *Create the Kernel Recipe Append File*: Move to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500346 ``meta-mylayer/recipes-kernel/linux`` directory and create the
347 kernel's append file. This example uses the ``linux-yocto-4.12``
348 kernel. Thus, the name of the append file is
Andrew Geisslerc926e172021-05-07 16:11:35 -0500349 ``linux-yocto_4.12.bbappend``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500350
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500351 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500352
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500353 SRC_URI += "file://patch-file-one.patch"
354 SRC_URI += "file://patch-file-two.patch"
355 SRC_URI += "file://patch-file-three.patch"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500356
357 The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
358 enable the OpenEmbedded build system to find patch files. For more
359 information on using append files, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600360 ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500361 section in the Yocto Project Development Tasks Manual.
362
363Modifying an Existing Recipe
364============================
365
366In many cases, you can customize an existing linux-yocto recipe to meet
367the needs of your project. Each release of the Yocto Project provides a
368few Linux kernel recipes from which you can choose. These are located in
369the :term:`Source Directory` in
370``meta/recipes-kernel/linux``.
371
372Modifying an existing recipe can consist of the following:
373
Andrew Geissler09209ee2020-12-13 08:44:15 -0600374- :ref:`kernel-dev/common:creating the append file`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500375
Andrew Geissler09209ee2020-12-13 08:44:15 -0600376- :ref:`kernel-dev/common:applying patches`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500377
Andrew Geissler09209ee2020-12-13 08:44:15 -0600378- :ref:`kernel-dev/common:changing the configuration`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500379
380Before modifying an existing recipe, be sure that you have created a
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500381minimal, custom layer from which you can work. See the
382":ref:`kernel-dev/common:creating and preparing a layer`" section for
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500383information.
384
385Creating the Append File
386------------------------
387
388You create this file in your custom layer. You also name it accordingly
389based on the linux-yocto recipe you are using. For example, if you are
Patrick Williamsac13d5f2023-11-24 18:59:46 -0600390modifying the ``meta/recipes-kernel/linux/linux-yocto_6.1.bb`` recipe,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500391the append file will typically be located as follows within your custom
392layer:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500393
394.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500395
Patrick Williamsac13d5f2023-11-24 18:59:46 -0600396 your-layer/recipes-kernel/linux/linux-yocto_6.1.bbappend
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500397
398The append file should initially extend the
399:term:`FILESPATH` search path by
400prepending the directory that contains your files to the
401:term:`FILESEXTRAPATHS`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500402variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500403
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500404 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500405
406The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``
407expands to "linux-yocto" in the current directory for this example. If
408you add any new files that modify the kernel recipe and you have
Andrew Geissler09036742021-06-25 14:25:14 -0500409extended :term:`FILESPATH` as described above, you must place the files in
Andrew Geisslerc926e172021-05-07 16:11:35 -0500410your layer in the following area::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500411
412 your-layer/recipes-kernel/linux/linux-yocto/
413
414.. note::
415
416 If you are working on a new machine Board Support Package (BSP), be
Andrew Geissler09209ee2020-12-13 08:44:15 -0600417 sure to refer to the :doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500418
419As an example, consider the following append file used by the BSPs in
420``meta-yocto-bsp``:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500421
422.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500423
Patrick Williamsac13d5f2023-11-24 18:59:46 -0600424 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500425
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700426Here are the contents of this file. Be aware that the actual commit ID
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500427strings in this example listing might be different than the actual
Andrew Geissler517393d2023-01-13 08:55:19 -0600428strings in the file from the ``meta-yocto-bsp`` layer upstream::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500429
Patrick Williamsac13d5f2023-11-24 18:59:46 -0600430 KBRANCH:genericx86 = "v6.1/standard/base"
431 KBRANCH:genericx86-64 = "v6.1/standard/base"
432 KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500433
Patrick Williamsac13d5f2023-11-24 18:59:46 -0600434 KMACHINE:genericx86 ?= "common-pc"
435 KMACHINE:genericx86-64 ?= "common-pc-64"
436 KMACHINE:beaglebone-yocto ?= "beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500437
Patrick Williamsac13d5f2023-11-24 18:59:46 -0600438 SRCREV_machine:genericx86 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86"
439 SRCREV_machine:genericx86-64 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86"
440 SRCREV_machine:beaglebone-yocto ?= "423e1996694b61fbfc8ec3bf062fc6461d64fde1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500441
Patrick Williamsac13d5f2023-11-24 18:59:46 -0600442 COMPATIBLE_MACHINE:genericx86 = "genericx86"
443 COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64"
444 COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500445
Patrick Williamsac13d5f2023-11-24 18:59:46 -0600446 LINUX_VERSION:genericx86 = "6.1.30"
447 LINUX_VERSION:genericx86-64 = "6.1.30"
448 LINUX_VERSION:beaglebone-yocto = "6.1.20"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500449
450This append file
451contains statements used to support several BSPs that ship with the
452Yocto Project. The file defines machines using the
453:term:`COMPATIBLE_MACHINE`
454variable and uses the
455:term:`KMACHINE` variable to ensure
456the machine name used by the OpenEmbedded build system maps to the
457machine name used by the Linux Yocto kernel. The file also uses the
458optional :term:`KBRANCH` variable to
459ensure the build process uses the appropriate kernel branch.
460
461Although this particular example does not use it, the
462:term:`KERNEL_FEATURES`
463variable could be used to enable features specific to the kernel. The
464append file points to specific commits in the
465:term:`Source Directory` Git repository and
466the ``meta`` Git repository branches to identify the exact kernel needed
467to build the BSP.
468
469One thing missing in this particular BSP, which you will typically need
470when developing a BSP, is the kernel configuration file (``.config``)
471for your BSP. When developing a BSP, you probably have a kernel
472configuration file or a set of kernel configuration files that, when
473taken together, define the kernel configuration for your BSP. You can
474accomplish this definition by putting the configurations in a file or a
475set of files inside a directory located at the same level as your
476kernel's append file and having the same name as the kernel's main
477recipe file. With all these conditions met, simply reference those files
478in the :term:`SRC_URI` statement in
479the append file.
480
481For example, suppose you had some configuration options in a file called
482``network_configs.cfg``. You can place that file inside a directory
Andrew Geissler09036742021-06-25 14:25:14 -0500483named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500484following to the append file. When the OpenEmbedded build system builds
Andrew Geissler517393d2023-01-13 08:55:19 -0600485the kernel, the configuration options are picked up and applied::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500486
487 SRC_URI += "file://network_configs.cfg"
488
489To group related configurations into multiple files, you perform a
490similar procedure. Here is an example that groups separate
491configurations specifically for Ethernet and graphics into their own
Andrew Geissler09036742021-06-25 14:25:14 -0500492files and adds the configurations by using a :term:`SRC_URI` statement like
Andrew Geisslerc926e172021-05-07 16:11:35 -0500493the following in your append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500494
495 SRC_URI += "file://myconfig.cfg \
496 file://eth.cfg \
497 file://gfx.cfg"
498
499Another variable you can use in your kernel recipe append file is the
500:term:`FILESEXTRAPATHS`
501variable. When you use this statement, you are extending the locations
502used by the OpenEmbedded system to look for files and patches as the
503recipe is processed.
504
505.. note::
506
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700507 There are other ways of grouping and defining configuration
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500508 options. For example, if you are working with a local clone of the
509 kernel repository, you could checkout the kernel's ``meta`` branch,
510 make your changes, and then push the changes to the local bare clone
511 of the kernel. The result is that you directly add configuration
512 options to the ``meta`` branch for your BSP. The configuration
513 options will likely end up in that location anyway if the BSP gets
514 added to the Yocto Project.
515
516 In general, however, the Yocto Project maintainers take care of
Andrew Geissler5f350902021-07-23 13:09:54 -0400517 moving the :term:`SRC_URI`-specified configuration options to the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700518 kernel's ``meta`` branch. Not only is it easier for BSP developers
519 not to have to put those configurations in the branch,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500520 but having the maintainers do it allows them to apply 'global'
521 knowledge about the kinds of common configuration options multiple
522 BSPs in the tree are typically using. This allows for promotion of
523 common configurations into common features.
524
525Applying Patches
526----------------
527
528If you have a single patch or a small series of patches that you want to
529apply to the Linux kernel source, you can do so just as you would with
530any other recipe. You first copy the patches to the path added to
531:term:`FILESEXTRAPATHS` in
532your ``.bbappend`` file as described in the previous section, and then
533reference them in :term:`SRC_URI`
534statements.
535
536For example, you can apply a three-patch series by adding the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500537lines to your linux-yocto ``.bbappend`` file in your layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500538
539 SRC_URI += "file://0001-first-change.patch"
540 SRC_URI += "file://0002-second-change.patch"
541 SRC_URI += "file://0003-third-change.patch"
542
543The next time you run BitBake to build
544the Linux kernel, BitBake detects the change in the recipe and fetches
545and applies the patches before building the kernel.
546
547For a detailed example showing how to patch the kernel using
548``devtool``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600549":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500550and
Andrew Geissler09209ee2020-12-13 08:44:15 -0600551":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500552sections.
553
554Changing the Configuration
555--------------------------
556
557You can make wholesale or incremental changes to the final ``.config``
558file used for the eventual Linux kernel configuration by including a
559``defconfig`` file and by specifying configuration fragments in the
560:term:`SRC_URI` to be applied to that
561file.
562
563If you have a complete, working Linux kernel ``.config`` file you want
564to use for the configuration, as before, copy that file to the
565appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux``
566directory, and rename the copied file to "defconfig". Then, add the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500567following lines to the linux-yocto ``.bbappend`` file in your layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500568
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500569 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500570 SRC_URI += "file://defconfig"
571
Andrew Geissler09036742021-06-25 14:25:14 -0500572The :term:`SRC_URI` tells the build system how to search
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500573for the file, while the
574:term:`FILESEXTRAPATHS`
575extends the :term:`FILESPATH`
576variable (search directories) to include the ``${PN}`` directory you
577created to hold the configuration changes.
578
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700579You can also use a regular ``defconfig`` file, as generated by the
580:ref:`ref-tasks-savedefconfig`
581task instead of a complete ``.config`` file. This only specifies the
582non-default configuration values. You need to additionally set
583:term:`KCONFIG_MODE`
584in the linux-yocto ``.bbappend`` file in your layer::
585
586 KCONFIG_MODE = "alldefconfig"
587
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500588.. note::
589
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500590 The build system applies the configurations from the ``defconfig``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500591 file before applying any subsequent configuration fragments. The
592 final kernel configuration is a combination of the configurations in
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500593 the ``defconfig`` file and any configuration fragments you provide. You need
594 to realize that if you have any configuration fragments, the build system
595 applies these on top of and after applying the existing ``defconfig`` file
596 configurations.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500597
598Generally speaking, the preferred approach is to determine the
599incremental change you want to make and add that as a configuration
600fragment. For example, if you want to add support for a basic serial
601console, create a file named ``8250.cfg`` in the ``${PN}`` directory
Andrew Geisslerc926e172021-05-07 16:11:35 -0500602with the following content (without indentation)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500603
604 CONFIG_SERIAL_8250=y
605 CONFIG_SERIAL_8250_CONSOLE=y
606 CONFIG_SERIAL_8250_PCI=y
607 CONFIG_SERIAL_8250_NR_UARTS=4
608 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
609 CONFIG_SERIAL_CORE=y
610 CONFIG_SERIAL_CORE_CONSOLE=y
611
612Next, include this
Andrew Geissler09036742021-06-25 14:25:14 -0500613configuration fragment and extend the :term:`FILESPATH` variable in your
Andrew Geisslerc926e172021-05-07 16:11:35 -0500614``.bbappend`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500615
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500616 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500617 SRC_URI += "file://8250.cfg"
618
619The next time you run BitBake to build the
620Linux kernel, BitBake detects the change in the recipe and fetches and
621applies the new configuration before building the kernel.
622
623For a detailed example showing how to configure the kernel, see the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500624":ref:`kernel-dev/common:configuring the kernel`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500625
626Using an "In-Tree"  ``defconfig`` File
627--------------------------------------
628
629It might be desirable to have kernel configuration fragment support
630through a ``defconfig`` file that is pulled from the kernel source tree
631for the configured machine. By default, the OpenEmbedded build system
632looks for ``defconfig`` files in the layer used for Metadata, which is
Andrew Geisslerc926e172021-05-07 16:11:35 -0500633"out-of-tree", and then configures them using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500634
635 SRC_URI += "file://defconfig"
636
637If you do not want to maintain copies of
638``defconfig`` files in your layer but would rather allow users to use
639the default configuration from the kernel tree and still be able to add
640configuration fragments to the
641:term:`SRC_URI` through, for example,
642append files, you can direct the OpenEmbedded build system to use a
643``defconfig`` file that is "in-tree".
644
645To specify an "in-tree" ``defconfig`` file, use the following statement
Andrew Geisslerc926e172021-05-07 16:11:35 -0500646form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500647
Andrew Geissler6aa7eec2023-03-03 12:41:14 -0600648 KBUILD_DEFCONFIG:<machine> ?= "defconfig_file"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500649
Andrew Geissler6aa7eec2023-03-03 12:41:14 -0600650Here is an example that assigns the :term:`KBUILD_DEFCONFIG` variable utilizing
651an override for the "raspberrypi2" :term:`MACHINE` and provides the path to the
652"in-tree" ``defconfig`` file to be used for a Raspberry Pi 2, which is based on
653the Broadcom 2708/2709 chipset::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500654
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500655 KBUILD_DEFCONFIG:raspberrypi2 ?= "bcm2709_defconfig"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500656
657Aside from modifying your kernel recipe and providing your own
658``defconfig`` file, you need to be sure no files or statements set
Andrew Geissler5f350902021-07-23 13:09:54 -0400659:term:`SRC_URI` to use a ``defconfig`` other than your "in-tree" file (e.g.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500660a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500661build system detects a statement that identifies an "out-of-tree"
662``defconfig`` file, that statement will override your
Andrew Geissler09036742021-06-25 14:25:14 -0500663:term:`KBUILD_DEFCONFIG` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500664
665See the
666:term:`KBUILD_DEFCONFIG`
667variable description for more information.
668
669Using ``devtool`` to Patch the Kernel
670=====================================
671
672The steps in this procedure show you how you can patch the kernel using
Patrick Williams92b42cb2022-09-03 06:53:57 -0500673``devtool``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500674
675.. note::
676
677 Before attempting this procedure, be sure you have performed the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500678 steps to get ready for updating the kernel as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600679 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500680 section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500681
682Patching the kernel involves changing or adding configurations to an
683existing kernel, changing or adding recipes to the kernel that are
684needed to support specific hardware features, or even altering the
685source code itself.
686
687This example creates a simple patch by adding some QEMU emulator console
688output at boot time through ``printk`` statements in the kernel's
689``calibrate.c`` source code file. Applying the patch and booting the
690modified image causes the added messages to appear on the emulator's
691console. The example is a continuation of the setup procedure found in
Andrew Geissler09209ee2020-12-13 08:44:15 -0600692the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500693
Andrew Geissler517393d2023-01-13 08:55:19 -0600694#. *Check Out the Kernel Source Files:* First you must use ``devtool``
Patrick Williams92b42cb2022-09-03 06:53:57 -0500695 to checkout the kernel source code in its workspace.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500696
697 .. note::
698
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500699 See this step in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600700 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500701 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500702
Andrew Geisslerc926e172021-05-07 16:11:35 -0500703 Use the following ``devtool`` command to check out the code::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500704
705 $ devtool modify linux-yocto
706
707 .. note::
708
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700709 During the checkout operation, there is a bug that could cause
710 errors such as the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500711
712 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500713
714 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
715 be3a89ce7c47178880ba7bf6293d7404 for
716 /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
717
718
719 You can safely ignore these messages. The source code is correctly
720 checked out.
721
Andrew Geissler517393d2023-01-13 08:55:19 -0600722#. *Edit the Source Files* Follow these steps to make some simple
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500723 changes to the source files:
724
Andrew Geissler517393d2023-01-13 08:55:19 -0600725 #. *Change the working directory*: In the previous step, the output
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500726 noted where you can find the source files (e.g.
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500727 ``poky_sdk/workspace/sources/linux-yocto``). Change to where the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500728 kernel source code is before making your edits to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500729 ``calibrate.c`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500730
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500731 $ cd poky_sdk/workspace/sources/linux-yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500732
Andrew Geissler517393d2023-01-13 08:55:19 -0600733 #. *Edit the source file*: Edit the ``init/calibrate.c`` file to have
Andrew Geisslerc926e172021-05-07 16:11:35 -0500734 the following changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500735
736 void calibrate_delay(void)
737 {
738 unsigned long lpj;
739 static bool printed;
740 int this_cpu = smp_processor_id();
741
742 printk("*************************************\n");
743 printk("* *\n");
744 printk("* HELLO YOCTO KERNEL *\n");
745 printk("* *\n");
746 printk("*************************************\n");
747
748 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
749 .
750 .
751 .
752
Andrew Geissler517393d2023-01-13 08:55:19 -0600753#. *Build the Updated Kernel Source:* To build the updated kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -0500754 source, use ``devtool``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500755
756 $ devtool build linux-yocto
757
Andrew Geissler517393d2023-01-13 08:55:19 -0600758#. *Create the Image With the New Kernel:* Use the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500759 ``devtool build-image`` command to create a new image that has the
Andrew Geissler517393d2023-01-13 08:55:19 -0600760 new kernel::
761
762 $ cd ~
763 $ devtool build-image core-image-minimal
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500764
765 .. note::
766
767 If the image you originally created resulted in a Wic file, you
768 can use an alternate method to create the new image with the
769 updated kernel. For an example, see the steps in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600770 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500771 Wiki Page.
772
Andrew Geissler517393d2023-01-13 08:55:19 -0600773#. *Test the New Image:* For this example, you can run the new image
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500774 using QEMU to verify your changes:
775
Andrew Geissler517393d2023-01-13 08:55:19 -0600776 #. *Boot the image*: Boot the modified image in the QEMU emulator
Andrew Geisslerc926e172021-05-07 16:11:35 -0500777 using this command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500778
779 $ runqemu qemux86
780
Andrew Geissler517393d2023-01-13 08:55:19 -0600781 #. *Verify the changes*: Log into the machine using ``root`` with no
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500782 password and then use the following shell command to scroll
783 through the console's boot output.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500784
785 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500786
787 # dmesg | less
788
789 You should see
790 the results of your ``printk`` statements as part of the output
791 when you scroll down the console window.
792
Andrew Geissler517393d2023-01-13 08:55:19 -0600793#. *Stage and commit your changes*: Change
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500794 your working directory to where you modified the ``calibrate.c`` file
Andrew Geisslerc926e172021-05-07 16:11:35 -0500795 and use these Git commands to stage and commit your changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500796
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500797 $ cd poky_sdk/workspace/sources/linux-yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500798 $ git status
799 $ git add init/calibrate.c
800 $ git commit -m "calibrate: Add printk example"
801
Andrew Geissler517393d2023-01-13 08:55:19 -0600802#. *Export the Patches and Create an Append File:* To export your
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500803 commits as patches and create a ``.bbappend`` file, use the following
Andrew Geissler517393d2023-01-13 08:55:19 -0600804 command. This example uses the previously established layer named ``meta-mylayer``::
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500805
806 $ devtool finish linux-yocto ~/meta-mylayer
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500807
808 .. note::
809
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500810 See Step 3 of the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600811 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500812 section for information on setting up this layer.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500813
814 Once the command
815 finishes, the patches and the ``.bbappend`` file are located in the
816 ``~/meta-mylayer/recipes-kernel/linux`` directory.
817
Andrew Geissler517393d2023-01-13 08:55:19 -0600818#. *Build the Image With Your Modified Kernel:* You can now build an
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500819 image that includes your kernel patches. Execute the following
Patrick Williams2390b1b2022-11-03 13:47:49 -0500820 command from your :term:`Build Directory` in the terminal
Andrew Geisslerc926e172021-05-07 16:11:35 -0500821 set up to run BitBake::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500822
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500823 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500824 $ bitbake core-image-minimal
825
826Using Traditional Kernel Development to Patch the Kernel
827========================================================
828
829The steps in this procedure show you how you can patch the kernel using
Patrick Williams92b42cb2022-09-03 06:53:57 -0500830traditional kernel development (i.e. not using ``devtool``
831as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600832":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500833section).
834
835.. note::
836
837 Before attempting this procedure, be sure you have performed the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500838 steps to get ready for updating the kernel as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600839 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500840 section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500841
842Patching the kernel involves changing or adding configurations to an
843existing kernel, changing or adding recipes to the kernel that are
844needed to support specific hardware features, or even altering the
845source code itself.
846
847The example in this section creates a simple patch by adding some QEMU
848emulator console output at boot time through ``printk`` statements in
849the kernel's ``calibrate.c`` source code file. Applying the patch and
850booting the modified image causes the added messages to appear on the
851emulator's console. The example is a continuation of the setup procedure
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500852found in the
853":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500854Section.
855
Andrew Geissler517393d2023-01-13 08:55:19 -0600856#. *Edit the Source Files* Prior to this step, you should have used Git
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500857 to create a local copy of the repository for your kernel. Assuming
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500858 you created the repository as directed in the
859 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500860 section, use the following commands to edit the ``calibrate.c`` file:
861
Andrew Geissler517393d2023-01-13 08:55:19 -0600862 #. *Change the working directory*: You need to locate the source
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500863 files in the local copy of the kernel Git repository. Change to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500864 where the kernel source code is before making your edits to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500865 ``calibrate.c`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500866
867 $ cd ~/linux-yocto-4.12/init
868
Andrew Geissler517393d2023-01-13 08:55:19 -0600869 #. *Edit the source file*: Edit the ``calibrate.c`` file to have the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500870 following changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500871
872 void calibrate_delay(void)
873 {
874 unsigned long lpj;
875 static bool printed;
876 int this_cpu = smp_processor_id();
877
878 printk("*************************************\n");
879 printk("* *\n");
880 printk("* HELLO YOCTO KERNEL *\n");
881 printk("* *\n");
882 printk("*************************************\n");
883
884 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
885 .
886 .
887 .
888
Andrew Geissler517393d2023-01-13 08:55:19 -0600889#. *Stage and Commit Your Changes:* Use standard Git commands to stage
Andrew Geisslerc926e172021-05-07 16:11:35 -0500890 and commit the changes you just made::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500891
892 $ git add calibrate.c
893 $ git commit -m "calibrate.c - Added some printk statements"
894
895 If you do not
896 stage and commit your changes, the OpenEmbedded Build System will not
897 pick up the changes.
898
Andrew Geissler517393d2023-01-13 08:55:19 -0600899#. *Update Your local.conf File to Point to Your Source Files:* In
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500900 addition to your ``local.conf`` file specifying to use
901 "kernel-modules" and the "qemux86" machine, it must also point to the
902 updated kernel source files. Add
903 :term:`SRC_URI` and
904 :term:`SRCREV` statements similar
Andrew Geisslerc926e172021-05-07 16:11:35 -0500905 to the following to your ``local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500906
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500907 $ cd poky/build/conf
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500908
Andrew Geisslerc926e172021-05-07 16:11:35 -0500909 Add the following to the ``local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500910
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500911 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 -0500912 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 -0500913 SRCREV_meta:qemux86 = "${AUTOREV}"
914 SRCREV_machine:qemux86 = "${AUTOREV}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500915
916 .. note::
917
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500918 Be sure to replace `path-to`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500919 with the pathname to your local Git repositories. Also, you must
920 be sure to specify the correct branch and machine types. For this
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500921 example, the branch is ``standard/base`` and the machine is ``qemux86``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500922
Andrew Geissler517393d2023-01-13 08:55:19 -0600923#. *Build the Image:* With the source modified, your changes staged and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500924 committed, and the ``local.conf`` file pointing to the kernel files,
Andrew Geisslerc926e172021-05-07 16:11:35 -0500925 you can now use BitBake to build the image::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500926
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500927 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500928 $ bitbake core-image-minimal
929
Andrew Geissler517393d2023-01-13 08:55:19 -0600930#. *Boot the image*: Boot the modified image in the QEMU emulator using
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500931 this command. When prompted to login to the QEMU console, use "root"
Andrew Geisslerc926e172021-05-07 16:11:35 -0500932 with no password::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500933
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500934 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500935 $ runqemu qemux86
936
Andrew Geissler517393d2023-01-13 08:55:19 -0600937#. *Look for Your Changes:* As QEMU booted, you might have seen your
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500938 changes rapidly scroll by. If not, use these commands to see your
939 changes:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500940
941 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500942
943 # dmesg | less
944
945 You should see the results of your
946 ``printk`` statements as part of the output when you scroll down the
947 console window.
948
Andrew Geissler517393d2023-01-13 08:55:19 -0600949#. *Generate the Patch File:* Once you are sure that your patch works
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500950 correctly, you can generate a ``*.patch`` file in the kernel source
Andrew Geisslerc926e172021-05-07 16:11:35 -0500951 repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500952
953 $ cd ~/linux-yocto-4.12/init
954 $ git format-patch -1
955 0001-calibrate.c-Added-some-printk-statements.patch
956
Andrew Geissler517393d2023-01-13 08:55:19 -0600957#. *Move the Patch File to Your Layer:* In order for subsequent builds
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500958 to pick up patches, you need to move the patch file you created in
959 the previous step to your layer ``meta-mylayer``. For this example,
960 the layer created earlier is located in your home directory as
961 ``meta-mylayer``. When the layer was created using the
962 ``yocto-create`` script, no additional hierarchy was created to
963 support patches. Before moving the patch file, you need to add
Andrew Geisslerc926e172021-05-07 16:11:35 -0500964 additional structure to your layer using the following commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500965
966 $ cd ~/meta-mylayer
967 $ mkdir recipes-kernel
968 $ mkdir recipes-kernel/linux
969 $ mkdir recipes-kernel/linux/linux-yocto
970
971 Once you have created this
972 hierarchy in your layer, you can move the patch file using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500973 following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500974
975 $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto
976
Andrew Geissler517393d2023-01-13 08:55:19 -0600977#. *Create the Append File:* Finally, you need to create the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500978 ``linux-yocto_4.12.bbappend`` file and insert statements that allow
979 the OpenEmbedded build system to find the patch. The append file
980 needs to be in your layer's ``recipes-kernel/linux`` directory and it
981 must be named ``linux-yocto_4.12.bbappend`` and have the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500982 contents::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500983
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500984 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500985 SRC_URI += "file://0001-calibrate.c-Added-some-printk-statements.patch"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500986
987 The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
988 enable the OpenEmbedded build system to find the patch file.
989
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500990 For more information on append files and patches, see the
991 ":ref:`kernel-dev/common:creating the append file`" and
992 ":ref:`kernel-dev/common:applying patches`" sections. You can also see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600993 ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500994 section in the Yocto Project Development Tasks Manual.
995
996 .. note::
997
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500998 To build ``core-image-minimal`` again and see the effects of your patch,
999 you can essentially eliminate the temporary source files saved in
1000 ``poky/build/tmp/work/...`` and residual effects of the build by entering
Andrew Geisslerc926e172021-05-07 16:11:35 -05001001 the following sequence of commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001002
Andrew Geissler95ac1b82021-03-31 14:34:31 -05001003 $ cd poky/build
Patrick Williamsac13d5f2023-11-24 18:59:46 -06001004 $ bitbake -c cleanall linux-yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001005 $ bitbake core-image-minimal -c cleanall
1006 $ bitbake core-image-minimal
1007 $ runqemu qemux86
1008
1009
1010Configuring the Kernel
1011======================
1012
1013Configuring the Yocto Project kernel consists of making sure the
1014``.config`` file has all the right information in it for the image you
1015are building. You can use the ``menuconfig`` tool and configuration
1016fragments to make sure your ``.config`` file is just how you need it.
1017You can also save known configurations in a ``defconfig`` file that the
1018build system can use for kernel configuration.
1019
1020This section describes how to use ``menuconfig``, create and use
1021configuration fragments, and how to interactively modify your
1022``.config`` file to create the leanest kernel configuration file
1023possible.
1024
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001025For more information on kernel configuration, see the
1026":ref:`kernel-dev/common:changing the configuration`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001027
1028Using  ``menuconfig``
1029---------------------
1030
1031The easiest way to define kernel configurations is to set them through
1032the ``menuconfig`` tool. This tool provides an interactive method with
1033which to set kernel configurations. For general information on
Patrick Williams7784c422022-11-17 07:29:11 -06001034``menuconfig``, see :wikipedia:`Menuconfig`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001035
1036To use the ``menuconfig`` tool in the Yocto Project development
1037environment, you must do the following:
1038
1039- Because you launch ``menuconfig`` using BitBake, you must be sure to
Patrick Williams2390b1b2022-11-03 13:47:49 -05001040 set up your environment by running the :ref:`structure-core-script` script
1041 found in the :term:`Build Directory`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001042
1043- You must be sure of the state of your build's configuration in the
1044 :term:`Source Directory`.
1045
Andrew Geisslerc926e172021-05-07 16:11:35 -05001046- Your build host must have the following two packages installed::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001047
1048 libncurses5-dev
1049 libtinfo-dev
1050
1051The following commands initialize the BitBake environment, run the
1052:ref:`ref-tasks-kernel_configme`
1053task, and launch ``menuconfig``. These commands assume the Source
Andrew Geisslerc926e172021-05-07 16:11:35 -05001054Directory's top-level folder is ``poky``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001055
1056 $ cd poky
1057 $ source oe-init-build-env
1058 $ bitbake linux-yocto -c kernel_configme -f
1059 $ bitbake linux-yocto -c menuconfig
1060
1061Once ``menuconfig`` comes up, its standard
1062interface allows you to interactively examine and configure all the
1063kernel configuration parameters. After making your changes, simply exit
1064the tool and save your changes to create an updated version of the
1065``.config`` configuration file.
1066
1067.. note::
1068
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001069 You can use the entire ``.config`` file as the ``defconfig`` file. For
1070 information on ``defconfig`` files, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001071 ":ref:`kernel-dev/common:changing the configuration`",
1072 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`",
1073 and ":ref:`kernel-dev/common:creating a \`\`defconfig\`\` file`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001074 sections.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001075
1076Consider an example that configures the "CONFIG_SMP" setting for the
1077``linux-yocto-4.12`` kernel.
1078
1079.. note::
1080
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001081 The OpenEmbedded build system recognizes this kernel as ``linux-yocto``
Patrick Williams8e7b46e2023-05-01 14:19:06 -05001082 through Metadata (e.g. :term:`PREFERRED_VERSION`\ ``_linux-yocto ?= "4.12%"``).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001083
1084Once ``menuconfig`` launches, use the interface to navigate through the
1085selections to find the configuration settings in which you are
1086interested. For this example, you deselect "CONFIG_SMP" by clearing the
1087"Symmetric Multi-Processing Support" option. Using the interface, you
1088can find the option under "Processor Type and Features". To deselect
1089"CONFIG_SMP", use the arrow keys to highlight "Symmetric
1090Multi-Processing Support" and enter "N" to clear the asterisk. When you
1091are finished, exit out and save the change.
1092
Patrick Williams2390b1b2022-11-03 13:47:49 -05001093Saving the selections updates the ``.config`` configuration file. This is the
1094file that the OpenEmbedded build system uses to configure the kernel during
1095the build. You can find and examine this file in the :term:`Build Directory`
1096in ``tmp/work/``. The actual ``.config`` is located in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001097area where the specific kernel is built. For example, if you were
1098building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel
1099and you were building a QEMU image targeted for ``x86`` architecture,
1100the ``.config`` file would be:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001101
1102.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001103
1104 poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
1105 ...967-r0/linux-qemux86-standard-build/.config
1106
1107.. note::
1108
1109 The previous example directory is artificially split and many of the
1110 characters in the actual filename are omitted in order to make it
1111 more readable. Also, depending on the kernel you are using, the exact
1112 pathname might differ.
1113
1114Within the ``.config`` file, you can see the kernel settings. For
1115example, the following entry shows that symmetric multi-processor
Andrew Geisslerc926e172021-05-07 16:11:35 -05001116support is not set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001117
1118 # CONFIG_SMP is not set
1119
1120A good method to isolate changed configurations is to use a combination
1121of the ``menuconfig`` tool and simple shell commands. Before changing
1122configurations with ``menuconfig``, copy the existing ``.config`` and
1123rename it to something else, use ``menuconfig`` to make as many changes
1124as you want and save them, then compare the renamed configuration file
1125against the newly created file. You can use the resulting differences as
1126your base to create configuration fragments to permanently save in your
1127kernel layer.
1128
1129.. note::
1130
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001131 Be sure to make a copy of the ``.config`` file and do not just rename it.
1132 The build system needs an existing ``.config`` file from which to work.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001133
1134Creating a  ``defconfig`` File
1135------------------------------
1136
1137A ``defconfig`` file in the context of the Yocto Project is often a
1138``.config`` file that is copied from a build or a ``defconfig`` taken
1139from the kernel tree and moved into recipe space. You can use a
1140``defconfig`` file to retain a known set of kernel configurations from
1141which the OpenEmbedded build system can draw to create the final
1142``.config`` file.
1143
1144.. note::
1145
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001146 Out-of-the-box, the Yocto Project never ships a ``defconfig`` or ``.config``
1147 file. The OpenEmbedded build system creates the final ``.config`` file used
1148 to configure the kernel.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001149
1150To create a ``defconfig``, start with a complete, working Linux kernel
1151``.config`` file. Copy that file to the appropriate
1152``${``\ :term:`PN`\ ``}`` directory in
1153your layer's ``recipes-kernel/linux`` directory, and rename the copied
1154file to "defconfig" (e.g.
1155``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then,
1156add the following lines to the linux-yocto ``.bbappend`` file in your
Andrew Geisslerc926e172021-05-07 16:11:35 -05001157layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001158
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001159 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001160 SRC_URI += "file://defconfig"
1161
1162The :term:`SRC_URI` tells the build system how to search for the file, while the
1163:term:`FILESEXTRAPATHS` extends the :term:`FILESPATH`
1164variable (search directories) to include the ``${PN}`` directory you
1165created to hold the configuration changes.
1166
1167.. note::
1168
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001169 The build system applies the configurations from the ``defconfig``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001170 file before applying any subsequent configuration fragments. The
1171 final kernel configuration is a combination of the configurations in
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001172 the ``defconfig`` file and any configuration fragments you provide. You need
1173 to realize that if you have any configuration fragments, the build system
1174 applies these on top of and after applying the existing ``defconfig`` file
1175 configurations.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001176
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001177For more information on configuring the kernel, see the
1178":ref:`kernel-dev/common:changing the configuration`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001179
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001180Creating Configuration Fragments
1181--------------------------------
1182
1183Configuration fragments are simply kernel options that appear in a file
1184placed where the OpenEmbedded build system can find and apply them. The
1185build system applies configuration fragments after applying
1186configurations from a ``defconfig`` file. Thus, the final kernel
1187configuration is a combination of the configurations in the
1188``defconfig`` file and then any configuration fragments you provide. The
1189build system applies fragments on top of and after applying the existing
1190defconfig file configurations.
1191
1192Syntactically, the configuration statement is identical to what would
1193appear in the ``.config`` file, which is in the :term:`Build Directory`.
1194
1195.. note::
1196
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001197 For more information about where the ``.config`` file is located, see the
1198 example in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001199 ":ref:`kernel-dev/common:using \`\`menuconfig\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001200 section.
1201
1202It is simple to create a configuration fragment. One method is to use
1203shell commands. For example, issuing the following from the shell
1204creates a configuration fragment file named ``my_smp.cfg`` that enables
Andrew Geisslerc926e172021-05-07 16:11:35 -05001205multi-processor support within the kernel::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001206
1207 $ echo "CONFIG_SMP=y" >> my_smp.cfg
1208
1209.. note::
1210
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001211 All configuration fragment files must use the ``.cfg`` extension in order
1212 for the OpenEmbedded build system to recognize them as a configuration
1213 fragment.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001214
1215Another method is to create a configuration fragment using the
1216differences between two configuration files: one previously created and
1217saved, and one freshly created using the ``menuconfig`` tool.
1218
1219To create a configuration fragment using this method, follow these
1220steps:
1221
Andrew Geissler517393d2023-01-13 08:55:19 -06001222#. *Complete a Build Through Kernel Configuration:* Complete a build at
Andrew Geisslerc926e172021-05-07 16:11:35 -05001223 least through the kernel configuration task as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001224
1225 $ bitbake linux-yocto -c kernel_configme -f
1226
1227 This step ensures that you create a
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001228 ``.config`` file from a known state. Because there are situations where
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001229 your build state might become unknown, it is best to run this task
1230 prior to starting ``menuconfig``.
1231
Andrew Geissler517393d2023-01-13 08:55:19 -06001232#. *Launch menuconfig:* Run the ``menuconfig`` command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001233
1234 $ bitbake linux-yocto -c menuconfig
1235
Andrew Geissler517393d2023-01-13 08:55:19 -06001236#. *Create the Configuration Fragment:* Run the ``diffconfig`` command
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001237 to prepare a configuration fragment. The resulting file
1238 ``fragment.cfg`` is placed in the
1239 ``${``\ :term:`WORKDIR`\ ``}``
Andrew Geisslerc926e172021-05-07 16:11:35 -05001240 directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001241
1242 $ bitbake linux-yocto -c diffconfig
1243
1244The ``diffconfig`` command creates a file that is a list of Linux kernel
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001245``CONFIG_`` assignments. See the
1246":ref:`kernel-dev/common:changing the configuration`" section for additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001247information on how to use the output as a configuration fragment.
1248
1249.. note::
1250
1251 You can also use this method to create configuration fragments for a
Andrew Geissler09209ee2020-12-13 08:44:15 -06001252 BSP. See the ":ref:`kernel-dev/advanced:bsp descriptions`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001253 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001254
1255Where do you put your configuration fragment files? You can place these
1256files in an area pointed to by
1257:term:`SRC_URI` as directed by your
1258``bblayers.conf`` file, which is located in your layer. The OpenEmbedded
1259build system picks up the configuration and adds it to the kernel's
1260configuration. For example, suppose you had a set of configuration
1261options in a file called ``myconfig.cfg``. If you put that file inside a
1262directory named ``linux-yocto`` that resides in the same directory as
1263the kernel's append file within your layer and then add the following
1264statements to the kernel's append file, those configuration options will
Andrew Geisslerc926e172021-05-07 16:11:35 -05001265be picked up and applied when the kernel is built::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001266
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001267 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001268 SRC_URI += "file://myconfig.cfg"
1269
1270As mentioned earlier, you can group related configurations into multiple
Andrew Geissler09036742021-06-25 14:25:14 -05001271files and name them all in the :term:`SRC_URI` statement as well. For
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001272example, you could group separate configurations specifically for
1273Ethernet and graphics into their own files and add those by using a
Andrew Geissler09036742021-06-25 14:25:14 -05001274:term:`SRC_URI` statement like the following in your append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001275
1276 SRC_URI += "file://myconfig.cfg \
1277 file://eth.cfg \
1278 file://gfx.cfg"
1279
1280Validating Configuration
1281------------------------
1282
1283You can use the
1284:ref:`ref-tasks-kernel_configcheck`
Andrew Geisslerc926e172021-05-07 16:11:35 -05001285task to provide configuration validation::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001286
1287 $ bitbake linux-yocto -c kernel_configcheck -f
1288
1289Running this task produces warnings for when a
1290requested configuration does not appear in the final ``.config`` file or
1291when you override a policy configuration in a hardware configuration
1292fragment.
1293
1294In order to run this task, you must have an existing ``.config`` file.
Andrew Geissler09209ee2020-12-13 08:44:15 -06001295See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001296information on how to create a configuration file.
1297
Patrick Williams39653562024-03-01 08:54:02 -06001298Here is sample output from the :ref:`ref-tasks-kernel_configcheck` task:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001299
1300.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001301
1302 Loading cache: 100% |########################################################| Time: 0:00:00
1303 Loaded 1275 entries from dependency cache.
1304 NOTE: Resolving any missing task queue dependencies
1305
1306 Build Configuration:
1307 .
1308 .
1309 .
1310
1311 NOTE: Executing SetScene Tasks
1312 NOTE: Executing RunQueue Tasks
1313 WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck:
1314 [kernel config]: specified values did not make it into the kernel's final configuration:
1315
1316 ---------- CONFIG_X86_TSC -----------------
1317 Config: CONFIG_X86_TSC
1318 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
1319 Requested value: CONFIG_X86_TSC=y
1320 Actual value:
1321
1322
1323 ---------- CONFIG_X86_BIGSMP -----------------
1324 Config: CONFIG_X86_BIGSMP
1325 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1326 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1327 Requested value: # CONFIG_X86_BIGSMP is not set
1328 Actual value:
1329
1330
1331 ---------- CONFIG_NR_CPUS -----------------
1332 Config: CONFIG_NR_CPUS
1333 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1334 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
1335 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1336 Requested value: CONFIG_NR_CPUS=8
1337 Actual value: CONFIG_NR_CPUS=1
1338
1339
1340 ---------- CONFIG_SCHED_SMT -----------------
1341 Config: CONFIG_SCHED_SMT
1342 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1343 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1344 Requested value: CONFIG_SCHED_SMT=y
1345 Actual value:
1346
1347
1348
1349 NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded.
1350
1351 Summary: There were 3 WARNING messages shown.
1352
1353.. note::
1354
1355 The previous output example has artificial line breaks to make it
1356 more readable.
1357
1358The output describes the various problems that you can encounter along
1359with where to find the offending configuration items. You can use the
1360information in the logs to adjust your configuration files and then
1361repeat the
1362:ref:`ref-tasks-kernel_configme`
1363and
1364:ref:`ref-tasks-kernel_configcheck`
1365tasks until they produce no warnings.
1366
1367For more information on how to use the ``menuconfig`` tool, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001368:ref:`kernel-dev/common:using \`\`menuconfig\`\`` section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001369
1370Fine-Tuning the Kernel Configuration File
1371-----------------------------------------
1372
1373You can make sure the ``.config`` file is as lean or efficient as
1374possible by reading the output of the kernel configuration fragment
1375audit, noting any issues, making changes to correct the issues, and then
1376repeating.
1377
Patrick Williams2194f502022-10-16 14:26:09 -05001378As part of the kernel build process, the :ref:`ref-tasks-kernel_configcheck` task
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001379runs. This task validates the kernel configuration by checking the final
1380``.config`` file against the input files. During the check, the task
1381produces warning messages for the following issues:
1382
Patrick Williams8e7b46e2023-05-01 14:19:06 -05001383- Requested options that did not make it into the final ``.config`` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001384
1385- Configuration items that appear twice in the same configuration
1386 fragment.
1387
1388- Configuration items tagged as "required" that were overridden.
1389
1390- A board overrides a non-board specific option.
1391
1392- Listed options not valid for the kernel being processed. In other
1393 words, the option does not appear anywhere.
1394
1395.. note::
1396
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001397 The :ref:`ref-tasks-kernel_configcheck` task can also optionally report if
1398 an option is overridden during processing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001399
1400For each output warning, a message points to the file that contains a
1401list of the options and a pointer to the configuration fragment that
1402defines them. Collectively, the files are the key to streamlining the
1403configuration.
1404
1405To streamline the configuration, do the following:
1406
Andrew Geissler517393d2023-01-13 08:55:19 -06001407#. *Use a Working Configuration:* Start with a full configuration that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001408 you know works. Be sure the configuration builds and boots
1409 successfully. Use this configuration file as your baseline.
1410
Andrew Geissler517393d2023-01-13 08:55:19 -06001411#. *Run Configure and Check Tasks:* Separately run the
Patrick Williams2194f502022-10-16 14:26:09 -05001412 :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001413
1414 $ bitbake linux-yocto -c kernel_configme -f
1415 $ bitbake linux-yocto -c kernel_configcheck -f
1416
Andrew Geissler517393d2023-01-13 08:55:19 -06001417#. *Process the Results:* Take the resulting list of files from the
Patrick Williams2194f502022-10-16 14:26:09 -05001418 :ref:`ref-tasks-kernel_configcheck` task warnings and do the following:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001419
1420 - Drop values that are redefined in the fragment but do not change
1421 the final ``.config`` file.
1422
1423 - Analyze and potentially drop values from the ``.config`` file that
1424 override required configurations.
1425
1426 - Analyze and potentially remove non-board specific options.
1427
1428 - Remove repeated and invalid options.
1429
Andrew Geissler517393d2023-01-13 08:55:19 -06001430#. *Re-Run Configure and Check Tasks:* After you have worked through the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001431 output of the kernel configuration audit, you can re-run the
Patrick Williams2194f502022-10-16 14:26:09 -05001432 :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks to see the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001433 results of your changes. If you have more issues, you can deal with
1434 them as described in the previous step.
1435
1436Iteratively working through steps two through four eventually yields a
1437minimal, streamlined configuration file. Once you have the best
1438``.config``, you can build the Linux Yocto kernel.
1439
1440Expanding Variables
1441===================
1442
1443Sometimes it is helpful to determine what a variable expands to during a
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001444build. You can examine the values of variables by examining the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001445output of the ``bitbake -e`` command. The output is long and is more
Andrew Geisslerc926e172021-05-07 16:11:35 -05001446easily managed in a text file, which allows for easy searches::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001447
1448 $ bitbake -e virtual/kernel > some_text_file
1449
1450Within the text file, you can see
1451exactly how each variable is expanded and used by the OpenEmbedded build
1452system.
1453
1454Working with a "Dirty" Kernel Version String
1455============================================
1456
1457If you build a kernel image and the version string has a "+" or a
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001458"-dirty" at the end, it means there are uncommitted modifications in the kernel's
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001459source directory. Follow these steps to clean up the version string:
1460
Andrew Geissler517393d2023-01-13 08:55:19 -06001461#. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001462 Git repository (source directory) and use the following Git command
Andrew Geisslerc926e172021-05-07 16:11:35 -05001463 to list the files that have been changed, added, or removed::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001464
1465 $ git status
1466
Andrew Geissler517393d2023-01-13 08:55:19 -06001467#. *Commit the Changes:* You should commit those changes to the kernel
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001468 source tree regardless of whether or not you will save, export, or
Andrew Geisslerc926e172021-05-07 16:11:35 -05001469 use the changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001470
1471 $ git add
1472 $ git commit -s -a -m "getting rid of -dirty"
1473
Andrew Geissler517393d2023-01-13 08:55:19 -06001474#. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001475 kernel.
1476
1477 Depending on your particular kernel development workflow, the
1478 commands you use to rebuild the kernel might differ. For information
1479 on building the kernel image when using ``devtool``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001480 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001481 section. For
Andrew Geisslerd5838332022-05-27 11:33:10 -05001482 information on building the kernel image when using BitBake, see the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001483 ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001484 section.
1485
1486Working With Your Own Sources
1487=============================
1488
1489If you cannot work with one of the Linux kernel versions supported by
1490existing linux-yocto recipes, you can still make use of the Yocto
1491Project Linux kernel tooling by working with your own sources. When you
1492use your own sources, you will not be able to leverage the existing
1493kernel :term:`Metadata` and stabilization
1494work of the linux-yocto sources. However, you will be able to manage
1495your own Metadata in the same format as the linux-yocto sources.
1496Maintaining format compatibility facilitates converging with linux-yocto
1497on a future, mutually-supported kernel version.
1498
1499To help you use your own sources, the Yocto Project provides a
Andrew Geissler595f6302022-01-24 19:11:47 +00001500linux-yocto custom recipe that uses ``kernel.org`` sources and
1501the Yocto Project Linux kernel tools for managing kernel Metadata.
1502You can find this recipe in the ``poky`` Git repository:
1503:yocto_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
1504</poky/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001505
1506Here are some basic steps you can use to work with your own sources:
1507
Andrew Geissler517393d2023-01-13 08:55:19 -06001508#. *Create a Copy of the Kernel Recipe:* Copy the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001509 ``linux-yocto-custom.bb`` recipe to your layer and give it a
1510 meaningful name. The name should include the version of the Yocto
1511 Linux kernel you are using (e.g. ``linux-yocto-myproject_4.12.bb``,
1512 where "4.12" is the base version of the Linux kernel with which you
1513 would be working).
1514
Andrew Geissler517393d2023-01-13 08:55:19 -06001515#. *Create a Directory for Your Patches:* In the same directory inside
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001516 your layer, create a matching directory to store your patches and
1517 configuration files (e.g. ``linux-yocto-myproject``).
1518
Andrew Geissler517393d2023-01-13 08:55:19 -06001519#. *Ensure You Have Configurations:* Make sure you have either a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001520 ``defconfig`` file or configuration fragment files in your layer.
1521 When you use the ``linux-yocto-custom.bb`` recipe, you must specify a
1522 configuration. If you do not have a ``defconfig`` file, you can run
Andrew Geisslerc926e172021-05-07 16:11:35 -05001523 the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001524
1525 $ make defconfig
1526
1527 After running the command, copy the
1528 resulting ``.config`` file to the ``files`` directory in your layer
1529 as "defconfig" and then add it to the
1530 :term:`SRC_URI` variable in the
1531 recipe.
1532
1533 Running the ``make defconfig`` command results in the default
1534 configuration for your architecture as defined by your kernel.
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001535 However, there is no guarantee that this configuration is valid for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001536 your use case, or that your board will even boot. This is
1537 particularly true for non-x86 architectures.
1538
1539 To use non-x86 ``defconfig`` files, you need to be more specific and
1540 find one that matches your board (i.e. for arm, you look in
1541 ``arch/arm/configs`` and use the one that is the best starting point
1542 for your board).
1543
Andrew Geissler517393d2023-01-13 08:55:19 -06001544#. *Edit the Recipe:* Edit the following variables in your recipe as
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001545 appropriate for your project:
1546
1547 - :term:`SRC_URI`: The
Andrew Geissler09036742021-06-25 14:25:14 -05001548 :term:`SRC_URI` should specify a Git repository that uses one of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001549 supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``,
Andrew Geissler09036742021-06-25 14:25:14 -05001550 and so forth). The :term:`SRC_URI` variable should also specify either
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001551 a ``defconfig`` file or some configuration fragment files. The
Andrew Geissler09036742021-06-25 14:25:14 -05001552 skeleton recipe provides an example :term:`SRC_URI` as a syntax
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001553 reference.
1554
1555 - :term:`LINUX_VERSION`:
1556 The Linux kernel version you are using (e.g. "4.12").
1557
1558 - :term:`LINUX_VERSION_EXTENSION`:
1559 The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the
1560 resulting kernel and visible through the ``uname`` command.
1561
1562 - :term:`SRCREV`: The commit ID
1563 from which you want to build.
1564
1565 - :term:`PR`: Treat this variable the
1566 same as you would in any other recipe. Increment the variable to
1567 indicate to the OpenEmbedded build system that the recipe has
1568 changed.
1569
Andrew Geissler09036742021-06-25 14:25:14 -05001570 - :term:`PV`: The default :term:`PV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001571 assignment is typically adequate. It combines the
Andrew Geissler09036742021-06-25 14:25:14 -05001572 :term:`LINUX_VERSION` with the Source Control Manager (SCM) revision
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001573 as derived from the :term:`SRCPV`
1574 variable. The combined results are a string with the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001575 form::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001576
1577 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
1578
Andrew Geissler09036742021-06-25 14:25:14 -05001579 While lengthy, the extra verbosity in :term:`PV` helps ensure you are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001580 using the exact sources from which you intend to build.
1581
1582 - :term:`COMPATIBLE_MACHINE`:
1583 A list of the machines supported by your new recipe. This variable
1584 in the example recipe is set by default to a regular expression
1585 that matches only the empty string, "(^$)". This default setting
1586 triggers an explicit build failure. You must change it to match a
1587 list of the machines that your new recipe supports. For example,
1588 to support the ``qemux86`` and ``qemux86-64`` machines, use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001589 following form::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001590
1591 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001592
Andrew Geissler517393d2023-01-13 08:55:19 -06001593#. *Customize Your Recipe as Needed:* Provide further customizations to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001594 your recipe as needed just as you would customize an existing
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001595 linux-yocto recipe. See the
1596 ":ref:`ref-manual/devtool-reference:modifying an existing recipe`" section
1597 for information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001598
1599Working with Out-of-Tree Modules
1600================================
1601
1602This section describes steps to build out-of-tree modules on your target
1603and describes how to incorporate out-of-tree modules in the build.
1604
1605Building Out-of-Tree Modules on the Target
1606------------------------------------------
1607
1608While the traditional Yocto Project development model would be to
1609include kernel modules as part of the normal build process, you might
1610find it useful to build modules on the target. This could be the case if
1611your target system is capable and powerful enough to handle the
1612necessary compilation. Before deciding to build on your target, however,
1613you should consider the benefits of using a proper cross-development
1614environment from your build host.
1615
1616If you want to be able to build out-of-tree modules on the target, there
1617are some steps you need to take on the target that is running your SDK
1618image. Briefly, the ``kernel-dev`` package is installed by default on
1619all ``*.sdk`` images and the ``kernel-devsrc`` package is installed on
1620many of the ``*.sdk`` images. However, you need to create some scripts
1621prior to attempting to build the out-of-tree modules on the target that
1622is running that image.
1623
1624Prior to attempting to build the out-of-tree modules, you need to be on
1625the target as root and you need to change to the ``/usr/src/kernel``
1626directory. Next, ``make`` the scripts:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001627
1628.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001629
1630 # cd /usr/src/kernel
1631 # make scripts
1632
1633Because all SDK image recipes include ``dev-pkgs``, the
1634``kernel-dev`` packages will be installed as part of the SDK image and
1635the ``kernel-devsrc`` packages will be installed as part of applicable
1636SDK images. The SDK uses the scripts when building out-of-tree modules.
1637Once you have switched to that directory and created the scripts, you
1638should be able to build your out-of-tree modules on the target.
1639
1640Incorporating Out-of-Tree Modules
1641---------------------------------
1642
1643While it is always preferable to work with sources integrated into the
1644Linux kernel sources, if you need an external kernel module, the
1645``hello-mod.bb`` recipe is available as a template from which you can
1646create your own out-of-tree Linux kernel module recipe.
1647
1648This template recipe is located in the ``poky`` Git repository of the
Andrew Geissler595f6302022-01-24 19:11:47 +00001649Yocto Project:
1650:yocto_git:`meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
1651</poky/tree/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001652
1653To get started, copy this recipe to your layer and give it a meaningful
1654name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new
1655directory named ``files`` where you can store any source files, patches,
1656or other files necessary for building the module that do not come with
1657the sources. Finally, update the recipe as needed for the module.
1658Typically, you will need to set the following variables:
1659
1660- :term:`DESCRIPTION`
1661
1662- :term:`LICENSE* <LICENSE>`
1663
1664- :term:`SRC_URI`
1665
1666- :term:`PV`
1667
1668Depending on the build system used by the module sources, you might need
1669to make some adjustments. For example, a typical module ``Makefile``
Andrew Geisslerc926e172021-05-07 16:11:35 -05001670looks much like the one provided with the ``hello-mod`` template::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001671
1672 obj-m := hello.o
1673
1674 SRC := $(shell pwd)
1675
1676 all:
1677 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
1678
1679 modules_install:
1680 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
1681 ...
1682
1683The important point to note here is the :term:`KERNEL_SRC` variable. The
Andrew Geissler517393d2023-01-13 08:55:19 -06001684:ref:`ref-classes-module` class sets this variable and the :term:`KERNEL_PATH`
1685variable to ``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build
1686information to build modules. If your module ``Makefile`` uses a different
1687variable, you might want to override the :ref:`ref-tasks-compile` step, or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001688create a patch to the ``Makefile`` to work with the more typical
Andrew Geissler09036742021-06-25 14:25:14 -05001689:term:`KERNEL_SRC` or :term:`KERNEL_PATH` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001690
1691After you have prepared your recipe, you will likely want to include the
1692module in your images. To do this, see the documentation for the
1693following variables in the Yocto Project Reference Manual and set one of
1694them appropriately for your machine configuration file:
1695
1696- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
1697
1698- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
1699
1700- :term:`MACHINE_EXTRA_RDEPENDS`
1701
1702- :term:`MACHINE_EXTRA_RRECOMMENDS`
1703
1704Modules are often not required for boot and can be excluded from certain
Andrew Geisslerc926e172021-05-07 16:11:35 -05001705build configurations. The following allows for the most flexibility::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001706
1707 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
1708
1709The value is
1710derived by appending the module filename without the ``.ko`` extension
1711to the string "kernel-module-".
1712
1713Because the variable is
1714:term:`RRECOMMENDS` and not a
1715:term:`RDEPENDS` variable, the build
1716will not fail if this module is not available to include in the image.
1717
1718Inspecting Changes and Commits
1719==============================
1720
1721A common question when working with a kernel is: "What changes have been
1722applied to this tree?" Rather than using "grep" across directories to
1723see what has changed, you can use Git to inspect or search the kernel
1724tree. Using Git is an efficient way to see what has changed in the tree.
1725
1726What Changed in a Kernel?
1727-------------------------
1728
Patrick Williams39653562024-03-01 08:54:02 -06001729Here are a few examples that show how to use Git commands to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001730examine changes. These examples are by no means the only way to see
1731changes.
1732
1733.. note::
1734
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001735 In the following examples, unless you provide a commit range, ``kernel.org``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001736 history is blended with Yocto Project kernel changes. You can form
1737 ranges by using branch names from the kernel tree as the upper and
1738 lower commit markers with the Git commands. You can see the branch
1739 names through the web interface to the Yocto Project source
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001740 repositories at :yocto_git:`/`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001741
1742To see a full range of the changes, use the ``git whatchanged`` command
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001743and specify a commit range for the branch (`commit`\ ``..``\ `commit`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001744
1745Here is an example that looks at what has changed in the ``emenlow``
1746branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the
1747commit associated with the ``standard/base`` branch, while the upper
1748commit range is the commit associated with the ``standard/emenlow``
Andrew Geissler517393d2023-01-13 08:55:19 -06001749branch::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001750
1751 $ git whatchanged origin/standard/base..origin/standard/emenlow
1752
Andrew Geisslerc926e172021-05-07 16:11:35 -05001753To see short, one line summaries of changes use the ``git log`` command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001754
1755 $ git log --oneline origin/standard/base..origin/standard/emenlow
1756
Andrew Geisslerc926e172021-05-07 16:11:35 -05001757Use this command to see code differences for the changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001758
1759 $ git diff origin/standard/base..origin/standard/emenlow
1760
1761Use this command to see the commit log messages and the text
Andrew Geisslerc926e172021-05-07 16:11:35 -05001762differences::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001763
1764 $ git show origin/standard/base..origin/standard/emenlow
1765
1766Use this command to create individual patches for each change. Here is
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001767an example that creates patch files for each commit and places them
Andrew Geisslerc926e172021-05-07 16:11:35 -05001768in your ``Documents`` directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001769
1770 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
1771
1772Showing a Particular Feature or Branch Change
1773---------------------------------------------
1774
1775Tags in the Yocto Project kernel tree divide changes for significant
1776features or branches. The ``git show`` tag command shows changes based
Andrew Geisslerc926e172021-05-07 16:11:35 -05001777on a tag. Here is an example that shows ``systemtap`` changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001778
1779 $ git show systemtap
1780
1781You can use the ``git branch --contains`` tag command to
1782show the branches that contain a particular feature. This command shows
Andrew Geisslerc926e172021-05-07 16:11:35 -05001783the branches that contain the ``systemtap`` feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001784
1785 $ git branch --contains systemtap
1786
1787Adding Recipe-Space Kernel Features
1788===================================
1789
1790You can add kernel features in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001791:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001792by using the :term:`KERNEL_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001793variable and by specifying the feature's ``.scc`` file path in the
1794:term:`SRC_URI` statement. When you
1795add features using this method, the OpenEmbedded build system checks to
1796be sure the features are present. If the features are not present, the
1797build stops. Kernel features are the last elements processed for
1798configuring and patching the kernel. Therefore, adding features in this
1799manner is a way to enforce specific features are present and enabled
1800without needing to do a full audit of any other layer's additions to the
Andrew Geissler09036742021-06-25 14:25:14 -05001801:term:`SRC_URI` statement.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001802
1803You add a kernel feature by providing the feature as part of the
Andrew Geissler09036742021-06-25 14:25:14 -05001804:term:`KERNEL_FEATURES` variable and by providing the path to the feature's
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001805``.scc`` file, which is relative to the root of the kernel Metadata. The
1806OpenEmbedded build system searches all forms of kernel Metadata on the
Andrew Geissler09036742021-06-25 14:25:14 -05001807:term:`SRC_URI` statement regardless of whether the Metadata is in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001808"kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e.
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001809part of the kernel recipe). See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001810":ref:`kernel-dev/advanced:kernel metadata location`" section for
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001811additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001812
Andrew Geissler09036742021-06-25 14:25:14 -05001813When you specify the feature's ``.scc`` file on the :term:`SRC_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001814statement, the OpenEmbedded build system adds the directory of that
1815``.scc`` file along with all its subdirectories to the kernel feature
1816search path. Because subdirectories are searched, you can reference a
Andrew Geissler09036742021-06-25 14:25:14 -05001817single ``.scc`` file in the :term:`SRC_URI` statement to reference multiple
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001818kernel features.
1819
1820Consider the following example that adds the "test.scc" feature to the
1821build.
1822
Andrew Geissler517393d2023-01-13 08:55:19 -06001823#. *Create the Feature File:* Create a ``.scc`` file and locate it just
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001824 as you would any other patch file, ``.cfg`` file, or fetcher item you
Andrew Geissler09036742021-06-25 14:25:14 -05001825 specify in the :term:`SRC_URI` statement.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001826
1827 .. note::
1828
1829 - You must add the directory of the ``.scc`` file to the
1830 fetcher's search path in the same manner as you would add a
1831 ``.patch`` file.
1832
1833 - You can create additional ``.scc`` files beneath the directory
1834 that contains the file you are adding. All subdirectories are
1835 searched during the build as potential feature directories.
1836
1837 Continuing with the example, suppose the "test.scc" feature you are
Andrew Geisslerc926e172021-05-07 16:11:35 -05001838 adding has a ``test.scc`` file in the following directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001839
1840 my_recipe
1841 |
1842 +-linux-yocto
1843 |
1844 +-test.cfg
1845 +-test.scc
1846
1847 In this example, the
1848 ``linux-yocto`` directory has both the feature ``test.scc`` file and
1849 a similarly named configuration fragment file ``test.cfg``.
1850
Andrew Geissler517393d2023-01-13 08:55:19 -06001851#. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
Andrew Geissler09036742021-06-25 14:25:14 -05001852 recipe's :term:`SRC_URI` statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001853
Andrew Geissler87f5cff2022-09-30 13:13:31 -05001854 SRC_URI += "file://test.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001855
1856 The leading space before the path is important as the path is
1857 appended to the existing path.
1858
Andrew Geissler517393d2023-01-13 08:55:19 -06001859#. *Specify the Feature as a Kernel Feature:* Use the
Andrew Geissler09036742021-06-25 14:25:14 -05001860 :term:`KERNEL_FEATURES` statement to specify the feature as a kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -05001861 feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001862
Andrew Geissler87f5cff2022-09-30 13:13:31 -05001863 KERNEL_FEATURES += "test.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001864
1865 The OpenEmbedded build
1866 system processes the kernel feature when it builds the kernel.
1867
1868 .. note::
1869
1870 If other features are contained below "test.scc", then their
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001871 directories are relative to the directory containing the ``test.scc``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001872 file.