From 5d4b08853e8cd074d5bc1c81a6a2aef014ce10c4 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 8 Oct 2012 10:14:58 -0700 Subject: documentation: dev-manual, bsp-guide - Removing/Moving Appendix A The kernel example appendix is being removed. This broke a lot of links. For now I have moved the information into a new section called "Patching the Kernel". I have preserved the information by adding the old appendix file as kerne-appendix-orig.xml. (From yocto-docs rev: 994235a69362dfb0114ef9001ea7f2f2e2fdc5c3) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 559 +++++++++++++++++++++ .../dev-manual/dev-manual-kernel-appendix-orig.xml | 553 ++++++++++++++++++++ documentation/dev-manual/dev-manual-model.xml | 21 +- documentation/dev-manual/dev-manual.xml | 2 - 4 files changed, 1122 insertions(+), 13 deletions(-) create mode 100644 documentation/dev-manual/dev-manual-kernel-appendix-orig.xml (limited to 'documentation/dev-manual') 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 @@ - -