summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
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/dev-manual
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/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml341
1 files changed, 0 insertions, 341 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
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-09 00:42:58 +0000