summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-kernel-appendix-orig.xml553
1 files changed, 0 insertions, 553 deletions
diff --git a/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml b/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml
deleted file mode 100644
index 7765feb9c1..0000000000
--- a/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml
+++ /dev/null
@@ -1,553 +0,0 @@
1<!DOCTYPE appendix 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
5<appendix id='dev-manual-kernel-appendix'>
6
7<title>Kernel Modification Example</title>
8
9 <para>
10 Kernel modification involves changing or adding configurations to an existing kernel,
11 changing or adding recipes to the kernel that are needed to support specific hardware features,
12 or even altering the source code itself.
13 This appendix presents simple examples that modify the kernel source code,
14 change the kernel configuration, and add a kernel source recipe.
15 <note>
16 You can use the <filename>yocto-kernel</filename> script
17 found in the <link linkend='source-directory'>Source Directory</link>
18 under <filename>scripts</filename> to manage kernel patches and configuration.
19 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
20 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
21 more information.</note>
22 </para>
23
24 <section id='modifying-the-kernel-source-code'>
25 <title>Modifying the Kernel Source Code</title>
26
27 <para>
28 This example adds some simple QEMU emulator console output at boot time by
29 adding <filename>printk</filename> statements to the kernel's
30 <filename>calibrate.c</filename> source code file.
31 Booting the modified image causes the added messages to appear on the emulator's
32 console.
33 </para>
34
35 <section id='understanding-the-files-you-need'>
36 <title>Understanding the Files You Need</title>
37
38 <para>
39 Before you modify the kernel, you need to know what Git repositories and file
40 structures you need.
41 Briefly, you need the following:
42 <itemizedlist>
43 <listitem><para>A local
44 <link linkend='source-directory'>Source Directory</link> for the
45 poky Git repository</para></listitem>
46 <listitem><para>Local copies of the
47 <link linkend='poky-extras-repo'><filename>poky-extras</filename></link>
48 Git repository placed within the Source Directory.</para></listitem>
49 <listitem><para>A bare clone of the
50 <link linkend='local-kernel-files'>Yocto Project Kernel</link> upstream Git
51 repository to which you want to push your modifications.
52 </para></listitem>
53 <listitem><para>A copy of that bare clone in which you make your source
54 modifications</para></listitem>
55 </itemizedlist>
56 </para>
57
58 <para>
59 The following figure summarizes these four areas.
60 Within each rectangular that represents a data structure, a
61 host development directory pathname appears at the
62 lower left-hand corner of the box.
63 These pathnames are the locations used in this example.
64 The figure also provides key statements and commands used during the kernel
65 modification process:
66 </para>
67
68 <para>
69 <imagedata fileref="figures/kernel-example-repos-generic.png" width="7in" depth="5in"
70 align="center" scale="100" />
71 </para>
72
73 <para>
74 Here is a brief description of the four areas:
75 <itemizedlist>
76 <listitem><para><emphasis>Local Source Directory:</emphasis>
77 This area contains all the metadata that supports building images
78 using the OpenEmbedded build system.
79 In this example, the
80 <link linkend='source-directory'>Source Directory</link> also
81 contains the
82 <link linkend='build-directory'>Build Directory</link>,
83 which contains the configuration directory
84 that lets you control the build.
85 Also in this example, the Source Directory contains local copies of the
86 <filename>poky-extras</filename> Git repository.</para>
87 <para>See the bulleted item
88 "<link linkend='local-yp-release'>Yocto Project Release</link>"
89 for information on how to get these files on your local system.</para></listitem>
90 <listitem><para><emphasis>Local copies of the&nbsp;<filename>poky-extras</filename>&nbsp;Git Repository:</emphasis>
91 This area contains the <filename>meta-kernel-dev</filename> layer,
92 which is where you make changes that append the kernel build recipes.
93 You edit <filename>.bbappend</filename> files to locate your
94 local kernel source files and to identify the kernel being built.
95 This Git repository is a gathering place for extensions to the Yocto Project
96 (or really any) kernel recipes that faciliate the creation and development
97 of kernel features, BSPs or configurations.</para>
98 <para>See the bulleted item
99 "<link linkend='poky-extras-repo'>The
100 <filename>poky-extras</filename> Git Repository</link>"
101 for information on how to get these files.</para></listitem>
102 <listitem><para><emphasis>Bare Clone of the Yocto Project kernel:</emphasis>
103 This bare Git repository tracks the upstream Git repository of the Linux
104 Yocto kernel source code you are changing.
105 When you modify the kernel you must work through a bare clone.
106 All source code changes you make to the kernel must be committed and
107 pushed to the bare clone using Git commands.
108 As mentioned, the <filename>.bbappend</filename> file in the
109 <filename>poky-extras</filename> repository points to the bare clone
110 so that the build process can locate the locally changed source files.</para>
111 <para>See the bulleted item
112 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
113 for information on how to set up the bare clone.
114 </para></listitem>
115 <listitem><para><emphasis>Copy of the Yocto Project Kernel Bare Clone:</emphasis>
116 This Git repository contains the actual source files that you modify.
117 Any changes you make to files in this location need to ultimately be pushed
118 to the bare clone using the <filename>git push</filename> command.</para>
119 <para>See the bulleted item
120 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
121 for information on how to set up the bare clone.
122 <note>Typically, Git workflows follow a scheme where changes made to a local area
123 are pulled into a Git repository.
124 However, because the <filename>git pull</filename> command does not work
125 with bare clones, this workflow pushes changes to the
126 repository even though you could use other more complicated methods to
127 get changes into the bare clone.</note>
128 </para></listitem>
129 </itemizedlist>
130 </para>
131 </section>
132
133 <section id='setting-up-the-local-yocto-project-files-git-repository'>
134 <title>Setting Up the Local Source Directory</title>
135
136 <para>
137 You can set up the
138 <link linkend='source-directory'>Source Directory</link>
139 through tarball extraction or by
140 cloning the <filename>poky</filename> Git repository.
141 This example uses <filename>poky</filename> as the root directory of the
142 local Source Directory.
143 See the bulleted item
144 "<link linkend='local-yp-release'>Yocto Project Release</link>"
145 for information on how to get these files.
146 </para>
147
148 <para>
149 Once you have Source Directory set up,
150 you have many development branches from which you can work.
151 From inside the local repository you can see the branch names and the tag names used
152 in the upstream Git repository by using either of the following commands:
153 <literallayout class='monospaced'>
154 $ cd poky
155 $ git branch -a
156 $ git tag -l
157 </literallayout>
158 This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;",
159 which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository.
160 The following commands create and checkout the local <filename>&DISTRO_NAME;</filename>
161 branch:
162 <literallayout class='monospaced'>
163 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
164 Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
165 Switched to a new branch '&DISTRO_NAME;'
166 </literallayout>
167 </para>
168 </section>
169
170 <section id='setting-up-the-poky-extras-git-repository'>
171 <title>Setting Up the Local poky-extras Git Repository</title>
172
173 <para>
174 This example creates a local copy of the <filename>poky-extras</filename> Git
175 repository inside the <filename>poky</filename> Source Directory.
176 See the bulleted item "<link linkend='poky-extras-repo'>The
177 <filename>poky-extras</filename> Git Repository</link>"
178 for information on how to set up a local copy of the
179 <filename>poky-extras</filename> repository.
180 </para>
181
182 <para>
183 Because this example uses the Yocto Project &DISTRO; Release code
184 named "&DISTRO_NAME;", which maps to the <filename>&DISTRO_NAME;</filename>
185 branch in the repository, you need to be sure you are using that
186 branch for <filename>poky-extras</filename>.
187 The following commands create and checkout the local
188 branch you are using for the <filename>&DISTRO_NAME;</filename>
189 branch:
190 <literallayout class='monospaced'>
191 $ cd ~/poky/poky-extras
192 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
193 Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
194 Switched to a new branch '&DISTRO_NAME;'
195 </literallayout>
196 </para>
197 </section>
198
199 <section id='setting-up-the-bare-clone-and-its-copy'>
200 <title>Setting Up the Bare Clone and its Copy</title>
201
202 <para>
203 This example modifies the <filename>linux-yocto-3.4</filename> kernel.
204 Thus, you need to create a bare clone of that kernel and then make a copy of the
205 bare clone.
206 See the bulleted item
207 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
208 for information on how to do that.
209 </para>
210
211 <para>
212 The bare clone exists for the kernel build tools and simply as the receiving end
213 of <filename>git push</filename>
214 commands after you make edits and commits inside the copy of the clone.
215 The copy (<filename>my-linux-yocto-3.4-work</filename> in this example) has to have
216 a local branch created and checked out for your work.
217 This example uses <filename>common-pc-base</filename> as the local branch.
218 The following commands create and checkout the branch:
219 <literallayout class='monospaced'>
220 $ cd ~/my-linux-yocto-3.4-work
221 $ git checkout -b standard-common-pc-base origin/standard/common-pc/base
222 Branch standard-common-pc-base set up to track remote branch
223 standard/common-pc/base from origin.
224 Switched to a new branch 'standard-common-pc-base'
225 </literallayout>
226 </para>
227 </section>
228
229 <section id='building-and-booting-the-default-qemu-kernel-image'>
230 <title>Building and Booting the Default QEMU Kernel Image</title>
231
232 <para>
233 Before we make changes to the kernel source files, this example first builds the
234 default image and then boots it inside the QEMU emulator.
235 <note>
236 Because a full build can take hours, you should check two variables in the
237 <filename>build</filename> directory that is created after you source the
238 <filename>&OE_INIT_FILE;</filename> script.
239 You can find these variables
240 <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>
241 in the <filename>build/conf</filename> directory in the
242 <filename>local.conf</filename> configuration file.
243 By default, these variables are commented out.
244 If your host development system supports multi-core and multi-thread capabilities,
245 you can uncomment these statements and set the variables to significantly shorten
246 the full build time.
247 As a guideline, set both <filename>BB_NUMBER_THREADS</filename> and
248 <filename>PARALLEL_MAKE</filename> to twice the number
249 of cores your machine supports.
250 </note>
251 The following two commands <filename>source</filename> the build environment setup script
252 and build the default <filename>qemux86</filename> image.
253 If necessary, the script creates the build directory:
254 <literallayout class='monospaced'>
255 $ cd ~/poky
256 $ source &OE_INIT_FILE;
257 You had no conf/local.conf file. This configuration file has therefore been
258 created for you with some default values. You may wish to edit it to use a
259 different MACHINE (target hardware) or enable parallel build options to take
260 advantage of multiple cores for example. See the file for more information as
261 common configuration options are commented.
262
263 The Yocto Project has extensive documentation about OE including a reference manual
264 which can be found at:
265 http://yoctoproject.org/documentation
266
267 For more information about OpenEmbedded see their website:
268 http://www.openembedded.org/
269
270 You had no conf/bblayers.conf file. The configuration file has been created for
271 you with some default values. To add additional metadata layers into your
272 configuration please add entries to this file.
273
274 The Yocto Project has extensive documentation about OE including a reference manual
275 which can be found at:
276 http://yoctoproject.org/documentation
277
278 For more information about OpenEmbedded see their website:
279 http://www.openembedded.org/
280
281
282
283 ### Shell environment set up for builds. ###
284
285 You can now run 'bitbake &lt;target&gt;>'
286
287 Common targets are:
288 core-image-minimal
289 core-image-sato
290 meta-toolchain
291 meta-toolchain-sdk
292 adt-installer
293 meta-ide-support
294
295 You can also run generated qemu images with a command like 'runqemu qemux86'
296 </literallayout>
297 </para>
298
299 <para>
300 The following <filename>bitbake</filename> command starts the build:
301 <literallayout class='monospaced'>
302 $ bitbake -k core-image-minimal
303 </literallayout>
304 <note>Be sure to check the settings in the <filename>local.conf</filename>
305 before starting the build.</note>
306 </para>
307
308 <para>
309 After the build completes, you can start the QEMU emulator using the resulting image
310 <filename>qemux86</filename> as follows:
311 <literallayout class='monospaced'>
312 $ runqemu qemux86
313 </literallayout>
314 </para>
315
316 <para>
317 As the image boots in the emulator, console message and status output appears
318 across the terminal window.
319 Because the output scrolls by quickly, it is difficult to read.
320 To examine the output, you log into the system using the
321 login <filename>root</filename> with no password.
322 Once you are logged in, issue the following command to scroll through the
323 console output:
324 <literallayout class='monospaced'>
325 # dmesg | less
326 </literallayout>
327 </para>
328
329 <para>
330 Take note of the output as you will want to look for your inserted print command output
331 later in the example.
332 </para>
333 </section>
334
335 <section id='changing-the-source-code-and-pushing-it-to-the-bare-clone'>
336 <title>Changing the Source Code and Pushing it to the Bare Clone</title>
337
338 <para>
339 The file you change in this example is named <filename>calibrate.c</filename>
340 and is located in the <filename>my-linux-yocto-3.4-work</filename> Git repository
341 (the copy of the bare clone) in <filename>init</filename>.
342 This example simply inserts several <filename>printk</filename> statements
343 at the beginning of the <filename>calibrate_delay</filename> function.
344 </para>
345
346 <para>
347 Here is the unaltered code at the start of this function:
348 <literallayout class='monospaced'>
349 void __cpuinit calibrate_delay(void)
350 {
351 unsigned long lpj;
352 static bool printed;
353 int this_cpu = smp_processor_id();
354
355 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
356 .
357 .
358 .
359 </literallayout>
360 </para>
361
362 <para>
363 Here is the altered code showing five new <filename>printk</filename> statements
364 near the top of the function:
365 <literallayout class='monospaced'>
366 void __cpuinit calibrate_delay(void)
367 {
368 unsigned long lpj;
369 static bool printed;
370 int this_cpu = smp_processor_id();
371
372 printk("*************************************\n");
373 printk("* *\n");
374 printk("* HELLO YOCTO KERNEL *\n");
375 printk("* *\n");
376 printk("*************************************\n");
377
378 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
379 .
380 .
381 .
382 </literallayout>
383 </para>
384
385 <para>
386 After making and saving your changes, you need to stage them for the push.
387 The following Git commands are one method of staging and committing your changes:
388 <literallayout class='monospaced'>
389 $ git add calibrate.c
390 $ git commit --signoff
391 </literallayout>
392 </para>
393
394 <para>
395 Once the source code has been modified, you need to use Git to push the changes to
396 the bare clone.
397 If you do not push the changes, then the OpenEmbedded build system will not pick
398 up the changed source files.
399 </para>
400
401 <para>
402 The following command pushes the changes to the bare clone:
403 <literallayout class='monospaced'>
404 $ git push origin standard-common-pc-base:standard/default/common-pc/base
405 </literallayout>
406 </para>
407 </section>
408
409 <section id='changing-build-parameters-for-your-build'>
410 <title>Changing Build Parameters for Your Build</title>
411
412 <para>
413 At this point, the source has been changed and pushed.
414 The example now defines some variables used by the OpenEmbedded build system
415 to locate your kernel source.
416 You essentially need to identify where to find the kernel recipe and the changed source code.
417 You also need to be sure some basic configurations are in place that identify the
418 type of machine you are building and to help speed up the build should your host support
419 multiple-core and thread capabilities.
420 </para>
421
422 <para>
423 Do the following to make sure the build parameters are set up for the example.
424 Once you set up these build parameters, they do not have to change unless you
425 change the target architecture of the machine you are building or you move
426 the bare clone, copy of the clone, or the <filename>poky-extras</filename> repository:
427 <itemizedlist>
428 <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
429 <filename>local.conf</filename> file in the build directory defines the build's
430 target architecture.
431 By default, <filename>MACHINE</filename> is set to
432 <filename>qemux86</filename>, which specifies a 32-bit
433 <trademark class='registered'>Intel</trademark> Architecture
434 target machine suitable for the QEMU emulator.
435 In this example, <filename>MACHINE</filename> is correctly configured.
436 </para></listitem>
437 <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
438 <filename>local.conf</filename> file are two variables that can speed your
439 build time if your host supports multi-core and multi-thread capabilities:
440 <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
441 If the host system has multiple cores then you can optimize build time
442 by setting both these variables to twice the number of
443 cores.</para></listitem>
444 <listitem><para><emphasis>Identify Your <filename>meta-kernel-dev</filename>
445 Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
446 <filename>bblayers.conf</filename> file found in the
447 <filename>poky/build/conf</filename> directory needs to have the path to your local
448 <filename>meta-kernel-dev</filename> layer.
449 By default, the <filename>BBLAYERS</filename> variable contains paths to
450 <filename>meta</filename> and <filename>meta-yocto</filename> in the
451 <filename>poky</filename> Git repository.
452 Add the path to your <filename>meta-kernel-dev</filename> location.
453 Be sure to substitute your user information in the statement.
454 Here is an example:
455 <literallayout class='monospaced'>
456 BBLAYERS = " \
457 /home/scottrif/poky/meta \
458 /home/scottrif/poky/meta-yocto \
459 /home/scottrif/poky/meta-yocto-bsp \
460 /home/scottrif/poky/poky-extras/meta-kernel-dev \
461 "
462 </literallayout></para></listitem>
463 <listitem><para><emphasis>Identify Your Source Files:</emphasis> In the
464 <filename>linux-yocto_3.4.bbappend</filename> file located in the
465 <filename>poky-extras/meta-kernel-dev/recipes-kernel/linux</filename>
466 directory, you need to identify the location of the
467 local source code, which in this example is the bare clone named
468 <filename>linux-yocto-3.4.git</filename>.
469 To do this, set the <filename>KSRC_linux_yocto</filename> variable to point to your
470 local <filename>linux-yocto-3.4.git</filename> Git repository by adding the
471 following statement.
472 Also, be sure the <filename>SRC_URI</filename> variable is pointing to
473 your kernel source files by removing the comment.
474 Finally, be sure to substitute your user information in the statement:
475 <literallayout class='monospaced'>
476 KSRC_linux_yocto_3_4 ?= "/home/scottrif/linux-yocto-3.4.git"
477 SRC_URI = "git://${KSRC_linux_yocto_3_4};protocol=file;nocheckout=1;branch=${KBRANCH},meta;name=machine,meta"
478 </literallayout></para></listitem>
479 </itemizedlist>
480 </para>
481
482 <note>
483 <para>Before attempting to build the modified kernel, there is one more set of changes you
484 need to make in the <filename>meta-kernel-dev</filename> layer.
485 Because all the kernel <filename>.bbappend</filename> files are parsed during the
486 build process regardless of whether you are using them or not, you should either
487 comment out the <filename>COMPATIBLE_MACHINE</filename> statements in all
488 unused <filename>.bbappend</filename> files, or simply remove (or rename) all the files
489 except the one your are using for the build
490 (i.e. <filename>linux-yocto_3.4.bbappend</filename> in this example).</para>
491 <para>If you do not make one of these two adjustments, your machine will be compatible
492 with all the kernel recipes in the <filename>meta-kernel-dev</filename> layer.
493 When your machine is comapatible with all the kernel recipes, the build attempts
494 to build all kernels in the layer.
495 You could end up with build errors blocking your work.</para>
496 </note>
497 </section>
498
499 <section id='building-and-booting-the-modified-qemu-kernel-image'>
500 <title>Building and Booting the Modified QEMU Kernel Image</title>
501
502 <para>
503 Next, you need to build the modified image.
504 Do the following:
505 <orderedlist>
506 <listitem><para>Your environment should be set up since you previously sourced
507 the <filename>&OE_INIT_FILE;</filename> script.
508 If it isn't, source the script again from <filename>poky</filename>.
509 <literallayout class='monospaced'>
510 $ cd ~/poky
511 $ source &OE_INIT_FILE;
512 </literallayout>
513 </para></listitem>
514 <listitem><para>Be sure old images are cleaned out by running the
515 <filename>cleanall</filename> BitBake task as follows from your build directory:
516 <literallayout class='monospaced'>
517 $ bitbake -c cleanall linux-yocto
518 </literallayout></para>
519 <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename>
520 directory insided the build directory.
521 Always use the BitBake <filename>cleanall</filename> task to clear
522 out previous builds.</note></para></listitem>
523 <listitem><para>Next, build the kernel image using this command:
524 <literallayout class='monospaced'>
525 $ bitbake -k core-image-minimal
526 </literallayout></para></listitem>
527 <listitem><para>Finally, boot the modified image in the QEMU emulator
528 using this command:
529 <literallayout class='monospaced'>
530 $ runqemu qemux86
531 </literallayout></para></listitem>
532 </orderedlist>
533 </para>
534
535 <para>
536 Log into the machine using <filename>root</filename> with no password and then
537 use the following shell command to scroll through the console's boot output.
538 <literallayout class='monospaced'>
539 # dmesg | less
540 </literallayout>
541 </para>
542
543 <para>
544 You should see the results of your <filename>printk</filename> statements
545 as part of the output.
546 </para>
547 </section>
548 </section>
549</appendix>
550
551<!--
552vim: expandtab tw=80 ts=4
553-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-11-22 11:20:39 +0000