summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-08-15 15:52:21 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-09-02 00:52:48 +0100
commita99c2c5581f8847fa3d95696f0f985ea87f9da9d (patch)
tree85f1555032abc37a0f016970f13063f0f6ec05f8 /documentation/kernel-dev
parent2c0c962dd94513d7bbdf93439613ae926aca1d23 (diff)
downloadpoky-a99c2c5581f8847fa3d95696f0f985ea87f9da9d.tar.gz
dev-manual, kernel-dev, sdk-manual: Moved patching kernel section
Moved the "Patching the Kernel" section, which was in the dev-manual to the kernel-dev manual. During the move, renamed the section to "Using devtool to Patch the Kernel". This move bothered a lot of links so I had to fix them in various manuals. (From yocto-docs rev: a000be1eddf33e4d7de8f350e076d48e27ca4b98) 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.xml364
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.xml5
-rw-r--r--documentation/kernel-dev/kernel-dev-intro.xml8
3 files changed, 363 insertions, 14 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index bb50a7def6..c55f68bc24 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -75,9 +75,8 @@
75 See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>" 75 See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
76 section for some general resources. 76 section for some general resources.
77 You can also see the 77 You can also see the
78 "<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section 78 "<link linkend='set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</link>"
79 of the Yocto Project Development Manual for a detailed 79 section for a detailed example.
80 example.
81 </para> 80 </para>
82 81
83 <section id='creating-the-append-file'> 82 <section id='creating-the-append-file'>
@@ -295,9 +294,10 @@
295 </para> 294 </para>
296 295
297 <para> 296 <para>
298 For a detailed example showing how to patch the kernel, see the 297 For a detailed example showing how to patch the kernel using
299 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" 298 <filename>devtool</filename>, see the
300 section in the Yocto Project Development Manual. 299 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
300 section.
301 </para> 301 </para>
302 </section> 302 </section>
303 303
@@ -449,6 +449,354 @@
449 </section> 449 </section>
450 </section> 450 </section>
451 451
452 <section id="using-devtool-to-patch-the-kernel">
453 <title>Using <filename>devtool</filename> to Patch the Kernel</title>
454
455 <para>
456 Patching the kernel involves changing or adding configurations to an existing kernel,
457 changing or adding recipes to the kernel that are needed to support specific hardware features,
458 or even altering the source code itself.
459 <note>
460 You can use the <filename>yocto-kernel</filename> script
461 found in the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
462 under <filename>scripts</filename> to manage kernel patches and configuration.
463 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>"
464 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
465 more information.</note>
466 </para>
467
468 <para>
469 This example creates a simple patch by adding some QEMU emulator console
470 output at boot time through <filename>printk</filename> statements in the kernel's
471 <filename>calibrate.c</filename> source code file.
472 Applying the patch and booting the modified image causes the added
473 messages to appear on the emulator's console.
474 </para>
475
476 <para>
477 The example assumes a clean build exists for the <filename>qemux86</filename>
478 machine in a
479 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
480 named <filename>poky</filename>.
481 Furthermore, the
482 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
483 is <filename>build</filename> and is located in
484 <filename>poky</filename> and the kernel is based on the
485 Linux 3.4 kernel.
486 </para>
487
488 <para>
489 Also, for more information on patching the kernel, see the
490 "<link linkend='applying-patches'>Applying Patches</link>"
491 section.
492 </para>
493
494 <section id='create-a-layer-for-your-changes'>
495 <title>Create a Layer for your Changes</title>
496
497 <para>
498 The first step is to create a layer so you can isolate your
499 changes.
500 Rather than use the <filename>yocto-layer</filename> script
501 to create the layer, this example steps through the process
502 by hand.
503 If you want information on the script that creates a general
504 layer, see the
505 "<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>"
506 section in the Yocto Project Development Manual.
507 </para>
508
509 <para>
510 These two commands create a directory you can use for your
511 layer:
512 <literallayout class='monospaced'>
513 $ cd ~/poky
514 $ mkdir meta-mylayer
515 </literallayout>
516 Creating a directory that follows the Yocto Project layer naming
517 conventions sets up the layer for your changes.
518 The layer is where you place your configuration files, append
519 files, and patch files.
520 To learn more about creating a layer and filling it with the
521 files you need, see the
522 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
523 section in the Yocto Project Development Manual.
524 </para>
525 </section>
526
527 <section id='finding-the-kernel-source-code'>
528 <title>Finding the Kernel Source Code</title>
529
530 <para>
531 Each time you build a kernel image, the kernel source code
532 is fetched and unpacked into the following directory:
533 <literallayout class='monospaced'>
534 ${S}/linux
535 </literallayout>
536 See the "<ulink url='&YOCTO_DOCS_DEV_URL;#finding-the-temporary-source-code'>Finding Temporary Source Code</ulink>"
537 section in the Yocto Project Development Manual and the
538 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
539 variable for more information about where source is kept
540 during a build.
541 </para>
542
543 <para>
544 For this example, we are going to patch the
545 <filename>init/calibrate.c</filename> file
546 by adding some simple console <filename>printk</filename> statements that we can
547 see when we boot the image using QEMU.
548 </para>
549 </section>
550
551 <section id='creating-the-patch'>
552 <title>Creating the Patch</title>
553
554 <para>
555 Two methods exist by which you can create the patch:
556 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
557 and
558 <ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Quilt</ulink>.
559 For kernel patches, the Git workflow is more appropriate.
560 This section assumes the Git workflow and shows the steps
561 specific to this example.
562 <orderedlist>
563 <listitem><para>
564 <emphasis>Change the working directory</emphasis>:
565 Change to where the kernel source code is before making
566 your edits to the <filename>calibrate.c</filename> file:
567 <literallayout class='monospaced'>
568 $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
569 </literallayout>
570 Because you are working in an established Git repository,
571 you must be in this directory in order to commit your changes
572 and create the patch file.
573 <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
574 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
575 represent the version and revision for the
576 <filename>linux-yocto</filename> recipe.
577 The <filename>PV</filename> variable includes the Git meta and machine
578 hashes, which make the directory name longer than you might
579 expect.
580 </note></para></listitem>
581 <listitem><para>
582 <emphasis>Edit the source file</emphasis>:
583 Edit the <filename>init/calibrate.c</filename> file to have the
584 following changes:
585 <literallayout class='monospaced'>
586 void calibrate_delay(void)
587 {
588 unsigned long lpj;
589 static bool printed;
590 int this_cpu = smp_processor_id();
591
592 printk("*************************************\n");
593 printk("* *\n");
594 printk("* HELLO YOCTO KERNEL *\n");
595 printk("* *\n");
596 printk("*************************************\n");
597
598 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
599 .
600 .
601 .
602 </literallayout></para></listitem>
603 <listitem><para><emphasis>Stage and commit your changes</emphasis>:
604 These Git commands display the modified file, stage it, and then
605 commit the file:
606 <literallayout class='monospaced'>
607 $ git status
608 $ git add init/calibrate.c
609 $ git commit -m "calibrate: Add printk example"
610 </literallayout></para></listitem>
611 <listitem><para><emphasis>Generate the patch file</emphasis>:
612 This Git command creates the a patch file named
613 <filename>0001-calibrate-Add-printk-example.patch</filename>
614 in the current directory.
615 <literallayout class='monospaced'>
616 $ git format-patch -1
617 </literallayout>
618 </para></listitem>
619 </orderedlist>
620 </para>
621 </section>
622
623 <section id='set-up-your-layer-for-the-build'>
624 <title>Set Up Your Layer for the Build</title>
625
626 <para>These steps get your layer set up for the build:
627 <orderedlist>
628 <listitem><para><emphasis>Create additional structure</emphasis>:
629 Create the additional layer structure:
630 <literallayout class='monospaced'>
631 $ cd ~/poky/meta-mylayer
632 $ mkdir conf
633 $ mkdir recipes-kernel
634 $ mkdir recipes-kernel/linux
635 $ mkdir recipes-kernel/linux/linux-yocto
636 </literallayout>
637 The <filename>conf</filename> directory holds your configuration files, while the
638 <filename>recipes-kernel</filename> directory holds your append file and
639 your patch file.</para></listitem>
640 <listitem><para><emphasis>Create the layer configuration file</emphasis>:
641 Move to the <filename>meta-mylayer/conf</filename> directory and create
642 the <filename>layer.conf</filename> file as follows:
643 <literallayout class='monospaced'>
644 # We have a conf and classes directory, add to BBPATH
645 BBPATH .= ":${LAYERDIR}"
646
647 # We have recipes-* directories, add to BBFILES
648 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
649 ${LAYERDIR}/recipes-*/*/*.bbappend"
650
651 BBFILE_COLLECTIONS += "mylayer"
652 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
653 BBFILE_PRIORITY_mylayer = "5"
654 </literallayout>
655 Notice <filename>mylayer</filename> as part of the last three
656 statements.</para></listitem>
657 <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
658 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
659 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
660 <literallayout class='monospaced'>
661 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
662
663 SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
664 </literallayout>
665 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
666 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
667 statements enable the OpenEmbedded build system to find the patch file.
668 For more information on using append files, see the
669 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
670 section in the Yocto Project Development Manual.
671 </para></listitem>
672 <listitem><para>
673 <emphasis>Put the patch file in your layer</emphasis>:
674 Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
675 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
676 directory.</para></listitem>
677 </orderedlist>
678 </para>
679 </section>
680
681 <section id='set-up-for-the-build'>
682 <title>Set Up for the Build</title>
683
684 <para>
685 Do the following to make sure the build parameters are set up for the example.
686 Once you set up these build parameters, they do not have to change unless you
687 change the target architecture of the machine you are building:
688 <itemizedlist>
689 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
690 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
691 definition within the <filename>local.conf</filename> file in the
692 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
693 specifies the target architecture used when building the Linux kernel.
694 By default, <filename>MACHINE</filename> is set to
695 <filename>qemux86</filename>, which specifies a 32-bit
696 <trademark class='registered'>Intel</trademark> Architecture
697 target machine suitable for the QEMU emulator.</para></listitem>
698 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
699 layer:</emphasis> The
700 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
701 variable in the
702 <filename>bblayers.conf</filename> file found in the
703 <filename>poky/build/conf</filename> directory needs to have the path to your local
704 <filename>meta-mylayer</filename> layer.
705 By default, the <filename>BBLAYERS</filename> variable contains paths to
706 <filename>meta</filename>, <filename>meta-poky</filename>, and
707 <filename>meta-yocto-bsp</filename> in the
708 <filename>poky</filename> Git repository.
709 Add the path to your <filename>meta-mylayer</filename> location:
710 <literallayout class='monospaced'>
711 BBLAYERS ?= " \
712 $HOME/poky/meta \
713 $HOME/poky/meta-poky \
714 $HOME/poky/meta-yocto-bsp \
715 $HOME/poky/meta-mylayer \
716 "
717 </literallayout></para></listitem>
718 </itemizedlist>
719 </para>
720 </section>
721
722 <section id='build-the-modified-qemu-kernel-image'>
723 <title>Build the Modified QEMU Kernel Image</title>
724
725 <para>
726 The following steps build your modified kernel image:
727 <orderedlist>
728 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
729 Your environment should be set up since you previously sourced
730 the
731 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
732 script.
733 If it is not, source the script again from <filename>poky</filename>.
734 <literallayout class='monospaced'>
735 $ cd ~/poky
736 $ source &OE_INIT_FILE;
737 </literallayout>
738 </para></listitem>
739 <listitem><para>
740 <emphasis>Clean up</emphasis>:
741 Be sure to clean the shared state out by using BitBake
742 to run from within the Build Directory the
743 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>
744 task as follows:
745 <literallayout class='monospaced'>
746 $ bitbake -c cleansstate linux-yocto
747 </literallayout></para>
748 <para>
749 <note>
750 Never remove any files by hand from the
751 <filename>tmp/deploy</filename>
752 directory inside the
753 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
754 Always use the various BitBake clean tasks to
755 clear out previous build artifacts.
756 For information on the clean tasks, see the
757 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>",
758 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>",
759 and
760 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>"
761 sections all in the Yocto Project Reference
762 Manual.
763 </note>
764 </para></listitem>
765 <listitem><para>
766 <emphasis>Build the image</emphasis>:
767 Next, build the kernel image using this command:
768 <literallayout class='monospaced'>
769 $ bitbake -k linux-yocto
770 </literallayout></para></listitem>
771 </orderedlist>
772 </para>
773 </section>
774
775 <section id='boot-the-image-and-verify-your-changes'>
776 <title>Boot the Image and Verify Your Changes</title>
777
778 <para>
779 These steps boot the image and allow you to see the changes
780 <orderedlist>
781 <listitem><para><emphasis>Boot the image</emphasis>:
782 Boot the modified image in the QEMU emulator
783 using this command:
784 <literallayout class='monospaced'>
785 $ runqemu qemux86
786 </literallayout></para></listitem>
787 <listitem><para><emphasis>Verify the changes</emphasis>:
788 Log into the machine using <filename>root</filename> with no password and then
789 use the following shell command to scroll through the console's boot output.
790 <literallayout class='monospaced'>
791 # dmesg | less
792 </literallayout>
793 You should see the results of your <filename>printk</filename> statements
794 as part of the output.</para></listitem>
795 </orderedlist>
796 </para>
797 </section>
798 </section>
799
452 <section id='using-an-iterative-development-process'> 800 <section id='using-an-iterative-development-process'>
453 <title>Using an Iterative Development Process</title> 801 <title>Using an Iterative Development Process</title>
454 802
@@ -747,8 +1095,8 @@
747 "<link linkend='applying-patches'>Applying Patches</link>" 1095 "<link linkend='applying-patches'>Applying Patches</link>"
748 section. 1096 section.
749 If you are not familiar with generating patches, refer to the 1097 If you are not familiar with generating patches, refer to the
750 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>" 1098 "<link linkend='creating-the-patch'>Creating the Patch</link>"
751 section in the Yocto Project Development Manual. 1099 section.
752 </para> 1100 </para>
753 </section> 1101 </section>
754 </section> 1102 </section>
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index 7f6b82fee5..60d67d64fe 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -461,9 +461,8 @@
461 "<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>" 461 "<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>"
462 section. 462 section.
463 You can also reference the 463 You can also reference the
464 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" 464 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
465 section in the Yocto Project Development Manual for a detailed 465 section for a detailed example that modifies the kernel.
466 example that modifies the kernel.
467 </para> 466 </para>
468 </section> 467 </section>
469</appendix> 468</appendix>
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index 95c50e4691..899ed65db2 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -108,12 +108,14 @@
108 You can find additional information here: 108 You can find additional information here:
109 <itemizedlist> 109 <itemizedlist>
110 <listitem><para> 110 <listitem><para>
111 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" 111 The
112 in the Yocto Project Development Manual. 112 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
113 section.
113 </para></listitem> 114 </para></listitem>
114 <listitem><para> 115 <listitem><para>
116 The
115 "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>" 117 "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
116 in the Yocto Project Development Manual. 118 section in the Yocto Project Development Manual.
117 </para></listitem> 119 </para></listitem>
118 </itemizedlist> 120 </itemizedlist>
119 This illustration and the following list summarizes the kernel 121 This illustration and the following list summarizes the kernel