summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-common.xml
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:30:32 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 13:56:17 +0100
commit43d07a285181e64c30d98d10ff93ef50391efe59 (patch)
tree78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/kernel-dev/kernel-dev-common.xml
parent1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff)
downloadpoky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-common.xml')
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml2730
1 files changed, 0 insertions, 2730 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
deleted file mode 100644
index 8e8a6dbed4..0000000000
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ /dev/null
@@ -1,2730 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='kernel-dev-common'>
7<title>Common Tasks</title>
8
9 <para>
10 This chapter presents several common tasks you perform when you
11 work with the Yocto Project Linux kernel.
12 These tasks include preparing your host development system for
13 kernel development, preparing a layer, modifying an existing recipe,
14 patching the kernel, configuring the kernel, iterative development,
15 working with your own sources, and incorporating out-of-tree modules.
16 <note>
17 The examples presented in this chapter work with the Yocto Project
18 2.4 Release and forward.
19 </note>
20 </para>
21
22 <section id='preparing-the-build-host-to-work-on-the-kernel'>
23 <title>Preparing the Build Host to Work on the Kernel</title>
24
25 <para>
26 Before you can do any kernel development, you need to be
27 sure your build host is set up to use the Yocto Project.
28 For information on how to get set up, see the
29 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
30 section in the Yocto Project Development Tasks Manual.
31 Part of preparing the system is creating a local Git
32 repository of the
33 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
34 (<filename>poky</filename>) on your system.
35 Follow the steps in the
36 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
37 section in the Yocto Project Development Tasks Manual to set up your
38 Source Directory.
39 <note>
40 Be sure you check out the appropriate development branch or
41 you create your local branch by checking out a specific tag
42 to get the desired version of Yocto Project.
43 See the
44 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
45 and
46 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
47 sections in the Yocto Project Development Tasks Manual for more
48 information.
49 </note>
50 </para>
51
52 <para>
53 Kernel development is best accomplished using
54 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
55 and not through traditional kernel workflow methods.
56 The remainder of this section provides information for both
57 scenarios.
58 </para>
59
60 <section id='getting-ready-to-develop-using-devtool'>
61 <title>Getting Ready to Develop Using <filename>devtool</filename></title>
62
63 <para>
64 Follow these steps to prepare to update the kernel image using
65 <filename>devtool</filename>.
66 Completing this procedure leaves you with a clean kernel image
67 and ready to make modifications as described in the
68 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
69 section:
70 <orderedlist>
71 <listitem><para>
72 <emphasis>Initialize the BitBake Environment:</emphasis>
73 Before building an extensible SDK, you need to
74 initialize the BitBake build environment by sourcing the
75 build environment script
76 (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>):
77 <literallayout class='monospaced'>
78 $ cd ~/poky
79 $ source oe-init-build-env
80 </literallayout>
81 <note>
82 The previous commands assume the
83 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
84 (i.e. <filename>poky</filename>) have been cloned
85 using Git and the local repository is named
86 "poky".
87 </note>
88 </para></listitem>
89 <listitem><para>
90 <emphasis>Prepare Your <filename>local.conf</filename> File:</emphasis>
91 By default, the
92 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
93 variable is set to "qemux86-64", which is fine if you are
94 building for the QEMU emulator in 64-bit mode.
95 However, if you are not, you need to set the
96 <filename>MACHINE</filename> variable appropriately in
97 your <filename>conf/local.conf</filename> file found in
98 the
99 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
100 (i.e. <filename>~/poky/build</filename> in this
101 example).</para>
102
103 <para>Also, since you are preparing to work on the
104 kernel image, you need to set the
105 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
106 variable to include kernel modules.</para>
107
108 <para>In this example we wish to build for qemux86 so
109 we must set the <filename>MACHINE</filename> variable
110 to "qemux86" and also add the "kernel-modules". As described
111 we do this by appending to <filename>conf/local.conf</filename>:
112 <literallayout class='monospaced'>
113 MACHINE = "qemux86"
114 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
115 </literallayout>
116 </para></listitem>
117 <listitem><para>
118 <emphasis>Create a Layer for Patches:</emphasis>
119 You need to create a layer to hold patches created
120 for the kernel image.
121 You can use the
122 <filename>bitbake-layers create-layer</filename>
123 command as follows:
124 <literallayout class='monospaced'>
125 $ cd ~/poky/build
126 $ bitbake-layers create-layer ../../meta-mylayer
127 NOTE: Starting bitbake server...
128 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
129 $
130 </literallayout>
131 <note>
132 For background information on working with
133 common and BSP layers, see the
134 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
135 section in the Yocto Project Development Tasks
136 Manual and the
137 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
138 section in the Yocto Project Board Support (BSP)
139 Developer's Guide, respectively.
140 For information on how to use the
141 <filename>bitbake-layers create-layer</filename>
142 command to quickly set up a layer, see the
143 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
144 section in the Yocto Project Development Tasks
145 Manual.
146 </note>
147 </para></listitem>
148 <listitem><para>
149 <emphasis>Inform the BitBake Build Environment About
150 Your Layer:</emphasis>
151 As directed when you created your layer, you need to
152 add the layer to the
153 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
154 variable in the <filename>bblayers.conf</filename> file
155 as follows:
156 <literallayout class='monospaced'>
157 $ cd ~/poky/build
158 $ bitbake-layers add-layer ../../meta-mylayer
159 NOTE: Starting bitbake server...
160 $
161 </literallayout>
162 </para></listitem>
163 <listitem><para>
164 <emphasis>Build the Extensible SDK:</emphasis>
165 Use BitBake to build the extensible SDK specifically
166 for use with images to be run using QEMU:
167 <literallayout class='monospaced'>
168 $ cd ~/poky/build
169 $ bitbake core-image-minimal -c populate_sdk_ext
170 </literallayout>
171 Once the build finishes, you can find the SDK installer
172 file (i.e. <filename>*.sh</filename> file) in the
173 following directory:
174 <literallayout class='monospaced'>
175 ~/poky/build/tmp/deploy/sdk
176 </literallayout>
177 For this example, the installer file is named
178 <filename>poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh</filename>
179 </para></listitem>
180 <listitem><para>
181 <emphasis>Install the Extensible SDK:</emphasis>
182 Use the following command to install the SDK.
183 For this example, install the SDK in the default
184 <filename>~/poky_sdk</filename> directory:
185 <literallayout class='monospaced'>
186 $ cd ~/poky/build/tmp/deploy/sdk
187 $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh
188 Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
189 ============================================================================
190 Enter target directory for SDK (default: ~/poky_sdk):
191 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
192 Extracting SDK......................................done
193 Setting it up...
194 Extracting buildtools...
195 Preparing build system...
196 Parsing recipes: 100% |#################################################################| Time: 0:00:52
197 Initializing tasks: 100% |############## ###############################################| Time: 0:00:04
198 Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00
199 Parsing recipes: 100% |#################################################################| Time: 0:00:33
200 Initializing tasks: 100% |##############################################################| Time: 0:00:00
201 done
202 SDK has been successfully set up and is ready to be used.
203 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
204 $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux
205 </literallayout>
206 </para></listitem>
207 <listitem><para id='setting-up-the-esdk-terminal'>
208 <emphasis>Set Up a New Terminal to Work With the
209 Extensible SDK:</emphasis>
210 You must set up a new terminal to work with the SDK.
211 You cannot use the same BitBake shell used to build the
212 installer.</para>
213
214 <para>After opening a new shell, run the SDK environment
215 setup script as directed by the output from installing
216 the SDK:
217 <literallayout class='monospaced'>
218 $ source ~/poky_sdk/environment-setup-i586-poky-linux
219 "SDK environment now set up; additionally you may now run devtool to perform development tasks.
220 Run devtool --help for further details.
221 </literallayout>
222 <note>
223 If you get a warning about attempting to use the
224 extensible SDK in an environment set up to run
225 BitBake, you did not use a new shell.
226 </note>
227 </para></listitem>
228 <listitem><para>
229 <emphasis>Build the Clean Image:</emphasis>
230 The final step in preparing to work on the kernel is to
231 build an initial image using
232 <filename>devtool</filename> in the new terminal you
233 just set up and initialized for SDK work:
234 <literallayout class='monospaced'>
235 $ devtool build-image
236 Parsing recipes: 100% |##########################################| Time: 0:00:05
237 Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors.
238 WARNING: No packages to add, building image core-image-minimal unmodified
239 Loading cache: 100% |############################################| Time: 0:00:00
240 Loaded 1299 entries from dependency cache.
241 NOTE: Resolving any missing task queue dependencies
242 Initializing tasks: 100% |#######################################| Time: 0:00:07
243 Checking sstate mirror object availability: 100% |###############| Time: 0:00:00
244 NOTE: Executing SetScene Tasks
245 NOTE: Executing RunQueue Tasks
246 NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded.
247 NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86
248 </literallayout>
249 If you were building for actual hardware and not for
250 emulation, you could flash the image to a USB stick
251 on <filename>/dev/sdd</filename> and boot your device.
252 For an example that uses a Minnowboard, see the
253 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink>
254 Wiki page.
255 </para></listitem>
256 </orderedlist>
257 </para>
258
259 <para>
260 At this point you have set up to start making modifications to
261 the kernel by using the extensible SDK.
262 For a continued example, see the
263 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
264 section.
265 </para>
266 </section>
267
268 <section id='getting-ready-for-traditional-kernel-development'>
269 <title>Getting Ready for Traditional Kernel Development</title>
270
271 <para>
272 Getting ready for traditional kernel development using the Yocto
273 Project involves many of the same steps as described in the
274 previous section.
275 However, you need to establish a local copy of the kernel source
276 since you will be editing these files.
277 </para>
278
279 <para>
280 Follow these steps to prepare to update the kernel image using
281 traditional kernel development flow with the Yocto Project.
282 Completing this procedure leaves you ready to make modifications
283 to the kernel source as described in the
284 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
285 section:
286 <orderedlist>
287 <listitem><para>
288 <emphasis>Initialize the BitBake Environment:</emphasis>
289 Before you can do anything using BitBake, you need to
290 initialize the BitBake build environment by sourcing the
291 build environment script
292 (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>).
293 Also, for this example, be sure that the local branch
294 you have checked out for <filename>poky</filename> is
295 the Yocto Project &DISTRO_NAME; branch.
296 If you need to checkout out the &DISTRO_NAME; branch,
297 see the
298 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking out by Branch in Poky</ulink>"
299 section in the Yocto Project Development Tasks Manual.
300 <literallayout class='monospaced'>
301 $ cd ~/poky
302 $ git branch
303 master
304 * &DISTRO_NAME;
305 $ source oe-init-build-env
306 </literallayout>
307 <note>
308 The previous commands assume the
309 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
310 (i.e. <filename>poky</filename>) have been cloned
311 using Git and the local repository is named
312 "poky".
313 </note>
314 </para></listitem>
315 <listitem><para>
316 <emphasis>Prepare Your <filename>local.conf</filename>
317 File:</emphasis>
318 By default, the
319 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
320 variable is set to "qemux86-64", which is fine if you are
321 building for the QEMU emulator in 64-bit mode.
322 However, if you are not, you need to set the
323 <filename>MACHINE</filename> variable appropriately in
324 your <filename>conf/local.conf</filename> file found
325 in the
326 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
327 (i.e. <filename>~/poky/build</filename> in this
328 example).</para>
329
330 <para>Also, since you are preparing to work on the
331 kernel image, you need to set the
332 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
333 variable to include kernel modules.</para>
334
335 <para>In this example we wish to build for qemux86 so
336 we must set the <filename>MACHINE</filename> variable
337 to "qemux86" and also add the "kernel-modules". As described
338 we do this by appending to <filename>conf/local.conf</filename>:
339 <literallayout class='monospaced'>
340 MACHINE = "qemux86"
341 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
342 </literallayout>
343 </para></listitem>
344 <listitem><para>
345 <emphasis>Create a Layer for Patches:</emphasis>
346 You need to create a layer to hold patches created
347 for the kernel image.
348 You can use the
349 <filename>bitbake-layers create-layer</filename>
350 command as follows:
351 <literallayout class='monospaced'>
352 $ cd ~/poky/build
353 $ bitbake-layers create-layer ../../meta-mylayer
354 NOTE: Starting bitbake server...
355 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
356 </literallayout>
357 <note>
358 For background information on working with
359 common and BSP layers, see the
360 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
361 section in the Yocto Project Development Tasks
362 Manual and the
363 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
364 section in the Yocto Project Board Support (BSP)
365 Developer's Guide, respectively.
366 For information on how to use the
367 <filename>bitbake-layers create-layer</filename>
368 command to quickly set up a layer, see the
369 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
370 section in the Yocto Project Development Tasks
371 Manual.
372 </note>
373 </para></listitem>
374 <listitem><para>
375 <emphasis>Inform the BitBake Build Environment About
376 Your Layer:</emphasis>
377 As directed when you created your layer, you need to add
378 the layer to the
379 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
380 variable in the <filename>bblayers.conf</filename> file
381 as follows:
382 <literallayout class='monospaced'>
383 $ cd ~/poky/build
384 $ bitbake-layers add-layer ../../meta-mylayer
385 NOTE: Starting bitbake server ...
386 $
387 </literallayout>
388 </para></listitem>
389 <listitem><para>
390 <emphasis>Create a Local Copy of the Kernel Git
391 Repository:</emphasis>
392 You can find Git repositories of supported Yocto Project
393 kernels organized under "Yocto Linux Kernel" in the
394 Yocto Project Source Repositories at
395 <ulink url='&YOCTO_GIT_URL;'></ulink>.
396 </para>
397
398 <para>
399 For simplicity, it is recommended that you create your
400 copy of the kernel Git repository outside of the
401 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
402 which is usually named <filename>poky</filename>.
403 Also, be sure you are in the
404 <filename>standard/base</filename> branch.
405 </para>
406
407 <para>
408 The following commands show how to create a local copy
409 of the <filename>linux-yocto-4.12</filename> kernel and
410 be in the <filename>standard/base</filename> branch.
411 <note>
412 The <filename>linux-yocto-4.12</filename> kernel
413 can be used with the Yocto Project 2.4 release
414 and forward.
415 You cannot use the
416 <filename>linux-yocto-4.12</filename> kernel with
417 releases prior to Yocto Project 2.4:
418 </note>
419 <literallayout class='monospaced'>
420 $ cd ~
421 $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base
422 Cloning into 'linux-yocto-4.12'...
423 remote: Counting objects: 6097195, done.
424 remote: Compressing objects: 100% (901026/901026), done.
425 remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256)
426 Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done.
427 Resolving deltas: 100% (5152604/5152604), done.
428 Checking connectivity... done.
429 Checking out files: 100% (59846/59846), done.
430 </literallayout>
431 </para></listitem>
432 <listitem><para>
433 <emphasis>Create a Local Copy of the Kernel Cache Git
434 Repository:</emphasis>
435 For simplicity, it is recommended that you create your
436 copy of the kernel cache Git repository outside of the
437 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
438 which is usually named <filename>poky</filename>.
439 Also, for this example, be sure you are in the
440 <filename>yocto-4.12</filename> branch.
441 </para>
442
443 <para>
444 The following commands show how to create a local copy
445 of the <filename>yocto-kernel-cache</filename> and
446 be in the <filename>yocto-4.12</filename> branch:
447 <literallayout class='monospaced'>
448 $ cd ~
449 $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12
450 Cloning into 'yocto-kernel-cache'...
451 remote: Counting objects: 22639, done.
452 remote: Compressing objects: 100% (9761/9761), done.
453 remote: Total 22639 (delta 12400), reused 22586 (delta 12347)
454 Receiving objects: 100% (22639/22639), 22.34 MiB | 6.27 MiB/s, done.
455 Resolving deltas: 100% (12400/12400), done.
456 Checking connectivity... done.
457 </literallayout>
458 </para></listitem>
459 </orderedlist>
460 </para>
461
462 <para>
463 At this point, you are ready to start making modifications to
464 the kernel using traditional kernel development steps.
465 For a continued example, see the
466 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
467 section.
468 </para>
469 </section>
470 </section>
471
472 <section id='creating-and-preparing-a-layer'>
473 <title>Creating and Preparing a Layer</title>
474
475 <para>
476 If you are going to be modifying kernel recipes, it is recommended
477 that you create and prepare your own layer in which to do your
478 work.
479 Your layer contains its own
480 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
481 append files (<filename>.bbappend</filename>) and provides a
482 convenient mechanism to create your own recipe files
483 (<filename>.bb</filename>) as well as store and use kernel
484 patch files.
485 For background information on working with layers, see the
486 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
487 section in the Yocto Project Development Tasks Manual.
488 <note><title>Tip</title>
489 The Yocto Project comes with many tools that simplify
490 tasks you need to perform.
491 One such tool is the
492 <filename>bitbake-layers create-layer</filename>
493 command, which simplifies creating a new layer.
494 See the
495 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
496 section in the Yocto Project Development Tasks Manual for
497 information on how to use this script to quick set up a
498 new layer.
499 </note>
500 </para>
501
502 <para>
503 To better understand the layer you create for kernel development,
504 the following section describes how to create a layer
505 without the aid of tools.
506 These steps assume creation of a layer named
507 <filename>mylayer</filename> in your home directory:
508 <orderedlist>
509 <listitem><para>
510 <emphasis>Create Structure</emphasis>:
511 Create the layer's structure:
512 <literallayout class='monospaced'>
513 $ cd $HOME
514 $ mkdir meta-mylayer
515 $ mkdir meta-mylayer/conf
516 $ mkdir meta-mylayer/recipes-kernel
517 $ mkdir meta-mylayer/recipes-kernel/linux
518 $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto
519 </literallayout>
520 The <filename>conf</filename> directory holds your
521 configuration files, while the
522 <filename>recipes-kernel</filename> directory holds your
523 append file and eventual patch files.
524 </para></listitem>
525 <listitem><para>
526 <emphasis>Create the Layer Configuration File</emphasis>:
527 Move to the <filename>meta-mylayer/conf</filename>
528 directory and create the <filename>layer.conf</filename>
529 file as follows:
530 <literallayout class='monospaced'>
531 # We have a conf and classes directory, add to BBPATH
532 BBPATH .= ":${LAYERDIR}"
533
534 # We have recipes-* directories, add to BBFILES
535 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
536 ${LAYERDIR}/recipes-*/*/*.bbappend"
537
538 BBFILE_COLLECTIONS += "mylayer"
539 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
540 BBFILE_PRIORITY_mylayer = "5"
541 </literallayout>
542 Notice <filename>mylayer</filename> as part of the last
543 three statements.
544 </para></listitem>
545 <listitem><para>
546 <emphasis>Create the Kernel Recipe Append File</emphasis>:
547 Move to the
548 <filename>meta-mylayer/recipes-kernel/linux</filename>
549 directory and create the kernel's append file.
550 This example uses the
551 <filename>linux-yocto-4.12</filename> kernel.
552 Thus, the name of the append file is
553 <filename>linux-yocto_4.12.bbappend</filename>:
554 <literallayout class='monospaced'>
555 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
556
557 SRC_URI_append = " file://<replaceable>patch-file-one</replaceable>"
558 SRC_URI_append = " file://<replaceable>patch-file-two</replaceable>"
559 SRC_URI_append = " file://<replaceable>patch-file-three</replaceable>"
560 </literallayout>
561 The
562 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
563 and
564 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
565 statements enable the OpenEmbedded build system to find
566 patch files.
567 For more information on using append files, see the
568 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
569 section in the Yocto Project Development Tasks Manual.
570 </para></listitem>
571 </orderedlist>
572 </para>
573 </section>
574
575 <section id='modifying-an-existing-recipe'>
576 <title>Modifying an Existing Recipe</title>
577
578 <para>
579 In many cases, you can customize an existing linux-yocto recipe to
580 meet the needs of your project.
581 Each release of the Yocto Project provides a few Linux
582 kernel recipes from which you can choose.
583 These are located in the
584 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
585 in <filename>meta/recipes-kernel/linux</filename>.
586 </para>
587
588 <para>
589 Modifying an existing recipe can consist of the following:
590 <itemizedlist>
591 <listitem><para>Creating the append file</para></listitem>
592 <listitem><para>Applying patches</para></listitem>
593 <listitem><para>Changing the configuration</para></listitem>
594 </itemizedlist>
595 </para>
596
597 <para>
598 Before modifying an existing recipe, be sure that you have created
599 a minimal, custom layer from which you can work.
600 See the
601 "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
602 section for information.
603 </para>
604
605 <section id='creating-the-append-file'>
606 <title>Creating the Append File</title>
607
608 <para>
609 You create this file in your custom layer.
610 You also name it accordingly based on the linux-yocto recipe
611 you are using.
612 For example, if you are modifying the
613 <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>
614 recipe, the append file will typically be located as follows
615 within your custom layer:
616 <literallayout class='monospaced'>
617 <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.12.bbappend
618 </literallayout>
619 The append file should initially extend the
620 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
621 search path by prepending the directory that contains your
622 files to the
623 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
624 variable as follows:
625 <literallayout class='monospaced'>
626 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
627 </literallayout>
628 The path <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
629 expands to "linux-yocto" in the current directory for this
630 example.
631 If you add any new files that modify the kernel recipe and you
632 have extended <filename>FILESPATH</filename> as
633 described above, you must place the files in your layer in the
634 following area:
635 <literallayout class='monospaced'>
636 <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto/
637 </literallayout>
638 <note>If you are working on a new machine Board Support Package
639 (BSP), be sure to refer to the
640 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
641 </note>
642 </para>
643
644 <para>
645 As an example, consider the following append file
646 used by the BSPs in <filename>meta-yocto-bsp</filename>:
647 <literallayout class='monospaced'>
648 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend
649 </literallayout>
650 The following listing shows the file.
651 Be aware that the actual commit ID strings in this
652 example listing might be different than the actual strings
653 in the file from the <filename>meta-yocto-bsp</filename>
654 layer upstream.
655 <literallayout class='monospaced'>
656 KBRANCH_genericx86 = "standard/base"
657 KBRANCH_genericx86-64 = "standard/base"
658
659 KMACHINE_genericx86 ?= "common-pc"
660 KMACHINE_genericx86-64 ?= "common-pc-64"
661 KBRANCH_edgerouter = "standard/edgerouter"
662 KBRANCH_beaglebone = "standard/beaglebone"
663
664 SRCREV_machine_genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
665 SRCREV_machine_genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
666 SRCREV_machine_edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
667 SRCREV_machine_beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
668
669
670 COMPATIBLE_MACHINE_genericx86 = "genericx86"
671 COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
672 COMPATIBLE_MACHINE_edgerouter = "edgerouter"
673 COMPATIBLE_MACHINE_beaglebone = "beaglebone"
674
675 LINUX_VERSION_genericx86 = "4.12.7"
676 LINUX_VERSION_genericx86-64 = "4.12.7"
677 LINUX_VERSION_edgerouter = "4.12.10"
678 LINUX_VERSION_beaglebone = "4.12.10"
679 </literallayout>
680 This append file contains statements used to support
681 several BSPs that ship with the Yocto Project.
682 The file defines machines using the
683 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
684 variable and uses the
685 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
686 variable to ensure the machine name used by the OpenEmbedded
687 build system maps to the machine name used by the Linux Yocto
688 kernel.
689 The file also uses the optional
690 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
691 variable to ensure the build process uses the
692 appropriate kernel branch.
693 </para>
694
695 <para>
696 Although this particular example does not use it, the
697 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
698 variable could be used to enable features specific to
699 the kernel.
700 The append file points to specific commits in the
701 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
702 Git repository and the <filename>meta</filename> Git repository
703 branches to identify the exact kernel needed to build the
704 BSP.
705 </para>
706
707 <para>
708 One thing missing in this particular BSP, which you will
709 typically need when developing a BSP, is the kernel
710 configuration file (<filename>.config</filename>) for your BSP.
711 When developing a BSP, you probably have a kernel configuration
712 file or a set of kernel configuration files that, when taken
713 together, define the kernel configuration for your BSP.
714 You can accomplish this definition by putting the configurations
715 in a file or a set of files inside a directory located at the
716 same level as your kernel's append file and having the same
717 name as the kernel's main recipe file.
718 With all these conditions met, simply reference those files in
719 the
720 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
721 statement in the append file.
722 </para>
723
724 <para>
725 For example, suppose you had some configuration options
726 in a file called <filename>network_configs.cfg</filename>.
727 You can place that file inside a directory named
728 <filename>linux-yocto</filename> and then add
729 a <filename>SRC_URI</filename> statement such as the
730 following to the append file.
731 When the OpenEmbedded build system builds the kernel, the
732 configuration options are picked up and applied.
733 <literallayout class='monospaced'>
734 SRC_URI += "file://network_configs.cfg"
735 </literallayout>
736 </para>
737
738 <para>
739 To group related configurations into multiple files, you
740 perform a similar procedure.
741 Here is an example that groups separate configurations
742 specifically for Ethernet and graphics into their own
743 files and adds the configurations by using a
744 <filename>SRC_URI</filename> statement like the following
745 in your append file:
746 <literallayout class='monospaced'>
747 SRC_URI += "file://myconfig.cfg \
748 file://eth.cfg \
749 file://gfx.cfg"
750 </literallayout>
751 </para>
752
753 <para>
754 Another variable you can use in your kernel recipe append
755 file is the
756 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
757 variable.
758 When you use this statement, you are extending the locations
759 used by the OpenEmbedded system to look for files and
760 patches as the recipe is processed.
761 </para>
762
763 <note>
764 <para>
765 Other methods exist to accomplish grouping and defining
766 configuration options.
767 For example, if you are working with a local clone of the
768 kernel repository, you could checkout the kernel's
769 <filename>meta</filename> branch, make your changes, and
770 then push the changes to the local bare clone of the
771 kernel.
772 The result is that you directly add configuration options
773 to the <filename>meta</filename> branch for your BSP.
774 The configuration options will likely end up in that
775 location anyway if the BSP gets added to the Yocto Project.
776 </para>
777
778 <para>
779 In general, however, the Yocto Project maintainers take
780 care of moving the <filename>SRC_URI</filename>-specified
781 configuration options to the kernel's
782 <filename>meta</filename> branch.
783 Not only is it easier for BSP developers to not have to
784 worry about putting those configurations in the branch,
785 but having the maintainers do it allows them to apply
786 'global' knowledge about the kinds of common configuration
787 options multiple BSPs in the tree are typically using.
788 This allows for promotion of common configurations into
789 common features.
790 </para>
791 </note>
792 </section>
793
794 <section id='applying-patches'>
795 <title>Applying Patches</title>
796
797 <para>
798 If you have a single patch or a small series of patches
799 that you want to apply to the Linux kernel source, you
800 can do so just as you would with any other recipe.
801 You first copy the patches to the path added to
802 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
803 in your <filename>.bbappend</filename> file as described in
804 the previous section, and then reference them in
805 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
806 statements.
807 </para>
808
809 <para>
810 For example, you can apply a three-patch series by adding the
811 following lines to your linux-yocto
812 <filename>.bbappend</filename> file in your layer:
813 <literallayout class='monospaced'>
814 SRC_URI += "file://0001-first-change.patch"
815 SRC_URI += "file://0002-second-change.patch"
816 SRC_URI += "file://0003-third-change.patch"
817 </literallayout>
818 The next time you run BitBake to build the Linux kernel,
819 BitBake detects the change in the recipe and fetches and
820 applies the patches before building the kernel.
821 </para>
822
823 <para>
824 For a detailed example showing how to patch the kernel using
825 <filename>devtool</filename>, see the
826 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
827 and
828 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
829 sections.
830 </para>
831 </section>
832
833 <section id='changing-the-configuration'>
834 <title>Changing the Configuration</title>
835
836 <para>
837 You can make wholesale or incremental changes to the final
838 <filename>.config</filename> file used for the eventual
839 Linux kernel configuration by including a
840 <filename>defconfig</filename> file and by specifying
841 configuration fragments in the
842 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
843 to be applied to that file.
844 </para>
845
846 <para>
847 If you have a complete, working Linux kernel
848 <filename>.config</filename>
849 file you want to use for the configuration, as before, copy
850 that file to the appropriate <filename>${PN}</filename>
851 directory in your layer's
852 <filename>recipes-kernel/linux</filename> directory,
853 and rename the copied file to "defconfig".
854 Then, add the following lines to the linux-yocto
855 <filename>.bbappend</filename> file in your layer:
856 <literallayout class='monospaced'>
857 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
858 SRC_URI += "file://defconfig"
859 </literallayout>
860 The <filename>SRC_URI</filename> tells the build system how to
861 search for the file, while the
862 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
863 extends the
864 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
865 variable (search directories) to include the
866 <filename>${PN}</filename> directory you created to hold the
867 configuration changes.
868 </para>
869
870 <note>
871 The build system applies the configurations from the
872 <filename>defconfig</filename> file before applying any
873 subsequent configuration fragments.
874 The final kernel configuration is a combination of the
875 configurations in the <filename>defconfig</filename> file and
876 any configuration fragments you provide.
877 You need to realize that if you have any configuration
878 fragments, the build system applies these on top of and
879 after applying the existing <filename>defconfig</filename>
880 file configurations.
881 </note>
882
883 <para>
884 Generally speaking, the preferred approach is to determine the
885 incremental change you want to make and add that as a
886 configuration fragment.
887 For example, if you want to add support for a basic serial
888 console, create a file named <filename>8250.cfg</filename> in
889 the <filename>${PN}</filename> directory with the following
890 content (without indentation):
891 <literallayout class='monospaced'>
892 CONFIG_SERIAL_8250=y
893 CONFIG_SERIAL_8250_CONSOLE=y
894 CONFIG_SERIAL_8250_PCI=y
895 CONFIG_SERIAL_8250_NR_UARTS=4
896 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
897 CONFIG_SERIAL_CORE=y
898 CONFIG_SERIAL_CORE_CONSOLE=y
899 </literallayout>
900 Next, include this configuration fragment and extend the
901 <filename>FILESPATH</filename> variable in your
902 <filename>.bbappend</filename> file:
903 <literallayout class='monospaced'>
904 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
905 SRC_URI += "file://8250.cfg"
906 </literallayout>
907 The next time you run BitBake to build the Linux kernel, BitBake
908 detects the change in the recipe and fetches and applies the
909 new configuration before building the kernel.
910 </para>
911
912 <para>
913 For a detailed example showing how to configure the kernel,
914 see the
915 "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>"
916 section.
917 </para>
918 </section>
919
920 <section id='using-an-in-tree-defconfig-file'>
921 <title>Using an "In-Tree"&nbsp;&nbsp;<filename>defconfig</filename> File</title>
922
923 <para>
924 It might be desirable to have kernel configuration fragment
925 support through a <filename>defconfig</filename> file that
926 is pulled from the kernel source tree for the configured
927 machine.
928 By default, the OpenEmbedded build system looks for
929 <filename>defconfig</filename> files in the layer used for
930 Metadata, which is "out-of-tree", and then configures them
931 using the following:
932 <literallayout class='monospaced'>
933 SRC_URI += "file://defconfig"
934 </literallayout>
935 If you do not want to maintain copies of
936 <filename>defconfig</filename> files in your layer but would
937 rather allow users to use the default configuration from the
938 kernel tree and still be able to add configuration fragments
939 to the
940 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
941 through, for example, append files, you can direct the
942 OpenEmbedded build system to use a
943 <filename>defconfig</filename> file that is "in-tree".
944 </para>
945
946 <para>
947 To specify an "in-tree" <filename>defconfig</filename> file,
948 use the following statement form:
949 <literallayout class='monospaced'>
950 KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
951 </literallayout>
952 Here is an example that assigns the
953 <filename>KBUILD_DEFCONFIG</filename> variable based on
954 "raspberrypi2" and provides the path to the "in-tree"
955 <filename>defconfig</filename> file
956 to be used for a Raspberry Pi 2,
957 which is based on the Broadcom 2708/2709 chipset:
958 <literallayout class='monospaced'>
959 KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig"
960 </literallayout>
961 </para>
962
963 <para>
964 Aside from modifying your kernel recipe and providing your own
965 <filename>defconfig</filename> file, you need to be sure no
966 files or statements set <filename>SRC_URI</filename> to use a
967 <filename>defconfig</filename> other than your "in-tree"
968 file (e.g. a kernel's
969 <filename>linux-</filename><replaceable>machine</replaceable><filename>.inc</filename>
970 file).
971 In other words, if the build system detects a statement
972 that identifies an "out-of-tree"
973 <filename>defconfig</filename> file, that statement
974 will override your
975 <filename>KBUILD_DEFCONFIG</filename> variable.
976 </para>
977
978 <para>
979 See the
980 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG'><filename>KBUILD_DEFCONFIG</filename></ulink>
981 variable description for more information.
982 </para>
983 </section>
984 </section>
985
986 <section id="using-devtool-to-patch-the-kernel">
987 <title>Using <filename>devtool</filename> to Patch the Kernel</title>
988
989 <para>
990 The steps in this procedure show you how you can patch the
991 kernel using the extensible SDK and <filename>devtool</filename>.
992 <note>
993 Before attempting this procedure, be sure you have performed
994 the steps to get ready for updating the kernel as described
995 in the
996 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
997 section.
998 </note>
999 </para>
1000
1001 <para>
1002 Patching the kernel involves changing or adding configurations
1003 to an existing kernel, changing or adding recipes to the kernel
1004 that are needed to support specific hardware features, or even
1005 altering the source code itself.
1006 </para>
1007
1008 <para>
1009 This example creates a simple patch by adding some QEMU emulator
1010 console output at boot time through <filename>printk</filename>
1011 statements in the kernel's <filename>calibrate.c</filename> source
1012 code file.
1013 Applying the patch and booting the modified image causes the added
1014 messages to appear on the emulator's console.
1015 The example is a continuation of the setup procedure found in
1016 the
1017 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
1018 Section.
1019 <orderedlist>
1020 <listitem><para>
1021 <emphasis>Check Out the Kernel Source Files:</emphasis>
1022 First you must use <filename>devtool</filename> to checkout
1023 the kernel source code in its workspace.
1024 Be sure you are in the terminal set up to do work
1025 with the extensible SDK.
1026 <note>
1027 See this
1028 <link linkend='setting-up-the-esdk-terminal'>step</link>
1029 in the
1030 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
1031 section for more information.
1032 </note>
1033 Use the following <filename>devtool</filename> command
1034 to check out the code:
1035 <literallayout class='monospaced'>
1036 $ devtool modify linux-yocto
1037 </literallayout>
1038 <note>
1039 During the checkout operation, a bug exists that could
1040 cause errors such as the following to appear:
1041 <literallayout class='monospaced'>
1042 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
1043 be3a89ce7c47178880ba7bf6293d7404 for
1044 /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
1045 </literallayout>
1046 You can safely ignore these messages.
1047 The source code is correctly checked out.
1048 </note>
1049 </para></listitem>
1050 <listitem><para>
1051 <emphasis>Edit the Source Files</emphasis>
1052 Follow these steps to make some simple changes to the source
1053 files:
1054 <orderedlist>
1055 <listitem><para>
1056 <emphasis>Change the working directory</emphasis>:
1057 In the previous step, the output noted where you can find
1058 the source files (e.g.
1059 <filename>~/poky_sdk/workspace/sources/linux-yocto</filename>).
1060 Change to where the kernel source code is before making
1061 your edits to the <filename>calibrate.c</filename> file:
1062 <literallayout class='monospaced'>
1063 $ cd ~/poky_sdk/workspace/sources/linux-yocto
1064 </literallayout>
1065 </para></listitem>
1066 <listitem><para>
1067 <emphasis>Edit the source file</emphasis>:
1068 Edit the <filename>init/calibrate.c</filename> file to have
1069 the following changes:
1070 <literallayout class='monospaced'>
1071 void calibrate_delay(void)
1072 {
1073 unsigned long lpj;
1074 static bool printed;
1075 int this_cpu = smp_processor_id();
1076
1077 printk("*************************************\n");
1078 printk("* *\n");
1079 printk("* HELLO YOCTO KERNEL *\n");
1080 printk("* *\n");
1081 printk("*************************************\n");
1082
1083 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
1084 .
1085 .
1086 .
1087 </literallayout>
1088 </para></listitem>
1089 </orderedlist>
1090 </para></listitem>
1091 <listitem><para>
1092 <emphasis>Build the Updated Kernel Source:</emphasis>
1093 To build the updated kernel source, use
1094 <filename>devtool</filename>:
1095 <literallayout class='monospaced'>
1096 $ devtool build linux-yocto
1097 </literallayout>
1098 </para></listitem>
1099 <listitem><para>
1100 <emphasis>Create the Image With the New Kernel:</emphasis>
1101 Use the <filename>devtool build-image</filename> command
1102 to create a new image that has the new kernel.
1103 <note>
1104 If the image you originally created resulted in a Wic
1105 file, you can use an alternate method to create the new
1106 image with the updated kernel.
1107 For an example, see the steps in the
1108 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink>
1109 Wiki Page.
1110 </note>
1111 <literallayout class='monospaced'>
1112 $ cd ~
1113 $ devtool build-image core-image-minimal
1114 </literallayout>
1115 </para></listitem>
1116 <listitem><para>
1117 <emphasis>Test the New Image:</emphasis>
1118 For this example, you can run the new image using QEMU
1119 to verify your changes:
1120 <orderedlist>
1121 <listitem><para>
1122 <emphasis>Boot the image</emphasis>:
1123 Boot the modified image in the QEMU emulator
1124 using this command:
1125 <literallayout class='monospaced'>
1126 $ runqemu qemux86
1127 </literallayout>
1128 </para></listitem>
1129 <listitem><para>
1130 <emphasis>Verify the changes</emphasis>:
1131 Log into the machine using <filename>root</filename>
1132 with no password and then use the following shell
1133 command to scroll through the console's boot output.
1134 <literallayout class='monospaced'>
1135 # dmesg | less
1136 </literallayout>
1137 You should see the results of your
1138 <filename>printk</filename> statements
1139 as part of the output when you scroll down the
1140 console window.
1141 </para></listitem>
1142 </orderedlist>
1143 </para></listitem>
1144 <listitem><para>
1145 <emphasis>Stage and commit your changes</emphasis>:
1146 Within your eSDK terminal, change your working directory to
1147 where you modified the <filename>calibrate.c</filename>
1148 file and use these Git commands to stage and commit your
1149 changes:
1150 <literallayout class='monospaced'>
1151 $ cd ~/poky_sdk/workspace/sources/linux-yocto
1152 $ git status
1153 $ git add init/calibrate.c
1154 $ git commit -m "calibrate: Add printk example"
1155 </literallayout>
1156 </para></listitem>
1157 <listitem><para>
1158 <emphasis>Export the Patches and Create an Append File:</emphasis>
1159 To export your commits as patches and create a
1160 <filename>.bbappend</filename> file, use the following
1161 command in the terminal used to work with the extensible
1162 SDK.
1163 This example uses the previously established layer named
1164 <filename>meta-mylayer</filename>.
1165 <note>
1166 See Step 3 of the
1167 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using devtool</link>"
1168 section for information on setting up this layer.
1169 </note>
1170 <literallayout class='monospaced'>
1171 $ devtool finish linux-yocto ~/meta-mylayer
1172 </literallayout>
1173 Once the command finishes, the patches and the
1174 <filename>.bbappend</filename> file are located in the
1175 <filename>~/meta-mylayer/recipes-kernel/linux</filename>
1176 directory.
1177 </para></listitem>
1178 <listitem><para>
1179 <emphasis>Build the Image With Your Modified Kernel:</emphasis>
1180 You can now build an image that includes your kernel
1181 patches.
1182 Execute the following command from your
1183 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
1184 in the terminal set up to run BitBake:
1185 <literallayout class='monospaced'>
1186 $ cd ~/poky/build
1187 $ bitbake core-image-minimal
1188 </literallayout>
1189 </para></listitem>
1190 </orderedlist>
1191 </para>
1192 </section>
1193
1194 <section id="using-traditional-kernel-development-to-patch-the-kernel">
1195 <title>Using Traditional Kernel Development to Patch the Kernel</title>
1196
1197 <para>
1198 The steps in this procedure show you how you can patch the
1199 kernel using traditional kernel development (i.e. not using
1200 <filename>devtool</filename> and the extensible SDK as
1201 described in the
1202 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
1203 section).
1204 <note>
1205 Before attempting this procedure, be sure you have performed
1206 the steps to get ready for updating the kernel as described
1207 in the
1208 "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
1209 section.
1210 </note>
1211 </para>
1212
1213 <para>
1214 Patching the kernel involves changing or adding configurations
1215 to an existing kernel, changing or adding recipes to the kernel
1216 that are needed to support specific hardware features, or even
1217 altering the source code itself.
1218 </para>
1219
1220 <para>
1221 The example in this section creates a simple patch by adding some
1222 QEMU emulator console output at boot time through
1223 <filename>printk</filename> statements in the kernel's
1224 <filename>calibrate.c</filename> source code file.
1225 Applying the patch and booting the modified image causes the added
1226 messages to appear on the emulator's console.
1227 The example is a continuation of the setup procedure found in
1228 the
1229 "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
1230 Section.
1231 <orderedlist>
1232 <listitem><para>
1233 <emphasis>Edit the Source Files</emphasis>
1234 Prior to this step, you should have used Git to create a
1235 local copy of the repository for your kernel.
1236 Assuming you created the repository as directed in the
1237 "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
1238 section, use the following commands to edit the
1239 <filename>calibrate.c</filename> file:
1240 <orderedlist>
1241 <listitem><para>
1242 <emphasis>Change the working directory</emphasis>:
1243 You need to locate the source files in the
1244 local copy of the kernel Git repository:
1245 Change to where the kernel source code is before making
1246 your edits to the <filename>calibrate.c</filename> file:
1247 <literallayout class='monospaced'>
1248 $ cd ~/linux-yocto-4.12/init
1249 </literallayout>
1250 </para></listitem>
1251 <listitem><para>
1252 <emphasis>Edit the source file</emphasis>:
1253 Edit the <filename>calibrate.c</filename> file to have
1254 the following changes:
1255 <literallayout class='monospaced'>
1256 void calibrate_delay(void)
1257 {
1258 unsigned long lpj;
1259 static bool printed;
1260 int this_cpu = smp_processor_id();
1261
1262 printk("*************************************\n");
1263 printk("* *\n");
1264 printk("* HELLO YOCTO KERNEL *\n");
1265 printk("* *\n");
1266 printk("*************************************\n");
1267
1268 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
1269 .
1270 .
1271 .
1272 </literallayout>
1273 </para></listitem>
1274 </orderedlist>
1275 </para></listitem>
1276 <listitem><para>
1277 <emphasis>Stage and Commit Your Changes:</emphasis>
1278 Use standard Git commands to stage and commit the changes
1279 you just made:
1280 <literallayout class='monospaced'>
1281 $ git add calibrate.c
1282 $ git commit -m "calibrate.c - Added some printk statements"
1283 </literallayout>
1284 If you do not stage and commit your changes, the OpenEmbedded
1285 Build System will not pick up the changes.
1286 </para></listitem>
1287 <listitem><para>
1288 <emphasis>Update Your <filename>local.conf</filename> File
1289 to Point to Your Source Files:</emphasis>
1290 In addition to your <filename>local.conf</filename> file
1291 specifying to use "kernel-modules" and the "qemux86"
1292 machine, it must also point to the updated kernel source
1293 files.
1294 Add
1295 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1296 and
1297 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1298 statements similar to the following to your
1299 <filename>local.conf</filename>:
1300 <literallayout class='monospaced'>
1301 $ cd ~/poky/build/conf
1302 </literallayout>
1303 Add the following to the <filename>local.conf</filename>:
1304 <literallayout class='monospaced'>
1305 SRC_URI_pn-linux-yocto = "git:///<replaceable>path-to</replaceable>/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \
1306 git:///<replaceable>path-to</replaceable>/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
1307 SRCREV_meta_qemux86 = "${AUTOREV}"
1308 SRCREV_machine_qemux86 = "${AUTOREV}"
1309 </literallayout>
1310 <note>
1311 Be sure to replace
1312 <replaceable>path-to</replaceable> with the pathname
1313 to your local Git repositories.
1314 Also, you must be sure to specify the correct branch
1315 and machine types.
1316 For this example, the branch is
1317 <filename>standard/base</filename> and the machine is
1318 "qemux86".
1319 </note>
1320 </para></listitem>
1321 <listitem><para>
1322 <emphasis>Build the Image:</emphasis>
1323 With the source modified, your changes staged and
1324 committed, and the <filename>local.conf</filename> file
1325 pointing to the kernel files, you can now use BitBake to
1326 build the image:
1327 <literallayout class='monospaced'>
1328 $ cd ~/poky/build
1329 $ bitbake core-image-minimal
1330 </literallayout>
1331 </para></listitem>
1332 <listitem><para>
1333 <emphasis>Boot the image</emphasis>:
1334 Boot the modified image in the QEMU emulator
1335 using this command.
1336 When prompted to login to the QEMU console, use "root"
1337 with no password:
1338 <literallayout class='monospaced'>
1339 $ cd ~/poky/build
1340 $ runqemu qemux86
1341 </literallayout>
1342 </para></listitem>
1343 <listitem><para>
1344 <emphasis>Look for Your Changes:</emphasis>
1345 As QEMU booted, you might have seen your changes rapidly
1346 scroll by.
1347 If not, use these commands to see your changes:
1348 <literallayout class='monospaced'>
1349 # dmesg | less
1350 </literallayout>
1351 You should see the results of your
1352 <filename>printk</filename> statements
1353 as part of the output when you scroll down the
1354 console window.
1355 </para></listitem>
1356 <listitem><para>
1357 <emphasis>Generate the Patch File:</emphasis>
1358 Once you are sure that your patch works correctly, you
1359 can generate a <filename>*.patch</filename> file in the
1360 kernel source repository:
1361 <literallayout class='monospaced'>
1362 $ cd ~/linux-yocto-4.12/init
1363 $ git format-patch -1
1364 0001-calibrate.c-Added-some-printk-statements.patch
1365 </literallayout>
1366 </para></listitem>
1367 <listitem><para>
1368 <emphasis>Move the Patch File to Your Layer:</emphasis>
1369 In order for subsequent builds to pick up patches, you
1370 need to move the patch file you created in the previous
1371 step to your layer <filename>meta-mylayer</filename>.
1372 For this example, the layer created earlier is located
1373 in your home directory as <filename>meta-mylayer</filename>.
1374 When the layer was created using the
1375 <filename>yocto-create</filename> script, no additional
1376 hierarchy was created to support patches.
1377 Before moving the patch file, you need to add additional
1378 structure to your layer using the following commands:
1379 <literallayout class='monospaced'>
1380 $ cd ~/meta-mylayer
1381 $ mkdir recipes-kernel
1382 $ mkdir recipes-kernel/linux
1383 $ mkdir recipes-kernel/linux/linux-yocto
1384 </literallayout>
1385 Once you have created this hierarchy in your layer, you can
1386 move the patch file using the following command:
1387 <literallayout class='monospaced'>
1388 $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto
1389 </literallayout>
1390 </para></listitem>
1391 <listitem><para>
1392 <emphasis>Create the Append File:</emphasis>
1393 Finally, you need to create the
1394 <filename>linux-yocto_4.12.bbappend</filename> file and
1395 insert statements that allow the OpenEmbedded build
1396 system to find the patch.
1397 The append file needs to be in your layer's
1398 <filename>recipes-kernel/linux</filename>
1399 directory and it must be named
1400 <filename>linux-yocto_4.12.bbappend</filename> and have
1401 the following contents:
1402 <literallayout class='monospaced'>
1403 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1404
1405 SRC_URI_append = " file://0001-calibrate.c-Added-some-printk-statements.patch"
1406 </literallayout>
1407 The
1408 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1409 and
1410 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1411 statements enable the OpenEmbedded build system to find
1412 the patch file.</para>
1413
1414 <para>For more information on append files and patches,
1415 see the
1416 "<link linkend='creating-the-append-file'>Creating the Append File</link>"
1417 and
1418 "<link linkend='applying-patches'>Applying Patches</link>"
1419 sections.
1420 You can also see the
1421 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer"</ulink>"
1422 section in the Yocto Project Development Tasks Manual.
1423 <note>
1424 To build <filename>core-image-minimal</filename>
1425 again and see the effects of your patch, you can
1426 essentially eliminate the temporary source files
1427 saved in <filename>poky/build/tmp/work/...</filename>
1428 and residual effects of the build by entering the
1429 following sequence of commands:
1430 <literallayout class='monospaced'>
1431 $ cd ~/poky/build
1432 $ bitbake -c cleanall yocto-linux
1433 $ bitbake core-image-minimal -c cleanall
1434 $ bitbake core-image-minimal
1435 $ runqemu qemux86
1436 </literallayout>
1437 </note>
1438 </para></listitem>
1439 </orderedlist>
1440 </para>
1441 </section>
1442
1443 <section id='configuring-the-kernel'>
1444 <title>Configuring the Kernel</title>
1445
1446 <para>
1447 Configuring the Yocto Project kernel consists of making sure the
1448 <filename>.config</filename> file has all the right information
1449 in it for the image you are building.
1450 You can use the <filename>menuconfig</filename> tool and
1451 configuration fragments to make sure your
1452 <filename>.config</filename> file is just how you need it.
1453 You can also save known configurations in a
1454 <filename>defconfig</filename> file that the build system can use
1455 for kernel configuration.
1456 </para>
1457
1458 <para>
1459 This section describes how to use <filename>menuconfig</filename>,
1460 create and use configuration fragments, and how to interactively
1461 modify your <filename>.config</filename> file to create the
1462 leanest kernel configuration file possible.
1463 </para>
1464
1465 <para>
1466 For more information on kernel configuration, see the
1467 "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
1468 section.
1469 </para>
1470
1471 <section id='using-menuconfig'>
1472 <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
1473
1474 <para>
1475 The easiest way to define kernel configurations is to set
1476 them through the <filename>menuconfig</filename> tool.
1477 This tool provides an interactive method with which
1478 to set kernel configurations.
1479 For general information on <filename>menuconfig</filename>, see
1480 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
1481 </para>
1482
1483 <para>
1484 To use the <filename>menuconfig</filename> tool in the Yocto
1485 Project development environment, you must do the following:
1486 <itemizedlist>
1487 <listitem><para>
1488 Because you launch <filename>menuconfig</filename>
1489 using BitBake, you must be sure to set up your
1490 environment by running the
1491 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1492 script found in the
1493 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
1494 </para></listitem>
1495 <listitem><para>
1496 You must be sure of the state of your build's
1497 configuration in the
1498 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
1499 </para></listitem>
1500 <listitem><para>
1501 Your build host must have the following two packages
1502 installed:
1503 <literallayout class='monospaced'>
1504 libncurses5-dev
1505 libtinfo-dev
1506 </literallayout>
1507 </para></listitem>
1508 </itemizedlist>
1509 </para>
1510
1511 <para>
1512 The following commands initialize the BitBake environment,
1513 run the
1514 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink>
1515 task, and launch <filename>menuconfig</filename>.
1516 These commands assume the Source Directory's top-level folder
1517 is <filename>~/poky</filename>:
1518 <literallayout class='monospaced'>
1519 $ cd poky
1520 $ source oe-init-build-env
1521 $ bitbake linux-yocto -c kernel_configme -f
1522 $ bitbake linux-yocto -c menuconfig
1523 </literallayout>
1524 Once <filename>menuconfig</filename> comes up, its standard
1525 interface allows you to interactively examine and configure
1526 all the kernel configuration parameters.
1527 After making your changes, simply exit the tool and save your
1528 changes to create an updated version of the
1529 <filename>.config</filename> configuration file.
1530 <note>
1531 You can use the entire <filename>.config</filename> file
1532 as the <filename>defconfig</filename> file.
1533 For information on <filename>defconfig</filename> files,
1534 see the
1535 "<link linkend='changing-the-configuration'>Changing the Configuration</link>",
1536 "<link linkend='using-an-in-tree-defconfig-file'>Using an In-Tree <filename>defconfig</filename> File</link>,
1537 and
1538 "<link linkend='creating-a-defconfig-file'>Creating a <filename>defconfig</filename> File</link>"
1539 sections.
1540 </note>
1541 </para>
1542
1543 <para>
1544 Consider an example that configures the "CONFIG_SMP" setting
1545 for the <filename>linux-yocto-4.12</filename> kernel.
1546 <note>
1547 The OpenEmbedded build system recognizes this kernel as
1548 <filename>linux-yocto</filename> through Metadata (e.g.
1549 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink><filename>_linux-yocto ?= "12.4%"</filename>).
1550 </note>
1551 Once <filename>menuconfig</filename> launches, use the
1552 interface to navigate through the selections to find the
1553 configuration settings in which you are interested.
1554 For this example, you deselect "CONFIG_SMP" by clearing the
1555 "Symmetric Multi-Processing Support" option.
1556 Using the interface, you can find the option under
1557 "Processor Type and Features".
1558 To deselect "CONFIG_SMP", use the arrow keys to
1559 highlight "Symmetric Multi-Processing Support" and enter "N"
1560 to clear the asterisk.
1561 When you are finished, exit out and save the change.
1562 </para>
1563
1564 <para>
1565 Saving the selections updates the <filename>.config</filename>
1566 configuration file.
1567 This is the file that the OpenEmbedded build system uses to
1568 configure the kernel during the build.
1569 You can find and examine this file in the Build Directory in
1570 <filename>tmp/work/</filename>.
1571 The actual <filename>.config</filename> is located in the
1572 area where the specific kernel is built.
1573 For example, if you were building a Linux Yocto kernel based
1574 on the <filename>linux-yocto-4.12</filename> kernel and you
1575 were building a QEMU image targeted for
1576 <filename>x86</filename> architecture, the
1577 <filename>.config</filename> file would be:
1578 <literallayout class='monospaced'>
1579 poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
1580 ...967-r0/linux-qemux86-standard-build/.config
1581 </literallayout>
1582 <note>
1583 The previous example directory is artificially split and
1584 many of the characters in the actual filename are omitted
1585 in order to make it more readable.
1586 Also, depending on the kernel you are using, the exact
1587 pathname might differ.
1588 </note>
1589 </para>
1590
1591 <para>
1592 Within the <filename>.config</filename> file, you can see the
1593 kernel settings.
1594 For example, the following entry shows that symmetric
1595 multi-processor support is not set:
1596 <literallayout class='monospaced'>
1597 # CONFIG_SMP is not set
1598 </literallayout>
1599 </para>
1600
1601 <para>
1602 A good method to isolate changed configurations is to use a
1603 combination of the <filename>menuconfig</filename> tool and
1604 simple shell commands.
1605 Before changing configurations with
1606 <filename>menuconfig</filename>, copy the existing
1607 <filename>.config</filename> and rename it to something else,
1608 use <filename>menuconfig</filename> to make as many changes as
1609 you want and save them, then compare the renamed configuration
1610 file against the newly created file.
1611 You can use the resulting differences as your base to create
1612 configuration fragments to permanently save in your kernel
1613 layer.
1614 <note>
1615 Be sure to make a copy of the <filename>.config</filename>
1616 file and do not just rename it.
1617 The build system needs an existing
1618 <filename>.config</filename> file from which to work.
1619 </note>
1620 </para>
1621 </section>
1622
1623 <section id='creating-a-defconfig-file'>
1624 <title>Creating a&nbsp;&nbsp;<filename>defconfig</filename> File</title>
1625
1626 <para>
1627 A <filename>defconfig</filename> file in the context of
1628 the Yocto Project is often a <filename>.config</filename>
1629 file that is copied from a build or a
1630 <filename>defconfig</filename> taken from the kernel tree
1631 and moved into recipe space.
1632 You can use a <filename>defconfig</filename> file
1633 to retain a known set of kernel configurations from which the
1634 OpenEmbedded build system can draw to create the final
1635 <filename>.config</filename> file.
1636 <note>
1637 Out-of-the-box, the Yocto Project never ships a
1638 <filename>defconfig</filename> or
1639 <filename>.config</filename> file.
1640 The OpenEmbedded build system creates the final
1641 <filename>.config</filename> file used to configure the
1642 kernel.
1643 </note>
1644 </para>
1645
1646 <para>
1647 To create a <filename>defconfig</filename>, start with a
1648 complete, working Linux kernel <filename>.config</filename>
1649 file.
1650 Copy that file to the appropriate
1651 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
1652 directory in your layer's
1653 <filename>recipes-kernel/linux</filename> directory, and rename
1654 the copied file to "defconfig" (e.g.
1655 <filename>~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig</filename>).
1656 Then, add the following lines to the linux-yocto
1657 <filename>.bbappend</filename> file in your layer:
1658 <literallayout class='monospaced'>
1659 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1660 SRC_URI += "file://defconfig"
1661 </literallayout>
1662 The
1663 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1664 tells the build system how to search for the file, while the
1665 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1666 extends the
1667 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1668 variable (search directories) to include the
1669 <filename>${PN}</filename> directory you created to hold the
1670 configuration changes.
1671 <note>
1672 The build system applies the configurations from the
1673 <filename>defconfig</filename> file before applying any
1674 subsequent configuration fragments.
1675 The final kernel configuration is a combination of the
1676 configurations in the <filename>defconfig</filename>
1677 file and any configuration fragments you provide.
1678 You need to realize that if you have any configuration
1679 fragments, the build system applies these on top of and
1680 after applying the existing defconfig file configurations.
1681 </note>
1682 For more information on configuring the kernel, see the
1683 "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
1684 section.
1685 </para>
1686 </section>
1687
1688 <section id='creating-config-fragments'>
1689 <title>Creating Configuration Fragments</title>
1690
1691 <para>
1692 Configuration fragments are simply kernel options that
1693 appear in a file placed where the OpenEmbedded build system
1694 can find and apply them.
1695 The build system applies configuration fragments after
1696 applying configurations from a <filename>defconfig</filename>
1697 file.
1698 Thus, the final kernel configuration is a combination of the
1699 configurations in the <filename>defconfig</filename>
1700 file and then any configuration fragments you provide.
1701 The build system applies fragments on top of and
1702 after applying the existing defconfig file configurations.
1703 </para>
1704
1705 <para>
1706 Syntactically, the configuration statement is identical to
1707 what would appear in the <filename>.config</filename> file,
1708 which is in the
1709 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
1710 <note>
1711 For more information about where the
1712 <filename>.config</filename> file is located, see the
1713 example in the
1714 "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>"
1715 section.
1716 </note>
1717 </para>
1718
1719 <para>
1720 It is simple to create a configuration fragment.
1721 One method is to use shell commands.
1722 For example, issuing the following from the shell creates a
1723 configuration fragment file named
1724 <filename>my_smp.cfg</filename> that enables multi-processor
1725 support within the kernel:
1726 <literallayout class='monospaced'>
1727 $ echo "CONFIG_SMP=y" >> my_smp.cfg
1728 </literallayout>
1729 <note>
1730 All configuration fragment files must use the
1731 <filename>.cfg</filename> extension in order for the
1732 OpenEmbedded build system to recognize them as a
1733 configuration fragment.
1734 </note>
1735 </para>
1736
1737 <para>
1738 Another method is to create a configuration fragment using the
1739 differences between two configuration files: one previously
1740 created and saved, and one freshly created using the
1741 <filename>menuconfig</filename> tool.
1742 </para>
1743
1744 <para>
1745 To create a configuration fragment using this method, follow
1746 these steps:
1747 <orderedlist>
1748 <listitem><para>
1749 <emphasis>Complete a Build Through Kernel Configuration:</emphasis>
1750 Complete a build at least through the kernel
1751 configuration task as follows:
1752 <literallayout class='monospaced'>
1753 $ bitbake linux-yocto -c kernel_configme -f
1754 </literallayout>
1755 This step ensures that you create a
1756 <filename>.config</filename> file from a known state.
1757 Because situations exist where your build state might
1758 become unknown, it is best to run this task prior
1759 to starting <filename>menuconfig</filename>.
1760 </para></listitem>
1761 <listitem><para>
1762 <emphasis>Launch <filename>menuconfig</filename>:</emphasis>
1763 Run the <filename>menuconfig</filename> command:
1764 <literallayout class='monospaced'>
1765 $ bitbake linux-yocto -c menuconfig
1766 </literallayout>
1767 </para></listitem>
1768 <listitem><para>
1769 <emphasis>Create the Configuration Fragment:</emphasis>
1770 Run the <filename>diffconfig</filename>
1771 command to prepare a configuration fragment.
1772 The resulting file <filename>fragment.cfg</filename>
1773 is placed in the
1774 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> directory:
1775 <literallayout class='monospaced'>
1776 $ bitbake linux-yocto -c diffconfig
1777 </literallayout>
1778 </para></listitem>
1779 </orderedlist>
1780 </para>
1781
1782 <para>
1783 The <filename>diffconfig</filename> command creates a file
1784 that is a list of Linux kernel <filename>CONFIG_</filename>
1785 assignments.
1786 See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
1787 section for additional information on how to use the output
1788 as a configuration fragment.
1789 <note>
1790 You can also use this method to create configuration
1791 fragments for a BSP.
1792 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
1793 section for more information.
1794 </note>
1795 </para>
1796
1797 <para>
1798 Where do you put your configuration fragment files?
1799 You can place these files in an area pointed to by
1800 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1801 as directed by your <filename>bblayers.conf</filename> file,
1802 which is located in your layer.
1803 The OpenEmbedded build system picks up the configuration and
1804 adds it to the kernel's configuration.
1805 For example, suppose you had a set of configuration options
1806 in a file called <filename>myconfig.cfg</filename>.
1807 If you put that file inside a directory named
1808 <filename>linux-yocto</filename> that resides in the same
1809 directory as the kernel's append file within your layer
1810 and then add the following statements to the kernel's append
1811 file, those configuration options will be picked up and applied
1812 when the kernel is built:
1813 <literallayout class='monospaced'>
1814 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1815 SRC_URI += "file://myconfig.cfg"
1816 </literallayout>
1817 </para>
1818
1819 <para>
1820 As mentioned earlier, you can group related configurations
1821 into multiple files and name them all in the
1822 <filename>SRC_URI</filename> statement as well.
1823 For example, you could group separate configurations
1824 specifically for Ethernet and graphics into their own files
1825 and add those by using a <filename>SRC_URI</filename> statement
1826 like the following in your append file:
1827 <literallayout class='monospaced'>
1828 SRC_URI += "file://myconfig.cfg \
1829 file://eth.cfg \
1830 file://gfx.cfg"
1831 </literallayout>
1832 </para>
1833 </section>
1834
1835 <section id='validating-configuration'>
1836 <title>Validating Configuration</title>
1837
1838 <para>
1839 You can use the
1840 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink>
1841 task to provide configuration validation:
1842 <literallayout class='monospaced'>
1843 $ bitbake linux-yocto -c kernel_configcheck -f
1844 </literallayout>
1845 Running this task produces warnings for when a
1846 requested configuration does not appear in the final
1847 <filename>.config</filename> file or when you override a
1848 policy configuration in a hardware configuration fragment.
1849 </para>
1850
1851 <para>
1852 In order to run this task, you must have an existing
1853 <filename>.config</filename> file.
1854 See the
1855 "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>"
1856 section for information on how to create a configuration file.
1857 </para>
1858
1859 <para>
1860 Following is sample output from the
1861 <filename>do_kernel_configcheck</filename> task:
1862 <literallayout class='monospaced'>
1863 Loading cache: 100% |########################################################| Time: 0:00:00
1864 Loaded 1275 entries from dependency cache.
1865 NOTE: Resolving any missing task queue dependencies
1866
1867 Build Configuration:
1868 .
1869 .
1870 .
1871
1872 NOTE: Executing SetScene Tasks
1873 NOTE: Executing RunQueue Tasks
1874 WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck:
1875 [kernel config]: specified values did not make it into the kernel's final configuration:
1876
1877 ---------- CONFIG_X86_TSC -----------------
1878 Config: CONFIG_X86_TSC
1879 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
1880 Requested value: CONFIG_X86_TSC=y
1881 Actual value:
1882
1883
1884 ---------- CONFIG_X86_BIGSMP -----------------
1885 Config: CONFIG_X86_BIGSMP
1886 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1887 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1888 Requested value: # CONFIG_X86_BIGSMP is not set
1889 Actual value:
1890
1891
1892 ---------- CONFIG_NR_CPUS -----------------
1893 Config: CONFIG_NR_CPUS
1894 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1895 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
1896 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1897 Requested value: CONFIG_NR_CPUS=8
1898 Actual value: CONFIG_NR_CPUS=1
1899
1900
1901 ---------- CONFIG_SCHED_SMT -----------------
1902 Config: CONFIG_SCHED_SMT
1903 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1904 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1905 Requested value: CONFIG_SCHED_SMT=y
1906 Actual value:
1907
1908
1909
1910 NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded.
1911
1912 Summary: There were 3 WARNING messages shown.
1913 </literallayout>
1914 <note>
1915 The previous output example has artificial line breaks
1916 to make it more readable.
1917 </note>
1918 </para>
1919
1920 <para>
1921 The output describes the various problems that you can
1922 encounter along with where to find the offending configuration
1923 items.
1924 You can use the information in the logs to adjust your
1925 configuration files and then repeat the
1926 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink>
1927 and
1928 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink>
1929 tasks until they produce no warnings.
1930 </para>
1931
1932 <para>
1933 For more information on how to use the
1934 <filename>menuconfig</filename> tool, see the
1935 "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>"
1936 section.
1937 </para>
1938 </section>
1939
1940 <section id='fine-tuning-the-kernel-configuration-file'>
1941 <title>Fine-Tuning the Kernel Configuration File</title>
1942
1943 <para>
1944 You can make sure the <filename>.config</filename> file is as
1945 lean or efficient as possible by reading the output of the
1946 kernel configuration fragment audit, noting any issues, making
1947 changes to correct the issues, and then repeating.
1948 </para>
1949
1950 <para>
1951 As part of the kernel build process, the
1952 <filename>do_kernel_configcheck</filename> task runs.
1953 This task validates the kernel configuration by checking the
1954 final <filename>.config</filename> file against the input
1955 files.
1956 During the check, the task produces warning messages for the
1957 following issues:
1958 <itemizedlist>
1959 <listitem><para>
1960 Requested options that did not make the final
1961 <filename>.config</filename> file.
1962 </para></listitem>
1963 <listitem><para>
1964 Configuration items that appear twice in the same
1965 configuration fragment.
1966 </para></listitem>
1967 <listitem><para>
1968 Configuration items tagged as "required" that were
1969 overridden.
1970 </para></listitem>
1971 <listitem><para>
1972 A board overrides a non-board specific option.
1973 </para></listitem>
1974 <listitem><para>
1975 Listed options not valid for the kernel being
1976 processed.
1977 In other words, the option does not appear anywhere.
1978 </para></listitem>
1979 </itemizedlist>
1980 <note>
1981 The <filename>do_kernel_configcheck</filename> task can
1982 also optionally report if an option is overridden during
1983 processing.
1984 </note>
1985 </para>
1986
1987 <para>
1988 For each output warning, a message points to the file
1989 that contains a list of the options and a pointer to the
1990 configuration fragment that defines them.
1991 Collectively, the files are the key to streamlining the
1992 configuration.
1993 </para>
1994
1995 <para>
1996 To streamline the configuration, do the following:
1997 <orderedlist>
1998 <listitem><para>
1999 <emphasis>Use a Working Configuration:</emphasis>
2000 Start with a full configuration that you
2001 know works.
2002 Be sure the configuration builds and boots
2003 successfully.
2004 Use this configuration file as your baseline.
2005 </para></listitem>
2006 <listitem><para>
2007 <emphasis>Run Configure and Check Tasks:</emphasis>
2008 Separately run the
2009 <filename>do_kernel_configme</filename> and
2010 <filename>do_kernel_configcheck</filename> tasks:
2011 <literallayout class='monospaced'>
2012 $ bitbake linux-yocto -c kernel_configme -f
2013 $ bitbake linux-yocto -c kernel_configcheck -f
2014 </literallayout>
2015 </para></listitem>
2016 <listitem><para>
2017 <emphasis>Process the Results:</emphasis>
2018 Take the resulting list of files from the
2019 <filename>do_kernel_configcheck</filename> task
2020 warnings and do the following:
2021 <itemizedlist>
2022 <listitem><para>
2023 Drop values that are redefined in the fragment
2024 but do not change the final
2025 <filename>.config</filename> file.
2026 </para></listitem>
2027 <listitem><para>
2028 Analyze and potentially drop values from the
2029 <filename>.config</filename> file that override
2030 required configurations.
2031 </para></listitem>
2032 <listitem><para>
2033 Analyze and potentially remove non-board
2034 specific options.
2035 </para></listitem>
2036 <listitem><para>
2037 Remove repeated and invalid options.
2038 </para></listitem>
2039 </itemizedlist>
2040 </para></listitem>
2041 <listitem><para>
2042 <emphasis>Re-Run Configure and Check Tasks:</emphasis>
2043 After you have worked through the output of the kernel
2044 configuration audit, you can re-run the
2045 <filename>do_kernel_configme</filename> and
2046 <filename>do_kernel_configcheck</filename> tasks to
2047 see the results of your changes.
2048 If you have more issues, you can deal with them as
2049 described in the previous step.
2050 </para></listitem>
2051 </orderedlist>
2052 </para>
2053
2054 <para>
2055 Iteratively working through steps two through four eventually
2056 yields a minimal, streamlined configuration file.
2057 Once you have the best <filename>.config</filename>, you can
2058 build the Linux Yocto kernel.
2059 </para>
2060 </section>
2061 </section>
2062
2063 <section id='expanding-variables'>
2064 <title>Expanding Variables</title>
2065
2066 <para>
2067 Sometimes it is helpful to determine what a variable expands
2068 to during a build.
2069 You can do examine the values of variables by examining the
2070 output of the <filename>bitbake -e</filename> command.
2071 The output is long and is more easily managed in a text file,
2072 which allows for easy searches:
2073 <literallayout class='monospaced'>
2074 $ bitbake -e virtual/kernel > <replaceable>some_text_file</replaceable>
2075 </literallayout>
2076 Within the text file, you can see exactly how each variable is
2077 expanded and used by the OpenEmbedded build system.
2078 </para>
2079 </section>
2080
2081 <section id='working-with-a-dirty-kernel-version-string'>
2082 <title>Working with a "Dirty" Kernel Version String</title>
2083
2084 <para>
2085 If you build a kernel image and the version string has a
2086 "+" or a "-dirty" at the end, uncommitted modifications exist
2087 in the kernel's source directory.
2088 Follow these steps to clean up the version string:
2089 <orderedlist>
2090 <listitem><para>
2091 <emphasis>Discover the Uncommitted Changes:</emphasis>
2092 Go to the kernel's locally cloned Git repository
2093 (source directory) and use the following Git command
2094 to list the files that have been changed, added, or
2095 removed:
2096 <literallayout class='monospaced'>
2097 $ git status
2098 </literallayout>
2099 </para></listitem>
2100 <listitem><para>
2101 <emphasis>Commit the Changes:</emphasis>
2102 You should commit those changes to the kernel source
2103 tree regardless of whether or not you will save,
2104 export, or use the changes:
2105 <literallayout class='monospaced'>
2106 $ git add
2107 $ git commit -s -a -m "getting rid of -dirty"
2108 </literallayout>
2109 </para></listitem>
2110 <listitem><para>
2111 <emphasis>Rebuild the Kernel Image:</emphasis>
2112 Once you commit the changes, rebuild the kernel.</para>
2113
2114 <para>Depending on your particular kernel development
2115 workflow, the commands you use to rebuild the
2116 kernel might differ.
2117 For information on building the kernel image when
2118 using <filename>devtool</filename>, see the
2119 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
2120 section.
2121 For information on building the kernel image when
2122 using Bitbake, see the
2123 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
2124 section.
2125 </para></listitem>
2126 </orderedlist>
2127 </para>
2128 </section>
2129
2130 <section id='working-with-your-own-sources'>
2131 <title>Working With Your Own Sources</title>
2132
2133 <para>
2134 If you cannot work with one of the Linux kernel
2135 versions supported by existing linux-yocto recipes, you can
2136 still make use of the Yocto Project Linux kernel tooling by
2137 working with your own sources.
2138 When you use your own sources, you will not be able to
2139 leverage the existing kernel
2140 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> and
2141 stabilization work of the linux-yocto sources.
2142 However, you will be able to manage your own Metadata in the same
2143 format as the linux-yocto sources.
2144 Maintaining format compatibility facilitates converging with
2145 linux-yocto on a future, mutually-supported kernel version.
2146 </para>
2147
2148 <para>
2149 To help you use your own sources, the Yocto Project provides a
2150 linux-yocto custom recipe
2151 (<filename>linux-yocto-custom.bb</filename>) that uses
2152 <filename>kernel.org</filename> sources
2153 and the Yocto Project Linux kernel tools for managing
2154 kernel Metadata.
2155 You can find this recipe in the
2156 <filename>poky</filename> Git repository of the
2157 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
2158 at:
2159 <literallayout class="monospaced">
2160 poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
2161 </literallayout>
2162 </para>
2163
2164 <para>
2165 Here are some basic steps you can use to work with your own
2166 sources:
2167 <orderedlist>
2168 <listitem><para>
2169 <emphasis>Create a Copy of the Kernel Recipe:</emphasis>
2170 Copy the <filename>linux-yocto-custom.bb</filename>
2171 recipe to your layer and give it a meaningful name.
2172 The name should include the version of the Yocto Linux
2173 kernel you are using (e.g.
2174 <filename>linux-yocto-myproject_4.12.bb</filename>,
2175 where "4.12" is the base version of the Linux kernel
2176 with which you would be working).
2177 </para></listitem>
2178 <listitem><para>
2179 <emphasis>Create a Directory for Your Patches:</emphasis>
2180 In the same directory inside your layer, create a matching
2181 directory to store your patches and configuration files
2182 (e.g. <filename>linux-yocto-myproject</filename>).
2183 </para></listitem>
2184 <listitem><para>
2185 <emphasis>Ensure You Have Configurations:</emphasis>
2186 Make sure you have either a <filename>defconfig</filename>
2187 file or configuration fragment files in your layer.
2188 When you use the <filename>linux-yocto-custom.bb</filename>
2189 recipe, you must specify a configuration.
2190 If you do not have a <filename>defconfig</filename> file,
2191 you can run the following:
2192 <literallayout class='monospaced'>
2193 $ make defconfig
2194 </literallayout>
2195 After running the command, copy the resulting
2196 <filename>.config</filename> file to the
2197 <filename>files</filename> directory in your layer
2198 as "defconfig" and then add it to the
2199 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2200 variable in the recipe.</para>
2201
2202 <para>Running the <filename>make defconfig</filename>
2203 command results in the default configuration for your
2204 architecture as defined by your kernel.
2205 However, no guarantee exists that this configuration is
2206 valid for your use case, or that your board will even boot.
2207 This is particularly true for non-x86 architectures.</para>
2208
2209 <para>To use non-x86 <filename>defconfig</filename> files,
2210 you need to be more specific and find one that matches your
2211 board (i.e. for arm, you look in
2212 <filename>arch/arm/configs</filename> and use the one that
2213 is the best starting point for your board).
2214 </para></listitem>
2215 <listitem><para>
2216 <emphasis>Edit the Recipe:</emphasis>
2217 Edit the following variables in your recipe as appropriate
2218 for your project:
2219 <itemizedlist>
2220 <listitem><para>
2221 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>:
2222 The <filename>SRC_URI</filename> should specify
2223 a Git repository that uses one of the supported Git
2224 fetcher protocols (i.e. <filename>file</filename>,
2225 <filename>git</filename>, <filename>http</filename>,
2226 and so forth).
2227 The <filename>SRC_URI</filename> variable should
2228 also specify either a <filename>defconfig</filename>
2229 file or some configuration fragment files.
2230 The skeleton recipe provides an example
2231 <filename>SRC_URI</filename> as a syntax reference.
2232 </para></listitem>
2233 <listitem><para>
2234 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
2235 The Linux kernel version you are using (e.g.
2236 "4.12").
2237 </para></listitem>
2238 <listitem><para>
2239 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>:
2240 The Linux kernel
2241 <filename>CONFIG_LOCALVERSION</filename> that is
2242 compiled into the resulting kernel and visible
2243 through the <filename>uname</filename> command.
2244 </para></listitem>
2245 <listitem><para>
2246 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
2247 The commit ID from which you want to build.
2248 </para></listitem>
2249 <listitem><para>
2250 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
2251 Treat this variable the same as you would in any
2252 other recipe.
2253 Increment the variable to indicate to the
2254 OpenEmbedded build system that the recipe has
2255 changed.
2256 </para></listitem>
2257 <listitem><para>
2258 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
2259 The default <filename>PV</filename> assignment is
2260 typically adequate.
2261 It combines the <filename>LINUX_VERSION</filename>
2262 with the Source Control Manager (SCM) revision
2263 as derived from the
2264 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>
2265 variable.
2266 The combined results are a string with the
2267 following form:
2268 <literallayout class='monospaced'>
2269 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
2270 </literallayout>
2271 While lengthy, the extra verbosity in
2272 <filename>PV</filename> helps ensure you are using
2273 the exact sources from which you intend to build.
2274 </para></listitem>
2275 <listitem><para>
2276 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
2277 A list of the machines supported by your new recipe.
2278 This variable in the example recipe is set
2279 by default to a regular expression that matches
2280 only the empty string, "(^$)".
2281 This default setting triggers an explicit build
2282 failure.
2283 You must change it to match a list of the machines
2284 that your new recipe supports.
2285 For example, to support the
2286 <filename>qemux86</filename> and
2287 <filename>qemux86-64</filename> machines, use
2288 the following form:
2289 <literallayout class='monospaced'>
2290 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
2291 </literallayout>
2292 </para></listitem>
2293 </itemizedlist>
2294 </para></listitem>
2295 <listitem><para>
2296 <emphasis>Customize Your Recipe as Needed:</emphasis>
2297 Provide further customizations to your recipe
2298 as needed just as you would customize an existing
2299 linux-yocto recipe.
2300 See the
2301 "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
2302 section for information.
2303 </para></listitem>
2304 </orderedlist>
2305 </para>
2306 </section>
2307
2308 <section id='working-with-out-of-tree-modules'>
2309 <title>Working with Out-of-Tree Modules</title>
2310
2311 <para>
2312 This section describes steps to build out-of-tree modules on
2313 your target and describes how to incorporate out-of-tree modules
2314 in the build.
2315 </para>
2316
2317 <section id='building-out-of-tree-modules-on-the-target'>
2318 <title>Building Out-of-Tree Modules on the Target</title>
2319
2320 <para>
2321 While the traditional Yocto Project development model would be
2322 to include kernel modules as part of the normal build
2323 process, you might find it useful to build modules on the
2324 target.
2325 This could be the case if your target system is capable
2326 and powerful enough to handle the necessary compilation.
2327 Before deciding to build on your target, however, you should
2328 consider the benefits of using a proper cross-development
2329 environment from your build host.
2330 </para>
2331
2332 <para>
2333 If you want to be able to build out-of-tree modules on
2334 the target, there are some steps you need to take
2335 on the target that is running your SDK image.
2336 Briefly, the <filename>kernel-dev</filename> package
2337 is installed by default on all
2338 <filename>*.sdk</filename> images and the
2339 <filename>kernel-devsrc</filename> package is installed
2340 on many of the <filename>*.sdk</filename> images.
2341 However, you need to create some scripts prior to
2342 attempting to build the out-of-tree modules on the target
2343 that is running that image.
2344 </para>
2345
2346 <para>
2347 Prior to attempting to build the out-of-tree modules,
2348 you need to be on the target as root and you need to
2349 change to the <filename>/usr/src/kernel</filename> directory.
2350 Next, <filename>make</filename> the scripts:
2351 <literallayout class='monospaced'>
2352 # cd /usr/src/kernel
2353 # make scripts
2354 </literallayout>
2355 Because all SDK image recipes include
2356 <filename>dev-pkgs</filename>, the
2357 <filename>kernel-dev</filename> packages will be installed
2358 as part of the SDK image and the
2359 <filename>kernel-devsrc</filename> packages will be installed
2360 as part of applicable SDK images.
2361 The SDK uses the scripts when building out-of-tree
2362 modules.
2363 Once you have switched to that directory and created the
2364 scripts, you should be able to build your out-of-tree modules
2365 on the target.
2366 </para>
2367 </section>
2368
2369 <section id='incorporating-out-of-tree-modules'>
2370 <title>Incorporating Out-of-Tree Modules</title>
2371
2372 <para>
2373 While it is always preferable to work with sources integrated
2374 into the Linux kernel sources, if you need an external kernel
2375 module, the <filename>hello-mod.bb</filename> recipe is
2376 available as a template from which you can create your
2377 own out-of-tree Linux kernel module recipe.
2378 </para>
2379
2380 <para>
2381 This template recipe is located in the
2382 <filename>poky</filename> Git repository of the
2383 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
2384 at:
2385 <literallayout class="monospaced">
2386 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
2387 </literallayout>
2388 </para>
2389
2390 <para>
2391 To get started, copy this recipe to your layer and give it a
2392 meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
2393 In the same directory, create a new directory named
2394 <filename>files</filename> where you can store any source files,
2395 patches, or other files necessary for building
2396 the module that do not come with the sources.
2397 Finally, update the recipe as needed for the module.
2398 Typically, you will need to set the following variables:
2399 <itemizedlist>
2400 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
2401 </para></listitem>
2402 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
2403 </para></listitem>
2404 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2405 </para></listitem>
2406 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
2407 </para></listitem>
2408 </itemizedlist>
2409 </para>
2410
2411 <para>
2412 Depending on the build system used by the module sources,
2413 you might need to make some adjustments.
2414 For example, a typical module <filename>Makefile</filename>
2415 looks much like the one provided with the
2416 <filename>hello-mod</filename> template:
2417 <literallayout class='monospaced'>
2418 obj-m := hello.o
2419
2420 SRC := $(shell pwd)
2421
2422 all:
2423 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
2424
2425 modules_install:
2426 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
2427 ...
2428 </literallayout>
2429 </para>
2430
2431 <para>
2432 The important point to note here is the
2433 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
2434 variable.
2435 The
2436 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-module'><filename>module</filename></ulink>
2437 class sets this variable and the
2438 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
2439 variable to
2440 <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
2441 with the necessary Linux kernel build information to build
2442 modules.
2443 If your module <filename>Makefile</filename> uses a different
2444 variable, you might want to override the
2445 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
2446 step, or create a patch to
2447 the <filename>Makefile</filename> to work with the more typical
2448 <filename>KERNEL_SRC</filename> or
2449 <filename>KERNEL_PATH</filename> variables.
2450 </para>
2451
2452 <para>
2453 After you have prepared your recipe, you will likely want to
2454 include the module in your images.
2455 To do this, see the documentation for the following variables in
2456 the Yocto Project Reference Manual and set one of them
2457 appropriately for your machine configuration file:
2458 <itemizedlist>
2459 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
2460 </para></listitem>
2461 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
2462 </para></listitem>
2463 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
2464 </para></listitem>
2465 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
2466 </para></listitem>
2467 </itemizedlist>
2468 </para>
2469
2470 <para>
2471 Modules are often not required for boot and can be excluded from
2472 certain build configurations.
2473 The following allows for the most flexibility:
2474 <literallayout class='monospaced'>
2475 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
2476 </literallayout>
2477 The value is derived by appending the module filename without
2478 the <filename>.ko</filename> extension to the string
2479 "kernel-module-".
2480 </para>
2481
2482 <para>
2483 Because the variable is
2484 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
2485 and not a
2486 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
2487 variable, the build will not fail if this module is not
2488 available to include in the image.
2489 </para>
2490 </section>
2491 </section>
2492
2493
2494 <section id='inspecting-changes-and-commits'>
2495 <title>Inspecting Changes and Commits</title>
2496
2497 <para>
2498 A common question when working with a kernel is:
2499 "What changes have been applied to this tree?"
2500 Rather than using "grep" across directories to see what has
2501 changed, you can use Git to inspect or search the kernel tree.
2502 Using Git is an efficient way to see what has changed in the tree.
2503 </para>
2504
2505 <section id='what-changed-in-a-kernel'>
2506 <title>What Changed in a Kernel?</title>
2507
2508 <para>
2509 Following are a few examples that show how to use Git
2510 commands to examine changes.
2511 These examples are by no means the only way to see changes.
2512 <note>
2513 In the following examples, unless you provide a commit
2514 range, <filename>kernel.org</filename> history is blended
2515 with Yocto Project kernel changes.
2516 You can form ranges by using branch names from the
2517 kernel tree as the upper and lower commit markers with
2518 the Git commands.
2519 You can see the branch names through the web interface
2520 to the Yocto Project source repositories at
2521 <ulink url='&YOCTO_GIT_URL;'></ulink>.
2522 </note>
2523 To see a full range of the changes, use the
2524 <filename>git whatchanged</filename> command and specify a
2525 commit range for the branch
2526 (<replaceable>commit</replaceable><filename>..</filename><replaceable>commit</replaceable>).
2527 </para>
2528
2529 <para>
2530 Here is an example that looks at what has changed in the
2531 <filename>emenlow</filename> branch of the
2532 <filename>linux-yocto-3.19</filename> kernel.
2533 The lower commit range is the commit associated with the
2534 <filename>standard/base</filename> branch, while
2535 the upper commit range is the commit associated with the
2536 <filename>standard/emenlow</filename> branch.
2537 <literallayout class='monospaced'>
2538 $ git whatchanged origin/standard/base..origin/standard/emenlow
2539 </literallayout>
2540 </para>
2541
2542 <para>
2543 To see short, one line summaries of changes use the
2544 <filename>git log</filename> command:
2545 <literallayout class='monospaced'>
2546 $ git log --oneline origin/standard/base..origin/standard/emenlow
2547 </literallayout>
2548 </para>
2549
2550 <para>
2551 Use this command to see code differences for the changes:
2552 <literallayout class='monospaced'>
2553 $ git diff origin/standard/base..origin/standard/emenlow
2554 </literallayout>
2555 </para>
2556
2557 <para>
2558 Use this command to see the commit log messages and the
2559 text differences:
2560 <literallayout class='monospaced'>
2561 $ git show origin/standard/base..origin/standard/emenlow
2562 </literallayout>
2563 </para>
2564
2565 <para>
2566 Use this command to create individual patches for
2567 each change.
2568 Here is an example that that creates patch files for each
2569 commit and places them in your <filename>Documents</filename>
2570 directory:
2571 <literallayout class='monospaced'>
2572 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
2573 </literallayout>
2574 </para>
2575 </section>
2576
2577 <section id='showing-a-particular-feature-or-branch-change'>
2578 <title>Showing a Particular Feature or Branch Change</title>
2579
2580 <para>
2581 Tags in the Yocto Project kernel tree divide changes for
2582 significant features or branches.
2583 The <filename>git show</filename>&nbsp;<replaceable>tag</replaceable>
2584 command shows changes based on a tag.
2585 Here is an example that shows <filename>systemtap</filename>
2586 changes:
2587 <literallayout class='monospaced'>
2588 $ git show systemtap
2589 </literallayout>
2590 You can use the
2591 <filename>git branch --contains</filename>&nbsp;<replaceable>tag</replaceable>
2592 command to show the branches that contain a particular feature.
2593 This command shows the branches that contain the
2594 <filename>systemtap</filename> feature:
2595 <literallayout class='monospaced'>
2596 $ git branch --contains systemtap
2597 </literallayout>
2598 </para>
2599 </section>
2600 </section>
2601
2602 <section id='adding-recipe-space-kernel-features'>
2603 <title>Adding Recipe-Space Kernel Features</title>
2604
2605 <para>
2606 You can add kernel features in the
2607 <link linkend='recipe-space-metadata'>recipe-space</link> by
2608 using the
2609 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
2610 variable and by specifying the feature's <filename>.scc</filename>
2611 file path in the
2612 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2613 statement.
2614 When you add features using this method, the OpenEmbedded build
2615 system checks to be sure the features are present.
2616 If the features are not present, the build stops.
2617 Kernel features are the last elements processed for configuring
2618 and patching the kernel.
2619 Therefore, adding features in this manner is a way
2620 to enforce specific features are present and enabled
2621 without needing to do a full audit of any other layer's additions
2622 to the <filename>SRC_URI</filename> statement.
2623 </para>
2624
2625 <para>
2626 You add a kernel feature by providing the feature as part of the
2627 <filename>KERNEL_FEATURES</filename> variable and by providing the
2628 path to the feature's <filename>.scc</filename> file, which is
2629 relative to the root of the kernel Metadata.
2630 The OpenEmbedded build system searches all forms of kernel
2631 Metadata on the <filename>SRC_URI</filename> statement regardless
2632 of whether the Metadata is in the "kernel-cache", system kernel
2633 Metadata, or a recipe-space Metadata (i.e. part of the kernel
2634 recipe).
2635 See the
2636 "<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>"
2637 section for additional information.
2638 </para>
2639
2640 <para>
2641 When you specify the feature's <filename>.scc</filename> file
2642 on the <filename>SRC_URI</filename> statement, the OpenEmbedded
2643 build system adds the directory of that
2644 <filename>.scc</filename> file along with all its subdirectories
2645 to the kernel feature search path.
2646 Because subdirectories are searched, you can reference a single
2647 <filename>.scc</filename> file in the
2648 <filename>SRC_URI</filename> statement to reference multiple kernel
2649 features.
2650 </para>
2651
2652 <para>
2653 Consider the following example that adds the "test.scc" feature
2654 to the build.
2655 <orderedlist>
2656 <listitem><para>
2657 <emphasis>Create the Feature File:</emphasis>
2658 Create a <filename>.scc</filename> file and locate it
2659 just as you would any other patch file,
2660 <filename>.cfg</filename> file, or fetcher item
2661 you specify in the <filename>SRC_URI</filename>
2662 statement.
2663 <note><title>Notes</title>
2664 <itemizedlist>
2665 <listitem><para>
2666 You must add the directory of the
2667 <filename>.scc</filename> file to the fetcher's
2668 search path in the same manner as you would
2669 add a <filename>.patch</filename> file.
2670 </para></listitem>
2671 <listitem><para>
2672 You can create additional
2673 <filename>.scc</filename> files beneath the
2674 directory that contains the file you are
2675 adding.
2676 All subdirectories are searched during the
2677 build as potential feature directories.
2678 </para></listitem>
2679 </itemizedlist>
2680 </note>
2681 Continuing with the example, suppose the "test.scc"
2682 feature you are adding has a
2683 <filename>test.scc</filename> file in the following
2684 directory:
2685 <literallayout class='monospaced'>
2686 <replaceable>my_recipe</replaceable>
2687 |
2688 +-linux-yocto
2689 |
2690 +-test.cfg
2691 +-test.scc
2692 </literallayout>
2693 In this example, the <filename>linux-yocto</filename>
2694 directory has both the feature
2695 <filename>test.scc</filename> file and a similarly
2696 named configuration fragment file
2697 <filename>test.cfg</filename>.
2698 </para></listitem>
2699 <listitem><para>
2700 <emphasis>Add the Feature File to <filename>SRC_URI</filename>:</emphasis>
2701 Add the <filename>.scc</filename> file to the
2702 recipe's <filename>SRC_URI</filename> statement:
2703 <literallayout class='monospaced'>
2704 SRC_URI_append = " file://test.scc"
2705 </literallayout>
2706 The leading space before the path is important as the
2707 path is appended to the existing path.
2708 </para></listitem>
2709 <listitem><para>
2710 <emphasis>Specify the Feature as a Kernel Feature:</emphasis>
2711 Use the <filename>KERNEL_FEATURES</filename> statement
2712 to specify the feature as a kernel feature:
2713 <literallayout class='monospaced'>
2714 KERNEL_FEATURES_append = " test.scc"
2715 </literallayout>
2716 The OpenEmbedded build system processes the kernel feature
2717 when it builds the kernel.
2718 <note>
2719 If other features are contained below "test.scc",
2720 then their directories are relative to the directory
2721 containing the <filename>test.scc</filename> file.
2722 </note>
2723 </para></listitem>
2724 </orderedlist>
2725 </para>
2726 </section>
2727</chapter>
2728<!--
2729vim: expandtab tw=80 ts=4
2730-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-13 02:13:38 +0000