From c9f796dbd7300970282c4c4bba1ac8e2eca2fba9 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 11 Jan 2013 14:04:40 -0800 Subject: kernel-dev: Re-write of the "Organizing Your Source" section. A serious pass through this system to reorganize it. (From yocto-docs rev: f13abc59730d78e5ffa5bce3d38519f8fc4c127f) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/kernel-dev/kernel-dev-advanced.xml | 181 ++++++++++++++--------- 1 file changed, 111 insertions(+), 70 deletions(-) (limited to 'documentation') diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 35b935eced..adfd774a41 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -56,7 +56,7 @@ contain the highest level visible CONFIG options as presented by the Linux kernel menuconfig system. This reduces your maintenance effort and allows you to further separate your configuration in ways that make sense for your project. A common split is policy and hardware. For example, all your kernels may support -the proc and sys filesystems, but only specific boards will require sound, usb, +the proc and sys filesystems, but only specific boards will require sound, USB, or specific drivers. Specifying these individually allows you to aggregate them together as needed, but maintain them in only one place. Similar logic applies to source changes. @@ -136,7 +136,7 @@ to source changes. The linux-yocto recipes define "standard", "tiny", and "preempt-rt" kernel types. See the Kernel Types section - for more inforation on kernel types. + for more information on kernel types. @@ -237,7 +237,7 @@ Together with KMACHINE, this defines the search arguments used by the Yocto Project Linux kernel tools to find the appropriate description within the metadata with which to build out the sources and configuration. The linux-yocto recipes define "standard", "tiny", and "preempt-rt" kernel types. See 3.3.4 for -more inforation on kernel types. +more information on kernel types. During the build, the kern-tools will search for the BSP description file that most closely matches the KMACHINE and LINUX_KERNEL_TYPE passed in from the @@ -332,7 +332,7 @@ or if you just don't want to maintain a Linux kernel git repository on your own. If you are doing active kernel development and are already maintaining a Linux kernel git repository of your own, you may find it more convenient to work with the meta-data in the same repository as the Linux kernel sources. This can make -iterative development of the Linux kernel more efficient outside of the bitbake +iterative development of the Linux kernel more efficient outside of the BitBake environment. Regardless of where the meta-data is stored, the syntax as @@ -406,10 +406,10 @@ meta/ `-- standard.cfg When the meta-data is stored in recipe-space, you must take steps to ensure -bitbake has the necessary information to decide which files to fetch and when +BitBake has the necessary information to decide which files to fetch and when they need to be fetched again. -It is only necessary to specify the .scc files on the SRC_URI; bitbake will +It is only necessary to specify the .scc files on the SRC_URI; BitBake will parse them and fetch any files referenced in the .scc files by the include, patch, or kconf commands. Because of this, it is necessary to bump the recipe PR value when changing the content of files not explicitly listed in the SRC_URI. @@ -1373,17 +1373,21 @@ the KTYPE has changed, now set to "tiny". -
- Working with Branches +
+ Organizing Your Source - Many recipes based on the linux-yocto-custom.bb - use Linux kernel sources that have only the single branch - "master". + Many recipes based on the linux-yocto-custom.bb + recipe use Linux kernel sources that have only a single + branch - "master". + This type of repository structure is fine for linear development + supporting a single machine and architecture. However, if you work with multiple boards and architectures, - you are likely to run into the situation where a series of patches - are needed for one board to boot. + a kernel source repository with multiple branches is more + efficient. + For example, suppose you need a series of patches for one board to boot. Sometimes, these patches are works-in-progress or fundamentally wrong, - yet still necessary for specific boards. + yet they are still necessary for specific boards. In these situations, you most likely do not want to include these patches in every kernel you build (i.e. have the patches as part of the lone "master" branch). @@ -1392,75 +1396,105 @@ the KTYPE has changed, now set to "tiny". - If you are supporting multiple boards and architectures, you have - some options as to how you want to isolate your changes: + Repository organization strategies exist that maximize source reuse, + remove redundancy, and logically order your changes. + This section presents strategies for the following cases: - Include feature patches in the BSP: - Encapsulate patches in a feature description and only include - the patches in the BSP descriptions of the applicable boards. - For more information, see the - "Patches" and - "BSP Descriptions" - sections. - Create a machine branch: - You can create a machine branch in your Linux kernel sources - and apply the patches there. - You can then specify this new branch as the - KBRANCH to use for this board. - You can do this in the recipe with the - KBRANCH variable: - - KBRANCH = "mynewbranch" - - or in the BSP description using the "branch" command: - - mybsp.scc: - define KMACHINE mybsp - define KTYPE standard - define KARCH i386 - include standard.scc - - branch mynewbranch - - include mybsp-hw.scc - + Encapsulating patches in a feature description + and only including the patches in the BSP descriptions of + the applicable boards. + Creating a machine branch in your + kernel source repository and applying the patches on that + branch only. + Creating a feature branch in your + kernel source repository and merging that branch into your + BSP when needed. + - The approach you take, feature or branch, is entirely up to you + The approach you take is entirely up to you and depends on what works best for your development model. - If you are actively working on board support, you may find that - working within a branch is more practical than trying to continually - reintegrate your patches into a feature. - On the other hand, if you are simply reusing some patches from an - external tree and are not working on them, you may find the - encapsulated feature to be appropriate as it does not require the - additional complexity of branching in your Linux kernel sources. +
+ Encapsulating Patches + + + if you are reusing patches from an external tree and are not + working on the patches, you might find the encapsulated feature + to be appropriate. + Given this scenario, you don't need to create any branches in the + source repository. + Rather, you just take the static patches you need and encapsulate + them within a feature description. + Once you have the feature description, you simply include that into + the BSP description as described in the + "BSP Descriptions" + section. + + + + You can find information on how to create patches and BSP + descriptions in the "Patches" and + "BSP Descriptions" + sections. + +
+
Machine Branches - The "Using Kernel Metadata in a Recipe" - section introduced the KBRANCH variable, which - defines the source branch to use from the Linux kernel Git repository - you are using. + When you have multiple machines and architectures to support, + or you are actively working on board support, it is more + efficient to create branches in the repository based on + individual machines. + Having machine branches allows common source to remain in the + "master" branch with any features specific to a machine stored + in the appropriate machine branch. + This organization method frees you from continually reintegrating + your patches into a feature. - If you are supporting multiple boards and architectures and find + Once you have a new branch, you can set up your kernel Metadata + to use the branch a couple different ways. + In the recipe, you can specify the new branch as the + KBRANCH to use for the board as + follows: + + KBRANCH = "mynewbranch" + + Another method is to use the branch command + in the BSP description: + + mybsp.scc: + define KMACHINE mybsp + define KTYPE standard + define KARCH i386 + include standard.scc + + branch mynewbranch + + include mybsp-hw.scc + + + + + If you find yourself with numerous branches, you might consider using a hierarchical branching system similar to what the linux-yocto Linux kernel repositories use: - <common>/<ktype>/<machine> + <common>/<kernel_type>/<machine> - If you had two ktypes, standard and small for instance, and three - machines, your Git tree might look like this: + If you had two kernel types, "standard" and "small" for + instance, and three machines, the branches in your + Git repository might look like this: common/base common/standard/base @@ -1473,16 +1507,17 @@ the KTYPE has changed, now set to "tiny". - This organization can help clarify the relationship of the branches to - each other. - In this case, "common/standard/machine_a" would include everything in - "common/base" and "common/standard/base". + This organization can help clarify the branch relationships. + In this case, common/standard/machine_a + includes everything in common/base and + common/standard/base. The "standard" and "small" branches add sources specific to those kernel types that for whatever reason are not appropriate for the other branches. The "base" branches are an artifact of the way Git manages - its data internally on the filesystem: it will not allow you to use - "common/standard" and "common/standard/machine_a" because it + its data internally on the filesystem: Git will not allow you + to use common/standard and + common/standard/machine_a because it would have to create a file and a directory named "standard". @@ -1518,7 +1553,13 @@ mybsp.scc: define KARCH i386 include standard.scc - branch mynewbranch + branch mynewbranchIf you are actively +working on board support, you may find that working within a branch is more +practical than trying to continually reintegrate your patches into a feature. On +the other hand, if you are simply reusing some patches from an external tree and +are not working on them, you may find the encapsulated feature to be appropriate +as it does not require the additional complexity of branching in your Linux +kernel sources include mybsp.scc @@ -1566,9 +1607,9 @@ Note: The "base" branches are an artifact of the way git manages its data Feature Branches - During active development a new feature, it can be more efficient - to work with that feature as a branch, rather than as a set of - patches which have to be regularly updated. + When you are actively developing new features, it can be more + efficient to work with that feature as a branch, rather than + as a set of patches that have to be regularly updated. The Yocto Project Linux kernel tools provide for this with the git merge command. -- cgit v1.2.3-54-g00ecf