From a99c2c5581f8847fa3d95696f0f985ea87f9da9d Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 15 Aug 2017 15:52:21 -0700 Subject: 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 Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 341 ------------------- documentation/kernel-dev/kernel-dev-common.xml | 364 ++++++++++++++++++++- .../kernel-dev/kernel-dev-concepts-appx.xml | 5 +- documentation/kernel-dev/kernel-dev-intro.xml | 8 +- documentation/sdk-manual/sdk-working-projects.xml | 6 +- 5 files changed, 366 insertions(+), 358 deletions(-) (limited to 'documentation') 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: -
- Patching the Kernel - - - Patching the kernel involves changing or adding configurations to an existing kernel, - changing or adding recipes to the kernel that are needed to support specific hardware features, - or even altering the source code itself. - - You can use the yocto-kernel script - found in the Source Directory - under scripts to manage kernel patches and configuration. - See the "Managing kernel Patches and Config Items with yocto-kernel" - section in the Yocto Project Board Support Packages (BSP) Developer's Guide for - more information. - - - - This example creates a simple patch by adding some QEMU emulator console - output at boot time through printk statements in the kernel's - calibrate.c source code file. - Applying the patch and booting the modified image causes the added - messages to appear on the emulator's console. - - - - The example assumes a clean build exists for the qemux86 - machine in a - Source Directory - named poky. - Furthermore, the - Build Directory - is build and is located in - poky and the kernel is based on the - Linux 3.4 kernel. - - - - Also, for more information on patching the kernel, see the - "Applying Patches" - section in the Yocto Project Linux Kernel Development Manual. - - -
- Create a Layer for your Changes - - - The first step is to create a layer so you can isolate your - changes. - Rather than use the yocto-layer script - to create the layer, this example steps through the process - by hand. - If you want information on the script that creates a general - layer, see the - "Creating a General Layer Using the yocto-layer Script" - section. - - - - These two commands create a directory you can use for your - layer: - - $ cd ~/poky - $ mkdir meta-mylayer - - Creating a directory that follows the Yocto Project layer naming - conventions sets up the layer for your changes. - The layer is where you place your configuration files, append - files, and patch files. - To learn more about creating a layer and filling it with the - files you need, see the "Understanding - and Creating Layers" section. - -
- -
- Finding the Kernel Source Code - - - Each time you build a kernel image, the kernel source code - is fetched and unpacked into the following directory: - - ${S}/linux - - See the "Finding Temporary Source Code" - section and the - S variable - for more information about where source is kept during a build. - - - - For this example, we are going to patch the - init/calibrate.c file - by adding some simple console printk statements that we can - see when we boot the image using QEMU. - -
- -
- Creating the Patch - - - Two methods exist by which you can create the patch: - devtool - and - Quilt. - For kernel patches, the Git workflow is more appropriate. - This section assumes the Git workflow and shows the steps specific to - this example. - - Change the working directory: - Change to where the kernel source code is before making - your edits to the calibrate.c file: - - $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux - - Because you are working in an established Git repository, - you must be in this directory in order to commit your changes - and create the patch file. - The PV and - PR variables - represent the version and revision for the - linux-yocto recipe. - The PV variable includes the Git meta and machine - hashes, which make the directory name longer than you might - expect. - - Edit the source file: - Edit the init/calibrate.c file to have the - following changes: - - void calibrate_delay(void) - { - unsigned long lpj; - static bool printed; - int this_cpu = smp_processor_id(); - - printk("*************************************\n"); - printk("* *\n"); - printk("* HELLO YOCTO KERNEL *\n"); - printk("* *\n"); - printk("*************************************\n"); - - if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { - . - . - . - - Stage and commit your changes: - These Git commands display the modified file, stage it, and then - commit the file: - - $ git status - $ git add init/calibrate.c - $ git commit -m "calibrate: Add printk example" - - Generate the patch file: - This Git command creates the a patch file named - 0001-calibrate-Add-printk-example.patch - in the current directory. - - $ git format-patch -1 - - - - -
- -
- Set Up Your Layer for the Build - - These steps get your layer set up for the build: - - Create additional structure: - Create the additional layer structure: - - $ cd ~/poky/meta-mylayer - $ mkdir conf - $ mkdir recipes-kernel - $ mkdir recipes-kernel/linux - $ mkdir recipes-kernel/linux/linux-yocto - - The conf directory holds your configuration files, while the - recipes-kernel directory holds your append file and - your patch file. - Create the layer configuration file: - Move to the meta-mylayer/conf directory and create - the layer.conf file as follows: - - # We have a conf and classes directory, add to BBPATH - BBPATH .= ":${LAYERDIR}" - - # We have recipes-* directories, add to BBFILES - BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ - ${LAYERDIR}/recipes-*/*/*.bbappend" - - BBFILE_COLLECTIONS += "mylayer" - BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" - BBFILE_PRIORITY_mylayer = "5" - - Notice mylayer as part of the last three - statements. - Create the kernel recipe append file: - Move to the meta-mylayer/recipes-kernel/linux directory and create - the linux-yocto_3.4.bbappend file as follows: - - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - - SRC_URI += "file://0001-calibrate-Add-printk-example.patch" - - The FILESEXTRAPATHS - and SRC_URI - statements enable the OpenEmbedded build system to find the patch file. - For more information on using append files, see the - "Using .bbappend Files in Your Layer" - section. - - Put the patch file in your layer: - Move the 0001-calibrate-Add-printk-example.patch file to - the meta-mylayer/recipes-kernel/linux/linux-yocto - directory. - - -
- -
- Set Up for the Build - - - Do the following to make sure the build parameters are set up for the example. - Once you set up these build parameters, they do not have to change unless you - change the target architecture of the machine you are building: - - Build for the correct target architecture: Your - selected MACHINE - definition within the local.conf file in the - Build Directory - specifies the target architecture used when building the Linux kernel. - By default, MACHINE is set to - qemux86, which specifies a 32-bit - Intel Architecture - target machine suitable for the QEMU emulator. - Identify your meta-mylayer - layer: The - BBLAYERS - variable in the - bblayers.conf file found in the - poky/build/conf directory needs to have the path to your local - meta-mylayer layer. - By default, the BBLAYERS variable contains paths to - meta, meta-poky, and - meta-yocto-bsp in the - poky Git repository. - Add the path to your meta-mylayer location: - - BBLAYERS ?= " \ - $HOME/poky/meta \ - $HOME/poky/meta-poky \ - $HOME/poky/meta-yocto-bsp \ - $HOME/poky/meta-mylayer \ - " - - - -
- -
- Build the Modified QEMU Kernel Image - - - The following steps build your modified kernel image: - - Be sure your build environment is initialized: - Your environment should be set up since you previously sourced - the - &OE_INIT_FILE; - script. - If it is not, source the script again from poky. - - $ cd ~/poky - $ source &OE_INIT_FILE; - - - Clean up: - Be sure to clean the shared state out by using BitBake - to run from within the Build Directory the - do_cleansstate - task as follows: - - $ bitbake -c cleansstate linux-yocto - - - - Never remove any files by hand from the - tmp/deploy - directory inside the - Build Directory. - Always use the various BitBake clean tasks to - clear out previous build artifacts. - For information on the clean tasks, see the - "do_clean", - "do_cleanall", - and - "do_cleansstate" - sections all in the Yocto Project Reference - Manual. - - - Build the image: - Next, build the kernel image using this command: - - $ bitbake -k linux-yocto - - - -
- -
- Boot the Image and Verify Your Changes - - - These steps boot the image and allow you to see the changes - - Boot the image: - Boot the modified image in the QEMU emulator - using this command: - - $ runqemu qemux86 - - Verify the changes: - Log into the machine using root with no password and then - use the following shell command to scroll through the console's boot output. - - # dmesg | less - - You should see the results of your printk statements - as part of the output. - - -
-
-
Making Images More Secure 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 @@ See the "Creating and Preparing a Layer" section for some general resources. You can also see the - "Set Up Your Layer for the Build" section - of the Yocto Project Development Manual for a detailed - example. + "Set Up Your Layer for the Build" + section for a detailed example.
@@ -295,9 +294,10 @@ - For a detailed example showing how to patch the kernel, see the - "Patching the Kernel" - section in the Yocto Project Development Manual. + For a detailed example showing how to patch the kernel using + devtool, see the + "Using devtool to Patch the Kernel" + section.
@@ -449,6 +449,354 @@
+
+ Using <filename>devtool</filename> to Patch the Kernel + + + Patching the kernel involves changing or adding configurations to an existing kernel, + changing or adding recipes to the kernel that are needed to support specific hardware features, + or even altering the source code itself. + + You can use the yocto-kernel script + found in the Source Directory + under scripts to manage kernel patches and configuration. + See the "Managing kernel Patches and Config Items with yocto-kernel" + section in the Yocto Project Board Support Packages (BSP) Developer's Guide for + more information. + + + + This example creates a simple patch by adding some QEMU emulator console + output at boot time through printk statements in the kernel's + calibrate.c source code file. + Applying the patch and booting the modified image causes the added + messages to appear on the emulator's console. + + + + The example assumes a clean build exists for the qemux86 + machine in a + Source Directory + named poky. + Furthermore, the + Build Directory + is build and is located in + poky and the kernel is based on the + Linux 3.4 kernel. + + + + Also, for more information on patching the kernel, see the + "Applying Patches" + section. + + +
+ Create a Layer for your Changes + + + The first step is to create a layer so you can isolate your + changes. + Rather than use the yocto-layer script + to create the layer, this example steps through the process + by hand. + If you want information on the script that creates a general + layer, see the + "Creating a General Layer Using the yocto-layer Script" + section in the Yocto Project Development Manual. + + + + These two commands create a directory you can use for your + layer: + + $ cd ~/poky + $ mkdir meta-mylayer + + Creating a directory that follows the Yocto Project layer naming + conventions sets up the layer for your changes. + The layer is where you place your configuration files, append + files, and patch files. + To learn more about creating a layer and filling it with the + files you need, see the + "Understanding and Creating Layers" + section in the Yocto Project Development Manual. + +
+ +
+ Finding the Kernel Source Code + + + Each time you build a kernel image, the kernel source code + is fetched and unpacked into the following directory: + + ${S}/linux + + See the "Finding Temporary Source Code" + section in the Yocto Project Development Manual and the + S + variable for more information about where source is kept + during a build. + + + + For this example, we are going to patch the + init/calibrate.c file + by adding some simple console printk statements that we can + see when we boot the image using QEMU. + +
+ +
+ Creating the Patch + + + Two methods exist by which you can create the patch: + devtool + and + Quilt. + For kernel patches, the Git workflow is more appropriate. + This section assumes the Git workflow and shows the steps + specific to this example. + + + Change the working directory: + Change to where the kernel source code is before making + your edits to the calibrate.c file: + + $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux + + Because you are working in an established Git repository, + you must be in this directory in order to commit your changes + and create the patch file. + The PV and + PR variables + represent the version and revision for the + linux-yocto recipe. + The PV variable includes the Git meta and machine + hashes, which make the directory name longer than you might + expect. + + + Edit the source file: + Edit the init/calibrate.c file to have the + following changes: + + void calibrate_delay(void) + { + unsigned long lpj; + static bool printed; + int this_cpu = smp_processor_id(); + + printk("*************************************\n"); + printk("* *\n"); + printk("* HELLO YOCTO KERNEL *\n"); + printk("* *\n"); + printk("*************************************\n"); + + if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { + . + . + . + + Stage and commit your changes: + These Git commands display the modified file, stage it, and then + commit the file: + + $ git status + $ git add init/calibrate.c + $ git commit -m "calibrate: Add printk example" + + Generate the patch file: + This Git command creates the a patch file named + 0001-calibrate-Add-printk-example.patch + in the current directory. + + $ git format-patch -1 + + + + +
+ +
+ Set Up Your Layer for the Build + + These steps get your layer set up for the build: + + Create additional structure: + Create the additional layer structure: + + $ cd ~/poky/meta-mylayer + $ mkdir conf + $ mkdir recipes-kernel + $ mkdir recipes-kernel/linux + $ mkdir recipes-kernel/linux/linux-yocto + + The conf directory holds your configuration files, while the + recipes-kernel directory holds your append file and + your patch file. + Create the layer configuration file: + Move to the meta-mylayer/conf directory and create + the layer.conf file as follows: + + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have recipes-* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "mylayer" + BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" + BBFILE_PRIORITY_mylayer = "5" + + Notice mylayer as part of the last three + statements. + Create the kernel recipe append file: + Move to the meta-mylayer/recipes-kernel/linux directory and create + the linux-yocto_3.4.bbappend file as follows: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + SRC_URI += "file://0001-calibrate-Add-printk-example.patch" + + The FILESEXTRAPATHS + and SRC_URI + statements enable the OpenEmbedded build system to find the patch file. + For more information on using append files, see the + "Using .bbappend Files in Your Layer" + section in the Yocto Project Development Manual. + + + Put the patch file in your layer: + Move the 0001-calibrate-Add-printk-example.patch file to + the meta-mylayer/recipes-kernel/linux/linux-yocto + directory. + + +
+ +
+ Set Up for the Build + + + Do the following to make sure the build parameters are set up for the example. + Once you set up these build parameters, they do not have to change unless you + change the target architecture of the machine you are building: + + Build for the correct target architecture: Your + selected MACHINE + definition within the local.conf file in the + Build Directory + specifies the target architecture used when building the Linux kernel. + By default, MACHINE is set to + qemux86, which specifies a 32-bit + Intel Architecture + target machine suitable for the QEMU emulator. + Identify your meta-mylayer + layer: The + BBLAYERS + variable in the + bblayers.conf file found in the + poky/build/conf directory needs to have the path to your local + meta-mylayer layer. + By default, the BBLAYERS variable contains paths to + meta, meta-poky, and + meta-yocto-bsp in the + poky Git repository. + Add the path to your meta-mylayer location: + + BBLAYERS ?= " \ + $HOME/poky/meta \ + $HOME/poky/meta-poky \ + $HOME/poky/meta-yocto-bsp \ + $HOME/poky/meta-mylayer \ + " + + + +
+ +
+ Build the Modified QEMU Kernel Image + + + The following steps build your modified kernel image: + + Be sure your build environment is initialized: + Your environment should be set up since you previously sourced + the + &OE_INIT_FILE; + script. + If it is not, source the script again from poky. + + $ cd ~/poky + $ source &OE_INIT_FILE; + + + + Clean up: + Be sure to clean the shared state out by using BitBake + to run from within the Build Directory the + do_cleansstate + task as follows: + + $ bitbake -c cleansstate linux-yocto + + + + Never remove any files by hand from the + tmp/deploy + directory inside the + Build Directory. + Always use the various BitBake clean tasks to + clear out previous build artifacts. + For information on the clean tasks, see the + "do_clean", + "do_cleanall", + and + "do_cleansstate" + sections all in the Yocto Project Reference + Manual. + + + + Build the image: + Next, build the kernel image using this command: + + $ bitbake -k linux-yocto + + + +
+ +
+ Boot the Image and Verify Your Changes + + + These steps boot the image and allow you to see the changes + + Boot the image: + Boot the modified image in the QEMU emulator + using this command: + + $ runqemu qemux86 + + Verify the changes: + Log into the machine using root with no password and then + use the following shell command to scroll through the console's boot output. + + # dmesg | less + + You should see the results of your printk statements + as part of the output. + + +
+
+
Using an Iterative Development Process @@ -747,8 +1095,8 @@ "Applying Patches" section. If you are not familiar with generating patches, refer to the - "Creating the Patch" - section in the Yocto Project Development Manual. + "Creating the Patch" + 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 @@ "Yocto Linux Kernel Architecture and Branching Strategies" section. You can also reference the - "Patching the Kernel" - section in the Yocto Project Development Manual for a detailed - example that modifies the kernel. + "Using devtool to Patch the Kernel" + section for a detailed example that modifies the kernel. 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 @@ You can find additional information here: - "Patching the Kernel" - in the Yocto Project Development Manual. + The + "Using devtool to Patch the Kernel" + section. + The "Configuring the Kernel" - in the Yocto Project Development Manual. + section in the Yocto Project Development Manual. 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 @@ supported architecture, you can modify the kernel image before you build it. See the - "Patching the Kernel" - section in the Yocto Project Development - manual for an example. + "Using devtool to Patch the Kernel" + section in the Yocto Project Linux Kernel + Development Manual for an example. -- cgit v1.2.3-54-g00ecf