From 57746012d0dbe2b2aa02321284eaf82b732c18b5 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 4 Oct 2011 06:54:04 -0700 Subject: documentation/dev-manual/dev-manual-kernel-appendix.xml: general updates I made a pass through the book to clean up all areas in preparation to running the examples again. Most changes were punctuation, manual section reference formats, and wordings. (From yocto-docs rev: 0d054f79c82ddc204938dea187312d1a80d0a2e1) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-kernel-appendix.xml | 148 ++++++++++----------- 1 file changed, 71 insertions(+), 77 deletions(-) (limited to 'documentation/dev-manual/dev-manual-kernel-appendix.xml') diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml index 2fb761a7fb..b6f8e39fe6 100644 --- a/documentation/dev-manual/dev-manual-kernel-appendix.xml +++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml @@ -47,7 +47,7 @@ The poky-extras Git repository placed within the local Yocto Project files Git repository A bare clone of the Linux Yocto kernel upstream Git - repository that you want to modify + repository to which you want to push your modifications. A copy of that bare clone in which you make your source modifcations @@ -56,9 +56,10 @@ The following figure summarizes these four areas. - Within each rectangular that represents a data structure an URL appears at the + Within each rectangular that represents a data structure, a + host development directory pathname appears at the lower left-hand corner of the box. - These URLs are the locations used in this example. + These pathnames are the locations used in this example. The figure also provides key statements and commands used during the kernel modification process: @@ -74,13 +75,12 @@ Local Yocto Project Files Git Repository: This area contains all the metadata that supports building images in the Yocto Project build environment - the local Yocto Project files. - The Local Yocto Project files Git repository also contains the build directory + The local Yocto Project files Git repository also contains the build directory and a configuration directory that let you control the build. - Note also that in this example the repository also contains the + Note also that in this example, the repository also contains the poky-extras Git repository. See the bulleted item - Yocto Project Release in - Getting Setup earlier in this manual + "Yocto Project Release" for information on how to get these files. poky-extras Git Repository: This area contains the meta-kernel-dev layer, @@ -91,9 +91,8 @@ (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 in - Getting Setup earlier in this manual + "The + poky-extras Git Repository" for information on how to get these files. Bare Clone of the Linux Yocto kernel: This bare Git repository tracks the upstream Git repository of the Linux @@ -105,8 +104,7 @@ poky-extras repository points to the bare clone so that the build process can locate the locally changed source files. See the bulleted item - Linux Yocto Kernel in - Getting Setup earlier in this manual + "Linux Yocto Kernel" for information on how to set up the bare clone. Copy of the Linux Yocto Kernel Bare Clone: @@ -114,13 +112,13 @@ 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 - "Linux Yocto Kernel" earlier in this manual + "Linux Yocto 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 other more complicated methods do exist that + repository even though you could use other more complicated methods to get changes into the bare clone. @@ -136,8 +134,7 @@ This example uses poky as the root directory of the local Yocto Project files Git repository. See the bulleted item - Yocto Project Release in - Getting Setup earlier in this manual + "Yocto Project Release" for information on how to get these files. @@ -151,14 +148,14 @@ $ git branch -a $ git tag -l - This example uses the Yocto Project 1.1_M3 Release, - which maps to the 1.1_M3 branch in the repository. - The following commands create and checkout the local 1.1_M3 + This example uses the Yocto Project 1.1 Release code named "edison", + which maps to the edison branch in the repository. + The following commands create and checkout the local edison branch: - $ git checkout -b 1.1_M3 origin/1.1_M3 - Branch 1.1_M3 set up to track remote branch 1.1_M3 from origin. - Switched to a new branch '1.1_M3' + $ git checkout -b edison origin/edison + Branch edison set up to track remote branch edison from origin. + Switched to a new branch 'edison' @@ -170,9 +167,8 @@ This example places the poky-extras Git repository inside of poky. See the bulleted item - The - poky-extras Git Repository in - Getting Setup earlier in this manual + "The + poky-extras Git Repository" for information on how to get the poky-extras repository. @@ -185,8 +181,7 @@ Thus, you need to create a bare clone of that kernel and then make a copy of the bare clone. See the bulleted item - Linux Yocto Kernel in - Getting Setup earlier in this manual + "Linux Yocto Kernel" for information on how to do that. @@ -230,7 +225,9 @@ of cores your machine supports and set PARALLEL_MAKE to one and a half times the number of cores your machine supports. - The following commands build the default qemux86 image: + The following two commands build the default qemux86 image and + source build environment setup script. + If necessary, the script creates the build directory: $ cd ~/poky $ source oe-init-build-env @@ -248,15 +245,14 @@ meta-ide-support You can also run generated qemu images with a command like 'runqemu qemux86' - - $ bitbake -k core-image-minimal - The source command sets up the build environment and, - if necessary, creates the build directory. - The following bitbake command starts the build. + 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. @@ -380,15 +376,16 @@ 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 + 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 + 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 + 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. @@ -397,7 +394,7 @@ cores and setting PARALLEL_MAKE to one and a half times the number of cores. Identify Your meta-kernel-dev - Layer - The BBLAYERS variable in the + 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. @@ -414,7 +411,7 @@ /home/scottrif/poky/poky-extras/meta-kernel-dev \ " - Identify Your Source Files - In the + Identify Your Source Files: In the linux-yocto_3.0.bbappend file located in the poky-extras/meta-kernel-dev/recipes-kernel/linux directory, you need to identify the location of the @@ -427,7 +424,7 @@ KSRC_linux_yocto ?= /home/scottrif/linux-yocto-3.0.git - Specify the Kernel Machine - Also in the + Specify the Kernel Machine: Also in the linux-yocto_3.0.bbappend file, you need to specify the kernel machine with the following statement: @@ -457,14 +454,14 @@ Your environment should be set up since you previously sourced the oe-init-build-env script. - If it isn't, source the script again from poky + If it isn't, source the script again from poky. Be sure old images are cleaned out by running the cleanall BitBake task as follows: $ bitbake -c cleanall linux-yocto - Never remove by hand any files from the tmp/deploy + Never remove any files by hand from the tmp/deploy directory insided the local Yocto Project files build directory. Always use the BitBake cleanall task to clear out previous builds. @@ -472,14 +469,12 @@ $ bitbake -k core-image-minimal - - - - - Finally, boot the modified image in the QEMU emulator using this command: - + Finally, boot the modified image in the QEMU emulator + using this command: + $ runqemu qemux86 - + + @@ -501,8 +496,8 @@ Changing the Kernel Configuration - This example changes the default behavior (off) of the Symmetric Multi-processing Support - (CONFIG_SMP) to on. + This example changes the default behavior, which is "off", of the Symmetric + Multi-processing Support (CONFIG_SMP) to "on". It is a simple example that demonstrates how to reconfigure the kernel. @@ -511,31 +506,29 @@ If you took the time to work through the example that modifies the kernel source code - in Modifying the Kernel Source - Code you are set up to quickly work through this example. + in "Modifying the Kernel Source + Code" you are already set up to quickly work through this example. If not, then work through the following list to prepare: Understand the development environment: - See - Understanding the Files You Need for information. + See "Understanding + the Files You Need" for information. Set up the local Yocto Project files Git repository: - See - Setting Up the Local Yocto Project Files Git Repository for + See "Setting + Up the Local Yocto Project Files Git Repository" for information. Set up the poky-extras Git repository: - See - Setting Up poky-extras Git repository for + See "Setting + Up poky-extras Git repository" for information. Set up the the bare clone and its copy: - See - Setting Up the Bare Clone and its Copy for information. - + See "Setting Up the + Bare Clone and its Copy" for information. Build the default QEMU kernel image: - See - Building and Booting the Default QEMU Kernel image - for information. + See "Building + and Booting the Default QEMU Kernel image" for information. Do not boot the image in the QEMU emulator at this point. @@ -546,7 +539,7 @@ By default, CONFIG_SMP supports single processor machines. - To see this default setting from within the QEMU emulator boot your image using + To see this default setting from within the QEMU emulator, boot your image using the emulator as follows: $ runqemu qemux86 @@ -572,7 +565,7 @@ The menuconfig tool provides an interactive method with which to set kernel configurations. - You need to run menuconfig inside the BitBake environment. + You need to run menuconfig inside the Yocto BitBake environment. Thus, the environment must be set up using the oe-init-build-env script found in the Yocto Project files Git repository build directory. If you have not sourced this script do so with the following commands: @@ -585,7 +578,7 @@ After setting up the environment to run menuconfig, you are ready to use the tool to interactively change the kernel configuration. - In this example we are basing our changes on the linux-yocto-3.0 + In this example, we are basing our changes on the linux-yocto-3.0 kernel. The Yocto Project build environment recognizes this kernel as linux-yocto. @@ -605,14 +598,15 @@ - Once you save the selection the .config configuration file + Once you save the selection, the .config configuration file is updated. This is the file that the build system uses to configure the Linux Yocto kernel when it is built. You can find and examine this file in the Yocto Project files Git repository in the build directory. This example uses the following. - Note that this example directory is arificially split in order to make it more + Note that this example directory is artificially split and many of the characters + in the actually filename are omitted in order to make it more readable: ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-2.6.37+git1+84f... @@ -621,7 +615,7 @@ - Within the .config you can see the following setting: + Within the .config file, you can see the following setting: CONFIG_SMP=y @@ -630,13 +624,12 @@ A good method to isolate changed configurations is to use a combination of the menuconfig tool and simple shell commands. - Before changing configurations with menuconfig simply rename + Before changing configurations with menuconfig, simply rename the default .config, use menuconfig to make as many changes an you want and save them, then compare the renamed configuration file against the newly created file. You can use the resulting differences as your base to create configuration fragments to permanently save in your kernel layer. - For an example of this procedure, see [WRITER'S NOTE: need forwarding link to section]. @@ -644,7 +637,7 @@ Recompiling the Kernel and Testing the New Configuration - At this point you are ready to recompile your kernel image with + At this point, you are ready to recompile your kernel image with the new setting in effect using the BitBake commands below: $ bitbake linux-yocto -c compile -f @@ -671,7 +664,7 @@ - From the output you can see that you have successfully reconfigured the kernel. + From the output, you can see that you have successfully reconfigured the kernel. @@ -680,13 +673,14 @@ Adding Kernel Recipes - This section presents an example that adds kernel recipes, which provide + A future release of this manual will present an example that adds kernel recipes, which provide new functionality to the kernel. - [Example to be supplied] - + + -- cgit v1.2.3-54-g00ecf