blob: dc3345a520c083a16ffa3e4cbbac16d07fcea8d9 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3************
4Common Tasks
5************
6
7This chapter presents several common tasks you perform when you work
8with the Yocto Project Linux kernel. These tasks include preparing your
9host development system for kernel development, preparing a layer,
10modifying an existing recipe, patching the kernel, configuring the
11kernel, iterative development, working with your own sources, and
12incorporating out-of-tree modules.
13
14.. note::
15
16 The examples presented in this chapter work with the Yocto Project
17 2.4 Release and forward.
18
19Preparing the Build Host to Work on the Kernel
20==============================================
21
22Before you can do any kernel development, you need to be sure your build
23host is set up to use the Yocto Project. For information on how to get
Andrew Geissler09209ee2020-12-13 08:44:15 -060024set up, see the ":doc:`/dev-manual/start`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -050025the Yocto Project Development Tasks Manual. Part of preparing the system
26is creating a local Git repository of the
27:term:`Source Directory` (``poky``) on your system. Follow the steps in the
Andrew Geissler09209ee2020-12-13 08:44:15 -060028":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050029section in the Yocto Project Development Tasks Manual to set up your
30Source Directory.
31
32.. note::
33
34 Be sure you check out the appropriate development branch or you
35 create your local branch by checking out a specific tag to get the
Andrew Geissler4c19ea12020-10-27 13:52:24 -050036 desired version of Yocto Project. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -060037 ":ref:`dev-manual/start:checking out by branch in poky`" and
38 ":ref:`dev-manual/start:checking out by tag in poky`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -050039 sections in the Yocto Project Development Tasks Manual for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050040
41Kernel development is best accomplished using
Andrew Geissler09209ee2020-12-13 08:44:15 -060042:ref:`devtool <sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050043and not through traditional kernel workflow methods. The remainder of
44this section provides information for both scenarios.
45
46Getting Ready to Develop Using ``devtool``
47------------------------------------------
48
49Follow these steps to prepare to update the kernel image using
50``devtool``. Completing this procedure leaves you with a clean kernel
Andrew Geissler4c19ea12020-10-27 13:52:24 -050051image and ready to make modifications as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -060052":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050053section:
54
551. *Initialize the BitBake Environment:* Before building an extensible
56 SDK, you need to initialize the BitBake build environment by sourcing
Andrew Geisslerc926e172021-05-07 16:11:35 -050057 the build environment script (i.e. :ref:`structure-core-script`)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050058
Andrew Geissler95ac1b82021-03-31 14:34:31 -050059 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -050060 $ source oe-init-build-env
61
62 .. note::
63
64 The previous commands assume the
Andrew Geissler09209ee2020-12-13 08:44:15 -060065 :ref:`overview-manual/development-environment:yocto project source repositories`
Andrew Geissler4c19ea12020-10-27 13:52:24 -050066 (i.e. ``poky``) have been cloned using Git and the local repository is named
Andrew Geisslerc9f78652020-09-18 14:11:35 -050067 "poky".
68
692. *Prepare Your local.conf File:* By default, the
70 :term:`MACHINE` variable is set to
71 "qemux86-64", which is fine if you are building for the QEMU emulator
72 in 64-bit mode. However, if you are not, you need to set the
Andrew Geissler09036742021-06-25 14:25:14 -050073 :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
Andrew Geisslerc9f78652020-09-18 14:11:35 -050074 found in the
75 :term:`Build Directory` (i.e.
Andrew Geissler95ac1b82021-03-31 14:34:31 -050076 ``poky/build`` in this example).
Andrew Geisslerc9f78652020-09-18 14:11:35 -050077
78 Also, since you are preparing to work on the kernel image, you need
79 to set the
80 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
81 variable to include kernel modules.
82
83 In this example we wish to build for qemux86 so we must set the
Andrew Geissler5f350902021-07-23 13:09:54 -040084 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
Andrew Geisslerc926e172021-05-07 16:11:35 -050085 As described we do this by appending to ``conf/local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050086
87 MACHINE = "qemux86"
88 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
89
903. *Create a Layer for Patches:* You need to create a layer to hold
91 patches created for the kernel image. You can use the
Andrew Geisslerc926e172021-05-07 16:11:35 -050092 ``bitbake-layers create-layer`` command as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050093
Andrew Geissler95ac1b82021-03-31 14:34:31 -050094 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -050095 $ bitbake-layers create-layer ../../meta-mylayer
96 NOTE: Starting bitbake server...
97 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
98 $
99
100 .. note::
101
102 For background information on working with common and BSP layers,
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500103 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600104 ":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500105 section in the Yocto Project Development Tasks Manual and the
106 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board
107 Support (BSP) Developer's Guide, respectively. For information on how to
108 use the ``bitbake-layers create-layer`` command to quickly set up a layer,
109 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600110 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500111 section in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112
1134. *Inform the BitBake Build Environment About Your Layer:* As directed
114 when you created your layer, you need to add the layer to the
115 :term:`BBLAYERS` variable in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500116 ``bblayers.conf`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500118 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500119 $ bitbake-layers add-layer ../../meta-mylayer
120 NOTE: Starting bitbake server...
121 $
122
1235. *Build the Extensible SDK:* Use BitBake to build the extensible SDK
Andrew Geisslerc926e172021-05-07 16:11:35 -0500124 specifically for use with images to be run using QEMU::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500125
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500126 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500127 $ bitbake core-image-minimal -c populate_sdk_ext
128
129 Once
130 the build finishes, you can find the SDK installer file (i.e.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500131 ``*.sh`` file) in the following directory::
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500132
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500133 poky/build/tmp/deploy/sdk
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500134
135 For this example, the installer file is named
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600136 ``poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500137
1386. *Install the Extensible SDK:* Use the following command to install
139 the SDK. For this example, install the SDK in the default
Andrew Geisslerc926e172021-05-07 16:11:35 -0500140 ``poky_sdk`` directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500141
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500142 $ cd poky/build/tmp/deploy/sdk
Andrew Geissler09209ee2020-12-13 08:44:15 -0600143 $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh
144 Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500145 ============================================================================
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500146 Enter target directory for SDK (default: poky_sdk):
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500147 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
148 Extracting SDK......................................done
149 Setting it up...
150 Extracting buildtools...
151 Preparing build system...
152 Parsing recipes: 100% |#################################################################| Time: 0:00:52
153 Initializing tasks: 100% |############## ###############################################| Time: 0:00:04
154 Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00
155 Parsing recipes: 100% |#################################################################| Time: 0:00:33
156 Initializing tasks: 100% |##############################################################| Time: 0:00:00
157 done
158 SDK has been successfully set up and is ready to be used.
159 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
160 $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux
161
162
1637. *Set Up a New Terminal to Work With the Extensible SDK:* You must set
164 up a new terminal to work with the SDK. You cannot use the same
165 BitBake shell used to build the installer.
166
167 After opening a new shell, run the SDK environment setup script as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500168 directed by the output from installing the SDK::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500169
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500170 $ source poky_sdk/environment-setup-i586-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500171 "SDK environment now set up; additionally you may now run devtool to perform development tasks.
172 Run devtool --help for further details.
173
174 .. note::
175
176 If you get a warning about attempting to use the extensible SDK in
177 an environment set up to run BitBake, you did not use a new shell.
178
1798. *Build the Clean Image:* The final step in preparing to work on the
180 kernel is to build an initial image using ``devtool`` in the new
Andrew Geisslerc926e172021-05-07 16:11:35 -0500181 terminal you just set up and initialized for SDK work::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500182
183 $ devtool build-image
184 Parsing recipes: 100% |##########################################| Time: 0:00:05
185 Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors.
186 WARNING: No packages to add, building image core-image-minimal unmodified
187 Loading cache: 100% |############################################| Time: 0:00:00
188 Loaded 1299 entries from dependency cache.
189 NOTE: Resolving any missing task queue dependencies
190 Initializing tasks: 100% |#######################################| Time: 0:00:07
191 Checking sstate mirror object availability: 100% |###############| Time: 0:00:00
192 NOTE: Executing SetScene Tasks
193 NOTE: Executing RunQueue Tasks
194 NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded.
195 NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86
196
197 If you were
198 building for actual hardware and not for emulation, you could flash
199 the image to a USB stick on ``/dev/sdd`` and boot your device. For an
200 example that uses a Minnowboard, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600201 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500202 Wiki page.
203
204At this point you have set up to start making modifications to the
205kernel by using the extensible SDK. For a continued example, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600206":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500207section.
208
209Getting Ready for Traditional Kernel Development
210------------------------------------------------
211
212Getting ready for traditional kernel development using the Yocto Project
213involves many of the same steps as described in the previous section.
214However, you need to establish a local copy of the kernel source since
215you will be editing these files.
216
217Follow these steps to prepare to update the kernel image using
218traditional kernel development flow with the Yocto Project. Completing
219this procedure leaves you ready to make modifications to the kernel
Andrew Geissler09209ee2020-12-13 08:44:15 -0600220source as described in the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500221section:
222
2231. *Initialize the BitBake Environment:* Before you can do anything
224 using BitBake, you need to initialize the BitBake build environment
225 by sourcing the build environment script (i.e.
226 :ref:`structure-core-script`).
227 Also, for this example, be sure that the local branch you have
228 checked out for ``poky`` is the Yocto Project &DISTRO_NAME; branch. If
229 you need to checkout out the &DISTRO_NAME; branch, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600230 ":ref:`dev-manual/start:checking out by branch in poky`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500231 section in the Yocto Project Development Tasks Manual.
232 ::
233
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500234 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500235 $ git branch
236 master
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500237 * &DISTRO_NAME_NO_CAP;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500238 $ source oe-init-build-env
239
240 .. note::
241
242 The previous commands assume the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600243 :ref:`overview-manual/development-environment:yocto project source repositories`
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500244 (i.e. ``poky``) have been cloned using Git and the local repository is named
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500245 "poky".
246
2472. *Prepare Your local.conf File:* By default, the
248 :term:`MACHINE` variable is set to
249 "qemux86-64", which is fine if you are building for the QEMU emulator
250 in 64-bit mode. However, if you are not, you need to set the
Andrew Geissler09036742021-06-25 14:25:14 -0500251 :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500252 found in the
253 :term:`Build Directory` (i.e.
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500254 ``poky/build`` in this example).
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500255
256 Also, since you are preparing to work on the kernel image, you need
257 to set the
258 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
259 variable to include kernel modules.
260
261 In this example we wish to build for qemux86 so we must set the
Andrew Geissler5f350902021-07-23 13:09:54 -0400262 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
Andrew Geisslerc926e172021-05-07 16:11:35 -0500263 As described we do this by appending to ``conf/local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500264
265 MACHINE = "qemux86"
266 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
267
2683. *Create a Layer for Patches:* You need to create a layer to hold
269 patches created for the kernel image. You can use the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500270 ``bitbake-layers create-layer`` command as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500271
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500272 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500273 $ bitbake-layers create-layer ../../meta-mylayer
274 NOTE: Starting bitbake server...
275 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
276
277 .. note::
278
279 For background information on working with common and BSP layers,
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500280 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600281 ":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500282 section in the Yocto Project Development Tasks Manual and the
283 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board
284 Support (BSP) Developer's Guide, respectively. For information on how to
285 use the ``bitbake-layers create-layer`` command to quickly set up a layer,
286 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600287 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500288 section in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500289
2904. *Inform the BitBake Build Environment About Your Layer:* As directed
291 when you created your layer, you need to add the layer to the
292 :term:`BBLAYERS` variable in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500293 ``bblayers.conf`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500294
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500295 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500296 $ bitbake-layers add-layer ../../meta-mylayer
297 NOTE: Starting bitbake server ...
298 $
299
3005. *Create a Local Copy of the Kernel Git Repository:* You can find Git
301 repositories of supported Yocto Project kernels organized under
302 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
303 :yocto_git:`/`.
304
305 For simplicity, it is recommended that you create your copy of the
306 kernel Git repository outside of the
307 :term:`Source Directory`, which is
308 usually named ``poky``. Also, be sure you are in the
309 ``standard/base`` branch.
310
311 The following commands show how to create a local copy of the
312 ``linux-yocto-4.12`` kernel and be in the ``standard/base`` branch.
313
314 .. note::
315
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500316 The ``linux-yocto-4.12`` kernel can be used with the Yocto Project 2.4
317 release and forward.
318 You cannot use the ``linux-yocto-4.12`` kernel with releases prior to
319 Yocto Project 2.4.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500320
321 ::
322
323 $ cd ~
324 $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base
325 Cloning into 'linux-yocto-4.12'...
326 remote: Counting objects: 6097195, done.
327 remote: Compressing objects: 100% (901026/901026), done.
328 remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256)
329 Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done.
330 Resolving deltas: 100% (5152604/5152604), done. Checking connectivity... done.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500331 Checking out files: 100% (59846/59846), done.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500332
3336. *Create a Local Copy of the Kernel Cache Git Repository:* For
334 simplicity, it is recommended that you create your copy of the kernel
335 cache Git repository outside of the
336 :term:`Source Directory`, which is
337 usually named ``poky``. Also, for this example, be sure you are in
338 the ``yocto-4.12`` branch.
339
340 The following commands show how to create a local copy of the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700341 ``yocto-kernel-cache`` and switch to the ``yocto-4.12`` branch::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500342
343 $ cd ~
344 $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12
345 Cloning into 'yocto-kernel-cache'...
346 remote: Counting objects: 22639, done.
347 remote: Compressing objects: 100% (9761/9761), done.
348 remote: Total 22639 (delta 12400), reused 22586 (delta 12347)
349 Receiving objects: 100% (22639/22639), 22.34 MiB | 6.27 MiB/s, done.
350 Resolving deltas: 100% (12400/12400), done.
351 Checking connectivity... done.
352
353At this point, you are ready to start making modifications to the kernel
354using traditional kernel development steps. For a continued example, see
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500355the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500356section.
357
358Creating and Preparing a Layer
359==============================
360
361If you are going to be modifying kernel recipes, it is recommended that
362you create and prepare your own layer in which to do your work. Your
363layer contains its own :term:`BitBake`
364append files (``.bbappend``) and provides a convenient mechanism to
365create your own recipe files (``.bb``) as well as store and use kernel
366patch files. For background information on working with layers, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600367":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500368section in the Yocto Project Development Tasks Manual.
369
370.. note::
371
372 The Yocto Project comes with many tools that simplify tasks you need
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500373 to perform. One such tool is the ``bitbake-layers create-layer``
374 command, which simplifies creating a new layer. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600375 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500376 section in the Yocto Project Development Tasks Manual for
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500377 information on how to use this script to quick set up a new layer.
378
379To better understand the layer you create for kernel development, the
380following section describes how to create a layer without the aid of
381tools. These steps assume creation of a layer named ``mylayer`` in your
382home directory:
383
Andrew Geisslerc926e172021-05-07 16:11:35 -05003841. *Create Structure*: Create the layer's structure::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500385
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500386 $ mkdir meta-mylayer
387 $ mkdir meta-mylayer/conf
388 $ mkdir meta-mylayer/recipes-kernel
389 $ mkdir meta-mylayer/recipes-kernel/linux
390 $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto
391
392 The ``conf`` directory holds your configuration files, while the
393 ``recipes-kernel`` directory holds your append file and eventual
394 patch files.
395
3962. *Create the Layer Configuration File*: Move to the
397 ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500398 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500399
400 # We have a conf and classes directory, add to BBPATH
401 BBPATH .= ":${LAYERDIR}"
402
403 # We have recipes-* directories, add to BBFILES
404 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
405 ${LAYERDIR}/recipes-*/*/*.bbappend"
406
407 BBFILE_COLLECTIONS += "mylayer"
408 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
409 BBFILE_PRIORITY_mylayer = "5"
410
411 Notice ``mylayer`` as part of the last three statements.
412
4133. *Create the Kernel Recipe Append File*: Move to the
414 ``meta-mylayer/recipes-kernel/linux`` directory and create the
415 kernel's append file. This example uses the ``linux-yocto-4.12``
416 kernel. Thus, the name of the append file is
Andrew Geisslerc926e172021-05-07 16:11:35 -0500417 ``linux-yocto_4.12.bbappend``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500418
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500419 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500420
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500421 SRC_URI:append = " file://patch-file-one.patch"
422 SRC_URI:append = " file://patch-file-two.patch"
423 SRC_URI:append = " file://patch-file-three.patch"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500424
425 The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
426 enable the OpenEmbedded build system to find patch files. For more
427 information on using append files, see the
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500428 ":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500429 section in the Yocto Project Development Tasks Manual.
430
431Modifying an Existing Recipe
432============================
433
434In many cases, you can customize an existing linux-yocto recipe to meet
435the needs of your project. Each release of the Yocto Project provides a
436few Linux kernel recipes from which you can choose. These are located in
437the :term:`Source Directory` in
438``meta/recipes-kernel/linux``.
439
440Modifying an existing recipe can consist of the following:
441
Andrew Geissler09209ee2020-12-13 08:44:15 -0600442- :ref:`kernel-dev/common:creating the append file`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500443
Andrew Geissler09209ee2020-12-13 08:44:15 -0600444- :ref:`kernel-dev/common:applying patches`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500445
Andrew Geissler09209ee2020-12-13 08:44:15 -0600446- :ref:`kernel-dev/common:changing the configuration`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500447
448Before modifying an existing recipe, be sure that you have created a
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500449minimal, custom layer from which you can work. See the
450":ref:`kernel-dev/common:creating and preparing a layer`" section for
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500451information.
452
453Creating the Append File
454------------------------
455
456You create this file in your custom layer. You also name it accordingly
457based on the linux-yocto recipe you are using. For example, if you are
458modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe,
459the append file will typically be located as follows within your custom
460layer:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500461
462.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500463
464 your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend
465
466The append file should initially extend the
467:term:`FILESPATH` search path by
468prepending the directory that contains your files to the
469:term:`FILESEXTRAPATHS`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500470variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500471
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500472 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500473
474The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``
475expands to "linux-yocto" in the current directory for this example. If
476you add any new files that modify the kernel recipe and you have
Andrew Geissler09036742021-06-25 14:25:14 -0500477extended :term:`FILESPATH` as described above, you must place the files in
Andrew Geisslerc926e172021-05-07 16:11:35 -0500478your layer in the following area::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500479
480 your-layer/recipes-kernel/linux/linux-yocto/
481
482.. note::
483
484 If you are working on a new machine Board Support Package (BSP), be
Andrew Geissler09209ee2020-12-13 08:44:15 -0600485 sure to refer to the :doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500486
487As an example, consider the following append file used by the BSPs in
488``meta-yocto-bsp``:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500489
490.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500491
492 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend
493
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700494Here are the contents of this file. Be aware that the actual commit ID
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500495strings in this example listing might be different than the actual
496strings in the file from the ``meta-yocto-bsp`` layer upstream.
497::
498
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500499 KBRANCH:genericx86 = "standard/base"
500 KBRANCH:genericx86-64 = "standard/base"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500501
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500502 KMACHINE:genericx86 ?= "common-pc"
503 KMACHINE:genericx86-64 ?= "common-pc-64"
504 KBRANCH:edgerouter = "standard/edgerouter"
505 KBRANCH:beaglebone = "standard/beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500506
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500507 SRCREV_machine:genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
508 SRCREV_machine:genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
509 SRCREV_machine:edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
510 SRCREV_machine:beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500511
512
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500513 COMPATIBLE_MACHINE:genericx86 = "genericx86"
514 COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64"
515 COMPATIBLE_MACHINE:edgerouter = "edgerouter"
516 COMPATIBLE_MACHINE:beaglebone = "beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500517
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500518 LINUX_VERSION:genericx86 = "4.12.7"
519 LINUX_VERSION:genericx86-64 = "4.12.7"
520 LINUX_VERSION:edgerouter = "4.12.10"
521 LINUX_VERSION:beaglebone = "4.12.10"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500522
523This append file
524contains statements used to support several BSPs that ship with the
525Yocto Project. The file defines machines using the
526:term:`COMPATIBLE_MACHINE`
527variable and uses the
528:term:`KMACHINE` variable to ensure
529the machine name used by the OpenEmbedded build system maps to the
530machine name used by the Linux Yocto kernel. The file also uses the
531optional :term:`KBRANCH` variable to
532ensure the build process uses the appropriate kernel branch.
533
534Although this particular example does not use it, the
535:term:`KERNEL_FEATURES`
536variable could be used to enable features specific to the kernel. The
537append file points to specific commits in the
538:term:`Source Directory` Git repository and
539the ``meta`` Git repository branches to identify the exact kernel needed
540to build the BSP.
541
542One thing missing in this particular BSP, which you will typically need
543when developing a BSP, is the kernel configuration file (``.config``)
544for your BSP. When developing a BSP, you probably have a kernel
545configuration file or a set of kernel configuration files that, when
546taken together, define the kernel configuration for your BSP. You can
547accomplish this definition by putting the configurations in a file or a
548set of files inside a directory located at the same level as your
549kernel's append file and having the same name as the kernel's main
550recipe file. With all these conditions met, simply reference those files
551in the :term:`SRC_URI` statement in
552the append file.
553
554For example, suppose you had some configuration options in a file called
555``network_configs.cfg``. You can place that file inside a directory
Andrew Geissler09036742021-06-25 14:25:14 -0500556named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500557following to the append file. When the OpenEmbedded build system builds
558the kernel, the configuration options are picked up and applied.
559::
560
561 SRC_URI += "file://network_configs.cfg"
562
563To group related configurations into multiple files, you perform a
564similar procedure. Here is an example that groups separate
565configurations specifically for Ethernet and graphics into their own
Andrew Geissler09036742021-06-25 14:25:14 -0500566files and adds the configurations by using a :term:`SRC_URI` statement like
Andrew Geisslerc926e172021-05-07 16:11:35 -0500567the following in your append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500568
569 SRC_URI += "file://myconfig.cfg \
570 file://eth.cfg \
571 file://gfx.cfg"
572
573Another variable you can use in your kernel recipe append file is the
574:term:`FILESEXTRAPATHS`
575variable. When you use this statement, you are extending the locations
576used by the OpenEmbedded system to look for files and patches as the
577recipe is processed.
578
579.. note::
580
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700581 There are other ways of grouping and defining configuration
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500582 options. For example, if you are working with a local clone of the
583 kernel repository, you could checkout the kernel's ``meta`` branch,
584 make your changes, and then push the changes to the local bare clone
585 of the kernel. The result is that you directly add configuration
586 options to the ``meta`` branch for your BSP. The configuration
587 options will likely end up in that location anyway if the BSP gets
588 added to the Yocto Project.
589
590 In general, however, the Yocto Project maintainers take care of
Andrew Geissler5f350902021-07-23 13:09:54 -0400591 moving the :term:`SRC_URI`-specified configuration options to the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700592 kernel's ``meta`` branch. Not only is it easier for BSP developers
593 not to have to put those configurations in the branch,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500594 but having the maintainers do it allows them to apply 'global'
595 knowledge about the kinds of common configuration options multiple
596 BSPs in the tree are typically using. This allows for promotion of
597 common configurations into common features.
598
599Applying Patches
600----------------
601
602If you have a single patch or a small series of patches that you want to
603apply to the Linux kernel source, you can do so just as you would with
604any other recipe. You first copy the patches to the path added to
605:term:`FILESEXTRAPATHS` in
606your ``.bbappend`` file as described in the previous section, and then
607reference them in :term:`SRC_URI`
608statements.
609
610For example, you can apply a three-patch series by adding the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500611lines to your linux-yocto ``.bbappend`` file in your layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500612
613 SRC_URI += "file://0001-first-change.patch"
614 SRC_URI += "file://0002-second-change.patch"
615 SRC_URI += "file://0003-third-change.patch"
616
617The next time you run BitBake to build
618the Linux kernel, BitBake detects the change in the recipe and fetches
619and applies the patches before building the kernel.
620
621For a detailed example showing how to patch the kernel using
622``devtool``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600623":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500624and
Andrew Geissler09209ee2020-12-13 08:44:15 -0600625":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500626sections.
627
628Changing the Configuration
629--------------------------
630
631You can make wholesale or incremental changes to the final ``.config``
632file used for the eventual Linux kernel configuration by including a
633``defconfig`` file and by specifying configuration fragments in the
634:term:`SRC_URI` to be applied to that
635file.
636
637If you have a complete, working Linux kernel ``.config`` file you want
638to use for the configuration, as before, copy that file to the
639appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux``
640directory, and rename the copied file to "defconfig". Then, add the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500641following lines to the linux-yocto ``.bbappend`` file in your layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500642
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500643 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500644 SRC_URI += "file://defconfig"
645
Andrew Geissler09036742021-06-25 14:25:14 -0500646The :term:`SRC_URI` tells the build system how to search
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500647for the file, while the
648:term:`FILESEXTRAPATHS`
649extends the :term:`FILESPATH`
650variable (search directories) to include the ``${PN}`` directory you
651created to hold the configuration changes.
652
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700653You can also use a regular ``defconfig`` file, as generated by the
654:ref:`ref-tasks-savedefconfig`
655task instead of a complete ``.config`` file. This only specifies the
656non-default configuration values. You need to additionally set
657:term:`KCONFIG_MODE`
658in the linux-yocto ``.bbappend`` file in your layer::
659
660 KCONFIG_MODE = "alldefconfig"
661
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500662.. note::
663
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500664 The build system applies the configurations from the ``defconfig``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500665 file before applying any subsequent configuration fragments. The
666 final kernel configuration is a combination of the configurations in
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500667 the ``defconfig`` file and any configuration fragments you provide. You need
668 to realize that if you have any configuration fragments, the build system
669 applies these on top of and after applying the existing ``defconfig`` file
670 configurations.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500671
672Generally speaking, the preferred approach is to determine the
673incremental change you want to make and add that as a configuration
674fragment. For example, if you want to add support for a basic serial
675console, create a file named ``8250.cfg`` in the ``${PN}`` directory
Andrew Geisslerc926e172021-05-07 16:11:35 -0500676with the following content (without indentation)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500677
678 CONFIG_SERIAL_8250=y
679 CONFIG_SERIAL_8250_CONSOLE=y
680 CONFIG_SERIAL_8250_PCI=y
681 CONFIG_SERIAL_8250_NR_UARTS=4
682 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
683 CONFIG_SERIAL_CORE=y
684 CONFIG_SERIAL_CORE_CONSOLE=y
685
686Next, include this
Andrew Geissler09036742021-06-25 14:25:14 -0500687configuration fragment and extend the :term:`FILESPATH` variable in your
Andrew Geisslerc926e172021-05-07 16:11:35 -0500688``.bbappend`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500689
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500690 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500691 SRC_URI += "file://8250.cfg"
692
693The next time you run BitBake to build the
694Linux kernel, BitBake detects the change in the recipe and fetches and
695applies the new configuration before building the kernel.
696
697For a detailed example showing how to configure the kernel, see the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500698":ref:`kernel-dev/common:configuring the kernel`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500699
700Using an "In-Tree"  ``defconfig`` File
701--------------------------------------
702
703It might be desirable to have kernel configuration fragment support
704through a ``defconfig`` file that is pulled from the kernel source tree
705for the configured machine. By default, the OpenEmbedded build system
706looks for ``defconfig`` files in the layer used for Metadata, which is
Andrew Geisslerc926e172021-05-07 16:11:35 -0500707"out-of-tree", and then configures them using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500708
709 SRC_URI += "file://defconfig"
710
711If you do not want to maintain copies of
712``defconfig`` files in your layer but would rather allow users to use
713the default configuration from the kernel tree and still be able to add
714configuration fragments to the
715:term:`SRC_URI` through, for example,
716append files, you can direct the OpenEmbedded build system to use a
717``defconfig`` file that is "in-tree".
718
719To specify an "in-tree" ``defconfig`` file, use the following statement
Andrew Geisslerc926e172021-05-07 16:11:35 -0500720form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500721
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500722 KBUILD_DEFCONFIG_KMACHINE ?= "defconfig_file"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500723
724Here is an example
Andrew Geissler09036742021-06-25 14:25:14 -0500725that assigns the :term:`KBUILD_DEFCONFIG` variable based on "raspberrypi2"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500726and provides the path to the "in-tree" ``defconfig`` file to be used for
Andrew Geisslerc926e172021-05-07 16:11:35 -0500727a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500728
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500729 KBUILD_DEFCONFIG:raspberrypi2 ?= "bcm2709_defconfig"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500730
731Aside from modifying your kernel recipe and providing your own
732``defconfig`` file, you need to be sure no files or statements set
Andrew Geissler5f350902021-07-23 13:09:54 -0400733:term:`SRC_URI` to use a ``defconfig`` other than your "in-tree" file (e.g.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500734a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500735build system detects a statement that identifies an "out-of-tree"
736``defconfig`` file, that statement will override your
Andrew Geissler09036742021-06-25 14:25:14 -0500737:term:`KBUILD_DEFCONFIG` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500738
739See the
740:term:`KBUILD_DEFCONFIG`
741variable description for more information.
742
743Using ``devtool`` to Patch the Kernel
744=====================================
745
746The steps in this procedure show you how you can patch the kernel using
747the extensible SDK and ``devtool``.
748
749.. note::
750
751 Before attempting this procedure, be sure you have performed the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500752 steps to get ready for updating the kernel as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600753 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500754 section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500755
756Patching the kernel involves changing or adding configurations to an
757existing kernel, changing or adding recipes to the kernel that are
758needed to support specific hardware features, or even altering the
759source code itself.
760
761This example creates a simple patch by adding some QEMU emulator console
762output at boot time through ``printk`` statements in the kernel's
763``calibrate.c`` source code file. Applying the patch and booting the
764modified image causes the added messages to appear on the emulator's
765console. The example is a continuation of the setup procedure found in
Andrew Geissler09209ee2020-12-13 08:44:15 -0600766the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500767
7681. *Check Out the Kernel Source Files:* First you must use ``devtool``
769 to checkout the kernel source code in its workspace. Be sure you are
770 in the terminal set up to do work with the extensible SDK.
771
772 .. note::
773
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500774 See this step in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600775 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500776 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500777
Andrew Geisslerc926e172021-05-07 16:11:35 -0500778 Use the following ``devtool`` command to check out the code::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500779
780 $ devtool modify linux-yocto
781
782 .. note::
783
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700784 During the checkout operation, there is a bug that could cause
785 errors such as the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500786
787 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500788
789 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
790 be3a89ce7c47178880ba7bf6293d7404 for
791 /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
792
793
794 You can safely ignore these messages. The source code is correctly
795 checked out.
796
7972. *Edit the Source Files* Follow these steps to make some simple
798 changes to the source files:
799
800 1. *Change the working directory*: In the previous step, the output
801 noted where you can find the source files (e.g.
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500802 ``poky_sdk/workspace/sources/linux-yocto``). Change to where the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500803 kernel source code is before making your edits to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500804 ``calibrate.c`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500805
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500806 $ cd poky_sdk/workspace/sources/linux-yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500807
808 2. *Edit the source file*: Edit the ``init/calibrate.c`` file to have
Andrew Geisslerc926e172021-05-07 16:11:35 -0500809 the following changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500810
811 void calibrate_delay(void)
812 {
813 unsigned long lpj;
814 static bool printed;
815 int this_cpu = smp_processor_id();
816
817 printk("*************************************\n");
818 printk("* *\n");
819 printk("* HELLO YOCTO KERNEL *\n");
820 printk("* *\n");
821 printk("*************************************\n");
822
823 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
824 .
825 .
826 .
827
8283. *Build the Updated Kernel Source:* To build the updated kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -0500829 source, use ``devtool``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500830
831 $ devtool build linux-yocto
832
8334. *Create the Image With the New Kernel:* Use the
834 ``devtool build-image`` command to create a new image that has the
835 new kernel.
836
837 .. note::
838
839 If the image you originally created resulted in a Wic file, you
840 can use an alternate method to create the new image with the
841 updated kernel. For an example, see the steps in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600842 :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500843 Wiki Page.
844
845 ::
846
847 $ cd ~
848 $ devtool build-image core-image-minimal
849
8505. *Test the New Image:* For this example, you can run the new image
851 using QEMU to verify your changes:
852
853 1. *Boot the image*: Boot the modified image in the QEMU emulator
Andrew Geisslerc926e172021-05-07 16:11:35 -0500854 using this command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500855
856 $ runqemu qemux86
857
858 2. *Verify the changes*: Log into the machine using ``root`` with no
859 password and then use the following shell command to scroll
860 through the console's boot output.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500861
862 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500863
864 # dmesg | less
865
866 You should see
867 the results of your ``printk`` statements as part of the output
868 when you scroll down the console window.
869
8706. *Stage and commit your changes*: Within your eSDK terminal, change
871 your working directory to where you modified the ``calibrate.c`` file
Andrew Geisslerc926e172021-05-07 16:11:35 -0500872 and use these Git commands to stage and commit your changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500873
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500874 $ cd poky_sdk/workspace/sources/linux-yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500875 $ git status
876 $ git add init/calibrate.c
877 $ git commit -m "calibrate: Add printk example"
878
8797. *Export the Patches and Create an Append File:* To export your
880 commits as patches and create a ``.bbappend`` file, use the following
881 command in the terminal used to work with the extensible SDK. This
882 example uses the previously established layer named ``meta-mylayer``.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500883 ::
884
885 $ devtool finish linux-yocto ~/meta-mylayer
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500886
887 .. note::
888
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500889 See Step 3 of the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600890 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500891 section for information on setting up this layer.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500892
893 Once the command
894 finishes, the patches and the ``.bbappend`` file are located in the
895 ``~/meta-mylayer/recipes-kernel/linux`` directory.
896
8978. *Build the Image With Your Modified Kernel:* You can now build an
898 image that includes your kernel patches. Execute the following
899 command from your
900 :term:`Build Directory` in the terminal
Andrew Geisslerc926e172021-05-07 16:11:35 -0500901 set up to run BitBake::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500902
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500903 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500904 $ bitbake core-image-minimal
905
906Using Traditional Kernel Development to Patch the Kernel
907========================================================
908
909The steps in this procedure show you how you can patch the kernel using
910traditional kernel development (i.e. not using ``devtool`` and the
911extensible SDK as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600912":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500913section).
914
915.. note::
916
917 Before attempting this procedure, be sure you have performed the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500918 steps to get ready for updating the kernel as described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600919 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500920 section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500921
922Patching the kernel involves changing or adding configurations to an
923existing kernel, changing or adding recipes to the kernel that are
924needed to support specific hardware features, or even altering the
925source code itself.
926
927The example in this section creates a simple patch by adding some QEMU
928emulator console output at boot time through ``printk`` statements in
929the kernel's ``calibrate.c`` source code file. Applying the patch and
930booting the modified image causes the added messages to appear on the
931emulator's console. The example is a continuation of the setup procedure
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500932found in the
933":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500934Section.
935
9361. *Edit the Source Files* Prior to this step, you should have used Git
937 to create a local copy of the repository for your kernel. Assuming
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500938 you created the repository as directed in the
939 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500940 section, use the following commands to edit the ``calibrate.c`` file:
941
942 1. *Change the working directory*: You need to locate the source
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500943 files in the local copy of the kernel Git repository. Change to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500944 where the kernel source code is before making your edits to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500945 ``calibrate.c`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500946
947 $ cd ~/linux-yocto-4.12/init
948
949 2. *Edit the source file*: Edit the ``calibrate.c`` file to have the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500950 following changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500951
952 void calibrate_delay(void)
953 {
954 unsigned long lpj;
955 static bool printed;
956 int this_cpu = smp_processor_id();
957
958 printk("*************************************\n");
959 printk("* *\n");
960 printk("* HELLO YOCTO KERNEL *\n");
961 printk("* *\n");
962 printk("*************************************\n");
963
964 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
965 .
966 .
967 .
968
9692. *Stage and Commit Your Changes:* Use standard Git commands to stage
Andrew Geisslerc926e172021-05-07 16:11:35 -0500970 and commit the changes you just made::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500971
972 $ git add calibrate.c
973 $ git commit -m "calibrate.c - Added some printk statements"
974
975 If you do not
976 stage and commit your changes, the OpenEmbedded Build System will not
977 pick up the changes.
978
9793. *Update Your local.conf File to Point to Your Source Files:* In
980 addition to your ``local.conf`` file specifying to use
981 "kernel-modules" and the "qemux86" machine, it must also point to the
982 updated kernel source files. Add
983 :term:`SRC_URI` and
984 :term:`SRCREV` statements similar
Andrew Geisslerc926e172021-05-07 16:11:35 -0500985 to the following to your ``local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500986
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500987 $ cd poky/build/conf
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500988
Andrew Geisslerc926e172021-05-07 16:11:35 -0500989 Add the following to the ``local.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500990
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500991 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 -0500992 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 -0500993 SRCREV_meta:qemux86 = "${AUTOREV}"
994 SRCREV_machine:qemux86 = "${AUTOREV}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500995
996 .. note::
997
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500998 Be sure to replace `path-to`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500999 with the pathname to your local Git repositories. Also, you must
1000 be sure to specify the correct branch and machine types. For this
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001001 example, the branch is ``standard/base`` and the machine is ``qemux86``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001002
10034. *Build the Image:* With the source modified, your changes staged and
1004 committed, and the ``local.conf`` file pointing to the kernel files,
Andrew Geisslerc926e172021-05-07 16:11:35 -05001005 you can now use BitBake to build the image::
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 core-image-minimal
1009
10105. *Boot the image*: Boot the modified image in the QEMU emulator using
1011 this command. When prompted to login to the QEMU console, use "root"
Andrew Geisslerc926e172021-05-07 16:11:35 -05001012 with no password::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001013
Andrew Geissler95ac1b82021-03-31 14:34:31 -05001014 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001015 $ runqemu qemux86
1016
10176. *Look for Your Changes:* As QEMU booted, you might have seen your
1018 changes rapidly scroll by. If not, use these commands to see your
1019 changes:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001020
1021 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001022
1023 # dmesg | less
1024
1025 You should see the results of your
1026 ``printk`` statements as part of the output when you scroll down the
1027 console window.
1028
10297. *Generate the Patch File:* Once you are sure that your patch works
1030 correctly, you can generate a ``*.patch`` file in the kernel source
Andrew Geisslerc926e172021-05-07 16:11:35 -05001031 repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001032
1033 $ cd ~/linux-yocto-4.12/init
1034 $ git format-patch -1
1035 0001-calibrate.c-Added-some-printk-statements.patch
1036
10378. *Move the Patch File to Your Layer:* In order for subsequent builds
1038 to pick up patches, you need to move the patch file you created in
1039 the previous step to your layer ``meta-mylayer``. For this example,
1040 the layer created earlier is located in your home directory as
1041 ``meta-mylayer``. When the layer was created using the
1042 ``yocto-create`` script, no additional hierarchy was created to
1043 support patches. Before moving the patch file, you need to add
Andrew Geisslerc926e172021-05-07 16:11:35 -05001044 additional structure to your layer using the following commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001045
1046 $ cd ~/meta-mylayer
1047 $ mkdir recipes-kernel
1048 $ mkdir recipes-kernel/linux
1049 $ mkdir recipes-kernel/linux/linux-yocto
1050
1051 Once you have created this
1052 hierarchy in your layer, you can move the patch file using the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001053 following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001054
1055 $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto
1056
10579. *Create the Append File:* Finally, you need to create the
1058 ``linux-yocto_4.12.bbappend`` file and insert statements that allow
1059 the OpenEmbedded build system to find the patch. The append file
1060 needs to be in your layer's ``recipes-kernel/linux`` directory and it
1061 must be named ``linux-yocto_4.12.bbappend`` and have the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001062 contents::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001063
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001064 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerd5838332022-05-27 11:33:10 -05001065 SRC_URI:append = " file://0001-calibrate.c-Added-some-printk-statements.patch"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001066
1067 The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
1068 enable the OpenEmbedded build system to find the patch file.
1069
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001070 For more information on append files and patches, see the
1071 ":ref:`kernel-dev/common:creating the append file`" and
1072 ":ref:`kernel-dev/common:applying patches`" sections. You can also see the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001073 ":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001074 section in the Yocto Project Development Tasks Manual.
1075
1076 .. note::
1077
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001078 To build ``core-image-minimal`` again and see the effects of your patch,
1079 you can essentially eliminate the temporary source files saved in
1080 ``poky/build/tmp/work/...`` and residual effects of the build by entering
Andrew Geisslerc926e172021-05-07 16:11:35 -05001081 the following sequence of commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001082
Andrew Geissler95ac1b82021-03-31 14:34:31 -05001083 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001084 $ bitbake -c cleanall yocto-linux
1085 $ bitbake core-image-minimal -c cleanall
1086 $ bitbake core-image-minimal
1087 $ runqemu qemux86
1088
1089
1090Configuring the Kernel
1091======================
1092
1093Configuring the Yocto Project kernel consists of making sure the
1094``.config`` file has all the right information in it for the image you
1095are building. You can use the ``menuconfig`` tool and configuration
1096fragments to make sure your ``.config`` file is just how you need it.
1097You can also save known configurations in a ``defconfig`` file that the
1098build system can use for kernel configuration.
1099
1100This section describes how to use ``menuconfig``, create and use
1101configuration fragments, and how to interactively modify your
1102``.config`` file to create the leanest kernel configuration file
1103possible.
1104
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001105For more information on kernel configuration, see the
1106":ref:`kernel-dev/common:changing the configuration`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001107
1108Using  ``menuconfig``
1109---------------------
1110
1111The easiest way to define kernel configurations is to set them through
1112the ``menuconfig`` tool. This tool provides an interactive method with
1113which to set kernel configurations. For general information on
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001114``menuconfig``, see https://en.wikipedia.org/wiki/Menuconfig.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001115
1116To use the ``menuconfig`` tool in the Yocto Project development
1117environment, you must do the following:
1118
1119- Because you launch ``menuconfig`` using BitBake, you must be sure to
1120 set up your environment by running the
1121 :ref:`structure-core-script` script found in
1122 the :term:`Build Directory`.
1123
1124- You must be sure of the state of your build's configuration in the
1125 :term:`Source Directory`.
1126
Andrew Geisslerc926e172021-05-07 16:11:35 -05001127- Your build host must have the following two packages installed::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001128
1129 libncurses5-dev
1130 libtinfo-dev
1131
1132The following commands initialize the BitBake environment, run the
1133:ref:`ref-tasks-kernel_configme`
1134task, and launch ``menuconfig``. These commands assume the Source
Andrew Geisslerc926e172021-05-07 16:11:35 -05001135Directory's top-level folder is ``poky``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001136
1137 $ cd poky
1138 $ source oe-init-build-env
1139 $ bitbake linux-yocto -c kernel_configme -f
1140 $ bitbake linux-yocto -c menuconfig
1141
1142Once ``menuconfig`` comes up, its standard
1143interface allows you to interactively examine and configure all the
1144kernel configuration parameters. After making your changes, simply exit
1145the tool and save your changes to create an updated version of the
1146``.config`` configuration file.
1147
1148.. note::
1149
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001150 You can use the entire ``.config`` file as the ``defconfig`` file. For
1151 information on ``defconfig`` files, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001152 ":ref:`kernel-dev/common:changing the configuration`",
1153 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`",
1154 and ":ref:`kernel-dev/common:creating a \`\`defconfig\`\` file`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001155 sections.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001156
1157Consider an example that configures the "CONFIG_SMP" setting for the
1158``linux-yocto-4.12`` kernel.
1159
1160.. note::
1161
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001162 The OpenEmbedded build system recognizes this kernel as ``linux-yocto``
1163 through Metadata (e.g. :term:`PREFERRED_VERSION`\ ``_linux-yocto ?= "12.4%"``).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001164
1165Once ``menuconfig`` launches, use the interface to navigate through the
1166selections to find the configuration settings in which you are
1167interested. For this example, you deselect "CONFIG_SMP" by clearing the
1168"Symmetric Multi-Processing Support" option. Using the interface, you
1169can find the option under "Processor Type and Features". To deselect
1170"CONFIG_SMP", use the arrow keys to highlight "Symmetric
1171Multi-Processing Support" and enter "N" to clear the asterisk. When you
1172are finished, exit out and save the change.
1173
1174Saving the selections updates the ``.config`` configuration file. This
1175is the file that the OpenEmbedded build system uses to configure the
1176kernel during the build. You can find and examine this file in the Build
1177Directory in ``tmp/work/``. The actual ``.config`` is located in the
1178area where the specific kernel is built. For example, if you were
1179building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel
1180and you were building a QEMU image targeted for ``x86`` architecture,
1181the ``.config`` file would be:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001182
1183.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001184
1185 poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
1186 ...967-r0/linux-qemux86-standard-build/.config
1187
1188.. note::
1189
1190 The previous example directory is artificially split and many of the
1191 characters in the actual filename are omitted in order to make it
1192 more readable. Also, depending on the kernel you are using, the exact
1193 pathname might differ.
1194
1195Within the ``.config`` file, you can see the kernel settings. For
1196example, the following entry shows that symmetric multi-processor
Andrew Geisslerc926e172021-05-07 16:11:35 -05001197support is not set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001198
1199 # CONFIG_SMP is not set
1200
1201A good method to isolate changed configurations is to use a combination
1202of the ``menuconfig`` tool and simple shell commands. Before changing
1203configurations with ``menuconfig``, copy the existing ``.config`` and
1204rename it to something else, use ``menuconfig`` to make as many changes
1205as you want and save them, then compare the renamed configuration file
1206against the newly created file. You can use the resulting differences as
1207your base to create configuration fragments to permanently save in your
1208kernel layer.
1209
1210.. note::
1211
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001212 Be sure to make a copy of the ``.config`` file and do not just rename it.
1213 The build system needs an existing ``.config`` file from which to work.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001214
1215Creating a  ``defconfig`` File
1216------------------------------
1217
1218A ``defconfig`` file in the context of the Yocto Project is often a
1219``.config`` file that is copied from a build or a ``defconfig`` taken
1220from the kernel tree and moved into recipe space. You can use a
1221``defconfig`` file to retain a known set of kernel configurations from
1222which the OpenEmbedded build system can draw to create the final
1223``.config`` file.
1224
1225.. note::
1226
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001227 Out-of-the-box, the Yocto Project never ships a ``defconfig`` or ``.config``
1228 file. The OpenEmbedded build system creates the final ``.config`` file used
1229 to configure the kernel.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001230
1231To create a ``defconfig``, start with a complete, working Linux kernel
1232``.config`` file. Copy that file to the appropriate
1233``${``\ :term:`PN`\ ``}`` directory in
1234your layer's ``recipes-kernel/linux`` directory, and rename the copied
1235file to "defconfig" (e.g.
1236``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then,
1237add the following lines to the linux-yocto ``.bbappend`` file in your
Andrew Geisslerc926e172021-05-07 16:11:35 -05001238layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001239
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001240 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001241 SRC_URI += "file://defconfig"
1242
1243The :term:`SRC_URI` tells the build system how to search for the file, while the
1244:term:`FILESEXTRAPATHS` extends the :term:`FILESPATH`
1245variable (search directories) to include the ``${PN}`` directory you
1246created to hold the configuration changes.
1247
1248.. note::
1249
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001250 The build system applies the configurations from the ``defconfig``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001251 file before applying any subsequent configuration fragments. The
1252 final kernel configuration is a combination of the configurations in
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001253 the ``defconfig`` file and any configuration fragments you provide. You need
1254 to realize that if you have any configuration fragments, the build system
1255 applies these on top of and after applying the existing ``defconfig`` file
1256 configurations.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001257
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001258For more information on configuring the kernel, see the
1259":ref:`kernel-dev/common:changing the configuration`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001260
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001261Creating Configuration Fragments
1262--------------------------------
1263
1264Configuration fragments are simply kernel options that appear in a file
1265placed where the OpenEmbedded build system can find and apply them. The
1266build system applies configuration fragments after applying
1267configurations from a ``defconfig`` file. Thus, the final kernel
1268configuration is a combination of the configurations in the
1269``defconfig`` file and then any configuration fragments you provide. The
1270build system applies fragments on top of and after applying the existing
1271defconfig file configurations.
1272
1273Syntactically, the configuration statement is identical to what would
1274appear in the ``.config`` file, which is in the :term:`Build Directory`.
1275
1276.. note::
1277
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001278 For more information about where the ``.config`` file is located, see the
1279 example in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001280 ":ref:`kernel-dev/common:using \`\`menuconfig\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001281 section.
1282
1283It is simple to create a configuration fragment. One method is to use
1284shell commands. For example, issuing the following from the shell
1285creates a configuration fragment file named ``my_smp.cfg`` that enables
Andrew Geisslerc926e172021-05-07 16:11:35 -05001286multi-processor support within the kernel::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001287
1288 $ echo "CONFIG_SMP=y" >> my_smp.cfg
1289
1290.. note::
1291
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001292 All configuration fragment files must use the ``.cfg`` extension in order
1293 for the OpenEmbedded build system to recognize them as a configuration
1294 fragment.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001295
1296Another method is to create a configuration fragment using the
1297differences between two configuration files: one previously created and
1298saved, and one freshly created using the ``menuconfig`` tool.
1299
1300To create a configuration fragment using this method, follow these
1301steps:
1302
13031. *Complete a Build Through Kernel Configuration:* Complete a build at
Andrew Geisslerc926e172021-05-07 16:11:35 -05001304 least through the kernel configuration task as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001305
1306 $ bitbake linux-yocto -c kernel_configme -f
1307
1308 This step ensures that you create a
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001309 ``.config`` file from a known state. Because there are situations where
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001310 your build state might become unknown, it is best to run this task
1311 prior to starting ``menuconfig``.
1312
Andrew Geisslerc926e172021-05-07 16:11:35 -050013132. *Launch menuconfig:* Run the ``menuconfig`` command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001314
1315 $ bitbake linux-yocto -c menuconfig
1316
13173. *Create the Configuration Fragment:* Run the ``diffconfig`` command
1318 to prepare a configuration fragment. The resulting file
1319 ``fragment.cfg`` is placed in the
1320 ``${``\ :term:`WORKDIR`\ ``}``
Andrew Geisslerc926e172021-05-07 16:11:35 -05001321 directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001322
1323 $ bitbake linux-yocto -c diffconfig
1324
1325The ``diffconfig`` command creates a file that is a list of Linux kernel
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001326``CONFIG_`` assignments. See the
1327":ref:`kernel-dev/common:changing the configuration`" section for additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001328information on how to use the output as a configuration fragment.
1329
1330.. note::
1331
1332 You can also use this method to create configuration fragments for a
Andrew Geissler09209ee2020-12-13 08:44:15 -06001333 BSP. See the ":ref:`kernel-dev/advanced:bsp descriptions`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001334 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001335
1336Where do you put your configuration fragment files? You can place these
1337files in an area pointed to by
1338:term:`SRC_URI` as directed by your
1339``bblayers.conf`` file, which is located in your layer. The OpenEmbedded
1340build system picks up the configuration and adds it to the kernel's
1341configuration. For example, suppose you had a set of configuration
1342options in a file called ``myconfig.cfg``. If you put that file inside a
1343directory named ``linux-yocto`` that resides in the same directory as
1344the kernel's append file within your layer and then add the following
1345statements to the kernel's append file, those configuration options will
Andrew Geisslerc926e172021-05-07 16:11:35 -05001346be picked up and applied when the kernel is built::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001347
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001348 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001349 SRC_URI += "file://myconfig.cfg"
1350
1351As mentioned earlier, you can group related configurations into multiple
Andrew Geissler09036742021-06-25 14:25:14 -05001352files and name them all in the :term:`SRC_URI` statement as well. For
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001353example, you could group separate configurations specifically for
1354Ethernet and graphics into their own files and add those by using a
Andrew Geissler09036742021-06-25 14:25:14 -05001355:term:`SRC_URI` statement like the following in your append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001356
1357 SRC_URI += "file://myconfig.cfg \
1358 file://eth.cfg \
1359 file://gfx.cfg"
1360
1361Validating Configuration
1362------------------------
1363
1364You can use the
1365:ref:`ref-tasks-kernel_configcheck`
Andrew Geisslerc926e172021-05-07 16:11:35 -05001366task to provide configuration validation::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001367
1368 $ bitbake linux-yocto -c kernel_configcheck -f
1369
1370Running this task produces warnings for when a
1371requested configuration does not appear in the final ``.config`` file or
1372when you override a policy configuration in a hardware configuration
1373fragment.
1374
1375In order to run this task, you must have an existing ``.config`` file.
Andrew Geissler09209ee2020-12-13 08:44:15 -06001376See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001377information on how to create a configuration file.
1378
1379Following is sample output from the ``do_kernel_configcheck`` task:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001380
1381.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001382
1383 Loading cache: 100% |########################################################| Time: 0:00:00
1384 Loaded 1275 entries from dependency cache.
1385 NOTE: Resolving any missing task queue dependencies
1386
1387 Build Configuration:
1388 .
1389 .
1390 .
1391
1392 NOTE: Executing SetScene Tasks
1393 NOTE: Executing RunQueue Tasks
1394 WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck:
1395 [kernel config]: specified values did not make it into the kernel's final configuration:
1396
1397 ---------- CONFIG_X86_TSC -----------------
1398 Config: CONFIG_X86_TSC
1399 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
1400 Requested value: CONFIG_X86_TSC=y
1401 Actual value:
1402
1403
1404 ---------- CONFIG_X86_BIGSMP -----------------
1405 Config: CONFIG_X86_BIGSMP
1406 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1407 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1408 Requested value: # CONFIG_X86_BIGSMP is not set
1409 Actual value:
1410
1411
1412 ---------- CONFIG_NR_CPUS -----------------
1413 Config: CONFIG_NR_CPUS
1414 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1415 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
1416 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1417 Requested value: CONFIG_NR_CPUS=8
1418 Actual value: CONFIG_NR_CPUS=1
1419
1420
1421 ---------- CONFIG_SCHED_SMT -----------------
1422 Config: CONFIG_SCHED_SMT
1423 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1424 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1425 Requested value: CONFIG_SCHED_SMT=y
1426 Actual value:
1427
1428
1429
1430 NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded.
1431
1432 Summary: There were 3 WARNING messages shown.
1433
1434.. note::
1435
1436 The previous output example has artificial line breaks to make it
1437 more readable.
1438
1439The output describes the various problems that you can encounter along
1440with where to find the offending configuration items. You can use the
1441information in the logs to adjust your configuration files and then
1442repeat the
1443:ref:`ref-tasks-kernel_configme`
1444and
1445:ref:`ref-tasks-kernel_configcheck`
1446tasks until they produce no warnings.
1447
1448For more information on how to use the ``menuconfig`` tool, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001449:ref:`kernel-dev/common:using \`\`menuconfig\`\`` section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001450
1451Fine-Tuning the Kernel Configuration File
1452-----------------------------------------
1453
1454You can make sure the ``.config`` file is as lean or efficient as
1455possible by reading the output of the kernel configuration fragment
1456audit, noting any issues, making changes to correct the issues, and then
1457repeating.
1458
1459As part of the kernel build process, the ``do_kernel_configcheck`` task
1460runs. This task validates the kernel configuration by checking the final
1461``.config`` file against the input files. During the check, the task
1462produces warning messages for the following issues:
1463
1464- Requested options that did not make the final ``.config`` file.
1465
1466- Configuration items that appear twice in the same configuration
1467 fragment.
1468
1469- Configuration items tagged as "required" that were overridden.
1470
1471- A board overrides a non-board specific option.
1472
1473- Listed options not valid for the kernel being processed. In other
1474 words, the option does not appear anywhere.
1475
1476.. note::
1477
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001478 The :ref:`ref-tasks-kernel_configcheck` task can also optionally report if
1479 an option is overridden during processing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001480
1481For each output warning, a message points to the file that contains a
1482list of the options and a pointer to the configuration fragment that
1483defines them. Collectively, the files are the key to streamlining the
1484configuration.
1485
1486To streamline the configuration, do the following:
1487
14881. *Use a Working Configuration:* Start with a full configuration that
1489 you know works. Be sure the configuration builds and boots
1490 successfully. Use this configuration file as your baseline.
1491
14922. *Run Configure and Check Tasks:* Separately run the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001493 ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001494
1495 $ bitbake linux-yocto -c kernel_configme -f
1496 $ bitbake linux-yocto -c kernel_configcheck -f
1497
14983. *Process the Results:* Take the resulting list of files from the
1499 ``do_kernel_configcheck`` task warnings and do the following:
1500
1501 - Drop values that are redefined in the fragment but do not change
1502 the final ``.config`` file.
1503
1504 - Analyze and potentially drop values from the ``.config`` file that
1505 override required configurations.
1506
1507 - Analyze and potentially remove non-board specific options.
1508
1509 - Remove repeated and invalid options.
1510
15114. *Re-Run Configure and Check Tasks:* After you have worked through the
1512 output of the kernel configuration audit, you can re-run the
1513 ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks to see the
1514 results of your changes. If you have more issues, you can deal with
1515 them as described in the previous step.
1516
1517Iteratively working through steps two through four eventually yields a
1518minimal, streamlined configuration file. Once you have the best
1519``.config``, you can build the Linux Yocto kernel.
1520
1521Expanding Variables
1522===================
1523
1524Sometimes it is helpful to determine what a variable expands to during a
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001525build. You can examine the values of variables by examining the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001526output of the ``bitbake -e`` command. The output is long and is more
Andrew Geisslerc926e172021-05-07 16:11:35 -05001527easily managed in a text file, which allows for easy searches::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001528
1529 $ bitbake -e virtual/kernel > some_text_file
1530
1531Within the text file, you can see
1532exactly how each variable is expanded and used by the OpenEmbedded build
1533system.
1534
1535Working with a "Dirty" Kernel Version String
1536============================================
1537
1538If you build a kernel image and the version string has a "+" or a
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001539"-dirty" at the end, it means there are uncommitted modifications in the kernel's
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001540source directory. Follow these steps to clean up the version string:
1541
15421. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned
1543 Git repository (source directory) and use the following Git command
Andrew Geisslerc926e172021-05-07 16:11:35 -05001544 to list the files that have been changed, added, or removed::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001545
1546 $ git status
1547
15482. *Commit the Changes:* You should commit those changes to the kernel
1549 source tree regardless of whether or not you will save, export, or
Andrew Geisslerc926e172021-05-07 16:11:35 -05001550 use the changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001551
1552 $ git add
1553 $ git commit -s -a -m "getting rid of -dirty"
1554
15553. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the
1556 kernel.
1557
1558 Depending on your particular kernel development workflow, the
1559 commands you use to rebuild the kernel might differ. For information
1560 on building the kernel image when using ``devtool``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001561 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001562 section. For
Andrew Geisslerd5838332022-05-27 11:33:10 -05001563 information on building the kernel image when using BitBake, see the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001564 ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001565 section.
1566
1567Working With Your Own Sources
1568=============================
1569
1570If you cannot work with one of the Linux kernel versions supported by
1571existing linux-yocto recipes, you can still make use of the Yocto
1572Project Linux kernel tooling by working with your own sources. When you
1573use your own sources, you will not be able to leverage the existing
1574kernel :term:`Metadata` and stabilization
1575work of the linux-yocto sources. However, you will be able to manage
1576your own Metadata in the same format as the linux-yocto sources.
1577Maintaining format compatibility facilitates converging with linux-yocto
1578on a future, mutually-supported kernel version.
1579
1580To help you use your own sources, the Yocto Project provides a
Andrew Geissler595f6302022-01-24 19:11:47 +00001581linux-yocto custom recipe that uses ``kernel.org`` sources and
1582the Yocto Project Linux kernel tools for managing kernel Metadata.
1583You can find this recipe in the ``poky`` Git repository:
1584:yocto_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
1585</poky/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001586
1587Here are some basic steps you can use to work with your own sources:
1588
15891. *Create a Copy of the Kernel Recipe:* Copy the
1590 ``linux-yocto-custom.bb`` recipe to your layer and give it a
1591 meaningful name. The name should include the version of the Yocto
1592 Linux kernel you are using (e.g. ``linux-yocto-myproject_4.12.bb``,
1593 where "4.12" is the base version of the Linux kernel with which you
1594 would be working).
1595
15962. *Create a Directory for Your Patches:* In the same directory inside
1597 your layer, create a matching directory to store your patches and
1598 configuration files (e.g. ``linux-yocto-myproject``).
1599
16003. *Ensure You Have Configurations:* Make sure you have either a
1601 ``defconfig`` file or configuration fragment files in your layer.
1602 When you use the ``linux-yocto-custom.bb`` recipe, you must specify a
1603 configuration. If you do not have a ``defconfig`` file, you can run
Andrew Geisslerc926e172021-05-07 16:11:35 -05001604 the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001605
1606 $ make defconfig
1607
1608 After running the command, copy the
1609 resulting ``.config`` file to the ``files`` directory in your layer
1610 as "defconfig" and then add it to the
1611 :term:`SRC_URI` variable in the
1612 recipe.
1613
1614 Running the ``make defconfig`` command results in the default
1615 configuration for your architecture as defined by your kernel.
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001616 However, there is no guarantee that this configuration is valid for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001617 your use case, or that your board will even boot. This is
1618 particularly true for non-x86 architectures.
1619
1620 To use non-x86 ``defconfig`` files, you need to be more specific and
1621 find one that matches your board (i.e. for arm, you look in
1622 ``arch/arm/configs`` and use the one that is the best starting point
1623 for your board).
1624
16254. *Edit the Recipe:* Edit the following variables in your recipe as
1626 appropriate for your project:
1627
1628 - :term:`SRC_URI`: The
Andrew Geissler09036742021-06-25 14:25:14 -05001629 :term:`SRC_URI` should specify a Git repository that uses one of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001630 supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``,
Andrew Geissler09036742021-06-25 14:25:14 -05001631 and so forth). The :term:`SRC_URI` variable should also specify either
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001632 a ``defconfig`` file or some configuration fragment files. The
Andrew Geissler09036742021-06-25 14:25:14 -05001633 skeleton recipe provides an example :term:`SRC_URI` as a syntax
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001634 reference.
1635
1636 - :term:`LINUX_VERSION`:
1637 The Linux kernel version you are using (e.g. "4.12").
1638
1639 - :term:`LINUX_VERSION_EXTENSION`:
1640 The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the
1641 resulting kernel and visible through the ``uname`` command.
1642
1643 - :term:`SRCREV`: The commit ID
1644 from which you want to build.
1645
1646 - :term:`PR`: Treat this variable the
1647 same as you would in any other recipe. Increment the variable to
1648 indicate to the OpenEmbedded build system that the recipe has
1649 changed.
1650
Andrew Geissler09036742021-06-25 14:25:14 -05001651 - :term:`PV`: The default :term:`PV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001652 assignment is typically adequate. It combines the
Andrew Geissler09036742021-06-25 14:25:14 -05001653 :term:`LINUX_VERSION` with the Source Control Manager (SCM) revision
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001654 as derived from the :term:`SRCPV`
1655 variable. The combined results are a string with the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001656 form::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001657
1658 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
1659
Andrew Geissler09036742021-06-25 14:25:14 -05001660 While lengthy, the extra verbosity in :term:`PV` helps ensure you are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001661 using the exact sources from which you intend to build.
1662
1663 - :term:`COMPATIBLE_MACHINE`:
1664 A list of the machines supported by your new recipe. This variable
1665 in the example recipe is set by default to a regular expression
1666 that matches only the empty string, "(^$)". This default setting
1667 triggers an explicit build failure. You must change it to match a
1668 list of the machines that your new recipe supports. For example,
1669 to support the ``qemux86`` and ``qemux86-64`` machines, use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001670 following form::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001671
1672 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001673
16745. *Customize Your Recipe as Needed:* Provide further customizations to
1675 your recipe as needed just as you would customize an existing
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001676 linux-yocto recipe. See the
1677 ":ref:`ref-manual/devtool-reference:modifying an existing recipe`" section
1678 for information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001679
1680Working with Out-of-Tree Modules
1681================================
1682
1683This section describes steps to build out-of-tree modules on your target
1684and describes how to incorporate out-of-tree modules in the build.
1685
1686Building Out-of-Tree Modules on the Target
1687------------------------------------------
1688
1689While the traditional Yocto Project development model would be to
1690include kernel modules as part of the normal build process, you might
1691find it useful to build modules on the target. This could be the case if
1692your target system is capable and powerful enough to handle the
1693necessary compilation. Before deciding to build on your target, however,
1694you should consider the benefits of using a proper cross-development
1695environment from your build host.
1696
1697If you want to be able to build out-of-tree modules on the target, there
1698are some steps you need to take on the target that is running your SDK
1699image. Briefly, the ``kernel-dev`` package is installed by default on
1700all ``*.sdk`` images and the ``kernel-devsrc`` package is installed on
1701many of the ``*.sdk`` images. However, you need to create some scripts
1702prior to attempting to build the out-of-tree modules on the target that
1703is running that image.
1704
1705Prior to attempting to build the out-of-tree modules, you need to be on
1706the target as root and you need to change to the ``/usr/src/kernel``
1707directory. Next, ``make`` the scripts:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001708
1709.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001710
1711 # cd /usr/src/kernel
1712 # make scripts
1713
1714Because all SDK image recipes include ``dev-pkgs``, the
1715``kernel-dev`` packages will be installed as part of the SDK image and
1716the ``kernel-devsrc`` packages will be installed as part of applicable
1717SDK images. The SDK uses the scripts when building out-of-tree modules.
1718Once you have switched to that directory and created the scripts, you
1719should be able to build your out-of-tree modules on the target.
1720
1721Incorporating Out-of-Tree Modules
1722---------------------------------
1723
1724While it is always preferable to work with sources integrated into the
1725Linux kernel sources, if you need an external kernel module, the
1726``hello-mod.bb`` recipe is available as a template from which you can
1727create your own out-of-tree Linux kernel module recipe.
1728
1729This template recipe is located in the ``poky`` Git repository of the
Andrew Geissler595f6302022-01-24 19:11:47 +00001730Yocto Project:
1731:yocto_git:`meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
1732</poky/tree/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001733
1734To get started, copy this recipe to your layer and give it a meaningful
1735name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new
1736directory named ``files`` where you can store any source files, patches,
1737or other files necessary for building the module that do not come with
1738the sources. Finally, update the recipe as needed for the module.
1739Typically, you will need to set the following variables:
1740
1741- :term:`DESCRIPTION`
1742
1743- :term:`LICENSE* <LICENSE>`
1744
1745- :term:`SRC_URI`
1746
1747- :term:`PV`
1748
1749Depending on the build system used by the module sources, you might need
1750to make some adjustments. For example, a typical module ``Makefile``
Andrew Geisslerc926e172021-05-07 16:11:35 -05001751looks much like the one provided with the ``hello-mod`` template::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001752
1753 obj-m := hello.o
1754
1755 SRC := $(shell pwd)
1756
1757 all:
1758 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
1759
1760 modules_install:
1761 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
1762 ...
1763
1764The important point to note here is the :term:`KERNEL_SRC` variable. The
1765:ref:`module <ref-classes-module>` class sets this variable and the
1766:term:`KERNEL_PATH` variable to
1767``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build
1768information to build modules. If your module ``Makefile`` uses a
1769different variable, you might want to override the
1770:ref:`ref-tasks-compile` step, or
1771create a patch to the ``Makefile`` to work with the more typical
Andrew Geissler09036742021-06-25 14:25:14 -05001772:term:`KERNEL_SRC` or :term:`KERNEL_PATH` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001773
1774After you have prepared your recipe, you will likely want to include the
1775module in your images. To do this, see the documentation for the
1776following variables in the Yocto Project Reference Manual and set one of
1777them appropriately for your machine configuration file:
1778
1779- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
1780
1781- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
1782
1783- :term:`MACHINE_EXTRA_RDEPENDS`
1784
1785- :term:`MACHINE_EXTRA_RRECOMMENDS`
1786
1787Modules are often not required for boot and can be excluded from certain
Andrew Geisslerc926e172021-05-07 16:11:35 -05001788build configurations. The following allows for the most flexibility::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001789
1790 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
1791
1792The value is
1793derived by appending the module filename without the ``.ko`` extension
1794to the string "kernel-module-".
1795
1796Because the variable is
1797:term:`RRECOMMENDS` and not a
1798:term:`RDEPENDS` variable, the build
1799will not fail if this module is not available to include in the image.
1800
1801Inspecting Changes and Commits
1802==============================
1803
1804A common question when working with a kernel is: "What changes have been
1805applied to this tree?" Rather than using "grep" across directories to
1806see what has changed, you can use Git to inspect or search the kernel
1807tree. Using Git is an efficient way to see what has changed in the tree.
1808
1809What Changed in a Kernel?
1810-------------------------
1811
1812Following are a few examples that show how to use Git commands to
1813examine changes. These examples are by no means the only way to see
1814changes.
1815
1816.. note::
1817
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001818 In the following examples, unless you provide a commit range, ``kernel.org``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001819 history is blended with Yocto Project kernel changes. You can form
1820 ranges by using branch names from the kernel tree as the upper and
1821 lower commit markers with the Git commands. You can see the branch
1822 names through the web interface to the Yocto Project source
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001823 repositories at :yocto_git:`/`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001824
1825To see a full range of the changes, use the ``git whatchanged`` command
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001826and specify a commit range for the branch (`commit`\ ``..``\ `commit`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001827
1828Here is an example that looks at what has changed in the ``emenlow``
1829branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the
1830commit associated with the ``standard/base`` branch, while the upper
1831commit range is the commit associated with the ``standard/emenlow``
1832branch.
1833::
1834
1835 $ git whatchanged origin/standard/base..origin/standard/emenlow
1836
Andrew Geisslerc926e172021-05-07 16:11:35 -05001837To see short, one line summaries of changes use the ``git log`` command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001838
1839 $ git log --oneline origin/standard/base..origin/standard/emenlow
1840
Andrew Geisslerc926e172021-05-07 16:11:35 -05001841Use this command to see code differences for the changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001842
1843 $ git diff origin/standard/base..origin/standard/emenlow
1844
1845Use this command to see the commit log messages and the text
Andrew Geisslerc926e172021-05-07 16:11:35 -05001846differences::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001847
1848 $ git show origin/standard/base..origin/standard/emenlow
1849
1850Use this command to create individual patches for each change. Here is
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001851an example that creates patch files for each commit and places them
Andrew Geisslerc926e172021-05-07 16:11:35 -05001852in your ``Documents`` directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001853
1854 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
1855
1856Showing a Particular Feature or Branch Change
1857---------------------------------------------
1858
1859Tags in the Yocto Project kernel tree divide changes for significant
1860features or branches. The ``git show`` tag command shows changes based
Andrew Geisslerc926e172021-05-07 16:11:35 -05001861on a tag. Here is an example that shows ``systemtap`` changes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001862
1863 $ git show systemtap
1864
1865You can use the ``git branch --contains`` tag command to
1866show the branches that contain a particular feature. This command shows
Andrew Geisslerc926e172021-05-07 16:11:35 -05001867the branches that contain the ``systemtap`` feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001868
1869 $ git branch --contains systemtap
1870
1871Adding Recipe-Space Kernel Features
1872===================================
1873
1874You can add kernel features in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001875:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001876by using the :term:`KERNEL_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001877variable and by specifying the feature's ``.scc`` file path in the
1878:term:`SRC_URI` statement. When you
1879add features using this method, the OpenEmbedded build system checks to
1880be sure the features are present. If the features are not present, the
1881build stops. Kernel features are the last elements processed for
1882configuring and patching the kernel. Therefore, adding features in this
1883manner is a way to enforce specific features are present and enabled
1884without needing to do a full audit of any other layer's additions to the
Andrew Geissler09036742021-06-25 14:25:14 -05001885:term:`SRC_URI` statement.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001886
1887You add a kernel feature by providing the feature as part of the
Andrew Geissler09036742021-06-25 14:25:14 -05001888:term:`KERNEL_FEATURES` variable and by providing the path to the feature's
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001889``.scc`` file, which is relative to the root of the kernel Metadata. The
1890OpenEmbedded build system searches all forms of kernel Metadata on the
Andrew Geissler09036742021-06-25 14:25:14 -05001891:term:`SRC_URI` statement regardless of whether the Metadata is in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001892"kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e.
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001893part of the kernel recipe). See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001894":ref:`kernel-dev/advanced:kernel metadata location`" section for
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001895additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001896
Andrew Geissler09036742021-06-25 14:25:14 -05001897When you specify the feature's ``.scc`` file on the :term:`SRC_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001898statement, the OpenEmbedded build system adds the directory of that
1899``.scc`` file along with all its subdirectories to the kernel feature
1900search path. Because subdirectories are searched, you can reference a
Andrew Geissler09036742021-06-25 14:25:14 -05001901single ``.scc`` file in the :term:`SRC_URI` statement to reference multiple
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001902kernel features.
1903
1904Consider the following example that adds the "test.scc" feature to the
1905build.
1906
19071. *Create the Feature File:* Create a ``.scc`` file and locate it just
1908 as you would any other patch file, ``.cfg`` file, or fetcher item you
Andrew Geissler09036742021-06-25 14:25:14 -05001909 specify in the :term:`SRC_URI` statement.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001910
1911 .. note::
1912
1913 - You must add the directory of the ``.scc`` file to the
1914 fetcher's search path in the same manner as you would add a
1915 ``.patch`` file.
1916
1917 - You can create additional ``.scc`` files beneath the directory
1918 that contains the file you are adding. All subdirectories are
1919 searched during the build as potential feature directories.
1920
1921 Continuing with the example, suppose the "test.scc" feature you are
Andrew Geisslerc926e172021-05-07 16:11:35 -05001922 adding has a ``test.scc`` file in the following directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001923
1924 my_recipe
1925 |
1926 +-linux-yocto
1927 |
1928 +-test.cfg
1929 +-test.scc
1930
1931 In this example, the
1932 ``linux-yocto`` directory has both the feature ``test.scc`` file and
1933 a similarly named configuration fragment file ``test.cfg``.
1934
19352. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
Andrew Geissler09036742021-06-25 14:25:14 -05001936 recipe's :term:`SRC_URI` statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001937
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001938 SRC_URI:append = " file://test.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001939
1940 The leading space before the path is important as the path is
1941 appended to the existing path.
1942
19433. *Specify the Feature as a Kernel Feature:* Use the
Andrew Geissler09036742021-06-25 14:25:14 -05001944 :term:`KERNEL_FEATURES` statement to specify the feature as a kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -05001945 feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001946
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001947 KERNEL_FEATURES:append = " test.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001948
1949 The OpenEmbedded build
1950 system processes the kernel feature when it builds the kernel.
1951
1952 .. note::
1953
1954 If other features are contained below "test.scc", then their
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001955 directories are relative to the directory containing the ``test.scc``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001956 file.