From 0e92314239dc4b81a1d944b54f485292b422f982 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 29 Jun 2017 14:42:06 -0700 Subject: kernel-dev: Re-write of Yocto Linux Architecture and Branch Strategies This section in Appepndix A was full of redundancies used to explain how the Yocto Project kernel development team has set up branching and kernel architecture. I consolidated a couple sub-sections into just the necessary single section. (From yocto-docs rev: e42efe28aec6bad3779c4b9ea58941272fb01651) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../kernel-dev/kernel-dev-concepts-appx.xml | 374 +++++++++++---------- 1 file changed, 192 insertions(+), 182 deletions(-) (limited to 'documentation') diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml index 21f7c2c686..7c9f34c729 100644 --- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml +++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml @@ -173,202 +173,212 @@ -
- Kernel Architecture +
+ Yocto Linux Kernel Architecture and Branching Strategies - This section describes the architecture of the Yocto Linux kernels - available through the Yocto Project and provides information - on the mechanisms used to achieve that architecture. + As mentioned earlier, a key goal of the Yocto Project is + to present the developer with a kernel that has a clear and + continuous history that is visible to the user. + The architecture and mechanisms, in particular the branching + strategies, used achieve that goal in a manner similar to + upstream Linux kernel development in + kernel.org. -
- Overview + + You can think of a Yocto Linux kernel as consisting of a + baseline Linux kernel with added features logically structured + on top of the baseline. + The features are tagged and organized by way of a branching + strategy implemented by the Yocto Project team using the + Source Code Manager (SCM) Git. + Notes + + + Git is the obvious SCM for meeting the Yocto Linux + kernel organizational and structural goals + described in this section. + Not only is Git the SCM for Linux kernel + development in kernel.org but, + Git continues to grow in popularity and supports + many different work flows, front-ends and + management techniques. + + + You can find documentation on Git at + . + You can also get an introduction to Git as it + applies to the Yocto Project in the + "Git" + section in the Yocto Project Reference Manual. + The latter reference provides an overview of + Git and presents a minimal set of Git commands + that allows you to be functional using Git. + You can use as much, or as little, of what Git + has to offer to accomplish what you need for your + project. + You do not have to be a "Git Expert" in order to + use it with the Yocto Project. + + + + - - As mentioned earlier, a key goal of the Yocto Project is - to present the developer with a kernel that has a clear and - continuous history that is visible to the user. - The architecture and mechanisms used achieve that goal in a - manner similar to upstream Linux kernel development in - kernel.org. - + + Using Git's tagging and branching features, the Yocto Project + team creates kernel branches at points where functionality is + no longer shared and thus, needs to be isolated. + For example, board-specific incompatibilities would require + different functionality and would require a branch to + separate the features. + Likewise, for specific kernel features, the same branching + strategy is used. + - - You can think of a Yocto Linux kernel as consisting of a - baseline Linux kernel with added features logically structured - on top of the baseline. - The features are tagged and organized by way of a branching - strategy implemented by the Yocto Project team using the - Source Code Manager (SCM) Git. - Notes - - - Git is the obvious SCM for meeting the Yocto Linux - kernel organizational and structural goals - described in this section. - Not only is Git the SCM for Linux kernel - development in kernel.org but, - Git continues to grow in popularity and supports - many different work flows, front-ends and - management techniques. - - - You can find documentation on Git at - . - You can also get an introduction to Git as it - applies to the Yocto Project in the - "Git" - section in the Yocto Project Reference Manual. - The latter reference provides an overview of - Git and presents a minimal set of Git commands - that allows you to be functional using Git. - You can use as much, or as little, of what Git - has to offer to accomplish what you need for your - project. - You do not have to be a "Git Expert" in order to - use it with the Yocto Project. - - - - + + This "tree-like" architecture results in a tree that has + features organized to be specific for particular + functionality, single kernel types, or a subset of kernel + types. + Thus, the user has the ability to see the added + features and the commits that make up those features. + In addition to being able to see added features, the user + can also view the history of what made up the baseline + Linux kernel. + - - The result is that the user has the ability to see the added - features and the commits that make up those features. - In addition to being able to see added features, the user - can also view the history of what made up the baseline - Linux kernel. - + + Another consequence of this strategy results in not having to + store the same feature twice internally in the tree. + Rather, the kernel team stores the unique differences required + to apply the feature onto the kernel type in question. + + The Yocto Project team strives to place features in the tree + such that features can be shared by all boards and kernel + types where possible. + However, during development cycles or when large features + are merged, the team cannot always follow this practice. + In those cases, the team uses isolated branches to merge + features. + + - - The following illustration shows the conceptual Yocto - Linux kernel. - - + + BSP-specific code additions are handled in a similar manner to + kernel-specific additions. + Some BSPs only make sense given certain kernel types. + So, for these types, the team creates branches off the end + of that kernel type for all of the BSPs that are supported on + that kernel type. + From the perspective of the tools that create the BSP branch, + the BSP is really no different than a feature. + Consequently, the same branching strategy applies to BSPs as + it does to kernel features. + So again, rather than store the BSP twice, the team only + stores the unique differences for the BSP across the supported + multiple kernels. + - - In the illustration, the "Kernel.org Branch Point" marks the - specific spot (or Linux kernel release) from which the - Yocto Linux kernel is created. - From this point forward in the tree, features and differences - are organized and tagged. - + + While this strategy can result in a tree with a significant number + of branches, it is important to realize that from the developer's + point of view, there is a linear path that travels from the + baseline kernel.org, through a select + group of features and ends with their BSP-specific commits. + In other words, the divisions of the kernel are transparent and + are not relevant to the developer on a day-to-day basis. + From the developer's perspective, this path is the "master" branch + in Git terms. + The developer does not need to be aware of the existence of any + other branches at all. + Of course, value exists in the having these branches in the tree, + should a person decide to explore them. + For example, a comparison between two BSPs at either the commit + level or at the line-by-line code diff level + is now a trivial operation. + - - The "Yocto Project Baseline Kernel" contains functionality that - is common to every kernel type and BSP that is organized - further along in the tree. - Placing these common features in the tree this way means - features do not have to be duplicated along individual - branches of the tree structure. - + + The following illustration shows the conceptual Yocto + Linux kernel. + + + + + In the illustration, the "Kernel.org Branch Point" marks the + specific spot (or Linux kernel release) from which the + Yocto Linux kernel is created. + From this point forward in the tree, features and differences + are organized and tagged. + + + + The "Yocto Project Baseline Kernel" contains functionality that + is common to every kernel type and BSP that is organized + further along in the tree. + Placing these common features in the tree this way means + features do not have to be duplicated along individual + branches of the tree structure. + + + + From the "Yocto Project Baseline Kernel", branch points represent + specific functionality for individual Board Support Packages + (BSPs) as well as real-time kernels. + The illustration represents this through three BSP-specific + branches and a real-time kernel branch. + Each branch represents some unique functionality for the BSP + or for a real-time Yocto Linux kernel. + - - From the Yocto Project Baseline Kernel, branch points represent - specific functionality for individual Board Support Packages - (BSPs) as well as real-time kernels. - The illustration represents this through three BSP-specific - branches and a real-time kernel branch. - Each branch represents some unique functionality for the BSP - or for a real-time Yocto Linux kernel. - + + In this example structure, the "Real-time (rt) Kernel" branch has + common features for all real-time Yocto Linux kernels and + contains more branches for individual BSP-specific real-time + kernels. + The illustration shows three branches as an example. + Each branch points the way to specific, unique features for a + respective real-time kernel as they apply to a given BSP. + - - In this example structure, the real-time kernel branch has - common features for all real-time Yocto Linux kernels and - contains more branches for individual BSP-specific real-time - kernels. - The illustration shows three branches as an example. - Each branch points the way to specific, unique features for a - respective real-time kernel as they apply to a given BSP. - + + The resulting tree structure presents a clear path of markers + (or branches) to the developer that, for all practical + purposes, is the Yocto Linux kernel needed for any given set of + requirements. + + Keep in mind the figure does not take into account all the + supported Yocto Linux kernels, but rather shows a single + generic kernel just for conceptual purposes. + Also keep in mind that this structure represents the Yocto + Project + Source Repositories + that are either pulled from during the build or established + on the host development system prior to the build by either + cloning a particular kernel's Git repository or by + downloading and unpacking a tarball. + + - - The resulting tree structure presents a clear path of markers - (or branches) to the developer that, for all practical - purposes, is the Yocto Linux kernel needed for any given set of - requirements. - - Keep in mind the figure does not take into account all the - supported Yocto Linux kernels, but rather shows a single - generic kernel just for conceptual purposes. - Also keep in mind that this structure represents the Yocto - Project - Source Repositories - that are either pulled from during the build or established - on the host development system prior to the build by either - cloning a particular kernel's Git repository or by - downloading and unpacking a tarball. - - -
+ + Working with the kernel as a structured tree follows recognized + community best practices. + In particular, the kernel as shipped with the product, should be + considered an "upstream source" and viewed as a series of + historical and documented modifications (commits). + These modifications represent the development and stabilization + done by the Yocto Project kernel development team. + -
- Branching Strategy and Workflow - - The Yocto Project team creates kernel branches at points where functionality is - no longer shared and thus, needs to be isolated. - For example, board-specific incompatibilities would require different functionality - and would require a branch to separate the features. - Likewise, for specific kernel features, the same branching strategy is used. - - - This branching strategy results in a tree that has features organized to be specific - for particular functionality, single kernel types, or a subset of kernel types. - This strategy also results in not having to store the same feature twice - internally in the tree. - Rather, the kernel team stores the unique differences required to apply the - feature onto the kernel type in question. - - The Yocto Project team strives to place features in the tree such that they can be - shared by all boards and kernel types where possible. - However, during development cycles or when large features are merged, - the team cannot always follow this practice. - In those cases, the team uses isolated branches to merge features. - - - - BSP-specific code additions are handled in a similar manner to kernel-specific additions. - Some BSPs only make sense given certain kernel types. - So, for these types, the team creates branches off the end of that kernel type for all - of the BSPs that are supported on that kernel type. - From the perspective of the tools that create the BSP branch, the BSP is really no - different than a feature. - Consequently, the same branching strategy applies to BSPs as it does to features. - So again, rather than store the BSP twice, the team only stores the unique - differences for the BSP across the supported multiple kernels. - - - While this strategy can result in a tree with a significant number of branches, it is - important to realize that from the developer's point of view, there is a linear - path that travels from the baseline kernel.org, through a select - group of features and ends with their BSP-specific commits. - In other words, the divisions of the kernel are transparent and are not relevant - to the developer on a day-to-day basis. - From the developer's perspective, this path is the "master" branch. - The developer does not need to be aware of the existence of any other branches at all. - Of course, there is value in the existence of these branches - in the tree, should a person decide to explore them. - For example, a comparison between two BSPs at either the commit level or at the line-by-line - code diff level is now a trivial operation. - - - Working with the kernel as a structured tree follows recognized community best practices. - In particular, the kernel as shipped with the product, should be - considered an "upstream source" and viewed as a series of - historical and documented modifications (commits). - These modifications represent the development and stabilization done - by the Yocto Project kernel development team. - - - Because commits only change at significant release points in the product life cycle, - developers can work on a branch created - from the last relevant commit in the shipped Yocto Project kernel. - As mentioned previously, the structure is transparent to the developer - because the kernel tree is left in this state after cloning and building the kernel. - -
+ + Because commits only change at significant release points in the + product life cycle, developers can work on a branch created + from the last relevant commit in the shipped Yocto Project kernel. + As mentioned previously, the structure is transparent to the + developer because the kernel tree is left in this state after + cloning and building the kernel. +