From 49166264bd93d2e4c0b4fcf3641468b37ca18b84 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 27 Dec 2012 14:50:40 -0600 Subject: kernel-dev: Formatting "Machine Branches" section. (From yocto-docs rev: 30a0d3c1ef3d91221ce3f90a3fd2f4b93bff1c30) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/kernel-dev/kernel-dev-advanced.xml | 182 +++++++++++++++++++++++ 1 file changed, 182 insertions(+) (limited to 'documentation') diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index ee90df2732..dbc3dfbe89 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -1308,6 +1308,188 @@ the KTYPE has changed, now set to "tiny". + + + +
+ Machine Branches + + + The "Using 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. + Many linux-yocto-custom derived recipes will be using Linux kernel + sources with only a single branch: "master". + However, when you are working 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. + Sometimes, these patches are works-in-progress or fundamentally wrong, + yet still necessary for specific boards. + In these situations, you most likely do not want to include these + patches in every kernel you build. + You have a couple of options. + + + + First, you could encapsulate these patches in a feature description + and only include them in the BSP description for the board(s) that + require them. + For more information, see the + "Patches" and + "BSP Descriptions" sections. + + + + Alternatively, you can create a 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.scc + + + + + The approach you take, feature or branch, 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. + + + + If you are supporting multiple boards and architectures and 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> + + + + + If you had two ktypes, standard and small for instance, and three + machines, your Git tree might look like this: + + common/base + common/standard/base + common/standard/machine_a + common/standard/machine_b + common/standard/machine_c + common/small/base + common/small/machine_a + + + + + 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". + 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 + would have to create a file and a directory named "standard". + + + + + Original text: + +Section 3.1 introduced the KBRANCH variable which defines the source branch to +use from the Linux kernel git repository you are using. Many linux-yocto-custom +derived recipes will be using Linux kernel sources with only a single branch: +"master". However, when you are working 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. Sometimes these patches are works in progress or +fundamentally wrong, yet still necessary for specific boards. In these +situations, you most likely do not want to include these patches in every kernel +you build. You have a couple of options. + +First, you could encapsulate these patches in a feature description and only +include them in the BSP description for the board(s) that require them (see +3.3.2 and 3.3.5). + +Alternatively, you can create a 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.scc + +The decision of which approach to take, feature or branch, 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. + +If you are supporting multiple boards and architectures and 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> + +If you had two ktypes, standard and small for instance, and three machines, your +git tree might look like this: + + common/base + common/standard/base + common/standard/machine_a + common/standard/machine_b + common/standard/machine_c + common/small/base + common/small/machine_a + +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". The "standard" and "small" branches +add sources specific to those kernel types that for whatever reason are not +appropriate for the other branches. + +Note: 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 would have to + create a file and a directory named "standard". + + +
+