From 1fc37b75cb845aa5bf19d908746235f8c398cba0 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 12 Oct 2012 20:02:43 -0700 Subject: documentation: dev-manual - edits to kernel section and compliance * Edits to get the patching the kernel section more sane. * A tweak to the opening sentence of the compliance section to rid it of the split-infinitives. (From yocto-docs rev: 8e2ff293e85a602efd98aceb20da5a2ea5f2a34d) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 324 +++++++++++---------- documentation/dev-manual/dev-manual-model.xml | 17 +- 2 files changed, 173 insertions(+), 168 deletions(-) (limited to 'documentation') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index fc7a535f85..ce41a28031 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1626,7 +1626,7 @@ - The example assumes a clean build exists for the x86qemu + The example assumes a clean build exists for the qemux86 machine in a Source Directory named poky. Furthermore, the Build Directory is build and is located in poky and @@ -1637,13 +1637,13 @@ Create a Layer for your Changes - The first step is to isolate your changes into a layer: + The first step is to create a layer so you can isolate your changes: $cd ~/poky $mkdir meta-mylayer Creating a directory that follows the Yocto Project layer naming - conventions sets up the area for your changes. + conventions sets up the layer for your changes. The layer is where you place your configuration files, append files, and patch files. To learn more about creating a layer and filling it with the @@ -1657,26 +1657,24 @@ Each time you build a kernel image, the kernel source code is fetched - and unpacked into a temporary location in the Build Directory. - See the "Finding the Temporary Source Code" - section for a description of where the OpenEmbedded build system places - kernel source files during a build. - Following is where machine-specific source code is temporarily stored - during the build: + and unpacked into the following directory: - ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} + ${S}/linux + See the "Finding the Temporary Source Code" + section and the + S variable + for more information about where source is kept during a build. For this example, the directory that holds the temporary source code is here: - ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3 + ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3/linux - Within the linux directory, you find directories for - the source. - For this example, we are going to patch the init/calibrate.c file + For this example, we are going to patch the + init/calibrate.c file by adding some simple console printk statements that we can see when we boot the image using QEMU. @@ -1686,39 +1684,31 @@ Creating the Patch - Two methods exist by which you can create the patch: Git workflow and Quilt workflow. + Two methods exist by which you can create the patch: + Git workflow and + Quilt workflow. For kernel patches, the Git workflow is more appropriate. - This section assumes the Git workflow. - - - - To create the patch for the calibrate.c, follow steps - 3 through 12 outlined in the - "Using a Git Workflow" - section. - For step 6 (Edit the Files), do the following: - - - - Locate the void __cpuinit calibrate_delay(void) - 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)) { - . - . - . - - - - - Alter the code as follows: - + This section assumes the Git workflow and shows the steps specific to + this example. + + Change the working directory: + Change to where the kernel source code is before making + your edits to the calibrate.c file: + + $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux + + Because you are working in an established Git repository, + you must be in this directory in order to commit your changes + and create the patch file. + The PV and + PR variables + represent the version and revision for the + linux-yocto recipe. + + Edit the source file: + Edit the init/calibrate.c file to have the + following changes: + void __cpuinit calibrate_delay(void) { unsigned long lpj; @@ -1735,44 +1725,49 @@ . . . - + + Stage and commit your changes: + These Git commands list out the changed file, stage it, and then + commit the files: + + $ git status + $ git add init/calibrate.c + $ git commit + + Generate the patch file: + This Git command creates the a patch file named + 0001-calibrate.c.patch in the current directory. + + $ git format-patch HEAD~1 + + The name of the patch file is based on your commit summary + line. + +
Get Your Layer Setup for the Build - - At this point, you have a patch file in the kernel's source code directory. - The patch file is named according to the commit's summary line and ends - with .patch. - For this example, it is named 0001-calibrate.c.patch. - - - - You need to move the patch file to your layer next. - The patch file needs to reside in the - meta-mylayer/recipes-kernel/linux/linux-yocto directory. - Create this directory path within your layer and move the patch file. - This directory path mirrors that used by the main kernel recipe in - the Source Directory (poky). - + These steps get your layer set up for the build: + + Create additional structure: + Create the additional layer structure: + $ cd ~/poky/meta-mylayer + $ mkdir conf $ mkdir recipes-kernel $ mkdir recipes-kernel/linux $ mkdir recipes-kernel/linux/linux-yocto - - - - - Next, you need to create a conf directory in your layer - and within it create the layer.conf file. - You can find information on this in the - "Creating Your Own Layer" - section. - Here is what your layer.conf should look like for this - example: - + + The conf directory holds your configuration files, while the + recipes-kernel directory holds your append file and + your patch file. + Create the layer configuration file: + Move to the meta-mylayer/conf directory and create + the layer.conf file as follows: + # We have a conf and classes directory, add to BBPATH BBPATH := "${LAYERDIR}:${BBPATH}" @@ -1783,80 +1778,85 @@ BBFILE_COLLECTIONS += "mylayer" BBFILE_PATTERN_mylayer := "^${LAYERDIR}/" BBFILE_PRIORITY_mylayer = "5" - - - - - 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: - - 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-mylayer - 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-mylayer layer. - By default, the BBLAYERS variable contains paths to - meta, meta-yocto, and - meta-yocto-bsp in the - poky Git repository. - Add the path to your meta-mylayer 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/meta-mylayer \ - " - - Create a bbappend File: You need to create - an append file for the main 3.4 kernel recipe. - Create the append file in the linux directory you - created earlier within your layer. - Assuming the patch file is named - 0001-documentation-calibrate.c.patch, your append - file, which must be named linux-yocto_3.4.bbappend, - has these statements: - + + Notice mylayer as part of the last three + statements. + Create the kernel recipe append file: + Move to the meta-mylayer/recipes-kernel/linux directory and create + the linux-yocto_3.4.bbappend file as follows: + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - SRC_URI += "file://0001-documentation-calibrate.c.patch" + SRC_URI += "file://0001-calibrate.c.patch" PRINC := "${@int(PRINC) + 1}" - - The FILESEXTRAPATHS and SRC_URI - statements ensure the OpenEmbedded build system picks up the patch file. - - - -
+ + The FILESEXTRAPATHS and SRC_URI + statements enable the OpenEmbedded build system to find the patch file. + + Put the patch file in your layer: + Move the 0001-calibrate.c.patch file to + the meta-mylayer/recipes-kernel/linux/linux-yocto + directory. + + + + +
+ Set Up for the Build + + + 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: + + 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-mylayer + 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-mylayer layer. + By default, the BBLAYERS variable contains paths to + meta, meta-yocto, and + meta-yocto-bsp in the + poky Git repository. + Add the path to your meta-mylayer location. + Be sure to substitute your user information in the statement: + + BBLAYERS = " \ + /home/<user>/poky/meta \ + /home/<user>/poky/meta-yocto \ + /home/<user>/poky/meta-yocto-bsp \ + /home/<user>/poky/meta-mylayer \ + " + + + +
-
- Building and Booting the Modified QEMU Kernel Image +
+ Build and Booting the Modified QEMU Kernel Image - Next, you need to build the modified image. - Do the following: + The following steps build and boot your modified kernel image: - Your environment should be set up since you previously sourced + Be sure your build environment is initialized: + 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. @@ -1864,7 +1864,8 @@ $ source &OE_INIT_FILE; - Be sure old images are cleaned out by running the + Clean up: + Be sure old images are cleaned out by running the cleanall BitBake task as follows from your build directory: $ bitbake -c cleanall linux-yocto @@ -1873,29 +1874,36 @@ directory inside the build directory. Always use the BitBake cleanall task to clear out previous builds. - Next, build the kernel image using this command: + Build the image: + Next, build the kernel image using this command: $ bitbake -k linux-yocto - 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 - - +
+ Verify Your Changes - You should see the results of your printk statements - as part of the output. + These steps boot the image and allow you to see the changes + + Boot the image: + Boot the modified image in the QEMU emulator + using this command: + + $ runqemu qemux86 + + Verify the changes: + Log into the machine using root with no password and then + use the following shell command to scroll through the console's boot output. + + # dmesg | less + + You should see the results of your printk statements + as part of the output. +
@@ -2625,8 +2633,8 @@ One of the concerns for a development organization using open source software is how to maintain compliance with various open source licensing during the lifecycle of the product. - While this section is not meant to be legal advice or to - comprehensively cover all scenarios, it is meant to + While this section does not provide legal advice or + comprehensively cover all scenarios, it does present methods that you can use to meet the compliance requirements during a software release. diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index 436ecb6fb7..b61eeb0678 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -1688,10 +1688,12 @@ directory. You need to be in the directory that has the temporary source code. That directory is defined by the S - variable. - For this discussion, assume that directory is linux. - Initialize a Git Repository: - Use the git init command to initialize a new local repository + variable. + If you are working with a kernel, you need to be in the + ${S}/linux directory. + If needed, initialize a Git Repository: + If you are not already in a Git repository, use the + git init command to initialize a new local repository that is based on the work directory: $ git init @@ -1730,11 +1732,6 @@ directory. "Building an Image" section of the Yocto Project Quick Start. - Change Your Working Directory: - After making your edits, move back to the directory from which you - initialized the Git repository. - Returning to this directory ensures you are using the correct branch when - you go to commit your changes. See the List of Files You Changed: Use the git status command to see what files you have actually edited. The ability to have Git track the files you have changed is an advantage that this @@ -1749,7 +1746,7 @@ directory. Again, for this discussion assume the files changed are in the linux directory: - $ git add linux/file1.c linux/file2.c linux/file3.c + $ git add <somepath>/file1.c <somepath>/file2.c <somepath>/file3.c Commit the Staged Files and View Your Changes: Use the git commit command to commit the changes to the -- cgit v1.2.3-54-g00ecf