summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-08-30 13:34:52 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-09-02 00:52:49 +0100
commitea256df2a8af386f5c8c7bc7744d6d790ab0a3f9 (patch)
tree4e32e1d442029a93ed8b36d0a37010372c5f3a23 /documentation/kernel-dev
parent2a1bdf7416391b4986fcc34c4de2b24d213948c1 (diff)
downloadpoky-ea256df2a8af386f5c8c7bc7744d6d790ab0a3f9.tar.gz
dev-manual, kernel-dev: Working kernel flow process using devtool
A work-in-progress of an example that modifies the kernel using the devtool. The procedure is not complete yet as it does not run properly. (From yocto-docs rev: 462ba2e46f237c294f05805ad5044291a085975d) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev')
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml742
-rw-r--r--documentation/kernel-dev/kernel-dev-intro.xml22
2 files changed, 395 insertions, 369 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index cb50912ea4..14381afefc 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -45,6 +45,67 @@
45 information. 45 information.
46 </note> 46 </note>
47 </para> 47 </para>
48
49 <para>
50 Following is a detailed example showing how to create a layer
51 without the aid of tools for building the kernel:
52 <orderedlist>
53 <listitem><para>
54 <emphasis>Create additional structure</emphasis>:
55 Create the additional layer structure:
56 <literallayout class='monospaced'>
57 $ cd ~/poky/meta-mylayer
58 $ mkdir conf
59 $ mkdir recipes-kernel
60 $ mkdir recipes-kernel/linux
61 $ mkdir recipes-kernel/linux/linux-yocto
62 </literallayout>
63 The <filename>conf</filename> directory holds your configuration files, while the
64 <filename>recipes-kernel</filename> directory holds your append file and
65 your patch file.
66 </para></listitem>
67 <listitem><para>
68 <emphasis>Create the layer configuration file</emphasis>:
69 Move to the <filename>meta-mylayer/conf</filename>
70 directory and create the <filename>layer.conf</filename>
71 file as follows:
72 <literallayout class='monospaced'>
73 # We have a conf and classes directory, add to BBPATH
74 BBPATH .= ":${LAYERDIR}"
75
76 # We have recipes-* directories, add to BBFILES
77 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
78 ${LAYERDIR}/recipes-*/*/*.bbappend"
79
80 BBFILE_COLLECTIONS += "mylayer"
81 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
82 BBFILE_PRIORITY_mylayer = "5"
83 </literallayout>
84 Notice <filename>mylayer</filename> as part of the last three
85 statements.</para></listitem>
86 <listitem><para>
87 <emphasis>Create the kernel recipe append file</emphasis>:
88 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
89 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
90 <literallayout class='monospaced'>
91 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
92
93 SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
94 </literallayout>
95 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
96 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
97 statements enable the OpenEmbedded build system to find the patch file.
98 For more information on using append files, see the
99 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
100 section in the Yocto Project Development Manual.
101 </para></listitem>
102 <listitem><para>
103 <emphasis>Put the patch file in your layer</emphasis>:
104 Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
105 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
106 directory.</para></listitem>
107 </orderedlist>
108 </para>
48 </section> 109 </section>
49 110
50 <section id='modifying-an-existing-recipe'> 111 <section id='modifying-an-existing-recipe'>
@@ -72,11 +133,9 @@
72 <para> 133 <para>
73 Before modifying an existing recipe, be sure that you have created 134 Before modifying an existing recipe, be sure that you have created
74 a minimal, custom layer from which you can work. 135 a minimal, custom layer from which you can work.
75 See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>" 136 See the
76 section for some general resources. 137 "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
77 You can also see the 138 section for information.
78 "<link linkend='set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</link>"
79 section for a detailed example.
80 </para> 139 </para>
81 140
82 <section id='creating-the-append-file'> 141 <section id='creating-the-append-file'>
@@ -452,63 +511,51 @@
452 <section id="using-devtool-to-patch-the-kernel"> 511 <section id="using-devtool-to-patch-the-kernel">
453 <title>Using <filename>devtool</filename> to Patch the Kernel</title> 512 <title>Using <filename>devtool</filename> to Patch the Kernel</title>
454 513
455
456 <para role='writernotes'> 514 <para role='writernotes'>
457 Some stuff here for the using devtool from the wiki. 515 This procedure currently does not work.
458 This whole section is WIP. 516 It is WIP.
459 <orderedlist> 517 </para>
460 <listitem><para role='writernotes'> 518
461 If you are dealing with real hardware, you can flash the 519 <para>
462 new kernel image to a USB stick and boot the hardware to 520 The steps in this procedure show you how you can patch the
463 see it run. 521 kernel using the extensible SDK and <filename>devtool</filename>.
464 </para></listitem> 522 <note>
465 <listitem><para role='writernotes'> 523 Before attempting this procedure, be sure you have performed
466 Checkout and modify the kernel source. 524 the steps to get ready for updating the kernel as described
467 This is where you make your changes to the image. 525 in the
468 </para></listitem> 526 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
469 <listitem><para role='writernotes'> 527 section.
470 Create a new image that uses the altered kernel. 528 </note>
471 </para></listitem>
472 <listitem><para role='writernotes'>
473 If you are working with actual hardware, you can flash
474 the new image to a USB stick and use it to boot up the
475 hardware.
476 You can see your changes in action.
477 </para></listitem>
478 </orderedlist>
479 </para> 529 </para>
480 530
481 <para> 531 <para>
482 Patching the kernel involves changing or adding configurations to an existing kernel, 532 Patching the kernel involves changing or adding configurations
483 changing or adding recipes to the kernel that are needed to support specific hardware features, 533 to an existing kernel, changing or adding recipes to the kernel
484 or even altering the source code itself. 534 that are needed to support specific hardware features, or even
535 altering the source code itself.
485 <note> 536 <note>
486 You can use the <filename>yocto-kernel</filename> script 537 You can also use the <filename>yocto-kernel</filename> script
487 found in the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> 538 found in the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
488 under <filename>scripts</filename> to manage kernel patches and configuration. 539 under <filename>scripts</filename> to manage kernel patches and configuration.
489 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>" 540 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>"
490 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for 541 section in the Yocto Project Board Support Packages (BSP)
491 more information.</note> 542 Developer's Guide for more information.
543 </note>
492 </para> 544 </para>
493 545
494 <para> 546 <para>
495 This example creates a simple patch by adding some QEMU emulator console 547 This example creates a simple patch by adding some QEMU emulator
496 output at boot time through <filename>printk</filename> statements in the kernel's 548 console output at boot time through <filename>printk</filename>
497 <filename>calibrate.c</filename> source code file. 549 statements in the kernel's <filename>calibrate.c</filename> source
550 code file.
498 Applying the patch and booting the modified image causes the added 551 Applying the patch and booting the modified image causes the added
499 messages to appear on the emulator's console. 552 messages to appear on the emulator's console.
500 </para> 553 <note>
501 554 The example is a continuation of the setup procedure found in
502 <para> 555 the
503 The example builds an extensible SDK, which is then used to 556 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop using <filename>devtool</filename></link>"
504 build, using <filename>devtool</filename>, a clean image for the 557 Section.
505 default <filename>qemux86</filename> machine in a 558 </note>
506 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
507 named <filename>poky</filename>.
508 In the example, the
509 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
510 is <filename>build</filename> and is located in the default
511 <filename>poky_sdk</filename> directory.
512 </para> 559 </para>
513 560
514 <para> 561 <para>
@@ -517,159 +564,93 @@
517 section. 564 section.
518 </para> 565 </para>
519 566
520 <section id='patch-kernel-set-up-the-build-host'> 567 <orderedlist>
521 <title>Set Up the Build Host</title> 568 <listitem><para>
522 569 <emphasis>Check Out the Kernel Source Files:</emphasis>
523 <para> 570 First you must use <filename>devtool</filename> to checkout
524 Prior to creating any actual patches for your kernel, you 571 the kernel source code in its workspace.
525 need to prepare the build host. 572 Be sure you are in the terminal set up to do work
526 This example builds an extensible SDK. 573 with the extensible SDK.
527 Follow these steps: 574 <note>
528 <itemizedlist> 575 See this
529 <listitem><para> 576 <link linkend='setting-up-the-esdk-terminal'>step</link>
530 <emphasis>Set Up the Build Environment:</emphasis> 577 in the
531 Be sure you are set up to use BitBake in a shell. 578 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
532 See the 579 section for more information.
533 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>" 580 </note>
534 section in the Yocto Project Development Manual for information 581 Use the following <filename>devtool</filename> command
535 on how to get a build host ready that is either a native 582 to check out the code:
536 Linux machine or a machine that uses CROPS.
537 </para></listitem>
538 <listitem><para>
539 <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
540 You need to have a local copy of the Yocto Project
541 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
542 (i.e. a local <filename>poky</filename> repository).
543 See the
544 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
545 and possibly the
546 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
547 and
548 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
549 sections all in the Yocto Project Development Manual for
550 information on how to clone the <filename>poky</filename>
551 repository and check out the appropriate branch for your work.
552 </para></listitem>
553 <listitem><para>
554 <emphasis>Initialize the Build Environment:</emphasis>
555 While in the root directory of the Source Directory (i.e.
556 <filename>poky</filename>), run the
557 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
558 environment setup script to define the OpenEmbedded
559 build environment on your build host.
560 <literallayout class='monospaced'>
561 $ source &OE_INIT_FILE;
562 </literallayout>
563 Among other things, the script creates the
564 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
565 which is <filename>build</filename> in this case
566 and is located in the
567 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
568 After the script runs, your current working directory
569 is set to the <filename>build</filename> directory.
570 <note>
571 For information on running a memory-resident
572 <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>,
573 see the
574 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
575 setup script.
576 </note>
577 </para></listitem>
578 </itemizedlist>
579 </para>
580 </section>
581
582 <section id='create-a-layer-for-your-changes'>
583 <title>Create a Layer for your Changes</title>
584
585 <para>
586 The first step is to create a layer so you can isolate your
587 changes to the kernel.
588 Rather than use the <filename>yocto-layer</filename> script
589 to create the layer, this example steps through the process
590 by hand.
591 If you want information on the script that creates a general
592 layer, see the
593 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
594 section in the Yocto Project Development Manual.
595 </para>
596
597 <para>
598 These two commands create a directory you can use for your
599 layer:
600 <literallayout class='monospaced'>
601 $ cd ~/poky
602 $ mkdir meta-mylayer
603 </literallayout>
604 Creating a directory that follows the Yocto Project layer naming
605 conventions sets up the layer for your changes.
606 The layer is where you place your configuration files, append
607 files, and patch files.
608 To learn more about creating a layer and filling it with the
609 files you need, see the
610 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
611 section in the Yocto Project Development Manual.
612 </para>
613 </section>
614
615 <section id='finding-the-kernel-source-code'>
616 <title>Finding the Kernel Source Code</title>
617
618 <para>
619 Each time you build a kernel image, the kernel source code
620 is fetched and unpacked into the following directory:
621 <literallayout class='monospaced'> 583 <literallayout class='monospaced'>
622 ${S}/linux 584 $ devtool modify linux-yocto
585 Loading cache: 100% |#######################################################################| Time: 0:00:00
586 Loaded 1300 entries from dependency cache.
587 WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
588 WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
589 WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
590
591 Summary: There was 1 WARNING message shown.
592 Loading cache: 100% |########################################################################| Time: 0:00:00
593 Loaded 1300 entries from dependency cache.
594 WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
595 WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
596 WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
597
598 Summary: There was 1 WARNING message shown.
599 NOTE: Executing RunQueue Tasks
600 NOTE: Executing do_fetch...
601 NOTE: Executing do_unpack...
602 NOTE: Tasks Summary: Attempted 2 tasks of which 0 didn't need to be rerun and all succeeded.
603 NOTE: Executing RunQueue Tasks
604 NOTE: Executing do_kernel_checkout...
605 NOTE: Tasks Summary: Attempted 3 tasks of which 2 didn't need to be rerun and all succeeded.
606 NOTE: Patching...
607 NOTE: Executing RunQueue Tasks
608 NOTE: Executing do_validate_branches...
609 NOTE: Executing do_kernel_metadata...
610 NOTE: Executing do_patch...
611 NOTE: Tasks Summary: Attempted 6 tasks of which 3 didn't need to be rerun and all succeeded.
612 NOTE: Generating kernel config
613 NOTE: Executing RunQueue Tasks
614 NOTE: Executing do_kernel_configme...
615 NOTE: Executing do_prepare_recipe_sysroot...
616 NOTE: Executing do_configure...
617 NOTE: Tasks Summary: Attempted 9 tasks of which 6 didn't need to be rerun and all succeeded.
618 NOTE: Copying kernel config to srctree
619 NOTE: Source tree extracted to /home/scottrif/poky_sdk/workspace/sources/linux-yocto
620 NOTE: Recipe linux-yocto now set up to build from /home/scottrif/poky_sdk/workspace/sources/linux-yocto
623 </literallayout> 621 </literallayout>
624 See the "<ulink url='&YOCTO_DOCS_DEV_URL;#finding-the-temporary-source-code'>Finding Temporary Source Code</ulink>" 622 <note>
625 section in the Yocto Project Development Manual and the 623 During the checkout operation, a bug exists that could
626 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> 624 cause errors such as the following to appear:
627 variable for more information about where source is kept 625 <literallayout class='monospaced'>
628 during a build. 626 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
629 </para> 627 be3a89ce7c47178880ba7bf6293d7404 for
630 628 /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
631 <para> 629 </literallayout>
632 For this example, we are going to patch the 630 You can safely ignore these messages.
633 <filename>init/calibrate.c</filename> file 631 The source code is correctly checked out.
634 by adding some simple console <filename>printk</filename> statements that we can 632 </note>
635 see when we boot the image using QEMU. 633 </para></listitem>
636 </para> 634 <listitem><para>
637 </section> 635 <emphasis>Edit the Source Files</emphasis>
638 636 Follow these steps to make some simple changes to the source
639 <section id='creating-the-patch'> 637 files:
640 <title>Creating the Patch</title>
641
642 <para>
643 Two methods exist by which you can create the patch:
644 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
645 and
646 <ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Quilt</ulink>.
647 For kernel patches, the Git workflow is more appropriate.
648 This section assumes the Git workflow and shows the steps
649 specific to this example.
650 <orderedlist> 638 <orderedlist>
651 <listitem><para> 639 <listitem><para>
652 <emphasis>Change the working directory</emphasis>: 640 <emphasis>Change the working directory</emphasis>:
641 In the previous step, the output noted where you can find
642 the source files (e.g.
643 <filename>~/poky_sdk/workspace/sources/linux-yocto</filename>).
653 Change to where the kernel source code is before making 644 Change to where the kernel source code is before making
654 your edits to the <filename>calibrate.c</filename> file: 645 your edits to the <filename>calibrate.c</filename> file:
655 <literallayout class='monospaced'> 646 <literallayout class='monospaced'>
656 $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux 647 $ cd ~/poky_sdk/workspace/sources/linux-yocto
657 </literallayout> 648 </literallayout>
658 Because you are working in an established Git repository, 649 </para></listitem>
659 you must be in this directory in order to commit your changes
660 and create the patch file.
661 <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
662 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
663 represent the version and revision for the
664 <filename>linux-yocto</filename> recipe.
665 The <filename>PV</filename> variable includes the Git meta and machine
666 hashes, which make the directory name longer than you might
667 expect.
668 </note></para></listitem>
669 <listitem><para> 650 <listitem><para>
670 <emphasis>Edit the source file</emphasis>: 651 <emphasis>Edit the source file</emphasis>:
671 Edit the <filename>init/calibrate.c</filename> file to have the 652 Edit the <filename>init/calibrate.c</filename> file to have
672 following changes: 653 the following changes:
673 <literallayout class='monospaced'> 654 <literallayout class='monospaced'>
674 void calibrate_delay(void) 655 void calibrate_delay(void)
675 { 656 {
@@ -687,202 +668,239 @@
687 . 668 .
688 . 669 .
689 . 670 .
690 </literallayout></para></listitem>
691 <listitem><para><emphasis>Stage and commit your changes</emphasis>:
692 These Git commands display the modified file, stage it, and then
693 commit the file:
694 <literallayout class='monospaced'>
695 $ git status
696 $ git add init/calibrate.c
697 $ git commit -m "calibrate: Add printk example"
698 </literallayout></para></listitem>
699 <listitem><para><emphasis>Generate the patch file</emphasis>:
700 This Git command creates the a patch file named
701 <filename>0001-calibrate-Add-printk-example.patch</filename>
702 in the current directory.
703 <literallayout class='monospaced'>
704 $ git format-patch -1
705 </literallayout> 671 </literallayout>
706 </para></listitem> 672 </para></listitem>
707 </orderedlist> 673 </orderedlist>
708 </para> 674 </para></listitem>
709 </section> 675 <listitem><para>
710 676 <emphasis>Build the Updated Kernel Source:</emphasis>
711 <section id='set-up-your-layer-for-the-build'> 677 To build the updated kernel source, use
712 <title>Set Up Your Layer for the Build</title> 678 <filename>devtool</filename>:
713 679 <literallayout class='monospaced'>
714 <para>These steps get your layer set up for the build: 680 $ devtool build linux-yocto
681 Parsing recipes: 100% |####################################################################################| Time: 0:00:31
682 Parsing of 831 .bb files complete (0 cached, 831 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors.
683 WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
684 NOTE: There are 1 recipes to be removed from sysroot qemux86, removing...
685 NOTE: Resolving any missing task queue dependencies
686 Initialising tasks: 100% |#################################################################################| Time: 0:00:00
687 Checking sstate mirror object availability: 100% |#########################################################| Time: 0:00:00
688 NOTE: Executing SetScene Tasks
689 NOTE: Executing RunQueue Tasks
690 linux-yocto-4.10.17+git999-r0 do_compile: NOTE: linux-yocto: compiling from external source tree /home/scottrif/poky_sdk/workspace/sources/linux-yocto
691 NOTE: Tasks Summary: Attempted 471 tasks of which 454 didn't need to be rerun and all succeeded.
692
693 Summary: There was 1 WARNING message shown.
694 </literallayout>
695 </para></listitem>
696<!--
697 <listitem><para>
698
699NOTE: This stuff is how it would have been if a *.wic file was created
700 when the image was built earlier. That is the method used by the
701 example in the wiki (https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk).
702 I am leaving it here for now.
703
704 <emphasis>Create the Image With the New Kernel:</emphasis>
705 Normally, you would create a new image using the
706 <filename>devtool build-image</filename> command.
707 However, this method can take some time and alters the
708 kernel source folder.
709 A faster option is to use
710 <ulink url='https://linux.die.net/man/8/kpartx'><filename>kpartx</filename></ulink>
711 to splice the new kernel into the image you have already built.
712 <note>
713 You might have to install <filename>kpartx</filename>
714 onto your build host.
715 </note>
716 Follow these steps to create the image with the new kernel:
715 <orderedlist> 717 <orderedlist>
716 <listitem><para><emphasis>Create additional structure</emphasis>: 718 <listitem><para>
717 Create the additional layer structure: 719 <emphasis>Make a Copy of Your Wic File:</emphasis>
718 <literallayout class='monospaced'> 720 Create a copy of your Wic from into the
719 $ cd ~/poky/meta-mylayer 721 <filename>/tmp</filename> directory:
720 $ mkdir conf
721 $ mkdir recipes-kernel
722 $ mkdir recipes-kernel/linux
723 $ mkdir recipes-kernel/linux/linux-yocto
724 </literallayout>
725 The <filename>conf</filename> directory holds your configuration files, while the
726 <filename>recipes-kernel</filename> directory holds your append file and
727 your patch file.</para></listitem>
728 <listitem><para><emphasis>Create the layer configuration file</emphasis>:
729 Move to the <filename>meta-mylayer/conf</filename> directory and create
730 the <filename>layer.conf</filename> file as follows:
731 <literallayout class='monospaced'>
732 # We have a conf and classes directory, add to BBPATH
733 BBPATH .= ":${LAYERDIR}"
734
735 # We have recipes-* directories, add to BBFILES
736 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
737 ${LAYERDIR}/recipes-*/*/*.bbappend"
738
739 BBFILE_COLLECTIONS += "mylayer"
740 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
741 BBFILE_PRIORITY_mylayer = "5"
742 </literallayout>
743 Notice <filename>mylayer</filename> as part of the last three
744 statements.</para></listitem>
745 <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
746 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
747 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
748 <literallayout class='monospaced'> 722 <literallayout class='monospaced'>
749 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 723 $ cp tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic /tmp
750
751 SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
752 </literallayout> 724 </literallayout>
753 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
754 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
755 statements enable the OpenEmbedded build system to find the patch file.
756 For more information on using append files, see the
757 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
758 section in the Yocto Project Development Manual.
759 </para></listitem> 725 </para></listitem>
760 <listitem><para> 726 <listitem><para>
761 <emphasis>Put the patch file in your layer</emphasis>: 727 <emphasis>Create Loopback Devices for Partitions:</emphasis>
762 Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to 728 Next, create loopback devices for each partition in
763 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename> 729 the Wic file.
764 directory.</para></listitem> 730 <note>
765 </orderedlist> 731 The first unused loopback device is automatically
766 </para> 732 allocated.
767 </section> 733 </note>
768 734 In this example, the command's output uses a variable
769 <section id='set-up-for-the-build'> 735 "<replaceable>X</replaceable>" to indicate the loopback
770 <title>Set Up for the Build</title> 736 device.
771 737 The actual output you get when you run the command lists
772 <para> 738 the actual loopback devices (e.g. "loop0p1", "loop0p2",
773 Do the following to make sure the build parameters are set up for the example. 739 and "loop0p3"):
774 Once you set up these build parameters, they do not have to change unless you
775 change the target architecture of the machine you are building:
776 <itemizedlist>
777 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
778 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
779 definition within the <filename>local.conf</filename> file in the
780 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
781 specifies the target architecture used when building the Linux kernel.
782 By default, <filename>MACHINE</filename> is set to
783 <filename>qemux86</filename>, which specifies a 32-bit
784 <trademark class='registered'>Intel</trademark> Architecture
785 target machine suitable for the QEMU emulator.</para></listitem>
786 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
787 layer:</emphasis> The
788 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
789 variable in the
790 <filename>bblayers.conf</filename> file found in the
791 <filename>poky/build/conf</filename> directory needs to have the path to your local
792 <filename>meta-mylayer</filename> layer.
793 By default, the <filename>BBLAYERS</filename> variable contains paths to
794 <filename>meta</filename>, <filename>meta-poky</filename>, and
795 <filename>meta-yocto-bsp</filename> in the
796 <filename>poky</filename> Git repository.
797 Add the path to your <filename>meta-mylayer</filename> location:
798 <literallayout class='monospaced'> 740 <literallayout class='monospaced'>
799 BBLAYERS ?= " \ 741 $ sudo kpartx -v -a /tmp/core-image-minimal-qemux86.wic
800 $HOME/poky/meta \ 742 add map loop<replaceable>X</replaceable>p1 (253:6): 0 47446 linear /dev/loopX 2048
801 $HOME/poky/meta-poky \ 743 add map loop<replaceable>X</replaceable>p2 (253:7): 0 119356 linear /dev/loopX 51200
802 $HOME/poky/meta-yocto-bsp \ 744 add map loop<replaceable>X</replaceable>p3 (253:8): 0 90112 linear /dev/loopX 170556
803 $HOME/poky/meta-mylayer \ 745 </literallayout>
804 " 746 </para></listitem>
805 </literallayout></para></listitem> 747 <listitem><para>
806 </itemizedlist> 748 <emphasis>Mount the First Device:</emphasis>
807 </para> 749 The kernel is in the first device, so mount
808 </section> 750 <filename>/dev/mapper/loop</filename><replaceable>X</replaceable><filename>p1</filename>:
809 751 <note>
810 <section id='build-the-modified-qemu-kernel-image'> 752 Be sure to replace the "<replaceable>X</replaceable>"
811 <title>Build the Modified QEMU Kernel Image</title> 753 in "loop<replaceable>X</replaceable>p1" with the
812 754 automatically allocated loopback device
813 <para> 755 (e.g loop0p1).
814 The following steps build your modified kernel image: 756 </note>
815 <orderedlist>
816 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
817 Your environment should be set up since you previously sourced
818 the
819 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
820 script.
821 If it is not, source the script again from <filename>poky</filename>.
822 <literallayout class='monospaced'> 757 <literallayout class='monospaced'>
823 $ cd ~/poky 758 $ sudo mkdir /mnt/wic-p1
824 $ source &OE_INIT_FILE; 759 $ sudo mount /dev/mapper/loop<replaceable>X</replaceable>p1 /mnt/wic-p1
825 </literallayout> 760 </literallayout>
826 </para></listitem> 761 </para></listitem>
827 <listitem><para> 762 <listitem><para>
828 <emphasis>Clean up</emphasis>: 763 <emphasis>Copy Over the New Kernel:</emphasis>
829 Be sure to clean the shared state out by using BitBake 764 Now copy over new kernel using the following:
830 to run from within the Build Directory the
831 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>
832 task as follows:
833 <literallayout class='monospaced'> 765 <literallayout class='monospaced'>
834 $ bitbake -c cleansstate linux-yocto 766 $ sudo cp workspace/sources/linux-yocto/arch/x86/boot/bzImage /mnt/wic-p1
835 </literallayout></para> 767 </literallayout>
836 <para>
837 <note>
838 Never remove any files by hand from the
839 <filename>tmp/deploy</filename>
840 directory inside the
841 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
842 Always use the various BitBake clean tasks to
843 clear out previous build artifacts.
844 For information on the clean tasks, see the
845 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>",
846 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>",
847 and
848 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>"
849 sections all in the Yocto Project Reference
850 Manual.
851 </note>
852 </para></listitem> 768 </para></listitem>
853 <listitem><para> 769 <listitem><para>
854 <emphasis>Build the image</emphasis>: 770 Finally, unmount the device and use
855 Next, build the kernel image using this command: 771 <filename>kpartx</filename> to delete the partition
772 mappings:
773 <note>
774 Replace the "<replaceable>X</replaceable>" in
775 "loop<replaceable>X</replaceable>" with the
776 automatically allocated loopback device from
777 earlier (e.g "loop0").
778 </note>
856 <literallayout class='monospaced'> 779 <literallayout class='monospaced'>
857 $ bitbake -k linux-yocto 780 $ sudo umount /mnt/wic-p1
858 </literallayout></para></listitem> 781 $ sudo kpartx -d /dev/loop<replaceable>X</replaceable>
782 </literallayout>
783 </para></listitem>
859 </orderedlist> 784 </orderedlist>
860 </para> 785 </para></listitem>
861 </section> 786-->
862 787 <listitem><para>
863 <section id='boot-the-image-and-verify-your-changes'> 788 <emphasis>Create the Image With the New Kernel:</emphasis>
864 <title>Boot the Image and Verify Your Changes</title> 789 Use the <filename>devtool build-image</filename> command
865 790 to create a new image that has the new kernel.
866 <para> 791 <note>
867 These steps boot the image and allow you to see the changes 792 If the image you originally created resulted in a Wic
793 file, you can use an alternate method to create the new
794 image with the updated kernel.
795 For an example, see the steps in the
796 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink>
797 Wiki Page.
798 </note>
799 <literallayout class='monospaced'>
800 $ cd ~
801 $ devtool build-image core-image-minimal
802 Loading cache: 100% |###########################################################################| Time: 0:00:00
803 Loaded 1299 entries from dependency cache.
804 Parsing recipes: 100% |#########################################################################| Time: 0:00:00
805 Parsing of 831 .bb files complete (830 cached, 1 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors.
806 WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
807 WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
808 WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
809
810 Summary: There was 1 WARNING message shown.
811 WARNING: Skipping recipe linux-yocto as it doesn't produce a package with the same name
812 WARNING: No recipes in workspace, building image core-image-minimal unmodified
813 Loading cache: 100% |###########################################################################| Time: 0:00:00
814 Loaded 1299 entries from dependency cache.
815 Parsing recipes: 100% |#########################################################################| Time: 0:00:00
816 Parsing of 831 .bb files complete (830 cached, 1 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors.
817 WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
818 NOTE: Resolving any missing task queue dependencies
819 Initialising tasks: 100% |######################################################################| Time: 0:00:06
820 Checking sstate mirror object availability: 100% |##############################################| Time: 0:00:00
821 NOTE: Executing SetScene Tasks
822 NOTE: Executing RunQueue Tasks
823 NOTE: Tasks Summary: Attempted 2393 tasks of which 2375 didn't need to be rerun and all succeeded.
824
825 Summary: There was 1 WARNING message shown.
826 NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86
827 </literallayout>
828 </para></listitem>
829 <listitem><para>
830 <emphasis>Test the New Image:</emphasis>
831 For this example, you can run the new image using QEMU
832 to verify your changes:
868 <orderedlist> 833 <orderedlist>
869 <listitem><para><emphasis>Boot the image</emphasis>: 834 <listitem><para>
835 <emphasis>Boot the image</emphasis>:
870 Boot the modified image in the QEMU emulator 836 Boot the modified image in the QEMU emulator
871 using this command: 837 using this command:
872 <literallayout class='monospaced'> 838 <literallayout class='monospaced'>
873 $ runqemu qemux86 839 $ runqemu qemux86
874 </literallayout></para></listitem> 840 </literallayout>
875 <listitem><para><emphasis>Verify the changes</emphasis>: 841 </para></listitem>
876 Log into the machine using <filename>root</filename> with no password and then 842 <listitem><para>
877 use the following shell command to scroll through the console's boot output. 843 <emphasis>Verify the changes</emphasis>:
844 Log into the machine using <filename>root</filename>
845 with no password and then use the following shell
846 command to scroll through the console's boot output.
878 <literallayout class='monospaced'> 847 <literallayout class='monospaced'>
879 # dmesg | less 848 # dmesg | less
880 </literallayout> 849 </literallayout>
881 You should see the results of your <filename>printk</filename> statements 850 You should see the results of your
882 as part of the output.</para></listitem> 851 <filename>printk</filename> statements
852 as part of the output when you scroll down the
853 console window.
854 </para></listitem>
883 </orderedlist> 855 </orderedlist>
884 </para> 856 </para></listitem>
885 </section> 857 <listitem><para>
858 <emphasis>Stage and commit your changes</emphasis>:
859 Within your eSDK terminal, change your working directory to
860 where you modified the <filename>calibrate.c</filename>
861 file and use these Git commands to stage and commit your
862 changes:
863 <literallayout class='monospaced'>
864 $ cd ~/poky_sdk/workspace/sources/linux-yocto
865 $ git status
866 $ git add init/calibrate.c
867 $ git commit -m "calibrate: Add printk example"
868 </literallayout>
869 </para></listitem>
870 <listitem><para>
871 <emphasis>Export the Patches and Create a <filename>.bbappend</filename>:</emphasis>
872 To export your commits as patches and create a
873 <filename>.bbappend</filename> file, use the following
874 command in the terminal used to work with the extensible
875 SDK.
876 This example uses the previously established layer named
877 <filename>meta-my-kernel</filename>.
878 <note>
879 See Step 3 of the
880 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop using devtool</link>"
881 section for information on setting up this layer.
882 </note>
883 <literallayout class='monospaced'>
884 $ devtool finish linux-yocto /path/to/meta-my-kernel
885 </literallayout>
886 Once the command finishes, the patches and the
887 <filename>.bbappend</filename> file are located in the
888 <filename>~/meta-my-kernel/recipes-kernel/linux</filename>
889 directory.
890 </para></listitem>
891 <listitem><para>
892 <emphasis>Build the Image With Your Modified Kernel:</emphasis>
893 You can now build an image that includes your kernel
894 patches.
895 Execute the following command from your
896 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
897 in the terminal set up to run BitBake:
898 <literallayout class='monospaced'>
899 $ cd ~/poky/build
900 $ bitbake core-image-minimal
901 </literallayout>
902 </para></listitem>
903 </orderedlist>
886 </section> 904 </section>
887 905
888 <section id='using-an-iterative-development-process'> 906 <section id='using-an-iterative-development-process'>
@@ -1174,7 +1192,7 @@
1174 are very time consuming. 1192 are very time consuming.
1175 </para> 1193 </para>
1176 1194
1177 <para> 1195 <para role='writernotes'>
1178 Once you are satisfied with your source code modifications, 1196 Once you are satisfied with your source code modifications,
1179 you can make them permanent by generating patches and 1197 you can make them permanent by generating patches and
1180 applying them to the 1198 applying them to the
@@ -1183,7 +1201,7 @@
1183 "<link linkend='applying-patches'>Applying Patches</link>" 1201 "<link linkend='applying-patches'>Applying Patches</link>"
1184 section. 1202 section.
1185 If you are not familiar with generating patches, refer to the 1203 If you are not familiar with generating patches, refer to the
1186 "<link linkend='creating-the-patch'>Creating the Patch</link>" 1204 "I need a linked section here for the patch stuff"
1187 section. 1205 section.
1188 </para> 1206 </para>
1189 </section> 1207 </section>
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index a2644aaa13..ce8e0fcb6d 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -108,6 +108,16 @@
108 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>" 108 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
109 section in the Yocto Project Development Manual to set up your 109 section in the Yocto Project Development Manual to set up your
110 Source Directory. 110 Source Directory.
111 <note>
112 Be sure you check out the appropriate development branch or
113 by tag to get the version of Yocto Project you want.
114 See the
115 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
116 and
117 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
118 sections in the Yocto Project Development Manual for more
119 information.
120 </note>
111 </para> 121 </para>
112 122
113 <para> 123 <para>
@@ -156,7 +166,7 @@
156 building for the QEMU emulator in 32-bit mode. 166 building for the QEMU emulator in 32-bit mode.
157 However, if you are not, you need to set the 167 However, if you are not, you need to set the
158 <filename>MACHINE</filename> variable appropriately in 168 <filename>MACHINE</filename> variable appropriately in
159 your <filename>local.conf</filename> file found in the 169 your <filename>conf/local.conf</filename> file found in the
160 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> 170 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
161 (i.e. <filename>~/poky/build</filename> in this example). 171 (i.e. <filename>~/poky/build</filename> in this example).
162 </para> 172 </para>
@@ -208,6 +218,7 @@
208 Use BitBake to build the extensible SDK specifically for 218 Use BitBake to build the extensible SDK specifically for
209 the Minnowboard: 219 the Minnowboard:
210 <literallayout class='monospaced'> 220 <literallayout class='monospaced'>
221 $ cd ~/poky/build
211 $ bitbake core-image-minimal -c populate_sdk_ext 222 $ bitbake core-image-minimal -c populate_sdk_ext
212 </literallayout> 223 </literallayout>
213 Once the build finishes, you can find the SDK installer 224 Once the build finishes, you can find the SDK installer
@@ -290,12 +301,9 @@
290 If you were building for actual hardware and not for 301 If you were building for actual hardware and not for
291 emulation, you could flash the image to a USB stick 302 emulation, you could flash the image to a USB stick
292 on <filename>/dev/sdd</filename> and boot your device. 303 on <filename>/dev/sdd</filename> and boot your device.
293 Use a command similar to the following command to flash 304 For an example that uses a Minnowboard, see the
294 the image: 305 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink>
295 <literallayout class='monospaced'> 306 Wiki page.
296 $ sudo dd if=tmp/deploy/images/<replaceable>architecture</replaceable>/core-image-minimal-<replaceable>architecture</replaceable>.wic of=/dev/sdd bs=1MB
297 $ sync
298 </literallayout>
299 </para></listitem> 307 </para></listitem>
300 </orderedlist> 308 </orderedlist>
301 </para> 309 </para>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 12:54:54 +0000