diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 94595756b8..aa03d85c56 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -123,6 +123,19 @@
section in the Yocto Project Reference Manual.
+ Once you have completed the previous steps, you are ready to
+ continue using a given development path on your native Linux
+ machine.
+ If you are going to use BitBake, see the
+ "Cloning the poky Repository"
+ section.
+ If you are going to use the Extensible SDK, see the
+ "Using the Extensible SDK"
+ Chapter in the Yocto Project Software Development Kit (SDK)
+ Developer's Guide.
+ If you are going to use Toaster, see the
+ "Setting Up and Using Toaster"
+ section in the Toaster User Manual.
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index cb50912ea4..14381afefc 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -45,6 +45,67 @@
information.
+
+
+ Following is a detailed example showing how to create a layer
+ without the aid of tools for building the kernel:
+
+
+ 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.
+
+
@@ -72,11 +133,9 @@
Before modifying an existing recipe, be sure that you have created
a minimal, custom layer from which you can work.
- 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 for a detailed example.
+ See the
+ "Creating and Preparing a Layer"
+ section for information.
@@ -452,63 +511,51 @@
Using <filename>devtool</filename> to Patch the Kernel
-
- Some stuff here for the using devtool from the wiki.
- This whole section is WIP.
-
-
- If you are dealing with real hardware, you can flash the
- new kernel image to a USB stick and boot the hardware to
- see it run.
-
-
- Checkout and modify the kernel source.
- This is where you make your changes to the image.
-
-
- Create a new image that uses the altered kernel.
-
-
- If you are working with actual hardware, you can flash
- the new image to a USB stick and use it to boot up the
- hardware.
- You can see your changes in action.
-
-
+ This procedure currently does not work.
+ It is WIP.
- 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.
+ The steps in this procedure show you how you can patch the
+ kernel using the extensible SDK and devtool.
- You can use the yocto-kernel script
+ Before attempting this procedure, be sure you have performed
+ the steps to get ready for updating the kernel as described
+ in the
+ "Getting Ready to Develop Using devtool"
+ section.
+
+
+
+
+ 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 also 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.
+ 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.
+ 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 builds an extensible SDK, which is then used to
- build, using devtool, a clean image for the
- default qemux86 machine in a
- Source Directory
- named poky.
- In the example, the
- Build Directory
- is build and is located in the default
- poky_sdk directory.
+
+ The example is a continuation of the setup procedure found in
+ the
+ "Getting Ready to Develop using devtool"
+ Section.
+
@@ -517,159 +564,93 @@
section.
-
- Set Up the Build Host
-
-
- Prior to creating any actual patches for your kernel, you
- need to prepare the build host.
- This example builds an extensible SDK.
- Follow these steps:
-
-
- Set Up the Build Environment:
- Be sure you are set up to use BitBake in a shell.
- See the
- "Setting Up the Development Host to Use the Yocto Project"
- section in the Yocto Project Development Manual for information
- on how to get a build host ready that is either a native
- Linux machine or a machine that uses CROPS.
-
-
- Clone the poky Repository:
- You need to have a local copy of the Yocto Project
- Source Directory
- (i.e. a local poky repository).
- See the
- "Cloning the poky Repository"
- and possibly the
- "Checking Out by Branch in Poky"
- and
- "Checking Out by Tag in Poky"
- sections all in the Yocto Project Development Manual for
- information on how to clone the poky
- repository and check out the appropriate branch for your work.
-
-
- Initialize the Build Environment:
- While in the root directory of the Source Directory (i.e.
- poky), run the
- &OE_INIT_FILE;
- environment setup script to define the OpenEmbedded
- build environment on your build host.
-
- $ source &OE_INIT_FILE;
-
- Among other things, the script creates the
- Build Directory,
- which is build in this case
- and is located in the
- Source Directory.
- After the script runs, your current working directory
- is set to the build directory.
-
- For information on running a memory-resident
- BitBake,
- see the
- oe-init-build-env-memres
- setup script.
-
-
-
-
-
-
-
- Create a Layer for your Changes
-
-
- The first step is to create a layer so you can isolate your
- changes to the kernel.
- 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:
+
+
+ Check Out the Kernel Source Files:
+ First you must use devtool to checkout
+ the kernel source code in its workspace.
+ Be sure you are in the terminal set up to do work
+ with the extensible SDK.
+
+ See this
+ step
+ in the
+ "Getting Ready to Develop Using devtool"
+ section for more information.
+
+ Use the following devtool command
+ to check out the code:
- $ cd ~/poky
- $ mkdir meta-mylayer
+ $ devtool modify linux-yocto
+ Loading cache: 100% |#######################################################################| Time: 0:00:00
+ Loaded 1300 entries from dependency cache.
+ WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+ WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+ WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+
+ Summary: There was 1 WARNING message shown.
+ Loading cache: 100% |########################################################################| Time: 0:00:00
+ Loaded 1300 entries from dependency cache.
+ WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+ WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+ WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+
+ Summary: There was 1 WARNING message shown.
+ NOTE: Executing RunQueue Tasks
+ NOTE: Executing do_fetch...
+ NOTE: Executing do_unpack...
+ NOTE: Tasks Summary: Attempted 2 tasks of which 0 didn't need to be rerun and all succeeded.
+ NOTE: Executing RunQueue Tasks
+ NOTE: Executing do_kernel_checkout...
+ NOTE: Tasks Summary: Attempted 3 tasks of which 2 didn't need to be rerun and all succeeded.
+ NOTE: Patching...
+ NOTE: Executing RunQueue Tasks
+ NOTE: Executing do_validate_branches...
+ NOTE: Executing do_kernel_metadata...
+ NOTE: Executing do_patch...
+ NOTE: Tasks Summary: Attempted 6 tasks of which 3 didn't need to be rerun and all succeeded.
+ NOTE: Generating kernel config
+ NOTE: Executing RunQueue Tasks
+ NOTE: Executing do_kernel_configme...
+ NOTE: Executing do_prepare_recipe_sysroot...
+ NOTE: Executing do_configure...
+ NOTE: Tasks Summary: Attempted 9 tasks of which 6 didn't need to be rerun and all succeeded.
+ NOTE: Copying kernel config to srctree
+ NOTE: Source tree extracted to /home/scottrif/poky_sdk/workspace/sources/linux-yocto
+ NOTE: Recipe linux-yocto now set up to build from /home/scottrif/poky_sdk/workspace/sources/linux-yocto
- 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.
+
+ During the checkout operation, a bug exists that could
+ cause errors such as the following to appear:
+
+ ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
+ be3a89ce7c47178880ba7bf6293d7404 for
+ /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
+
+ You can safely ignore these messages.
+ The source code is correctly checked out.
+
+
+
+ Edit the Source Files
+ Follow these steps to make some simple changes to the source
+ files:
Change the working directory:
+ In the previous step, the output noted where you can find
+ the source files (e.g.
+ ~/poky_sdk/workspace/sources/linux-yocto).
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
+ $ cd ~/poky_sdk/workspace/sources/linux-yocto
- 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:
+ Edit the init/calibrate.c file to have
+ the following changes:
void calibrate_delay(void)
{
@@ -687,202 +668,239 @@
.
.
.
-
- 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
-
-
+
+
+ Build the Updated Kernel Source:
+ To build the updated kernel source, use
+ devtool:
+
+ $ devtool build linux-yocto
+ Parsing recipes: 100% |####################################################################################| Time: 0:00:31
+ Parsing of 831 .bb files complete (0 cached, 831 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors.
+ WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+ NOTE: There are 1 recipes to be removed from sysroot qemux86, removing...
+ NOTE: Resolving any missing task queue dependencies
+ Initialising tasks: 100% |#################################################################################| Time: 0:00:00
+ Checking sstate mirror object availability: 100% |#########################################################| Time: 0:00:00
+ NOTE: Executing SetScene Tasks
+ NOTE: Executing RunQueue Tasks
+ linux-yocto-4.10.17+git999-r0 do_compile: NOTE: linux-yocto: compiling from external source tree /home/scottrif/poky_sdk/workspace/sources/linux-yocto
+ NOTE: Tasks Summary: Attempted 471 tasks of which 454 didn't need to be rerun and all succeeded.
-
- Set Up Your Layer for the Build
+ Summary: There was 1 WARNING message shown.
+
+
+
+
+ Create the Image With the New Kernel:
+ Use the devtool build-image command
+ to create a new image that has the new kernel.
+
+ If the image you originally created resulted in a Wic
+ file, you can use an alternate method to create the new
+ image with the updated kernel.
+ For an example, see the steps in the
+ TipsAndTricks/KernelDevelopmentWithEsdk
+ Wiki Page.
+
+
+ $ cd ~
+ $ devtool build-image core-image-minimal
+ Loading cache: 100% |###########################################################################| Time: 0:00:00
+ Loaded 1299 entries from dependency cache.
+ Parsing recipes: 100% |#########################################################################| Time: 0:00:00
+ Parsing of 831 .bb files complete (830 cached, 1 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors.
+ WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+ WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+ WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
-
- Boot the Image and Verify Your Changes
+ Summary: There was 1 WARNING message shown.
+ WARNING: Skipping recipe linux-yocto as it doesn't produce a package with the same name
+ WARNING: No recipes in workspace, building image core-image-minimal unmodified
+ Loading cache: 100% |###########################################################################| Time: 0:00:00
+ Loaded 1299 entries from dependency cache.
+ Parsing recipes: 100% |#########################################################################| Time: 0:00:00
+ Parsing of 831 .bb files complete (830 cached, 1 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors.
+ WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+ NOTE: Resolving any missing task queue dependencies
+ Initialising tasks: 100% |######################################################################| Time: 0:00:06
+ Checking sstate mirror object availability: 100% |##############################################| Time: 0:00:00
+ NOTE: Executing SetScene Tasks
+ NOTE: Executing RunQueue Tasks
+ NOTE: Tasks Summary: Attempted 2393 tasks of which 2375 didn't need to be rerun and all succeeded.
-
- These steps boot the image and allow you to see the changes
+ Summary: There was 1 WARNING message shown.
+ NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86
+
+
+
+ Test the New Image:
+ For this example, you can run the new image using QEMU
+ to verify your changes:
- Boot the image:
+
+ 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.
+
+
+
+ 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.
+ You should see the results of your
+ printk statements
+ as part of the output when you scroll down the
+ console window.
+
-
-
+
+
+ Stage and commit your changes:
+ Within your eSDK terminal, change your working directory to
+ where you modified the calibrate.c
+ file and use these Git commands to stage and commit your
+ changes:
+
+ $ cd ~/poky_sdk/workspace/sources/linux-yocto
+ $ git status
+ $ git add init/calibrate.c
+ $ git commit -m "calibrate: Add printk example"
+
+
+
+ Export the Patches and Create a .bbappend:
+ To export your commits as patches and create a
+ .bbappend file, use the following
+ command in the terminal used to work with the extensible
+ SDK.
+ This example uses the previously established layer named
+ meta-my-kernel.
+
+ See Step 3 of the
+ "Getting Ready to Develop using devtool"
+ section for information on setting up this layer.
+
+
+ $ devtool finish linux-yocto /path/to/meta-my-kernel
+
+ Once the command finishes, the patches and the
+ .bbappend file are located in the
+ ~/meta-my-kernel/recipes-kernel/linux
+ directory.
+
+
+ Build the Image With Your Modified Kernel:
+ You can now build an image that includes your kernel
+ patches.
+ Execute the following command from your
+ Build Directory
+ in the terminal set up to run BitBake:
+
+ $ cd ~/poky/build
+ $ bitbake core-image-minimal
+
+
+
@@ -1174,7 +1192,7 @@
are very time consuming.
-
+
Once you are satisfied with your source code modifications,
you can make them permanent by generating patches and
applying them to the
@@ -1183,7 +1201,7 @@
"Applying Patches"
section.
If you are not familiar with generating patches, refer to the
- "Creating the Patch"
+ "I need a linked section here for the patch stuff"
section.
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index a2644aaa13..ce8e0fcb6d 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -108,6 +108,16 @@
"Cloning the poky Repository"
section in the Yocto Project Development Manual to set up your
Source Directory.
+
+ Be sure you check out the appropriate development branch or
+ by tag to get the version of Yocto Project you want.
+ See the
+ "Checking Out by Branch in Poky"
+ and
+ "Checking Out by Tag in Poky"
+ sections in the Yocto Project Development Manual for more
+ information.
+
@@ -156,7 +166,7 @@
building for the QEMU emulator in 32-bit mode.
However, if you are not, you need to set the
MACHINE variable appropriately in
- your local.conf file found in the
+ your conf/local.conf file found in the
Build Directory
(i.e. ~/poky/build in this example).
@@ -208,6 +218,7 @@
Use BitBake to build the extensible SDK specifically for
the Minnowboard:
+ $ cd ~/poky/build
$ bitbake core-image-minimal -c populate_sdk_ext
Once the build finishes, you can find the SDK installer
@@ -290,12 +301,9 @@
If you were building for actual hardware and not for
emulation, you could flash the image to a USB stick
on /dev/sdd and boot your device.
- Use a command similar to the following command to flash
- the image:
-
- $ sudo dd if=tmp/deploy/images/architecture/core-image-minimal-architecture.wic of=/dev/sdd bs=1MB
- $ sync
-
+ For an example that uses a Minnowboard, see the
+ TipsAndTricks/KernelDevelopmentWithEsdk
+ Wiki page.