diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 7c63e4f24d..2fa016a969 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -618,10 +618,10 @@
meta branch for your BSP.
The configuration options will likely end up in that location anyway if the BSP gets
added to the Yocto Project.
- For a better understanding of working with a local clone of the kernel repository
+
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 918d884681..4ce0a94873 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1590,6 +1590,565 @@
+
+
+
+
+
+
+
+
+
+
+
+
+ Patching the Kernel
+
+
+ Kernel modification 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.
+ This appendix presents simple examples that modify the kernel source code,
+ change the kernel configuration, and add a kernel source recipe.
+
+ 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 adds some simple QEMU emulator console output at boot time by
+ adding printk statements to the kernel's
+ calibrate.c source code file.
+ Booting the modified image causes the added messages to appear on the emulator's
+ console.
+
+
+
+ Understanding the Files You Need
+
+
+ Before you modify the kernel, you need to know what Git repositories and file
+ structures you need.
+ Briefly, you need the following:
+
+ A local
+ Source Directory for the
+ poky Git repository
+ Local copies of the
+ poky-extras
+ Git repository placed within the Source Directory.
+ A bare clone of the
+ Yocto Project Kernel upstream Git
+ repository to which you want to push your modifications.
+
+ A copy of that bare clone in which you make your source
+ modifications
+
+
+
+
+ The following figure summarizes these four areas.
+ Within each rectangular that represents a data structure, a
+ host development directory pathname appears at the
+ lower left-hand corner of the box.
+ These pathnames are the locations used in this example.
+ The figure also provides key statements and commands used during the kernel
+ modification process:
+
+
+
+
+
+
+
+ Here is a brief description of the four areas:
+
+ Local Source Directory:
+ This area contains all the metadata that supports building images
+ using the OpenEmbedded build system.
+ In this example, the
+ Source Directory also
+ contains the
+ Build Directory,
+ which contains the configuration directory
+ that lets you control the build.
+ Also in this example, the Source Directory contains local copies of the
+ poky-extras Git repository.
+ See the bulleted item
+ "Yocto Project Release"
+ for information on how to get these files on your local system.
+ Local copies of the poky-extras Git Repository:
+ This area contains the meta-kernel-dev layer,
+ which is where you make changes that append the kernel build recipes.
+ You edit .bbappend files to locate your
+ local kernel source files and to identify the kernel being built.
+ This Git repository is a gathering place for extensions to the Yocto Project
+ (or really any) kernel recipes that faciliate the creation and development
+ of kernel features, BSPs or configurations.
+ See the bulleted item
+ "The
+ poky-extras Git Repository"
+ for information on how to get these files.
+ Bare Clone of the Yocto Project kernel:
+ This bare Git repository tracks the upstream Git repository of the Linux
+ Yocto kernel source code you are changing.
+ When you modify the kernel you must work through a bare clone.
+ All source code changes you make to the kernel must be committed and
+ pushed to the bare clone using Git commands.
+ As mentioned, the .bbappend file in the
+ poky-extras repository points to the bare clone
+ so that the build process can locate the locally changed source files.
+ See the bulleted item
+ "Yocto Project Kernel"
+ for information on how to set up the bare clone.
+
+ Copy of the Yocto Project Kernel Bare Clone:
+ This Git repository contains the actual source files that you modify.
+ Any changes you make to files in this location need to ultimately be pushed
+ to the bare clone using the git push command.
+ See the bulleted item
+ "Yocto Project Kernel"
+ for information on how to set up the bare clone.
+ Typically, Git workflows follow a scheme where changes made to a local area
+ are pulled into a Git repository.
+ However, because the git pull command does not work
+ with bare clones, this workflow pushes changes to the
+ repository even though you could use other more complicated methods to
+ get changes into the bare clone.
+
+
+
+
+
+
+ Setting Up the Local Source Directory
+
+
+ You can set up the
+ Source Directory
+ through tarball extraction or by
+ cloning the poky Git repository.
+ This example uses poky as the root directory of the
+ local Source Directory.
+ See the bulleted item
+ "Yocto Project Release"
+ for information on how to get these files.
+
+
+
+ Once you have Source Directory set up,
+ you have many development branches from which you can work.
+ From inside the local repository you can see the branch names and the tag names used
+ in the upstream Git repository by using either of the following commands:
+
+ $ cd poky
+ $ git branch -a
+ $ git tag -l
+
+ This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;",
+ which maps to the &DISTRO_NAME; branch in the repository.
+ The following commands create and checkout the local &DISTRO_NAME;
+ branch:
+
+ $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
+ Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
+ Switched to a new branch '&DISTRO_NAME;'
+
+
+
+
+
+ Setting Up the Local poky-extras Git Repository
+
+
+ This example creates a local copy of the poky-extras Git
+ repository inside the poky Source Directory.
+ See the bulleted item "The
+ poky-extras Git Repository"
+ for information on how to set up a local copy of the
+ poky-extras repository.
+
+
+
+ Because this example uses the Yocto Project &DISTRO; Release code
+ named "&DISTRO_NAME;", which maps to the &DISTRO_NAME;
+ branch in the repository, you need to be sure you are using that
+ branch for poky-extras.
+ The following commands create and checkout the local
+ branch you are using for the &DISTRO_NAME;
+ branch:
+
+ $ cd ~/poky/poky-extras
+ $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
+ Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
+ Switched to a new branch '&DISTRO_NAME;'
+
+
+
+
+
+ Setting Up the Bare Clone and its Copy
+
+
+ This example modifies the linux-yocto-3.4 kernel.
+ Thus, you need to create a bare clone of that kernel and then make a copy of the
+ bare clone.
+ See the bulleted item
+ "Yocto Project Kernel"
+ for information on how to do that.
+
+
+
+ The bare clone exists for the kernel build tools and simply as the receiving end
+ of git push
+ commands after you make edits and commits inside the copy of the clone.
+ The copy (my-linux-yocto-3.4-work in this example) has to have
+ a local branch created and checked out for your work.
+ This example uses common-pc-base as the local branch.
+ The following commands create and checkout the branch:
+
+ $ cd ~/my-linux-yocto-3.4-work
+ $ git checkout -b standard-common-pc-base origin/standard/common-pc/base
+ Branch standard-common-pc-base set up to track remote branch
+ standard/common-pc/base from origin.
+ Switched to a new branch 'standard-common-pc-base'
+
+
+
+
+
+ Building and Booting the Default QEMU Kernel Image
+
+
+ Before we make changes to the kernel source files, this example first builds the
+ default image and then boots it inside the QEMU emulator.
+
+ Because a full build can take hours, you should check two variables in the
+ build directory that is created after you source the
+ &OE_INIT_FILE; script.
+ You can find these variables
+ BB_NUMBER_THREADS and PARALLEL_MAKE
+ in the build/conf directory in the
+ local.conf configuration file.
+ By default, these variables are commented out.
+ If your host development system supports multi-core and multi-thread capabilities,
+ you can uncomment these statements and set the variables to significantly shorten
+ the full build time.
+ As a guideline, set both BB_NUMBER_THREADS and
+ PARALLEL_MAKE to twice the number
+ of cores your machine supports.
+
+ The following two commands source the build environment setup script
+ and build the default qemux86 image.
+ If necessary, the script creates the build directory:
+
+ $ cd ~/poky
+ $ source &OE_INIT_FILE;
+ You had no conf/local.conf file. This configuration file has therefore been
+ created for you with some default values. You may wish to edit it to use a
+ different MACHINE (target hardware) or enable parallel build options to take
+ advantage of multiple cores for example. See the file for more information as
+ common configuration options are commented.
+
+ The Yocto Project has extensive documentation about OE including a reference manual
+ which can be found at:
+ http://yoctoproject.org/documentation
+
+ For more information about OpenEmbedded see their website:
+ http://www.openembedded.org/
+
+ You had no conf/bblayers.conf file. The configuration file has been created for
+ you with some default values. To add additional metadata layers into your
+ configuration please add entries to this file.
+
+ The Yocto Project has extensive documentation about OE including a reference manual
+ which can be found at:
+ http://yoctoproject.org/documentation
+
+ For more information about OpenEmbedded see their website:
+ http://www.openembedded.org/
+
+
+
+ ### Shell environment set up for builds. ###
+
+ You can now run 'bitbake <target>>'
+
+ Common targets are:
+ core-image-minimal
+ core-image-sato
+ meta-toolchain
+ meta-toolchain-sdk
+ adt-installer
+ meta-ide-support
+
+ You can also run generated qemu images with a command like 'runqemu qemux86'
+
+
+
+
+ The following bitbake command starts the build:
+
+ $ bitbake -k core-image-minimal
+
+ Be sure to check the settings in the local.conf
+ before starting the build.
+
+
+
+ After the build completes, you can start the QEMU emulator using the resulting image
+ qemux86 as follows:
+
+ $ runqemu qemux86
+
+
+
+
+ As the image boots in the emulator, console message and status output appears
+ across the terminal window.
+ Because the output scrolls by quickly, it is difficult to read.
+ To examine the output, you log into the system using the
+ login root with no password.
+ Once you are logged in, issue the following command to scroll through the
+ console output:
+
+ # dmesg | less
+
+
+
+
+ Take note of the output as you will want to look for your inserted print command output
+ later in the example.
+
+
+
+
+ Changing the Source Code and Pushing it to the Bare Clone
+
+
+ The file you change in this example is named calibrate.c
+ and is located in the my-linux-yocto-3.4-work Git repository
+ (the copy of the bare clone) in init.
+ This example simply inserts several printk statements
+ at the beginning of the calibrate_delay function.
+
+
+
+ Here is the unaltered code at the start of this function:
+
+ void __cpuinit calibrate_delay(void)
+ {
+ unsigned long lpj;
+ static bool printed;
+ int this_cpu = smp_processor_id();
+
+ if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
+ .
+ .
+ .
+
+
+
+
+ Here is the altered code showing five new printk statements
+ near the top of the function:
+
+ void __cpuinit 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)) {
+ .
+ .
+ .
+
+
+
+
+ After making and saving your changes, you need to stage them for the push.
+ The following Git commands are one method of staging and committing your changes:
+
+ $ git add calibrate.c
+ $ git commit --signoff
+
+
+
+
+ Once the source code has been modified, you need to use Git to push the changes to
+ the bare clone.
+ If you do not push the changes, then the OpenEmbedded build system will not pick
+ up the changed source files.
+
+
+
+ The following command pushes the changes to the bare clone:
+
+ $ git push origin standard-common-pc-base:standard/default/common-pc/base
+
+
+
+
+
+ Changing Build Parameters for Your Build
+
+
+ At this point, the source has been changed and pushed.
+ The example now defines some variables used by the OpenEmbedded build system
+ to locate your kernel source.
+ You essentially need to identify where to find the kernel recipe and the changed source code.
+ You also need to be sure some basic configurations are in place that identify the
+ type of machine you are building and to help speed up the build should your host support
+ multiple-core and thread capabilities.
+
+
+
+ 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 or you move
+ the bare clone, copy of the clone, or the poky-extras repository:
+
+ Build for the Correct Target Architecture: The
+ local.conf file in the build directory defines the build's
+ target architecture.
+ By default, MACHINE is set to
+ qemux86, which specifies a 32-bit
+ Intel Architecture
+ target machine suitable for the QEMU emulator.
+ In this example, MACHINE is correctly configured.
+
+ Optimize Build Time: Also in the
+ local.conf file are two variables that can speed your
+ build time if your host supports multi-core and multi-thread capabilities:
+ BB_NUMBER_THREADS and PARALLEL_MAKE.
+ If the host system has multiple cores then you can optimize build time
+ by setting both these variables to twice the number of
+ cores.
+ Identify Your meta-kernel-dev
+ 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-kernel-dev layer.
+ By default, the BBLAYERS variable contains paths to
+ meta and meta-yocto in the
+ poky Git repository.
+ Add the path to your meta-kernel-dev location.
+ Be sure to substitute your user information in the statement.
+ Here is an example:
+
+ BBLAYERS = " \
+ /home/scottrif/poky/meta \
+ /home/scottrif/poky/meta-yocto \
+ /home/scottrif/poky/meta-yocto-bsp \
+ /home/scottrif/poky/poky-extras/meta-kernel-dev \
+ "
+
+ Identify Your Source Files: In the
+ linux-yocto_3.4.bbappend file located in the
+ poky-extras/meta-kernel-dev/recipes-kernel/linux
+ directory, you need to identify the location of the
+ local source code, which in this example is the bare clone named
+ linux-yocto-3.4.git.
+ To do this, set the KSRC_linux_yocto variable to point to your
+ local linux-yocto-3.4.git Git repository by adding the
+ following statement.
+ Also, be sure the SRC_URI variable is pointing to
+ your kernel source files by removing the comment.
+ Finally, be sure to substitute your user information in the statement:
+
+ KSRC_linux_yocto_3_4 ?= "/home/scottrif/linux-yocto-3.4.git"
+ SRC_URI = "git://${KSRC_linux_yocto_3_4};protocol=file;nocheckout=1;branch=${KBRANCH},meta;name=machine,meta"
+
+
+
+
+
+ Before attempting to build the modified kernel, there is one more set of changes you
+ need to make in the meta-kernel-dev layer.
+ Because all the kernel .bbappend files are parsed during the
+ build process regardless of whether you are using them or not, you should either
+ comment out the COMPATIBLE_MACHINE statements in all
+ unused .bbappend files, or simply remove (or rename) all the files
+ except the one your are using for the build
+ (i.e. linux-yocto_3.4.bbappend in this example).
+ If you do not make one of these two adjustments, your machine will be compatible
+ with all the kernel recipes in the meta-kernel-dev layer.
+ When your machine is comapatible with all the kernel recipes, the build attempts
+ to build all kernels in the layer.
+ You could end up with build errors blocking your work.
+
+
+
+
+ Building and Booting the Modified QEMU Kernel Image
+
+
+ Next, you need to build the modified image.
+ Do the following:
+
+ Your environment should be set up since you previously sourced
+ the &OE_INIT_FILE; script.
+ If it isn't, source the script again from poky.
+
+ $ cd ~/poky
+ $ source &OE_INIT_FILE;
+
+
+ Be sure old images are cleaned out by running the
+ cleanall BitBake task as follows from your build directory:
+
+ $ bitbake -c cleanall linux-yocto
+
+ Never remove any files by hand from the tmp/deploy
+ directory insided the build directory.
+ Always use the BitBake cleanall task to clear
+ out previous builds.
+ Next, build the kernel image using this command:
+
+ $ bitbake -k core-image-minimal
+
+ Finally, boot the modified image in the QEMU emulator
+ using this command:
+
+ $ runqemu qemux86
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
Updating Existing Images
diff --git a/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml b/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml
new file mode 100644
index 0000000000..6ea77d030c
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml
@@ -0,0 +1,553 @@
+ %poky; ] >
+
+
+
+Kernel Modification Example
+
+
+ Kernel modification 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.
+ This appendix presents simple examples that modify the kernel source code,
+ change the kernel configuration, and add a kernel source recipe.
+
+ 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.
+
+
+
+ Modifying the Kernel Source Code
+
+
+ This example adds some simple QEMU emulator console output at boot time by
+ adding printk statements to the kernel's
+ calibrate.c source code file.
+ Booting the modified image causes the added messages to appear on the emulator's
+ console.
+
+
+
+ Understanding the Files You Need
+
+
+ Before you modify the kernel, you need to know what Git repositories and file
+ structures you need.
+ Briefly, you need the following:
+
+ A local
+ Source Directory for the
+ poky Git repository
+ Local copies of the
+ poky-extras
+ Git repository placed within the Source Directory.
+ A bare clone of the
+ Yocto Project Kernel upstream Git
+ repository to which you want to push your modifications.
+
+ A copy of that bare clone in which you make your source
+ modifications
+
+
+
+
+ The following figure summarizes these four areas.
+ Within each rectangular that represents a data structure, a
+ host development directory pathname appears at the
+ lower left-hand corner of the box.
+ These pathnames are the locations used in this example.
+ The figure also provides key statements and commands used during the kernel
+ modification process:
+
+
+
+
+
+
+
+ Here is a brief description of the four areas:
+
+ Local Source Directory:
+ This area contains all the metadata that supports building images
+ using the OpenEmbedded build system.
+ In this example, the
+ Source Directory also
+ contains the
+ Build Directory,
+ which contains the configuration directory
+ that lets you control the build.
+ Also in this example, the Source Directory contains local copies of the
+ poky-extras Git repository.
+ See the bulleted item
+ "Yocto Project Release"
+ for information on how to get these files on your local system.
+ Local copies of the poky-extras Git Repository:
+ This area contains the meta-kernel-dev layer,
+ which is where you make changes that append the kernel build recipes.
+ You edit .bbappend files to locate your
+ local kernel source files and to identify the kernel being built.
+ This Git repository is a gathering place for extensions to the Yocto Project
+ (or really any) kernel recipes that faciliate the creation and development
+ of kernel features, BSPs or configurations.
+ See the bulleted item
+ "The
+ poky-extras Git Repository"
+ for information on how to get these files.
+ Bare Clone of the Yocto Project kernel:
+ This bare Git repository tracks the upstream Git repository of the Linux
+ Yocto kernel source code you are changing.
+ When you modify the kernel you must work through a bare clone.
+ All source code changes you make to the kernel must be committed and
+ pushed to the bare clone using Git commands.
+ As mentioned, the .bbappend file in the
+ poky-extras repository points to the bare clone
+ so that the build process can locate the locally changed source files.
+ See the bulleted item
+ "Yocto Project Kernel"
+ for information on how to set up the bare clone.
+
+ Copy of the Yocto Project Kernel Bare Clone:
+ This Git repository contains the actual source files that you modify.
+ Any changes you make to files in this location need to ultimately be pushed
+ to the bare clone using the git push command.
+ See the bulleted item
+ "Yocto Project Kernel"
+ for information on how to set up the bare clone.
+ Typically, Git workflows follow a scheme where changes made to a local area
+ are pulled into a Git repository.
+ However, because the git pull command does not work
+ with bare clones, this workflow pushes changes to the
+ repository even though you could use other more complicated methods to
+ get changes into the bare clone.
+
+
+
+
+
+
+ Setting Up the Local Source Directory
+
+
+ You can set up the
+ Source Directory
+ through tarball extraction or by
+ cloning the poky Git repository.
+ This example uses poky as the root directory of the
+ local Source Directory.
+ See the bulleted item
+ "Yocto Project Release"
+ for information on how to get these files.
+
+
+
+ Once you have Source Directory set up,
+ you have many development branches from which you can work.
+ From inside the local repository you can see the branch names and the tag names used
+ in the upstream Git repository by using either of the following commands:
+
+ $ cd poky
+ $ git branch -a
+ $ git tag -l
+
+ This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;",
+ which maps to the &DISTRO_NAME; branch in the repository.
+ The following commands create and checkout the local &DISTRO_NAME;
+ branch:
+
+ $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
+ Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
+ Switched to a new branch '&DISTRO_NAME;'
+
+
+
+
+
+ Setting Up the Local poky-extras Git Repository
+
+
+ This example creates a local copy of the poky-extras Git
+ repository inside the poky Source Directory.
+ See the bulleted item "The
+ poky-extras Git Repository"
+ for information on how to set up a local copy of the
+ poky-extras repository.
+
+
+
+ Because this example uses the Yocto Project &DISTRO; Release code
+ named "&DISTRO_NAME;", which maps to the &DISTRO_NAME;
+ branch in the repository, you need to be sure you are using that
+ branch for poky-extras.
+ The following commands create and checkout the local
+ branch you are using for the &DISTRO_NAME;
+ branch:
+
+ $ cd ~/poky/poky-extras
+ $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
+ Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
+ Switched to a new branch '&DISTRO_NAME;'
+
+
+
+
+
+ Setting Up the Bare Clone and its Copy
+
+
+ This example modifies the linux-yocto-3.4 kernel.
+ Thus, you need to create a bare clone of that kernel and then make a copy of the
+ bare clone.
+ See the bulleted item
+ "Yocto Project Kernel"
+ for information on how to do that.
+
+
+
+ The bare clone exists for the kernel build tools and simply as the receiving end
+ of git push
+ commands after you make edits and commits inside the copy of the clone.
+ The copy (my-linux-yocto-3.4-work in this example) has to have
+ a local branch created and checked out for your work.
+ This example uses common-pc-base as the local branch.
+ The following commands create and checkout the branch:
+
+ $ cd ~/my-linux-yocto-3.4-work
+ $ git checkout -b standard-common-pc-base origin/standard/common-pc/base
+ Branch standard-common-pc-base set up to track remote branch
+ standard/common-pc/base from origin.
+ Switched to a new branch 'standard-common-pc-base'
+
+
+
+
+
+ Building and Booting the Default QEMU Kernel Image
+
+
+ Before we make changes to the kernel source files, this example first builds the
+ default image and then boots it inside the QEMU emulator.
+
+ Because a full build can take hours, you should check two variables in the
+ build directory that is created after you source the
+ &OE_INIT_FILE; script.
+ You can find these variables
+ BB_NUMBER_THREADS and PARALLEL_MAKE
+ in the build/conf directory in the
+ local.conf configuration file.
+ By default, these variables are commented out.
+ If your host development system supports multi-core and multi-thread capabilities,
+ you can uncomment these statements and set the variables to significantly shorten
+ the full build time.
+ As a guideline, set both BB_NUMBER_THREADS and
+ PARALLEL_MAKE to twice the number
+ of cores your machine supports.
+
+ The following two commands source the build environment setup script
+ and build the default qemux86 image.
+ If necessary, the script creates the build directory:
+
+ $ cd ~/poky
+ $ source &OE_INIT_FILE;
+ You had no conf/local.conf file. This configuration file has therefore been
+ created for you with some default values. You may wish to edit it to use a
+ different MACHINE (target hardware) or enable parallel build options to take
+ advantage of multiple cores for example. See the file for more information as
+ common configuration options are commented.
+
+ The Yocto Project has extensive documentation about OE including a reference manual
+ which can be found at:
+ http://yoctoproject.org/documentation
+
+ For more information about OpenEmbedded see their website:
+ http://www.openembedded.org/
+
+ You had no conf/bblayers.conf file. The configuration file has been created for
+ you with some default values. To add additional metadata layers into your
+ configuration please add entries to this file.
+
+ The Yocto Project has extensive documentation about OE including a reference manual
+ which can be found at:
+ http://yoctoproject.org/documentation
+
+ For more information about OpenEmbedded see their website:
+ http://www.openembedded.org/
+
+
+
+ ### Shell environment set up for builds. ###
+
+ You can now run 'bitbake <target>>'
+
+ Common targets are:
+ core-image-minimal
+ core-image-sato
+ meta-toolchain
+ meta-toolchain-sdk
+ adt-installer
+ meta-ide-support
+
+ You can also run generated qemu images with a command like 'runqemu qemux86'
+
+
+
+
+ The following bitbake command starts the build:
+
+ $ bitbake -k core-image-minimal
+
+ Be sure to check the settings in the local.conf
+ before starting the build.
+
+
+
+ After the build completes, you can start the QEMU emulator using the resulting image
+ qemux86 as follows:
+
+ $ runqemu qemux86
+
+
+
+
+ As the image boots in the emulator, console message and status output appears
+ across the terminal window.
+ Because the output scrolls by quickly, it is difficult to read.
+ To examine the output, you log into the system using the
+ login root with no password.
+ Once you are logged in, issue the following command to scroll through the
+ console output:
+
+ # dmesg | less
+
+
+
+
+ Take note of the output as you will want to look for your inserted print command output
+ later in the example.
+
+
+
+
+ Changing the Source Code and Pushing it to the Bare Clone
+
+
+ The file you change in this example is named calibrate.c
+ and is located in the my-linux-yocto-3.4-work Git repository
+ (the copy of the bare clone) in init.
+ This example simply inserts several printk statements
+ at the beginning of the calibrate_delay function.
+
+
+
+ Here is the unaltered code at the start of this function:
+
+ void __cpuinit calibrate_delay(void)
+ {
+ unsigned long lpj;
+ static bool printed;
+ int this_cpu = smp_processor_id();
+
+ if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
+ .
+ .
+ .
+
+
+
+
+ Here is the altered code showing five new printk statements
+ near the top of the function:
+
+ void __cpuinit 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)) {
+ .
+ .
+ .
+
+
+
+
+ After making and saving your changes, you need to stage them for the push.
+ The following Git commands are one method of staging and committing your changes:
+
+ $ git add calibrate.c
+ $ git commit --signoff
+
+
+
+
+ Once the source code has been modified, you need to use Git to push the changes to
+ the bare clone.
+ If you do not push the changes, then the OpenEmbedded build system will not pick
+ up the changed source files.
+
+
+
+ The following command pushes the changes to the bare clone:
+
+ $ git push origin standard-common-pc-base:standard/default/common-pc/base
+
+
+
+
+
+ Changing Build Parameters for Your Build
+
+
+ At this point, the source has been changed and pushed.
+ The example now defines some variables used by the OpenEmbedded build system
+ to locate your kernel source.
+ You essentially need to identify where to find the kernel recipe and the changed source code.
+ You also need to be sure some basic configurations are in place that identify the
+ type of machine you are building and to help speed up the build should your host support
+ multiple-core and thread capabilities.
+
+
+
+ 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 or you move
+ the bare clone, copy of the clone, or the poky-extras repository:
+
+ Build for the Correct Target Architecture: The
+ local.conf file in the build directory defines the build's
+ target architecture.
+ By default, MACHINE is set to
+ qemux86, which specifies a 32-bit
+ Intel Architecture
+ target machine suitable for the QEMU emulator.
+ In this example, MACHINE is correctly configured.
+
+ Optimize Build Time: Also in the
+ local.conf file are two variables that can speed your
+ build time if your host supports multi-core and multi-thread capabilities:
+ BB_NUMBER_THREADS and PARALLEL_MAKE.
+ If the host system has multiple cores then you can optimize build time
+ by setting both these variables to twice the number of
+ cores.
+ Identify Your meta-kernel-dev
+ 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-kernel-dev layer.
+ By default, the BBLAYERS variable contains paths to
+ meta and meta-yocto in the
+ poky Git repository.
+ Add the path to your meta-kernel-dev location.
+ Be sure to substitute your user information in the statement.
+ Here is an example:
+
+ BBLAYERS = " \
+ /home/scottrif/poky/meta \
+ /home/scottrif/poky/meta-yocto \
+ /home/scottrif/poky/meta-yocto-bsp \
+ /home/scottrif/poky/poky-extras/meta-kernel-dev \
+ "
+
+ Identify Your Source Files: In the
+ linux-yocto_3.4.bbappend file located in the
+ poky-extras/meta-kernel-dev/recipes-kernel/linux
+ directory, you need to identify the location of the
+ local source code, which in this example is the bare clone named
+ linux-yocto-3.4.git.
+ To do this, set the KSRC_linux_yocto variable to point to your
+ local linux-yocto-3.4.git Git repository by adding the
+ following statement.
+ Also, be sure the SRC_URI variable is pointing to
+ your kernel source files by removing the comment.
+ Finally, be sure to substitute your user information in the statement:
+
+ KSRC_linux_yocto_3_4 ?= "/home/scottrif/linux-yocto-3.4.git"
+ SRC_URI = "git://${KSRC_linux_yocto_3_4};protocol=file;nocheckout=1;branch=${KBRANCH},meta;name=machine,meta"
+
+
+
+
+
+ Before attempting to build the modified kernel, there is one more set of changes you
+ need to make in the meta-kernel-dev layer.
+ Because all the kernel .bbappend files are parsed during the
+ build process regardless of whether you are using them or not, you should either
+ comment out the COMPATIBLE_MACHINE statements in all
+ unused .bbappend files, or simply remove (or rename) all the files
+ except the one your are using for the build
+ (i.e. linux-yocto_3.4.bbappend in this example).
+ If you do not make one of these two adjustments, your machine will be compatible
+ with all the kernel recipes in the meta-kernel-dev layer.
+ When your machine is comapatible with all the kernel recipes, the build attempts
+ to build all kernels in the layer.
+ You could end up with build errors blocking your work.
+
+
+
+
+ Building and Booting the Modified QEMU Kernel Image
+
+
+ Next, you need to build the modified image.
+ Do the following:
+
+ Your environment should be set up since you previously sourced
+ the &OE_INIT_FILE; script.
+ If it isn't, source the script again from poky.
+
+ $ cd ~/poky
+ $ source &OE_INIT_FILE;
+
+
+ Be sure old images are cleaned out by running the
+ cleanall BitBake task as follows from your build directory:
+
+ $ bitbake -c cleanall linux-yocto
+
+ Never remove any files by hand from the tmp/deploy
+ directory insided the build directory.
+ Always use the BitBake cleanall task to clear
+ out previous builds.
+ Next, build the kernel image using this command:
+
+ $ bitbake -k core-image-minimal
+
+ Finally, boot the modified image in the QEMU emulator
+ using this command:
+
+ $ runqemu qemux86
+
+
+
+
+
+ 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.
+
+
+
+
+
+
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 844e0dc851..c96b2dda63 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -13,9 +13,6 @@
System Development:
System Development covers Board Support Package (BSP) development and kernel
modification or configuration.
- If you want to examine a specific example of the kernel modification and
- configuration model,
- see the "Kernel Modification Example" appendix.
For an example on how to create a BSP, see the
"Creating a New BSP Layer Using the yocto-bsp Script"
section in the Yocto Project Board Support Package (BSP) Developer's Guide.
@@ -234,9 +231,11 @@
kernel architecture and the steps to modify the kernel.
For a complete discussion of the kernel, see the
Yocto Project Kernel Architecture and Use Manual.
- You can reference the appendix
- "Kernel Modification Example"
- for a detailed example that changes the configuration of a kernel.
+ You can reference the
+ "Patching the Kernel" section
+ for an example that changes the source code of the kernel.
+ For information on how to configure the kernel, see the
+ "Configuring the Kernel section.
@@ -364,8 +363,8 @@
you work.
Once you make corrections, you must use Git to push the committed changes to the
bare clone.
- The example in
- Modifying the Kernel Source Code provides a detailed example.
+
@@ -394,7 +393,7 @@
branching strategy, see the
Yocto Project Kernel Architecture and Use Manual.
You can also reference the
- "Modifying the Kernel Source Code"
+ "Patching the Kernel"
section for a detailed example that modifies the kernel.
@@ -602,8 +601,8 @@
If your target architecture is similar to a supported architecture, you can
modify the kernel image before you build it.
See the
- "Kernel Modification Example"
- appendix later in this manual for an example.
+ "Patching the Kernel"
+ section for an example.
For information on pre-built kernel image naming schemes for images
that can run on the QEMU emulator, see the
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
index a5856e0995..eff0dce1f0 100644
--- a/documentation/dev-manual/dev-manual.xml
+++ b/documentation/dev-manual/dev-manual.xml
@@ -80,8 +80,6 @@
-
-