summaryrefslogtreecommitdiffstats
path: root/documentation
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
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')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml341
-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
-rw-r--r--documentation/sdk-manual/sdk-working-projects.xml6
5 files changed, 366 insertions, 358 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 5a00533f33..e88d4a796c 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -6625,347 +6625,6 @@ Some notes from Cal:
6625 </section> 6625 </section>
6626 </section> 6626 </section>
6627 6627
6628 <section id="patching-the-kernel">
6629 <title>Patching the Kernel</title>
6630
6631 <para>
6632 Patching the kernel involves changing or adding configurations to an existing kernel,
6633 changing or adding recipes to the kernel that are needed to support specific hardware features,
6634 or even altering the source code itself.
6635 <note>
6636 You can use the <filename>yocto-kernel</filename> script
6637 found in the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
6638 under <filename>scripts</filename> to manage kernel patches and configuration.
6639 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>"
6640 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
6641 more information.</note>
6642 </para>
6643
6644 <para>
6645 This example creates a simple patch by adding some QEMU emulator console
6646 output at boot time through <filename>printk</filename> statements in the kernel's
6647 <filename>calibrate.c</filename> source code file.
6648 Applying the patch and booting the modified image causes the added
6649 messages to appear on the emulator's console.
6650 </para>
6651
6652 <para>
6653 The example assumes a clean build exists for the <filename>qemux86</filename>
6654 machine in a
6655 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
6656 named <filename>poky</filename>.
6657 Furthermore, the
6658 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
6659 is <filename>build</filename> and is located in
6660 <filename>poky</filename> and the kernel is based on the
6661 Linux 3.4 kernel.
6662 </para>
6663
6664 <para>
6665 Also, for more information on patching the kernel, see the
6666 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#applying-patches'>Applying Patches</ulink>"
6667 section in the Yocto Project Linux Kernel Development Manual.
6668 </para>
6669
6670 <section id='create-a-layer-for-your-changes'>
6671 <title>Create a Layer for your Changes</title>
6672
6673 <para>
6674 The first step is to create a layer so you can isolate your
6675 changes.
6676 Rather than use the <filename>yocto-layer</filename> script
6677 to create the layer, this example steps through the process
6678 by hand.
6679 If you want information on the script that creates a general
6680 layer, see the
6681 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
6682 section.
6683 </para>
6684
6685 <para>
6686 These two commands create a directory you can use for your
6687 layer:
6688 <literallayout class='monospaced'>
6689 $ cd ~/poky
6690 $ mkdir meta-mylayer
6691 </literallayout>
6692 Creating a directory that follows the Yocto Project layer naming
6693 conventions sets up the layer for your changes.
6694 The layer is where you place your configuration files, append
6695 files, and patch files.
6696 To learn more about creating a layer and filling it with the
6697 files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding
6698 and Creating Layers</link>" section.
6699 </para>
6700 </section>
6701
6702 <section id='finding-the-kernel-source-code'>
6703 <title>Finding the Kernel Source Code</title>
6704
6705 <para>
6706 Each time you build a kernel image, the kernel source code
6707 is fetched and unpacked into the following directory:
6708 <literallayout class='monospaced'>
6709 ${S}/linux
6710 </literallayout>
6711 See the "<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>"
6712 section and the
6713 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
6714 for more information about where source is kept during a build.
6715 </para>
6716
6717 <para>
6718 For this example, we are going to patch the
6719 <filename>init/calibrate.c</filename> file
6720 by adding some simple console <filename>printk</filename> statements that we can
6721 see when we boot the image using QEMU.
6722 </para>
6723 </section>
6724
6725 <section id='creating-the-patch'>
6726 <title>Creating the Patch</title>
6727
6728 <para>
6729 Two methods exist by which you can create the patch:
6730 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
6731 and
6732 <link linkend='using-a-quilt-workflow'>Quilt</link>.
6733 For kernel patches, the Git workflow is more appropriate.
6734 This section assumes the Git workflow and shows the steps specific to
6735 this example.
6736 <orderedlist>
6737 <listitem><para><emphasis>Change the working directory</emphasis>:
6738 Change to where the kernel source code is before making
6739 your edits to the <filename>calibrate.c</filename> file:
6740 <literallayout class='monospaced'>
6741 $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
6742 </literallayout>
6743 Because you are working in an established Git repository,
6744 you must be in this directory in order to commit your changes
6745 and create the patch file.
6746 <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
6747 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
6748 represent the version and revision for the
6749 <filename>linux-yocto</filename> recipe.
6750 The <filename>PV</filename> variable includes the Git meta and machine
6751 hashes, which make the directory name longer than you might
6752 expect.
6753 </note></para></listitem>
6754 <listitem><para><emphasis>Edit the source file</emphasis>:
6755 Edit the <filename>init/calibrate.c</filename> file to have the
6756 following changes:
6757 <literallayout class='monospaced'>
6758 void calibrate_delay(void)
6759 {
6760 unsigned long lpj;
6761 static bool printed;
6762 int this_cpu = smp_processor_id();
6763
6764 printk("*************************************\n");
6765 printk("* *\n");
6766 printk("* HELLO YOCTO KERNEL *\n");
6767 printk("* *\n");
6768 printk("*************************************\n");
6769
6770 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
6771 .
6772 .
6773 .
6774 </literallayout></para></listitem>
6775 <listitem><para><emphasis>Stage and commit your changes</emphasis>:
6776 These Git commands display the modified file, stage it, and then
6777 commit the file:
6778 <literallayout class='monospaced'>
6779 $ git status
6780 $ git add init/calibrate.c
6781 $ git commit -m "calibrate: Add printk example"
6782 </literallayout></para></listitem>
6783 <listitem><para><emphasis>Generate the patch file</emphasis>:
6784 This Git command creates the a patch file named
6785 <filename>0001-calibrate-Add-printk-example.patch</filename>
6786 in the current directory.
6787 <literallayout class='monospaced'>
6788 $ git format-patch -1
6789 </literallayout>
6790 </para></listitem>
6791 </orderedlist>
6792 </para>
6793 </section>
6794
6795 <section id='set-up-your-layer-for-the-build'>
6796 <title>Set Up Your Layer for the Build</title>
6797
6798 <para>These steps get your layer set up for the build:
6799 <orderedlist>
6800 <listitem><para><emphasis>Create additional structure</emphasis>:
6801 Create the additional layer structure:
6802 <literallayout class='monospaced'>
6803 $ cd ~/poky/meta-mylayer
6804 $ mkdir conf
6805 $ mkdir recipes-kernel
6806 $ mkdir recipes-kernel/linux
6807 $ mkdir recipes-kernel/linux/linux-yocto
6808 </literallayout>
6809 The <filename>conf</filename> directory holds your configuration files, while the
6810 <filename>recipes-kernel</filename> directory holds your append file and
6811 your patch file.</para></listitem>
6812 <listitem><para><emphasis>Create the layer configuration file</emphasis>:
6813 Move to the <filename>meta-mylayer/conf</filename> directory and create
6814 the <filename>layer.conf</filename> file as follows:
6815 <literallayout class='monospaced'>
6816 # We have a conf and classes directory, add to BBPATH
6817 BBPATH .= ":${LAYERDIR}"
6818
6819 # We have recipes-* directories, add to BBFILES
6820 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
6821 ${LAYERDIR}/recipes-*/*/*.bbappend"
6822
6823 BBFILE_COLLECTIONS += "mylayer"
6824 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
6825 BBFILE_PRIORITY_mylayer = "5"
6826 </literallayout>
6827 Notice <filename>mylayer</filename> as part of the last three
6828 statements.</para></listitem>
6829 <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
6830 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
6831 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
6832 <literallayout class='monospaced'>
6833 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
6834
6835 SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
6836 </literallayout>
6837 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
6838 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
6839 statements enable the OpenEmbedded build system to find the patch file.
6840 For more information on using append files, see the
6841 "<link linkend='using-bbappend-files'>Using .bbappend Files in Your Layer</link>"
6842 section.
6843 </para></listitem>
6844 <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
6845 Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
6846 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
6847 directory.</para></listitem>
6848 </orderedlist>
6849 </para>
6850 </section>
6851
6852 <section id='set-up-for-the-build'>
6853 <title>Set Up for the Build</title>
6854
6855 <para>
6856 Do the following to make sure the build parameters are set up for the example.
6857 Once you set up these build parameters, they do not have to change unless you
6858 change the target architecture of the machine you are building:
6859 <itemizedlist>
6860 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
6861 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
6862 definition within the <filename>local.conf</filename> file in the
6863 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
6864 specifies the target architecture used when building the Linux kernel.
6865 By default, <filename>MACHINE</filename> is set to
6866 <filename>qemux86</filename>, which specifies a 32-bit
6867 <trademark class='registered'>Intel</trademark> Architecture
6868 target machine suitable for the QEMU emulator.</para></listitem>
6869 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
6870 layer:</emphasis> The
6871 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
6872 variable in the
6873 <filename>bblayers.conf</filename> file found in the
6874 <filename>poky/build/conf</filename> directory needs to have the path to your local
6875 <filename>meta-mylayer</filename> layer.
6876 By default, the <filename>BBLAYERS</filename> variable contains paths to
6877 <filename>meta</filename>, <filename>meta-poky</filename>, and
6878 <filename>meta-yocto-bsp</filename> in the
6879 <filename>poky</filename> Git repository.
6880 Add the path to your <filename>meta-mylayer</filename> location:
6881 <literallayout class='monospaced'>
6882 BBLAYERS ?= " \
6883 $HOME/poky/meta \
6884 $HOME/poky/meta-poky \
6885 $HOME/poky/meta-yocto-bsp \
6886 $HOME/poky/meta-mylayer \
6887 "
6888 </literallayout></para></listitem>
6889 </itemizedlist>
6890 </para>
6891 </section>
6892
6893 <section id='build-the-modified-qemu-kernel-image'>
6894 <title>Build the Modified QEMU Kernel Image</title>
6895
6896 <para>
6897 The following steps build your modified kernel image:
6898 <orderedlist>
6899 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
6900 Your environment should be set up since you previously sourced
6901 the
6902 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
6903 script.
6904 If it is not, source the script again from <filename>poky</filename>.
6905 <literallayout class='monospaced'>
6906 $ cd ~/poky
6907 $ source &OE_INIT_FILE;
6908 </literallayout>
6909 </para></listitem>
6910 <listitem><para><emphasis>Clean up</emphasis>:
6911 Be sure to clean the shared state out by using BitBake
6912 to run from within the Build Directory the
6913 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>
6914 task as follows:
6915 <literallayout class='monospaced'>
6916 $ bitbake -c cleansstate linux-yocto
6917 </literallayout></para>
6918 <para>
6919 <note>
6920 Never remove any files by hand from the
6921 <filename>tmp/deploy</filename>
6922 directory inside the
6923 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
6924 Always use the various BitBake clean tasks to
6925 clear out previous build artifacts.
6926 For information on the clean tasks, see the
6927 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>",
6928 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>",
6929 and
6930 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>"
6931 sections all in the Yocto Project Reference
6932 Manual.
6933 </note>
6934 </para></listitem>
6935 <listitem><para><emphasis>Build the image</emphasis>:
6936 Next, build the kernel image using this command:
6937 <literallayout class='monospaced'>
6938 $ bitbake -k linux-yocto
6939 </literallayout></para></listitem>
6940 </orderedlist>
6941 </para>
6942 </section>
6943
6944 <section id='boot-the-image-and-verify-your-changes'>
6945 <title>Boot the Image and Verify Your Changes</title>
6946
6947 <para>
6948 These steps boot the image and allow you to see the changes
6949 <orderedlist>
6950 <listitem><para><emphasis>Boot the image</emphasis>:
6951 Boot the modified image in the QEMU emulator
6952 using this command:
6953 <literallayout class='monospaced'>
6954 $ runqemu qemux86
6955 </literallayout></para></listitem>
6956 <listitem><para><emphasis>Verify the changes</emphasis>:
6957 Log into the machine using <filename>root</filename> with no password and then
6958 use the following shell command to scroll through the console's boot output.
6959 <literallayout class='monospaced'>
6960 # dmesg | less
6961 </literallayout>
6962 You should see the results of your <filename>printk</filename> statements
6963 as part of the output.</para></listitem>
6964 </orderedlist>
6965 </para>
6966 </section>
6967 </section>
6968
6969 <section id='making-images-more-secure'> 6628 <section id='making-images-more-secure'>
6970 <title>Making Images More Secure</title> 6629 <title>Making Images More Secure</title>
6971 6630
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
diff --git a/documentation/sdk-manual/sdk-working-projects.xml b/documentation/sdk-manual/sdk-working-projects.xml
index 526d9208a3..da83b1a7cf 100644
--- a/documentation/sdk-manual/sdk-working-projects.xml
+++ b/documentation/sdk-manual/sdk-working-projects.xml
@@ -349,9 +349,9 @@
349 supported architecture, you can modify the 349 supported architecture, you can modify the
350 kernel image before you build it. 350 kernel image before you build it.
351 See the 351 See the
352 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" 352 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</ulink>"
353 section in the Yocto Project Development 353 section in the Yocto Project Linux Kernel
354 manual for an example. 354 Development Manual for an example.
355 </para></listitem> 355 </para></listitem>
356 </itemizedlist> 356 </itemizedlist>
357 </para></listitem> 357 </para></listitem>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-12 02:06:15 +0000