blob: 1d85202df49aacc5c6eaaf7584cab6803e91b8a9 [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
390modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe,
391the 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
396 your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend
397
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
424 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend
425
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 Williams0ca19cc2021-08-16 14:03:13 -0500430 KBRANCH:genericx86 = "standard/base"
431 KBRANCH:genericx86-64 = "standard/base"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500432
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500433 KMACHINE:genericx86 ?= "common-pc"
434 KMACHINE:genericx86-64 ?= "common-pc-64"
435 KBRANCH:edgerouter = "standard/edgerouter"
436 KBRANCH:beaglebone = "standard/beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500437
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500438 SRCREV_machine:genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
439 SRCREV_machine:genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
440 SRCREV_machine:edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
441 SRCREV_machine:beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500442
443
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500444 COMPATIBLE_MACHINE:genericx86 = "genericx86"
445 COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64"
446 COMPATIBLE_MACHINE:edgerouter = "edgerouter"
447 COMPATIBLE_MACHINE:beaglebone = "beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500448
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500449 LINUX_VERSION:genericx86 = "4.12.7"
450 LINUX_VERSION:genericx86-64 = "4.12.7"
451 LINUX_VERSION:edgerouter = "4.12.10"
452 LINUX_VERSION:beaglebone = "4.12.10"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500453
454This append file
455contains statements used to support several BSPs that ship with the
456Yocto Project. The file defines machines using the
457:term:`COMPATIBLE_MACHINE`
458variable and uses the
459:term:`KMACHINE` variable to ensure
460the machine name used by the OpenEmbedded build system maps to the
461machine name used by the Linux Yocto kernel. The file also uses the
462optional :term:`KBRANCH` variable to
463ensure the build process uses the appropriate kernel branch.
464
465Although this particular example does not use it, the
466:term:`KERNEL_FEATURES`
467variable could be used to enable features specific to the kernel. The
468append file points to specific commits in the
469:term:`Source Directory` Git repository and
470the ``meta`` Git repository branches to identify the exact kernel needed
471to build the BSP.
472
473One thing missing in this particular BSP, which you will typically need
474when developing a BSP, is the kernel configuration file (``.config``)
475for your BSP. When developing a BSP, you probably have a kernel
476configuration file or a set of kernel configuration files that, when
477taken together, define the kernel configuration for your BSP. You can
478accomplish this definition by putting the configurations in a file or a
479set of files inside a directory located at the same level as your
480kernel's append file and having the same name as the kernel's main
481recipe file. With all these conditions met, simply reference those files
482in the :term:`SRC_URI` statement in
483the append file.
484
485For example, suppose you had some configuration options in a file called
486``network_configs.cfg``. You can place that file inside a directory
Andrew Geissler09036742021-06-25 14:25:14 -0500487named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500488following to the append file. When the OpenEmbedded build system builds
Andrew Geissler517393d2023-01-13 08:55:19 -0600489the kernel, the configuration options are picked up and applied::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500490
491 SRC_URI += "file://network_configs.cfg"
492
493To group related configurations into multiple files, you perform a
494similar procedure. Here is an example that groups separate
495configurations specifically for Ethernet and graphics into their own
Andrew Geissler09036742021-06-25 14:25:14 -0500496files and adds the configurations by using a :term:`SRC_URI` statement like
Andrew Geisslerc926e172021-05-07 16:11:35 -0500497the following in your append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500498
499 SRC_URI += "file://myconfig.cfg \
500 file://eth.cfg \
501 file://gfx.cfg"
502
503Another variable you can use in your kernel recipe append file is the
504:term:`FILESEXTRAPATHS`
505variable. When you use this statement, you are extending the locations
506used by the OpenEmbedded system to look for files and patches as the
507recipe is processed.
508
509.. note::
510
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700511 There are other ways of grouping and defining configuration
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500512 options. For example, if you are working with a local clone of the
513 kernel repository, you could checkout the kernel's ``meta`` branch,
514 make your changes, and then push the changes to the local bare clone
515 of the kernel. The result is that you directly add configuration
516 options to the ``meta`` branch for your BSP. The configuration
517 options will likely end up in that location anyway if the BSP gets
518 added to the Yocto Project.
519
520 In general, however, the Yocto Project maintainers take care of
Andrew Geissler5f350902021-07-23 13:09:54 -0400521 moving the :term:`SRC_URI`-specified configuration options to the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700522 kernel's ``meta`` branch. Not only is it easier for BSP developers
523 not to have to put those configurations in the branch,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500524 but having the maintainers do it allows them to apply 'global'
525 knowledge about the kinds of common configuration options multiple
526 BSPs in the tree are typically using. This allows for promotion of
527 common configurations into common features.
528
529Applying Patches
530----------------
531
532If you have a single patch or a small series of patches that you want to
533apply to the Linux kernel source, you can do so just as you would with
534any other recipe. You first copy the patches to the path added to
535:term:`FILESEXTRAPATHS` in
536your ``.bbappend`` file as described in the previous section, and then
537reference them in :term:`SRC_URI`
538statements.
539
540For example, you can apply a three-patch series by adding the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500541lines to your linux-yocto ``.bbappend`` file in your layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500542
543 SRC_URI += "file://0001-first-change.patch"
544 SRC_URI += "file://0002-second-change.patch"
545 SRC_URI += "file://0003-third-change.patch"
546
547The next time you run BitBake to build
548the Linux kernel, BitBake detects the change in the recipe and fetches
549and applies the patches before building the kernel.
550
551For a detailed example showing how to patch the kernel using
552``devtool``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600553":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500554and
Andrew Geissler09209ee2020-12-13 08:44:15 -0600555":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500556sections.
557
558Changing the Configuration
559--------------------------
560
561You can make wholesale or incremental changes to the final ``.config``
562file used for the eventual Linux kernel configuration by including a
563``defconfig`` file and by specifying configuration fragments in the
564:term:`SRC_URI` to be applied to that
565file.
566
567If you have a complete, working Linux kernel ``.config`` file you want
568to use for the configuration, as before, copy that file to the
569appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux``
570directory, and rename the copied file to "defconfig". Then, add the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500571following lines to the linux-yocto ``.bbappend`` file in your layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500572
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500573 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500574 SRC_URI += "file://defconfig"
575
Andrew Geissler09036742021-06-25 14:25:14 -0500576The :term:`SRC_URI` tells the build system how to search
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500577for the file, while the
578:term:`FILESEXTRAPATHS`
579extends the :term:`FILESPATH`
580variable (search directories) to include the ``${PN}`` directory you
581created to hold the configuration changes.
582
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700583You can also use a regular ``defconfig`` file, as generated by the
584:ref:`ref-tasks-savedefconfig`
585task instead of a complete ``.config`` file. This only specifies the
586non-default configuration values. You need to additionally set
587:term:`KCONFIG_MODE`
588in the linux-yocto ``.bbappend`` file in your layer::
589
590 KCONFIG_MODE = "alldefconfig"
591
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500592.. note::
593
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500594 The build system applies the configurations from the ``defconfig``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500595 file before applying any subsequent configuration fragments. The
596 final kernel configuration is a combination of the configurations in
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500597 the ``defconfig`` file and any configuration fragments you provide. You need
598 to realize that if you have any configuration fragments, the build system
599 applies these on top of and after applying the existing ``defconfig`` file
600 configurations.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500601
602Generally speaking, the preferred approach is to determine the
603incremental change you want to make and add that as a configuration
604fragment. For example, if you want to add support for a basic serial
605console, create a file named ``8250.cfg`` in the ``${PN}`` directory
Andrew Geisslerc926e172021-05-07 16:11:35 -0500606with the following content (without indentation)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500607
608 CONFIG_SERIAL_8250=y
609 CONFIG_SERIAL_8250_CONSOLE=y
610 CONFIG_SERIAL_8250_PCI=y
611 CONFIG_SERIAL_8250_NR_UARTS=4
612 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
613 CONFIG_SERIAL_CORE=y
614 CONFIG_SERIAL_CORE_CONSOLE=y
615
616Next, include this
Andrew Geissler09036742021-06-25 14:25:14 -0500617configuration fragment and extend the :term:`FILESPATH` variable in your
Andrew Geisslerc926e172021-05-07 16:11:35 -0500618``.bbappend`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500619
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500620 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500621 SRC_URI += "file://8250.cfg"
622
623The next time you run BitBake to build the
624Linux kernel, BitBake detects the change in the recipe and fetches and
625applies the new configuration before building the kernel.
626
627For a detailed example showing how to configure the kernel, see the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500628":ref:`kernel-dev/common:configuring the kernel`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500629
630Using an "In-Tree"  ``defconfig`` File
631--------------------------------------
632
633It might be desirable to have kernel configuration fragment support
634through a ``defconfig`` file that is pulled from the kernel source tree
635for the configured machine. By default, the OpenEmbedded build system
636looks for ``defconfig`` files in the layer used for Metadata, which is
Andrew Geisslerc926e172021-05-07 16:11:35 -0500637"out-of-tree", and then configures them using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500638
639 SRC_URI += "file://defconfig"
640
641If you do not want to maintain copies of
642``defconfig`` files in your layer but would rather allow users to use
643the default configuration from the kernel tree and still be able to add
644configuration fragments to the
645:term:`SRC_URI` through, for example,
646append files, you can direct the OpenEmbedded build system to use a
647``defconfig`` file that is "in-tree".
648
649To specify an "in-tree" ``defconfig`` file, use the following statement
Andrew Geisslerc926e172021-05-07 16:11:35 -0500650form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500651
Andrew Geissler6aa7eec2023-03-03 12:41:14 -0600652 KBUILD_DEFCONFIG:<machine> ?= "defconfig_file"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500653
Andrew Geissler6aa7eec2023-03-03 12:41:14 -0600654Here is an example that assigns the :term:`KBUILD_DEFCONFIG` variable utilizing
655an override for the "raspberrypi2" :term:`MACHINE` and provides the path to the
656"in-tree" ``defconfig`` file to be used for a Raspberry Pi 2, which is based on
657the Broadcom 2708/2709 chipset::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500658
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500659 KBUILD_DEFCONFIG:raspberrypi2 ?= "bcm2709_defconfig"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500660
661Aside from modifying your kernel recipe and providing your own
662``defconfig`` file, you need to be sure no files or statements set
Andrew Geissler5f350902021-07-23 13:09:54 -0400663:term:`SRC_URI` to use a ``defconfig`` other than your "in-tree" file (e.g.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500664a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500665build system detects a statement that identifies an "out-of-tree"
666``defconfig`` file, that statement will override your
Andrew Geissler09036742021-06-25 14:25:14 -0500667:term:`KBUILD_DEFCONFIG` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500668
669See the
670:term:`KBUILD_DEFCONFIG`
671variable description for more information.
672
673Using ``devtool`` to Patch the Kernel
674=====================================
675
676The steps in this procedure show you how you can patch the kernel using
Patrick Williams92b42cb2022-09-03 06:53:57 -0500677``devtool``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500678
679.. note::
680
681 Before attempting this procedure, be sure you have performed the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500682 steps to get ready for updating the kernel as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600683 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500684 section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500685
686Patching the kernel involves changing or adding configurations to an
687existing kernel, changing or adding recipes to the kernel that are
688needed to support specific hardware features, or even altering the
689source code itself.
690
691This example creates a simple patch by adding some QEMU emulator console
692output at boot time through ``printk`` statements in the kernel's
693``calibrate.c`` source code file. Applying the patch and booting the
694modified image causes the added messages to appear on the emulator's
695console. The example is a continuation of the setup procedure found in
Andrew Geissler09209ee2020-12-13 08:44:15 -0600696the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500697
Andrew Geissler517393d2023-01-13 08:55:19 -0600698#. *Check Out the Kernel Source Files:* First you must use ``devtool``
Patrick Williams92b42cb2022-09-03 06:53:57 -0500699 to checkout the kernel source code in its workspace.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500700
701 .. note::
702
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500703 See this step in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600704 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500705 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500706
Andrew Geisslerc926e172021-05-07 16:11:35 -0500707 Use the following ``devtool`` command to check out the code::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500708
709 $ devtool modify linux-yocto
710
711 .. note::
712
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700713 During the checkout operation, there is a bug that could cause
714 errors such as the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500715
716 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500717
718 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
719 be3a89ce7c47178880ba7bf6293d7404 for
720 /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
721
722
723 You can safely ignore these messages. The source code is correctly
724 checked out.
725
Andrew Geissler517393d2023-01-13 08:55:19 -0600726#. *Edit the Source Files* Follow these steps to make some simple
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500727 changes to the source files:
728
Andrew Geissler517393d2023-01-13 08:55:19 -0600729 #. *Change the working directory*: In the previous step, the output
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500730 noted where you can find the source files (e.g.
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500731 ``poky_sdk/workspace/sources/linux-yocto``). Change to where the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500732 kernel source code is before making your edits to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500733 ``calibrate.c`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500734
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500735 $ cd poky_sdk/workspace/sources/linux-yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500736
Andrew Geissler517393d2023-01-13 08:55:19 -0600737 #. *Edit the source file*: Edit the ``init/calibrate.c`` file to have
Andrew Geisslerc926e172021-05-07 16:11:35 -0500738 the following changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500739
740 void calibrate_delay(void)
741 {
742 unsigned long lpj;
743 static bool printed;
744 int this_cpu = smp_processor_id();
745
746 printk("*************************************\n");
747 printk("* *\n");
748 printk("* HELLO YOCTO KERNEL *\n");
749 printk("* *\n");
750 printk("*************************************\n");
751
752 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
753 .
754 .
755 .
756
Andrew Geissler517393d2023-01-13 08:55:19 -0600757#. *Build the Updated Kernel Source:* To build the updated kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -0500758 source, use ``devtool``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500759
760 $ devtool build linux-yocto
761
Andrew Geissler517393d2023-01-13 08:55:19 -0600762#. *Create the Image With the New Kernel:* Use the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500763 ``devtool build-image`` command to create a new image that has the
Andrew Geissler517393d2023-01-13 08:55:19 -0600764 new kernel::
765
766 $ cd ~
767 $ devtool build-image core-image-minimal
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500768
769 .. note::
770
771 If the image you originally created resulted in a Wic file, you
772 can use an alternate method to create the new image with the
773 updated kernel. For an example, see the steps in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600774 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500775 Wiki Page.
776
Andrew Geissler517393d2023-01-13 08:55:19 -0600777#. *Test the New Image:* For this example, you can run the new image
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500778 using QEMU to verify your changes:
779
Andrew Geissler517393d2023-01-13 08:55:19 -0600780 #. *Boot the image*: Boot the modified image in the QEMU emulator
Andrew Geisslerc926e172021-05-07 16:11:35 -0500781 using this command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500782
783 $ runqemu qemux86
784
Andrew Geissler517393d2023-01-13 08:55:19 -0600785 #. *Verify the changes*: Log into the machine using ``root`` with no
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500786 password and then use the following shell command to scroll
787 through the console's boot output.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500788
789 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500790
791 # dmesg | less
792
793 You should see
794 the results of your ``printk`` statements as part of the output
795 when you scroll down the console window.
796
Andrew Geissler517393d2023-01-13 08:55:19 -0600797#. *Stage and commit your changes*: Change
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500798 your working directory to where you modified the ``calibrate.c`` file
Andrew Geisslerc926e172021-05-07 16:11:35 -0500799 and use these Git commands to stage and commit your changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500800
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500801 $ cd poky_sdk/workspace/sources/linux-yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500802 $ git status
803 $ git add init/calibrate.c
804 $ git commit -m "calibrate: Add printk example"
805
Andrew Geissler517393d2023-01-13 08:55:19 -0600806#. *Export the Patches and Create an Append File:* To export your
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500807 commits as patches and create a ``.bbappend`` file, use the following
Andrew Geissler517393d2023-01-13 08:55:19 -0600808 command. This example uses the previously established layer named ``meta-mylayer``::
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500809
810 $ devtool finish linux-yocto ~/meta-mylayer
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500811
812 .. note::
813
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500814 See Step 3 of the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600815 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500816 section for information on setting up this layer.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500817
818 Once the command
819 finishes, the patches and the ``.bbappend`` file are located in the
820 ``~/meta-mylayer/recipes-kernel/linux`` directory.
821
Andrew Geissler517393d2023-01-13 08:55:19 -0600822#. *Build the Image With Your Modified Kernel:* You can now build an
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500823 image that includes your kernel patches. Execute the following
Patrick Williams2390b1b2022-11-03 13:47:49 -0500824 command from your :term:`Build Directory` in the terminal
Andrew Geisslerc926e172021-05-07 16:11:35 -0500825 set up to run BitBake::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500826
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500827 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500828 $ bitbake core-image-minimal
829
830Using Traditional Kernel Development to Patch the Kernel
831========================================================
832
833The steps in this procedure show you how you can patch the kernel using
Patrick Williams92b42cb2022-09-03 06:53:57 -0500834traditional kernel development (i.e. not using ``devtool``
835as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600836":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500837section).
838
839.. note::
840
841 Before attempting this procedure, be sure you have performed the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500842 steps to get ready for updating the kernel as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600843 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500844 section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500845
846Patching the kernel involves changing or adding configurations to an
847existing kernel, changing or adding recipes to the kernel that are
848needed to support specific hardware features, or even altering the
849source code itself.
850
851The example in this section creates a simple patch by adding some QEMU
852emulator console output at boot time through ``printk`` statements in
853the kernel's ``calibrate.c`` source code file. Applying the patch and
854booting the modified image causes the added messages to appear on the
855emulator's console. The example is a continuation of the setup procedure
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500856found in the
857":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500858Section.
859
Andrew Geissler517393d2023-01-13 08:55:19 -0600860#. *Edit the Source Files* Prior to this step, you should have used Git
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500861 to create a local copy of the repository for your kernel. Assuming
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500862 you created the repository as directed in the
863 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500864 section, use the following commands to edit the ``calibrate.c`` file:
865
Andrew Geissler517393d2023-01-13 08:55:19 -0600866 #. *Change the working directory*: You need to locate the source
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500867 files in the local copy of the kernel Git repository. Change to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500868 where the kernel source code is before making your edits to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500869 ``calibrate.c`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500870
871 $ cd ~/linux-yocto-4.12/init
872
Andrew Geissler517393d2023-01-13 08:55:19 -0600873 #. *Edit the source file*: Edit the ``calibrate.c`` file to have the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500874 following changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500875
876 void calibrate_delay(void)
877 {
878 unsigned long lpj;
879 static bool printed;
880 int this_cpu = smp_processor_id();
881
882 printk("*************************************\n");
883 printk("* *\n");
884 printk("* HELLO YOCTO KERNEL *\n");
885 printk("* *\n");
886 printk("*************************************\n");
887
888 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
889 .
890 .
891 .
892
Andrew Geissler517393d2023-01-13 08:55:19 -0600893#. *Stage and Commit Your Changes:* Use standard Git commands to stage
Andrew Geisslerc926e172021-05-07 16:11:35 -0500894 and commit the changes you just made::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500895
896 $ git add calibrate.c
897 $ git commit -m "calibrate.c - Added some printk statements"
898
899 If you do not
900 stage and commit your changes, the OpenEmbedded Build System will not
901 pick up the changes.
902
Andrew Geissler517393d2023-01-13 08:55:19 -0600903#. *Update Your local.conf File to Point to Your Source Files:* In
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500904 addition to your ``local.conf`` file specifying to use
905 "kernel-modules" and the "qemux86" machine, it must also point to the
906 updated kernel source files. Add
907 :term:`SRC_URI` and
908 :term:`SRCREV` statements similar
Andrew Geisslerc926e172021-05-07 16:11:35 -0500909 to the following to your ``local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500910
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500911 $ cd poky/build/conf
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500912
Andrew Geisslerc926e172021-05-07 16:11:35 -0500913 Add the following to the ``local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500914
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500915 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 -0500916 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 -0500917 SRCREV_meta:qemux86 = "${AUTOREV}"
918 SRCREV_machine:qemux86 = "${AUTOREV}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500919
920 .. note::
921
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500922 Be sure to replace `path-to`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500923 with the pathname to your local Git repositories. Also, you must
924 be sure to specify the correct branch and machine types. For this
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500925 example, the branch is ``standard/base`` and the machine is ``qemux86``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500926
Andrew Geissler517393d2023-01-13 08:55:19 -0600927#. *Build the Image:* With the source modified, your changes staged and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500928 committed, and the ``local.conf`` file pointing to the kernel files,
Andrew Geisslerc926e172021-05-07 16:11:35 -0500929 you can now use BitBake to build the image::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500930
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500931 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500932 $ bitbake core-image-minimal
933
Andrew Geissler517393d2023-01-13 08:55:19 -0600934#. *Boot the image*: Boot the modified image in the QEMU emulator using
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500935 this command. When prompted to login to the QEMU console, use "root"
Andrew Geisslerc926e172021-05-07 16:11:35 -0500936 with no password::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500937
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500938 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500939 $ runqemu qemux86
940
Andrew Geissler517393d2023-01-13 08:55:19 -0600941#. *Look for Your Changes:* As QEMU booted, you might have seen your
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500942 changes rapidly scroll by. If not, use these commands to see your
943 changes:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500944
945 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500946
947 # dmesg | less
948
949 You should see the results of your
950 ``printk`` statements as part of the output when you scroll down the
951 console window.
952
Andrew Geissler517393d2023-01-13 08:55:19 -0600953#. *Generate the Patch File:* Once you are sure that your patch works
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500954 correctly, you can generate a ``*.patch`` file in the kernel source
Andrew Geisslerc926e172021-05-07 16:11:35 -0500955 repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500956
957 $ cd ~/linux-yocto-4.12/init
958 $ git format-patch -1
959 0001-calibrate.c-Added-some-printk-statements.patch
960
Andrew Geissler517393d2023-01-13 08:55:19 -0600961#. *Move the Patch File to Your Layer:* In order for subsequent builds
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500962 to pick up patches, you need to move the patch file you created in
963 the previous step to your layer ``meta-mylayer``. For this example,
964 the layer created earlier is located in your home directory as
965 ``meta-mylayer``. When the layer was created using the
966 ``yocto-create`` script, no additional hierarchy was created to
967 support patches. Before moving the patch file, you need to add
Andrew Geisslerc926e172021-05-07 16:11:35 -0500968 additional structure to your layer using the following commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500969
970 $ cd ~/meta-mylayer
971 $ mkdir recipes-kernel
972 $ mkdir recipes-kernel/linux
973 $ mkdir recipes-kernel/linux/linux-yocto
974
975 Once you have created this
976 hierarchy in your layer, you can move the patch file using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500977 following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500978
979 $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto
980
Andrew Geissler517393d2023-01-13 08:55:19 -0600981#. *Create the Append File:* Finally, you need to create the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500982 ``linux-yocto_4.12.bbappend`` file and insert statements that allow
983 the OpenEmbedded build system to find the patch. The append file
984 needs to be in your layer's ``recipes-kernel/linux`` directory and it
985 must be named ``linux-yocto_4.12.bbappend`` and have the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500986 contents::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500987
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500988 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500989 SRC_URI += "file://0001-calibrate.c-Added-some-printk-statements.patch"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500990
991 The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
992 enable the OpenEmbedded build system to find the patch file.
993
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500994 For more information on append files and patches, see the
995 ":ref:`kernel-dev/common:creating the append file`" and
996 ":ref:`kernel-dev/common:applying patches`" sections. You can also see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600997 ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500998 section in the Yocto Project Development Tasks Manual.
999
1000 .. note::
1001
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001002 To build ``core-image-minimal`` again and see the effects of your patch,
1003 you can essentially eliminate the temporary source files saved in
1004 ``poky/build/tmp/work/...`` and residual effects of the build by entering
Andrew Geisslerc926e172021-05-07 16:11:35 -05001005 the following sequence of commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001006
Andrew Geissler95ac1b82021-03-31 14:34:31 -05001007 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001008 $ bitbake -c cleanall yocto-linux
1009 $ bitbake core-image-minimal -c cleanall
1010 $ bitbake core-image-minimal
1011 $ runqemu qemux86
1012
1013
1014Configuring the Kernel
1015======================
1016
1017Configuring the Yocto Project kernel consists of making sure the
1018``.config`` file has all the right information in it for the image you
1019are building. You can use the ``menuconfig`` tool and configuration
1020fragments to make sure your ``.config`` file is just how you need it.
1021You can also save known configurations in a ``defconfig`` file that the
1022build system can use for kernel configuration.
1023
1024This section describes how to use ``menuconfig``, create and use
1025configuration fragments, and how to interactively modify your
1026``.config`` file to create the leanest kernel configuration file
1027possible.
1028
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001029For more information on kernel configuration, see the
1030":ref:`kernel-dev/common:changing the configuration`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001031
1032Using  ``menuconfig``
1033---------------------
1034
1035The easiest way to define kernel configurations is to set them through
1036the ``menuconfig`` tool. This tool provides an interactive method with
1037which to set kernel configurations. For general information on
Patrick Williams7784c422022-11-17 07:29:11 -06001038``menuconfig``, see :wikipedia:`Menuconfig`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001039
1040To use the ``menuconfig`` tool in the Yocto Project development
1041environment, you must do the following:
1042
1043- Because you launch ``menuconfig`` using BitBake, you must be sure to
Patrick Williams2390b1b2022-11-03 13:47:49 -05001044 set up your environment by running the :ref:`structure-core-script` script
1045 found in the :term:`Build Directory`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001046
1047- You must be sure of the state of your build's configuration in the
1048 :term:`Source Directory`.
1049
Andrew Geisslerc926e172021-05-07 16:11:35 -05001050- Your build host must have the following two packages installed::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001051
1052 libncurses5-dev
1053 libtinfo-dev
1054
1055The following commands initialize the BitBake environment, run the
1056:ref:`ref-tasks-kernel_configme`
1057task, and launch ``menuconfig``. These commands assume the Source
Andrew Geisslerc926e172021-05-07 16:11:35 -05001058Directory's top-level folder is ``poky``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001059
1060 $ cd poky
1061 $ source oe-init-build-env
1062 $ bitbake linux-yocto -c kernel_configme -f
1063 $ bitbake linux-yocto -c menuconfig
1064
1065Once ``menuconfig`` comes up, its standard
1066interface allows you to interactively examine and configure all the
1067kernel configuration parameters. After making your changes, simply exit
1068the tool and save your changes to create an updated version of the
1069``.config`` configuration file.
1070
1071.. note::
1072
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001073 You can use the entire ``.config`` file as the ``defconfig`` file. For
1074 information on ``defconfig`` files, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001075 ":ref:`kernel-dev/common:changing the configuration`",
1076 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`",
1077 and ":ref:`kernel-dev/common:creating a \`\`defconfig\`\` file`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001078 sections.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001079
1080Consider an example that configures the "CONFIG_SMP" setting for the
1081``linux-yocto-4.12`` kernel.
1082
1083.. note::
1084
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001085 The OpenEmbedded build system recognizes this kernel as ``linux-yocto``
Patrick Williams8e7b46e2023-05-01 14:19:06 -05001086 through Metadata (e.g. :term:`PREFERRED_VERSION`\ ``_linux-yocto ?= "4.12%"``).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001087
1088Once ``menuconfig`` launches, use the interface to navigate through the
1089selections to find the configuration settings in which you are
1090interested. For this example, you deselect "CONFIG_SMP" by clearing the
1091"Symmetric Multi-Processing Support" option. Using the interface, you
1092can find the option under "Processor Type and Features". To deselect
1093"CONFIG_SMP", use the arrow keys to highlight "Symmetric
1094Multi-Processing Support" and enter "N" to clear the asterisk. When you
1095are finished, exit out and save the change.
1096
Patrick Williams2390b1b2022-11-03 13:47:49 -05001097Saving the selections updates the ``.config`` configuration file. This is the
1098file that the OpenEmbedded build system uses to configure the kernel during
1099the build. You can find and examine this file in the :term:`Build Directory`
1100in ``tmp/work/``. The actual ``.config`` is located in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001101area where the specific kernel is built. For example, if you were
1102building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel
1103and you were building a QEMU image targeted for ``x86`` architecture,
1104the ``.config`` file would be:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001105
1106.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001107
1108 poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
1109 ...967-r0/linux-qemux86-standard-build/.config
1110
1111.. note::
1112
1113 The previous example directory is artificially split and many of the
1114 characters in the actual filename are omitted in order to make it
1115 more readable. Also, depending on the kernel you are using, the exact
1116 pathname might differ.
1117
1118Within the ``.config`` file, you can see the kernel settings. For
1119example, the following entry shows that symmetric multi-processor
Andrew Geisslerc926e172021-05-07 16:11:35 -05001120support is not set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001121
1122 # CONFIG_SMP is not set
1123
1124A good method to isolate changed configurations is to use a combination
1125of the ``menuconfig`` tool and simple shell commands. Before changing
1126configurations with ``menuconfig``, copy the existing ``.config`` and
1127rename it to something else, use ``menuconfig`` to make as many changes
1128as you want and save them, then compare the renamed configuration file
1129against the newly created file. You can use the resulting differences as
1130your base to create configuration fragments to permanently save in your
1131kernel layer.
1132
1133.. note::
1134
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001135 Be sure to make a copy of the ``.config`` file and do not just rename it.
1136 The build system needs an existing ``.config`` file from which to work.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001137
1138Creating a  ``defconfig`` File
1139------------------------------
1140
1141A ``defconfig`` file in the context of the Yocto Project is often a
1142``.config`` file that is copied from a build or a ``defconfig`` taken
1143from the kernel tree and moved into recipe space. You can use a
1144``defconfig`` file to retain a known set of kernel configurations from
1145which the OpenEmbedded build system can draw to create the final
1146``.config`` file.
1147
1148.. note::
1149
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001150 Out-of-the-box, the Yocto Project never ships a ``defconfig`` or ``.config``
1151 file. The OpenEmbedded build system creates the final ``.config`` file used
1152 to configure the kernel.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001153
1154To create a ``defconfig``, start with a complete, working Linux kernel
1155``.config`` file. Copy that file to the appropriate
1156``${``\ :term:`PN`\ ``}`` directory in
1157your layer's ``recipes-kernel/linux`` directory, and rename the copied
1158file to "defconfig" (e.g.
1159``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then,
1160add the following lines to the linux-yocto ``.bbappend`` file in your
Andrew Geisslerc926e172021-05-07 16:11:35 -05001161layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001162
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001163 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001164 SRC_URI += "file://defconfig"
1165
1166The :term:`SRC_URI` tells the build system how to search for the file, while the
1167:term:`FILESEXTRAPATHS` extends the :term:`FILESPATH`
1168variable (search directories) to include the ``${PN}`` directory you
1169created to hold the configuration changes.
1170
1171.. note::
1172
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001173 The build system applies the configurations from the ``defconfig``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001174 file before applying any subsequent configuration fragments. The
1175 final kernel configuration is a combination of the configurations in
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001176 the ``defconfig`` file and any configuration fragments you provide. You need
1177 to realize that if you have any configuration fragments, the build system
1178 applies these on top of and after applying the existing ``defconfig`` file
1179 configurations.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001180
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001181For more information on configuring the kernel, see the
1182":ref:`kernel-dev/common:changing the configuration`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001183
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001184Creating Configuration Fragments
1185--------------------------------
1186
1187Configuration fragments are simply kernel options that appear in a file
1188placed where the OpenEmbedded build system can find and apply them. The
1189build system applies configuration fragments after applying
1190configurations from a ``defconfig`` file. Thus, the final kernel
1191configuration is a combination of the configurations in the
1192``defconfig`` file and then any configuration fragments you provide. The
1193build system applies fragments on top of and after applying the existing
1194defconfig file configurations.
1195
1196Syntactically, the configuration statement is identical to what would
1197appear in the ``.config`` file, which is in the :term:`Build Directory`.
1198
1199.. note::
1200
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001201 For more information about where the ``.config`` file is located, see the
1202 example in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001203 ":ref:`kernel-dev/common:using \`\`menuconfig\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001204 section.
1205
1206It is simple to create a configuration fragment. One method is to use
1207shell commands. For example, issuing the following from the shell
1208creates a configuration fragment file named ``my_smp.cfg`` that enables
Andrew Geisslerc926e172021-05-07 16:11:35 -05001209multi-processor support within the kernel::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001210
1211 $ echo "CONFIG_SMP=y" >> my_smp.cfg
1212
1213.. note::
1214
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001215 All configuration fragment files must use the ``.cfg`` extension in order
1216 for the OpenEmbedded build system to recognize them as a configuration
1217 fragment.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001218
1219Another method is to create a configuration fragment using the
1220differences between two configuration files: one previously created and
1221saved, and one freshly created using the ``menuconfig`` tool.
1222
1223To create a configuration fragment using this method, follow these
1224steps:
1225
Andrew Geissler517393d2023-01-13 08:55:19 -06001226#. *Complete a Build Through Kernel Configuration:* Complete a build at
Andrew Geisslerc926e172021-05-07 16:11:35 -05001227 least through the kernel configuration task as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001228
1229 $ bitbake linux-yocto -c kernel_configme -f
1230
1231 This step ensures that you create a
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001232 ``.config`` file from a known state. Because there are situations where
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001233 your build state might become unknown, it is best to run this task
1234 prior to starting ``menuconfig``.
1235
Andrew Geissler517393d2023-01-13 08:55:19 -06001236#. *Launch menuconfig:* Run the ``menuconfig`` command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001237
1238 $ bitbake linux-yocto -c menuconfig
1239
Andrew Geissler517393d2023-01-13 08:55:19 -06001240#. *Create the Configuration Fragment:* Run the ``diffconfig`` command
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001241 to prepare a configuration fragment. The resulting file
1242 ``fragment.cfg`` is placed in the
1243 ``${``\ :term:`WORKDIR`\ ``}``
Andrew Geisslerc926e172021-05-07 16:11:35 -05001244 directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001245
1246 $ bitbake linux-yocto -c diffconfig
1247
1248The ``diffconfig`` command creates a file that is a list of Linux kernel
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001249``CONFIG_`` assignments. See the
1250":ref:`kernel-dev/common:changing the configuration`" section for additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001251information on how to use the output as a configuration fragment.
1252
1253.. note::
1254
1255 You can also use this method to create configuration fragments for a
Andrew Geissler09209ee2020-12-13 08:44:15 -06001256 BSP. See the ":ref:`kernel-dev/advanced:bsp descriptions`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001257 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001258
1259Where do you put your configuration fragment files? You can place these
1260files in an area pointed to by
1261:term:`SRC_URI` as directed by your
1262``bblayers.conf`` file, which is located in your layer. The OpenEmbedded
1263build system picks up the configuration and adds it to the kernel's
1264configuration. For example, suppose you had a set of configuration
1265options in a file called ``myconfig.cfg``. If you put that file inside a
1266directory named ``linux-yocto`` that resides in the same directory as
1267the kernel's append file within your layer and then add the following
1268statements to the kernel's append file, those configuration options will
Andrew Geisslerc926e172021-05-07 16:11:35 -05001269be picked up and applied when the kernel is built::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001270
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001271 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001272 SRC_URI += "file://myconfig.cfg"
1273
1274As mentioned earlier, you can group related configurations into multiple
Andrew Geissler09036742021-06-25 14:25:14 -05001275files and name them all in the :term:`SRC_URI` statement as well. For
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001276example, you could group separate configurations specifically for
1277Ethernet and graphics into their own files and add those by using a
Andrew Geissler09036742021-06-25 14:25:14 -05001278:term:`SRC_URI` statement like the following in your append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001279
1280 SRC_URI += "file://myconfig.cfg \
1281 file://eth.cfg \
1282 file://gfx.cfg"
1283
1284Validating Configuration
1285------------------------
1286
1287You can use the
1288:ref:`ref-tasks-kernel_configcheck`
Andrew Geisslerc926e172021-05-07 16:11:35 -05001289task to provide configuration validation::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001290
1291 $ bitbake linux-yocto -c kernel_configcheck -f
1292
1293Running this task produces warnings for when a
1294requested configuration does not appear in the final ``.config`` file or
1295when you override a policy configuration in a hardware configuration
1296fragment.
1297
1298In order to run this task, you must have an existing ``.config`` file.
Andrew Geissler09209ee2020-12-13 08:44:15 -06001299See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001300information on how to create a configuration file.
1301
Patrick Williams2194f502022-10-16 14:26:09 -05001302Following is sample output from the :ref:`ref-tasks-kernel_configcheck` task:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001303
1304.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001305
1306 Loading cache: 100% |########################################################| Time: 0:00:00
1307 Loaded 1275 entries from dependency cache.
1308 NOTE: Resolving any missing task queue dependencies
1309
1310 Build Configuration:
1311 .
1312 .
1313 .
1314
1315 NOTE: Executing SetScene Tasks
1316 NOTE: Executing RunQueue Tasks
1317 WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck:
1318 [kernel config]: specified values did not make it into the kernel's final configuration:
1319
1320 ---------- CONFIG_X86_TSC -----------------
1321 Config: CONFIG_X86_TSC
1322 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
1323 Requested value: CONFIG_X86_TSC=y
1324 Actual value:
1325
1326
1327 ---------- CONFIG_X86_BIGSMP -----------------
1328 Config: CONFIG_X86_BIGSMP
1329 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1330 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1331 Requested value: # CONFIG_X86_BIGSMP is not set
1332 Actual value:
1333
1334
1335 ---------- CONFIG_NR_CPUS -----------------
1336 Config: CONFIG_NR_CPUS
1337 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1338 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
1339 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1340 Requested value: CONFIG_NR_CPUS=8
1341 Actual value: CONFIG_NR_CPUS=1
1342
1343
1344 ---------- CONFIG_SCHED_SMT -----------------
1345 Config: CONFIG_SCHED_SMT
1346 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1347 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1348 Requested value: CONFIG_SCHED_SMT=y
1349 Actual value:
1350
1351
1352
1353 NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded.
1354
1355 Summary: There were 3 WARNING messages shown.
1356
1357.. note::
1358
1359 The previous output example has artificial line breaks to make it
1360 more readable.
1361
1362The output describes the various problems that you can encounter along
1363with where to find the offending configuration items. You can use the
1364information in the logs to adjust your configuration files and then
1365repeat the
1366:ref:`ref-tasks-kernel_configme`
1367and
1368:ref:`ref-tasks-kernel_configcheck`
1369tasks until they produce no warnings.
1370
1371For more information on how to use the ``menuconfig`` tool, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001372:ref:`kernel-dev/common:using \`\`menuconfig\`\`` section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001373
1374Fine-Tuning the Kernel Configuration File
1375-----------------------------------------
1376
1377You can make sure the ``.config`` file is as lean or efficient as
1378possible by reading the output of the kernel configuration fragment
1379audit, noting any issues, making changes to correct the issues, and then
1380repeating.
1381
Patrick Williams2194f502022-10-16 14:26:09 -05001382As part of the kernel build process, the :ref:`ref-tasks-kernel_configcheck` task
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001383runs. This task validates the kernel configuration by checking the final
1384``.config`` file against the input files. During the check, the task
1385produces warning messages for the following issues:
1386
Patrick Williams8e7b46e2023-05-01 14:19:06 -05001387- Requested options that did not make it into the final ``.config`` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001388
1389- Configuration items that appear twice in the same configuration
1390 fragment.
1391
1392- Configuration items tagged as "required" that were overridden.
1393
1394- A board overrides a non-board specific option.
1395
1396- Listed options not valid for the kernel being processed. In other
1397 words, the option does not appear anywhere.
1398
1399.. note::
1400
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001401 The :ref:`ref-tasks-kernel_configcheck` task can also optionally report if
1402 an option is overridden during processing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001403
1404For each output warning, a message points to the file that contains a
1405list of the options and a pointer to the configuration fragment that
1406defines them. Collectively, the files are the key to streamlining the
1407configuration.
1408
1409To streamline the configuration, do the following:
1410
Andrew Geissler517393d2023-01-13 08:55:19 -06001411#. *Use a Working Configuration:* Start with a full configuration that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001412 you know works. Be sure the configuration builds and boots
1413 successfully. Use this configuration file as your baseline.
1414
Andrew Geissler517393d2023-01-13 08:55:19 -06001415#. *Run Configure and Check Tasks:* Separately run the
Patrick Williams2194f502022-10-16 14:26:09 -05001416 :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001417
1418 $ bitbake linux-yocto -c kernel_configme -f
1419 $ bitbake linux-yocto -c kernel_configcheck -f
1420
Andrew Geissler517393d2023-01-13 08:55:19 -06001421#. *Process the Results:* Take the resulting list of files from the
Patrick Williams2194f502022-10-16 14:26:09 -05001422 :ref:`ref-tasks-kernel_configcheck` task warnings and do the following:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001423
1424 - Drop values that are redefined in the fragment but do not change
1425 the final ``.config`` file.
1426
1427 - Analyze and potentially drop values from the ``.config`` file that
1428 override required configurations.
1429
1430 - Analyze and potentially remove non-board specific options.
1431
1432 - Remove repeated and invalid options.
1433
Andrew Geissler517393d2023-01-13 08:55:19 -06001434#. *Re-Run Configure and Check Tasks:* After you have worked through the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001435 output of the kernel configuration audit, you can re-run the
Patrick Williams2194f502022-10-16 14:26:09 -05001436 :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks to see the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001437 results of your changes. If you have more issues, you can deal with
1438 them as described in the previous step.
1439
1440Iteratively working through steps two through four eventually yields a
1441minimal, streamlined configuration file. Once you have the best
1442``.config``, you can build the Linux Yocto kernel.
1443
1444Expanding Variables
1445===================
1446
1447Sometimes it is helpful to determine what a variable expands to during a
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001448build. You can examine the values of variables by examining the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001449output of the ``bitbake -e`` command. The output is long and is more
Andrew Geisslerc926e172021-05-07 16:11:35 -05001450easily managed in a text file, which allows for easy searches::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001451
1452 $ bitbake -e virtual/kernel > some_text_file
1453
1454Within the text file, you can see
1455exactly how each variable is expanded and used by the OpenEmbedded build
1456system.
1457
1458Working with a "Dirty" Kernel Version String
1459============================================
1460
1461If you build a kernel image and the version string has a "+" or a
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001462"-dirty" at the end, it means there are uncommitted modifications in the kernel's
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001463source directory. Follow these steps to clean up the version string:
1464
Andrew Geissler517393d2023-01-13 08:55:19 -06001465#. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001466 Git repository (source directory) and use the following Git command
Andrew Geisslerc926e172021-05-07 16:11:35 -05001467 to list the files that have been changed, added, or removed::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001468
1469 $ git status
1470
Andrew Geissler517393d2023-01-13 08:55:19 -06001471#. *Commit the Changes:* You should commit those changes to the kernel
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001472 source tree regardless of whether or not you will save, export, or
Andrew Geisslerc926e172021-05-07 16:11:35 -05001473 use the changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001474
1475 $ git add
1476 $ git commit -s -a -m "getting rid of -dirty"
1477
Andrew Geissler517393d2023-01-13 08:55:19 -06001478#. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001479 kernel.
1480
1481 Depending on your particular kernel development workflow, the
1482 commands you use to rebuild the kernel might differ. For information
1483 on building the kernel image when using ``devtool``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001484 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001485 section. For
Andrew Geisslerd5838332022-05-27 11:33:10 -05001486 information on building the kernel image when using BitBake, see the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001487 ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001488 section.
1489
1490Working With Your Own Sources
1491=============================
1492
1493If you cannot work with one of the Linux kernel versions supported by
1494existing linux-yocto recipes, you can still make use of the Yocto
1495Project Linux kernel tooling by working with your own sources. When you
1496use your own sources, you will not be able to leverage the existing
1497kernel :term:`Metadata` and stabilization
1498work of the linux-yocto sources. However, you will be able to manage
1499your own Metadata in the same format as the linux-yocto sources.
1500Maintaining format compatibility facilitates converging with linux-yocto
1501on a future, mutually-supported kernel version.
1502
1503To help you use your own sources, the Yocto Project provides a
Andrew Geissler595f6302022-01-24 19:11:47 +00001504linux-yocto custom recipe that uses ``kernel.org`` sources and
1505the Yocto Project Linux kernel tools for managing kernel Metadata.
1506You can find this recipe in the ``poky`` Git repository:
1507:yocto_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
1508</poky/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001509
1510Here are some basic steps you can use to work with your own sources:
1511
Andrew Geissler517393d2023-01-13 08:55:19 -06001512#. *Create a Copy of the Kernel Recipe:* Copy the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001513 ``linux-yocto-custom.bb`` recipe to your layer and give it a
1514 meaningful name. The name should include the version of the Yocto
1515 Linux kernel you are using (e.g. ``linux-yocto-myproject_4.12.bb``,
1516 where "4.12" is the base version of the Linux kernel with which you
1517 would be working).
1518
Andrew Geissler517393d2023-01-13 08:55:19 -06001519#. *Create a Directory for Your Patches:* In the same directory inside
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001520 your layer, create a matching directory to store your patches and
1521 configuration files (e.g. ``linux-yocto-myproject``).
1522
Andrew Geissler517393d2023-01-13 08:55:19 -06001523#. *Ensure You Have Configurations:* Make sure you have either a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001524 ``defconfig`` file or configuration fragment files in your layer.
1525 When you use the ``linux-yocto-custom.bb`` recipe, you must specify a
1526 configuration. If you do not have a ``defconfig`` file, you can run
Andrew Geisslerc926e172021-05-07 16:11:35 -05001527 the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001528
1529 $ make defconfig
1530
1531 After running the command, copy the
1532 resulting ``.config`` file to the ``files`` directory in your layer
1533 as "defconfig" and then add it to the
1534 :term:`SRC_URI` variable in the
1535 recipe.
1536
1537 Running the ``make defconfig`` command results in the default
1538 configuration for your architecture as defined by your kernel.
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001539 However, there is no guarantee that this configuration is valid for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001540 your use case, or that your board will even boot. This is
1541 particularly true for non-x86 architectures.
1542
1543 To use non-x86 ``defconfig`` files, you need to be more specific and
1544 find one that matches your board (i.e. for arm, you look in
1545 ``arch/arm/configs`` and use the one that is the best starting point
1546 for your board).
1547
Andrew Geissler517393d2023-01-13 08:55:19 -06001548#. *Edit the Recipe:* Edit the following variables in your recipe as
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001549 appropriate for your project:
1550
1551 - :term:`SRC_URI`: The
Andrew Geissler09036742021-06-25 14:25:14 -05001552 :term:`SRC_URI` should specify a Git repository that uses one of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001553 supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``,
Andrew Geissler09036742021-06-25 14:25:14 -05001554 and so forth). The :term:`SRC_URI` variable should also specify either
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001555 a ``defconfig`` file or some configuration fragment files. The
Andrew Geissler09036742021-06-25 14:25:14 -05001556 skeleton recipe provides an example :term:`SRC_URI` as a syntax
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001557 reference.
1558
1559 - :term:`LINUX_VERSION`:
1560 The Linux kernel version you are using (e.g. "4.12").
1561
1562 - :term:`LINUX_VERSION_EXTENSION`:
1563 The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the
1564 resulting kernel and visible through the ``uname`` command.
1565
1566 - :term:`SRCREV`: The commit ID
1567 from which you want to build.
1568
1569 - :term:`PR`: Treat this variable the
1570 same as you would in any other recipe. Increment the variable to
1571 indicate to the OpenEmbedded build system that the recipe has
1572 changed.
1573
Andrew Geissler09036742021-06-25 14:25:14 -05001574 - :term:`PV`: The default :term:`PV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001575 assignment is typically adequate. It combines the
Andrew Geissler09036742021-06-25 14:25:14 -05001576 :term:`LINUX_VERSION` with the Source Control Manager (SCM) revision
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001577 as derived from the :term:`SRCPV`
1578 variable. The combined results are a string with the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001579 form::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001580
1581 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
1582
Andrew Geissler09036742021-06-25 14:25:14 -05001583 While lengthy, the extra verbosity in :term:`PV` helps ensure you are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001584 using the exact sources from which you intend to build.
1585
1586 - :term:`COMPATIBLE_MACHINE`:
1587 A list of the machines supported by your new recipe. This variable
1588 in the example recipe is set by default to a regular expression
1589 that matches only the empty string, "(^$)". This default setting
1590 triggers an explicit build failure. You must change it to match a
1591 list of the machines that your new recipe supports. For example,
1592 to support the ``qemux86`` and ``qemux86-64`` machines, use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001593 following form::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001594
1595 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001596
Andrew Geissler517393d2023-01-13 08:55:19 -06001597#. *Customize Your Recipe as Needed:* Provide further customizations to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001598 your recipe as needed just as you would customize an existing
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001599 linux-yocto recipe. See the
1600 ":ref:`ref-manual/devtool-reference:modifying an existing recipe`" section
1601 for information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001602
1603Working with Out-of-Tree Modules
1604================================
1605
1606This section describes steps to build out-of-tree modules on your target
1607and describes how to incorporate out-of-tree modules in the build.
1608
1609Building Out-of-Tree Modules on the Target
1610------------------------------------------
1611
1612While the traditional Yocto Project development model would be to
1613include kernel modules as part of the normal build process, you might
1614find it useful to build modules on the target. This could be the case if
1615your target system is capable and powerful enough to handle the
1616necessary compilation. Before deciding to build on your target, however,
1617you should consider the benefits of using a proper cross-development
1618environment from your build host.
1619
1620If you want to be able to build out-of-tree modules on the target, there
1621are some steps you need to take on the target that is running your SDK
1622image. Briefly, the ``kernel-dev`` package is installed by default on
1623all ``*.sdk`` images and the ``kernel-devsrc`` package is installed on
1624many of the ``*.sdk`` images. However, you need to create some scripts
1625prior to attempting to build the out-of-tree modules on the target that
1626is running that image.
1627
1628Prior to attempting to build the out-of-tree modules, you need to be on
1629the target as root and you need to change to the ``/usr/src/kernel``
1630directory. Next, ``make`` the scripts:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001631
1632.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001633
1634 # cd /usr/src/kernel
1635 # make scripts
1636
1637Because all SDK image recipes include ``dev-pkgs``, the
1638``kernel-dev`` packages will be installed as part of the SDK image and
1639the ``kernel-devsrc`` packages will be installed as part of applicable
1640SDK images. The SDK uses the scripts when building out-of-tree modules.
1641Once you have switched to that directory and created the scripts, you
1642should be able to build your out-of-tree modules on the target.
1643
1644Incorporating Out-of-Tree Modules
1645---------------------------------
1646
1647While it is always preferable to work with sources integrated into the
1648Linux kernel sources, if you need an external kernel module, the
1649``hello-mod.bb`` recipe is available as a template from which you can
1650create your own out-of-tree Linux kernel module recipe.
1651
1652This template recipe is located in the ``poky`` Git repository of the
Andrew Geissler595f6302022-01-24 19:11:47 +00001653Yocto Project:
1654:yocto_git:`meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
1655</poky/tree/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001656
1657To get started, copy this recipe to your layer and give it a meaningful
1658name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new
1659directory named ``files`` where you can store any source files, patches,
1660or other files necessary for building the module that do not come with
1661the sources. Finally, update the recipe as needed for the module.
1662Typically, you will need to set the following variables:
1663
1664- :term:`DESCRIPTION`
1665
1666- :term:`LICENSE* <LICENSE>`
1667
1668- :term:`SRC_URI`
1669
1670- :term:`PV`
1671
1672Depending on the build system used by the module sources, you might need
1673to make some adjustments. For example, a typical module ``Makefile``
Andrew Geisslerc926e172021-05-07 16:11:35 -05001674looks much like the one provided with the ``hello-mod`` template::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001675
1676 obj-m := hello.o
1677
1678 SRC := $(shell pwd)
1679
1680 all:
1681 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
1682
1683 modules_install:
1684 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
1685 ...
1686
1687The important point to note here is the :term:`KERNEL_SRC` variable. The
Andrew Geissler517393d2023-01-13 08:55:19 -06001688:ref:`ref-classes-module` class sets this variable and the :term:`KERNEL_PATH`
1689variable to ``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build
1690information to build modules. If your module ``Makefile`` uses a different
1691variable, you might want to override the :ref:`ref-tasks-compile` step, or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001692create a patch to the ``Makefile`` to work with the more typical
Andrew Geissler09036742021-06-25 14:25:14 -05001693:term:`KERNEL_SRC` or :term:`KERNEL_PATH` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001694
1695After you have prepared your recipe, you will likely want to include the
1696module in your images. To do this, see the documentation for the
1697following variables in the Yocto Project Reference Manual and set one of
1698them appropriately for your machine configuration file:
1699
1700- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
1701
1702- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
1703
1704- :term:`MACHINE_EXTRA_RDEPENDS`
1705
1706- :term:`MACHINE_EXTRA_RRECOMMENDS`
1707
1708Modules are often not required for boot and can be excluded from certain
Andrew Geisslerc926e172021-05-07 16:11:35 -05001709build configurations. The following allows for the most flexibility::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001710
1711 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
1712
1713The value is
1714derived by appending the module filename without the ``.ko`` extension
1715to the string "kernel-module-".
1716
1717Because the variable is
1718:term:`RRECOMMENDS` and not a
1719:term:`RDEPENDS` variable, the build
1720will not fail if this module is not available to include in the image.
1721
1722Inspecting Changes and Commits
1723==============================
1724
1725A common question when working with a kernel is: "What changes have been
1726applied to this tree?" Rather than using "grep" across directories to
1727see what has changed, you can use Git to inspect or search the kernel
1728tree. Using Git is an efficient way to see what has changed in the tree.
1729
1730What Changed in a Kernel?
1731-------------------------
1732
1733Following are a few examples that show how to use Git commands to
1734examine changes. These examples are by no means the only way to see
1735changes.
1736
1737.. note::
1738
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001739 In the following examples, unless you provide a commit range, ``kernel.org``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001740 history is blended with Yocto Project kernel changes. You can form
1741 ranges by using branch names from the kernel tree as the upper and
1742 lower commit markers with the Git commands. You can see the branch
1743 names through the web interface to the Yocto Project source
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001744 repositories at :yocto_git:`/`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001745
1746To see a full range of the changes, use the ``git whatchanged`` command
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001747and specify a commit range for the branch (`commit`\ ``..``\ `commit`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001748
1749Here is an example that looks at what has changed in the ``emenlow``
1750branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the
1751commit associated with the ``standard/base`` branch, while the upper
1752commit range is the commit associated with the ``standard/emenlow``
Andrew Geissler517393d2023-01-13 08:55:19 -06001753branch::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001754
1755 $ git whatchanged origin/standard/base..origin/standard/emenlow
1756
Andrew Geisslerc926e172021-05-07 16:11:35 -05001757To see short, one line summaries of changes use the ``git log`` command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001758
1759 $ git log --oneline origin/standard/base..origin/standard/emenlow
1760
Andrew Geisslerc926e172021-05-07 16:11:35 -05001761Use this command to see code differences for the changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001762
1763 $ git diff origin/standard/base..origin/standard/emenlow
1764
1765Use this command to see the commit log messages and the text
Andrew Geisslerc926e172021-05-07 16:11:35 -05001766differences::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001767
1768 $ git show origin/standard/base..origin/standard/emenlow
1769
1770Use this command to create individual patches for each change. Here is
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001771an example that creates patch files for each commit and places them
Andrew Geisslerc926e172021-05-07 16:11:35 -05001772in your ``Documents`` directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001773
1774 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
1775
1776Showing a Particular Feature or Branch Change
1777---------------------------------------------
1778
1779Tags in the Yocto Project kernel tree divide changes for significant
1780features or branches. The ``git show`` tag command shows changes based
Andrew Geisslerc926e172021-05-07 16:11:35 -05001781on a tag. Here is an example that shows ``systemtap`` changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001782
1783 $ git show systemtap
1784
1785You can use the ``git branch --contains`` tag command to
1786show the branches that contain a particular feature. This command shows
Andrew Geisslerc926e172021-05-07 16:11:35 -05001787the branches that contain the ``systemtap`` feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001788
1789 $ git branch --contains systemtap
1790
1791Adding Recipe-Space Kernel Features
1792===================================
1793
1794You can add kernel features in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001795:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001796by using the :term:`KERNEL_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001797variable and by specifying the feature's ``.scc`` file path in the
1798:term:`SRC_URI` statement. When you
1799add features using this method, the OpenEmbedded build system checks to
1800be sure the features are present. If the features are not present, the
1801build stops. Kernel features are the last elements processed for
1802configuring and patching the kernel. Therefore, adding features in this
1803manner is a way to enforce specific features are present and enabled
1804without needing to do a full audit of any other layer's additions to the
Andrew Geissler09036742021-06-25 14:25:14 -05001805:term:`SRC_URI` statement.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001806
1807You add a kernel feature by providing the feature as part of the
Andrew Geissler09036742021-06-25 14:25:14 -05001808:term:`KERNEL_FEATURES` variable and by providing the path to the feature's
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001809``.scc`` file, which is relative to the root of the kernel Metadata. The
1810OpenEmbedded build system searches all forms of kernel Metadata on the
Andrew Geissler09036742021-06-25 14:25:14 -05001811:term:`SRC_URI` statement regardless of whether the Metadata is in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001812"kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e.
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001813part of the kernel recipe). See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001814":ref:`kernel-dev/advanced:kernel metadata location`" section for
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001815additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001816
Andrew Geissler09036742021-06-25 14:25:14 -05001817When you specify the feature's ``.scc`` file on the :term:`SRC_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001818statement, the OpenEmbedded build system adds the directory of that
1819``.scc`` file along with all its subdirectories to the kernel feature
1820search path. Because subdirectories are searched, you can reference a
Andrew Geissler09036742021-06-25 14:25:14 -05001821single ``.scc`` file in the :term:`SRC_URI` statement to reference multiple
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001822kernel features.
1823
1824Consider the following example that adds the "test.scc" feature to the
1825build.
1826
Andrew Geissler517393d2023-01-13 08:55:19 -06001827#. *Create the Feature File:* Create a ``.scc`` file and locate it just
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001828 as you would any other patch file, ``.cfg`` file, or fetcher item you
Andrew Geissler09036742021-06-25 14:25:14 -05001829 specify in the :term:`SRC_URI` statement.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001830
1831 .. note::
1832
1833 - You must add the directory of the ``.scc`` file to the
1834 fetcher's search path in the same manner as you would add a
1835 ``.patch`` file.
1836
1837 - You can create additional ``.scc`` files beneath the directory
1838 that contains the file you are adding. All subdirectories are
1839 searched during the build as potential feature directories.
1840
1841 Continuing with the example, suppose the "test.scc" feature you are
Andrew Geisslerc926e172021-05-07 16:11:35 -05001842 adding has a ``test.scc`` file in the following directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001843
1844 my_recipe
1845 |
1846 +-linux-yocto
1847 |
1848 +-test.cfg
1849 +-test.scc
1850
1851 In this example, the
1852 ``linux-yocto`` directory has both the feature ``test.scc`` file and
1853 a similarly named configuration fragment file ``test.cfg``.
1854
Andrew Geissler517393d2023-01-13 08:55:19 -06001855#. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
Andrew Geissler09036742021-06-25 14:25:14 -05001856 recipe's :term:`SRC_URI` statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001857
Andrew Geissler87f5cff2022-09-30 13:13:31 -05001858 SRC_URI += "file://test.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001859
1860 The leading space before the path is important as the path is
1861 appended to the existing path.
1862
Andrew Geissler517393d2023-01-13 08:55:19 -06001863#. *Specify the Feature as a Kernel Feature:* Use the
Andrew Geissler09036742021-06-25 14:25:14 -05001864 :term:`KERNEL_FEATURES` statement to specify the feature as a kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -05001865 feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001866
Andrew Geissler87f5cff2022-09-30 13:13:31 -05001867 KERNEL_FEATURES += "test.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001868
1869 The OpenEmbedded build
1870 system processes the kernel feature when it builds the kernel.
1871
1872 .. note::
1873
1874 If other features are contained below "test.scc", then their
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001875 directories are relative to the directory containing the ``test.scc``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001876 file.