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.