summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml12
-rw-r--r--documentation/dev-manual/dev-manual-model.xml157
-rw-r--r--documentation/dev-manual/figures/kernel-dev-flow.pngbin62416 -> 45225 bytes
3 files changed, 51 insertions, 118 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 4ce0a94873..48d86fac25 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1608,8 +1608,6 @@
1608 Kernel modification involves changing or adding configurations to an existing kernel, 1608 Kernel modification involves changing or adding configurations to an existing kernel,
1609 changing or adding recipes to the kernel that are needed to support specific hardware features, 1609 changing or adding recipes to the kernel that are needed to support specific hardware features,
1610 or even altering the source code itself. 1610 or even altering the source code itself.
1611 This appendix presents simple examples that modify the kernel source code,
1612 change the kernel configuration, and add a kernel source recipe.
1613 <note> 1611 <note>
1614 You can use the <filename>yocto-kernel</filename> script 1612 You can use the <filename>yocto-kernel</filename> script
1615 found in the <link linkend='source-directory'>Source Directory</link> 1613 found in the <link linkend='source-directory'>Source Directory</link>
@@ -1627,6 +1625,16 @@
1627 console. 1625 console.
1628 </para> 1626 </para>
1629 1627
1628 <section id='finding-the-kernel-source-files'>
1629 <title>Finding the Kernel Source Files</title>
1630
1631 <para>
1632 Describe how to find the source files in the build area.
1633 We are not assuming they are using their own kernel tree.
1634
1635 </para>
1636 </section>
1637
1630 <section id='understanding-the-files-you-need'> 1638 <section id='understanding-the-files-you-need'>
1631 <title>Understanding the Files You Need</title> 1639 <title>Understanding the Files You Need</title>
1632 1640
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index c96b2dda63..ab14ebd4d4 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -8,7 +8,8 @@
8 8
9<para> 9<para>
10 Many development models exist for which you can use the Yocto Project. 10 Many development models exist for which you can use the Yocto Project.
11 This chapter overviews the following methods: 11 This chapter overviews simple methods that use tools provided by the
12 Yocto Project:
12 <itemizedlist> 13 <itemizedlist>
13 <listitem><para><emphasis>System Development:</emphasis> 14 <listitem><para><emphasis>System Development:</emphasis>
14 System Development covers Board Support Package (BSP) development and kernel 15 System Development covers Board Support Package (BSP) development and kernel
@@ -322,8 +323,8 @@
322 </note> 323 </note>
323 324
324 <para> 325 <para>
325 Storage of all the available kernel source code is one thing, while representing the 326 Upstream storage of all the available kernel source code is one thing, while
326 code on your host development system is another. 327 representing and using the code on your host development system is another.
327 Conceptually, you can think of the kernel source repositories as all the 328 Conceptually, you can think of the kernel source repositories as all the
328 source files necessary for all the supported kernels. 329 source files necessary for all the supported kernels.
329 As a developer, you are just interested in the source files for the kernel on 330 As a developer, you are just interested in the source files for the kernel on
@@ -332,39 +333,14 @@
332 </para> 333 </para>
333 334
334 <para> 335 <para>
335 You make kernel source code available on your host development system by using 336 Kernel source code is available on your host system a couple of different
336 Git to create a bare clone of the Yocto Project kernel Git repository 337 ways.
337 in which you are interested. 338 If you are working in the kernel all the time, you probably would want
338 Then, you use Git again to clone a copy of that bare clone. 339 to set up your own local Git repository of the kernel tree.
339 This copy represents the directory structure on your host system that is particular 340 If you just need to make some patches to the kernel, you can get at
340 to the kernel you want. 341 temporary kernel source files extracted and used during the OpenEmbedded
341 The files in the copy of the bare clone are the files you actually modify 342 build system.
342 to change the kernel. 343 We will just talk about working with the temporary source code.
343 See the <link linkend='local-kernel-files'>Yocto Project Kernel</link> item earlier
344 in this manual for an example of how to set up the kernel source directory
345 structure on your host system.
346 </para>
347
348 <para>
349 This next figure illustrates how the kernel source files might be arranged on
350 your host system.
351 </para>
352
353 <para>
354 <imagedata fileref="figures/kernel-overview-3-generic.png"
355 width="6in" depth="4in" align="center" scale="100" />
356 </para>
357
358 <para>
359 In the previous figure, the file structure on the left represents the bare clone
360 set up to track the Yocto Project kernel Git repository.
361 The structure on the right represents the copy of the bare clone.
362 When you make modifcations to the kernel source code, this is the area in which
363 you work.
364 Once you make corrections, you must use Git to push the committed changes to the
365 bare clone.
366<!-- The example in <xref linkend='modifying-the-kernel-source-code'>
367 Modifying the Kernel Source Code</xref> provides a detailed example. -->
368 </para> 344 </para>
369 345
370 <para> 346 <para>
@@ -407,7 +383,7 @@
407 383
408 <para> 384 <para>
409 <imagedata fileref="figures/kernel-dev-flow.png" 385 <imagedata fileref="figures/kernel-dev-flow.png"
410 width="6in" depth="7.5in" align="center" scalefit="1" /> 386 width="6in" depth="5in" align="center" scalefit="1" />
411 </para> 387 </para>
412 388
413 <para> 389 <para>
@@ -424,43 +400,39 @@
424 For information on how to get these files, see the bulleted item 400 For information on how to get these files, see the bulleted item
425 "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual. 401 "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual.
426 </para></listitem> 402 </para></listitem>
427 <listitem><para><emphasis>Set up a local copy of the <filename>poky-extras</filename> Git 403 <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>:
428 repository</emphasis>: This local repository is the area for your configuration 404 Temporary kernel source files are kept in the Build Directory created by the
429 fragments, new kernel recipes, and the kernel <filename>.bbappend</filename> 405 OpenEmbedded build system when you run BitBake.
430 file used during the build. 406 If you have never built the kernel you are interested in, you need to run
431 It is good practice to set this repository up inside your local 407 an initial build to establish local kernel source files.</para>
432 <link linkend='source-directory'>Source Directory</link>. 408 <para>If you are building an image for the first time, you need to get the build
433 For information on how to get these files, see the bulleted item 409 environment ready by sourcing
434 "<link linkend='poky-extras-repo'>The <filename>poky-extras</filename> Git Repository</link>" 410 the environment setup script.
435 earlier in this manual. 411 You also need to be sure two key configuration files
436 <note>While it is certainly possible to modify the kernel without involving 412 (<filename>local.conf</filename> and <filename>bblayers.conf</filename>)
437 a local Git repository, the suggested workflow for kernel modification 413 are configured appropriately.</para>
438 using the Yocto Project does use a Git repository.</note></para></listitem> 414 <para>The entire process for building an image is overviewed in the
439 <listitem><para><emphasis>Establish a local copy of the Yocto Project kernel files on your 415 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
440 system</emphasis>: In order to make modifications to the kernel you need two things: 416 section of the Yocto Project Quick Start.
441 a bare clone of the Yocto Project kernel you are modifying and 417 You might want to reference this information.
442 a copy of that bare clone. 418 You can find more information on BitBake in the user manual, which is found in the
443 The bare clone is required by the build process and is the area to which you 419 <filename>bitbake/doc/manual</filename> directory of the
444 push your kernel source changes (pulling does not work with bare clones). 420 <link linkend='source-directory'>Source Directory</link>.</para>
445 The copy of the bare clone is a local Git repository that contains all the kernel's 421 <para>The build process supports several types of images to satisfy different needs.
446 source files. 422 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
447 You make your changes to the files in this copy of the bare clone. 423 the Yocto Project Reference Manual for information on supported images.
448 For information on how to set these two items up, see the bulleted item 424 </para></listitem>
449 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
450 earlier in this manual.</para></listitem>
451 <listitem><para><emphasis>Make changes to the kernel source code if 425 <listitem><para><emphasis>Make changes to the kernel source code if
452 applicable</emphasis>: Modifying the kernel does not always mean directly 426 applicable</emphasis>: Modifying the kernel does not always mean directly
453 changing source files. 427 changing source files.
454 However, if you have to do this, you make the changes in the local 428 However, if you have to do this, you make the changes to the files in the
455 Git repository you set up to hold the source files (i.e. the copy of the 429 Build directory.</para></listitem>
456 bare clone).
457 Once the changes are made, you need to use Git commands to commit the changes
458 and then push them to the bare clone.</para></listitem>
459 <listitem><para><emphasis>Make kernel configuration changes 430 <listitem><para><emphasis>Make kernel configuration changes
460 if applicable</emphasis>: 431 if applicable</emphasis>:
461 If your situation calls for changing the kernel's configuration, you can 432 If your situation calls for changing the kernel's configuration, you can
462 use <filename>menuconfig</filename> 433 use the <filename>yocto-kernel</filename> script or <filename>menuconfig</filename>
463 to enable and disable kernel configurations. 434 to enable and disable kernel configurations.
435 Using the script lets you interactively set up kernel configurations.
464 Using <filename>menuconfig</filename> allows you to interactively develop and test the 436 Using <filename>menuconfig</filename> allows you to interactively develop and test the
465 configuration changes you are making to the kernel. 437 configuration changes you are making to the kernel.
466 When saved, changes using <filename>menuconfig</filename> update the kernel's 438 When saved, changes using <filename>menuconfig</filename> update the kernel's
@@ -476,55 +448,8 @@
476 <filename>.config</filename> file against a saved original and gather those 448 <filename>.config</filename> file against a saved original and gather those
477 changes into a config fragment to be referenced from within the kernel's 449 changes into a config fragment to be referenced from within the kernel's
478 <filename>.bbappend</filename> file.</para></listitem> 450 <filename>.bbappend</filename> file.</para></listitem>
479 <listitem><para><emphasis>Add or extend kernel recipes if applicable</emphasis>: 451 <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>:
480 The standard 452 Rebuilding the kernel image applies your changes.</para></listitem>
481 layer structure organizes recipe files inside the
482 <filename>meta-kernel-dev</filename> layer that is within the local
483 <filename>poky-extras</filename> Git repository.
484 If you need to add new kernel recipes, you add them within this layer.
485 Also within this area, you will find the <filename>.bbappend</filename>
486 file that appends information to the kernel's recipe file used during the
487 build.
488 </para></listitem>
489 <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
490 changes to your kernel (configurations, source code changes, recipe additions,
491 or recipe changes), there remains a few things
492 you need to do in order for the build system to create your image.
493 If you have not done so, you need to get the build environment ready by sourcing
494 the environment setup script described earlier.
495 You also need to be sure two key configuration files
496 (<filename>local.conf</filename> and <filename>bblayers.conf</filename>)
497 are configured appropriately.</para>
498 <para>The entire process for building an image is overviewed in the
499 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
500 section of the Yocto Project Quick Start.
501 You might want to reference this information.
502 Also, you should look at the detailed examples found in the appendices at
503 at the end of this manual.</para></listitem>
504 <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded
505 build system uses the BitBake
506 tool to build images based on the type of image you want to create.
507 You can find more information on BitBake in the user manual, which is found in the
508 <filename>bitbake/doc/manual</filename> directory of the
509 <link linkend='source-directory'>Source Directory</link>.</para>
510 <para>The build process supports several types of images to satisfy different needs.
511 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
512 the Yocto Project Reference Manual for information on supported images.</para></listitem>
513 <listitem><para><emphasis>Make your configuration changes available
514 in the kernel layer</emphasis>: Up to this point, all the configuration changes to the
515 kernel have been done and tested iteratively.
516 Once they are tested and ready to go, you can move them into the kernel layer,
517 which allows you to distribute the layer.</para></listitem>
518 <listitem><para><emphasis>If applicable, share your in-tree changes</emphasis>:
519 If the changes you made
520 are suited for all Yocto Project kernel users, you might want to send them on
521 for inclusion into the upstream kernel's Git repository.
522 If the changes are accepted, the Yocto Project Maintainer pulls them into
523 the master branch of the kernel tree.
524 Doing so makes them available to everyone using the kernel.</para>
525 <para>For information on how to submit a change to the Yocto Project, see the
526 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section
527 earlier in this manual.</para></listitem>
528 </orderedlist> 453 </orderedlist>
529 </para> 454 </para>
530 </section> 455 </section>
diff --git a/documentation/dev-manual/figures/kernel-dev-flow.png b/documentation/dev-manual/figures/kernel-dev-flow.png
index 3244d3eb90..edd9e82af7 100644
--- a/documentation/dev-manual/figures/kernel-dev-flow.png
+++ b/documentation/dev-manual/figures/kernel-dev-flow.png
Binary files differ