From bc02fb725ba1c33884c090462b61aaed6f71c79f Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 8 Oct 2012 10:18:03 -0700 Subject: documentation: dev-manual - removed Appendix A. The kernel example appendix is now gone. (From yocto-docs rev: d744e76034ff2711a8c40b9bb1982971d28a04b1) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-kernel-appendix.xml | 553 --------------------- 1 file changed, 553 deletions(-) delete mode 100644 documentation/dev-manual/dev-manual-kernel-appendix.xml (limited to 'documentation/dev-manual') diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml deleted file mode 100644 index 6ea77d030c..0000000000 --- a/documentation/dev-manual/dev-manual-kernel-appendix.xml +++ /dev/null @@ -1,553 +0,0 @@ - %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. - -
-
- - - -- cgit v1.2.3-54-g00ecf