From 7c08b602e684f0e76a7fc3264a7e67e98b467d24 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 9 Oct 2012 06:32:34 -0700 Subject: documentation: dev-manual, bsp-guide, kernel-manual - kernel workflow The kernel workflow section was re-written to reflect that the kernel appendix has been removed. Also, changes to the flow in general no longer make reference to the bare clone and the copy of the bare clone as a method used to modify the kernel. Many links were modified in other manuals as well. (From yocto-docs rev: 38adbcb00d4305029cfa94e5ef047da41823f021) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/bsp-guide/bsp.xml | 4 - .../dev-manual/dev-manual-common-tasks.xml | 12 +- documentation/dev-manual/dev-manual-model.xml | 157 ++++++--------------- .../dev-manual/figures/kernel-dev-flow.png | Bin 62416 -> 45225 bytes documentation/kernel-manual/kernel-doc-intro.xml | 2 +- 5 files changed, 52 insertions(+), 123 deletions(-) (limited to 'documentation') diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index 2fa016a969..1f1667114c 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -618,10 +618,6 @@ 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. - diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 4ce0a94873..48d86fac25 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1608,8 +1608,6 @@ 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 @@ -1627,6 +1625,16 @@ console. +
+ Finding the Kernel Source Files + + + Describe how to find the source files in the build area. + We are not assuming they are using their own kernel tree. + + +
+
Understanding the Files You Need diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index c96b2dda63..ab14ebd4d4 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -8,7 +8,8 @@ Many development models exist for which you can use the Yocto Project. - This chapter overviews the following methods: + This chapter overviews simple methods that use tools provided by the + Yocto Project: System Development: System Development covers Board Support Package (BSP) development and kernel @@ -322,8 +323,8 @@ - Storage of all the available kernel source code is one thing, while representing the - code on your host development system is another. + Upstream storage of all the available kernel source code is one thing, while + representing and using the code on your host development system is another. Conceptually, you can think of the kernel source repositories as all the source files necessary for all the supported kernels. As a developer, you are just interested in the source files for the kernel on @@ -332,39 +333,14 @@ - You make kernel source code available on your host development system by using - Git to create a bare clone of the Yocto Project kernel Git repository - in which you are interested. - Then, you use Git again to clone a copy of that bare clone. - This copy represents the directory structure on your host system that is particular - to the kernel you want. - The files in the copy of the bare clone are the files you actually modify - to change the kernel. - See the Yocto Project Kernel item earlier - in this manual for an example of how to set up the kernel source directory - structure on your host system. - - - - This next figure illustrates how the kernel source files might be arranged on - your host system. - - - - - - - - In the previous figure, the file structure on the left represents the bare clone - set up to track the Yocto Project kernel Git repository. - The structure on the right represents the copy of the bare clone. - When you make modifcations to the kernel source code, this is the area in which - you work. - Once you make corrections, you must use Git to push the committed changes to the - bare clone. - + Kernel source code is available on your host system a couple of different + ways. + If you are working in the kernel all the time, you probably would want + to set up your own local Git repository of the kernel tree. + If you just need to make some patches to the kernel, you can get at + temporary kernel source files extracted and used during the OpenEmbedded + build system. + We will just talk about working with the temporary source code. @@ -407,7 +383,7 @@ + width="6in" depth="5in" align="center" scalefit="1" /> @@ -424,43 +400,39 @@ For information on how to get these files, see the bulleted item "Yocto Project Release" earlier in this manual. - Set up a local copy of the poky-extras Git - repository: This local repository is the area for your configuration - fragments, new kernel recipes, and the kernel .bbappend - file used during the build. - It is good practice to set this repository up inside your local - Source Directory. - For information on how to get these files, see the bulleted item - "The poky-extras Git Repository" - earlier in this manual. - While it is certainly possible to modify the kernel without involving - a local Git repository, the suggested workflow for kernel modification - using the Yocto Project does use a Git repository. - Establish a local copy of the Yocto Project kernel files on your - system: In order to make modifications to the kernel you need two things: - a bare clone of the Yocto Project kernel you are modifying and - a copy of that bare clone. - The bare clone is required by the build process and is the area to which you - push your kernel source changes (pulling does not work with bare clones). - The copy of the bare clone is a local Git repository that contains all the kernel's - source files. - You make your changes to the files in this copy of the bare clone. - For information on how to set these two items up, see the bulleted item - "Yocto Project Kernel" - earlier in this manual. + Establish the temporary kernel source files: + Temporary kernel source files are kept in the Build Directory created by the + OpenEmbedded build system when you run BitBake. + If you have never built the kernel you are interested in, you need to run + an initial build to establish local kernel source files. + If you are building an image for the first time, you need to get the build + environment ready by sourcing + the environment setup script. + You also need to be sure two key configuration files + (local.conf and bblayers.conf) + are configured appropriately. + The entire process for building an image is overviewed in the + "Building an Image" + section of the Yocto Project Quick Start. + You might want to reference this information. + You can find more information on BitBake in the user manual, which is found in the + bitbake/doc/manual directory of the + Source Directory. + The build process supports several types of images to satisfy different needs. + See the "Images" chapter in + the Yocto Project Reference Manual for information on supported images. + Make changes to the kernel source code if applicable: Modifying the kernel does not always mean directly changing source files. - However, if you have to do this, you make the changes in the local - Git repository you set up to hold the source files (i.e. the copy of the - bare clone). - Once the changes are made, you need to use Git commands to commit the changes - and then push them to the bare clone. + However, if you have to do this, you make the changes to the files in the + Build directory. Make kernel configuration changes if applicable: If your situation calls for changing the kernel's configuration, you can - use menuconfig + use the yocto-kernel script or menuconfig to enable and disable kernel configurations. + Using the script lets you interactively set up kernel configurations. Using menuconfig allows you to interactively develop and test the configuration changes you are making to the kernel. When saved, changes using menuconfig update the kernel's @@ -476,55 +448,8 @@ .config file against a saved original and gather those changes into a config fragment to be referenced from within the kernel's .bbappend file. - Add or extend kernel recipes if applicable: - The standard - layer structure organizes recipe files inside the - meta-kernel-dev layer that is within the local - poky-extras Git repository. - If you need to add new kernel recipes, you add them within this layer. - Also within this area, you will find the .bbappend - file that appends information to the kernel's recipe file used during the - build. - - Prepare for the build: Once you have made all the - changes to your kernel (configurations, source code changes, recipe additions, - or recipe changes), there remains a few things - you need to do in order for the build system to create your image. - If you have not done so, you need to get the build environment ready by sourcing - the environment setup script described earlier. - You also need to be sure two key configuration files - (local.conf and bblayers.conf) - are configured appropriately. - The entire process for building an image is overviewed in the - "Building an Image" - section of the Yocto Project Quick Start. - You might want to reference this information. - Also, you should look at the detailed examples found in the appendices at - at the end of this manual. - Build the image: The OpenEmbedded - build system uses the BitBake - tool to build images based on the type of image you want to create. - You can find more information on BitBake in the user manual, which is found in the - bitbake/doc/manual directory of the - Source Directory. - The build process supports several types of images to satisfy different needs. - See the "Images" chapter in - the Yocto Project Reference Manual for information on supported images. - Make your configuration changes available - in the kernel layer: Up to this point, all the configuration changes to the - kernel have been done and tested iteratively. - Once they are tested and ready to go, you can move them into the kernel layer, - which allows you to distribute the layer. - If applicable, share your in-tree changes: - If the changes you made - are suited for all Yocto Project kernel users, you might want to send them on - for inclusion into the upstream kernel's Git repository. - If the changes are accepted, the Yocto Project Maintainer pulls them into - the master branch of the kernel tree. - Doing so makes them available to everyone using the kernel. - For information on how to submit a change to the Yocto Project, see the - "How to Submit a Change" section - earlier in this manual. + Rebuild the kernel image with your changes: + Rebuilding the kernel image applies your changes.
diff --git a/documentation/dev-manual/figures/kernel-dev-flow.png b/documentation/dev-manual/figures/kernel-dev-flow.png index 3244d3eb90..edd9e82af7 100644 Binary files a/documentation/dev-manual/figures/kernel-dev-flow.png and b/documentation/dev-manual/figures/kernel-dev-flow.png differ diff --git a/documentation/kernel-manual/kernel-doc-intro.xml b/documentation/kernel-manual/kernel-doc-intro.xml index 164f8c3940..71a3135b0a 100644 --- a/documentation/kernel-manual/kernel-doc-intro.xml +++ b/documentation/kernel-manual/kernel-doc-intro.xml @@ -55,7 +55,7 @@ "Kernel Modification Workflow" - "Kernel Modification Example" + "Patching the Kernel" -- cgit v1.2.3-54-g00ecf