# Yocto Project Kernel Concepts

## Introduction

This chapter provides conceptual information about the Yocto Project kernel:

- Kernel Goals

- Yocto Project Kernel Development and Maintenance Overview

- Kernel Architecture

- Kernel Tools

## Kernel Goals

The complexity of embedded kernel design has increased dramatically. Whether it is managing multiple implementations of a particular feature or tuning and optimizing board specific features, flexibility and maintainability are key concerns. The Yocto Project Linux kernel is presented with the embedded developer's needs in mind and has evolved to assist in these key concerns. For example, prior methods such as applying hundreds of patches to an extracted tarball have been replaced with proven techniques that allow easy inspection, bisection and analysis of changes. Application of these techniques also creates a platform for performing integration and collaboration with the thousands of upstream development projects.

With all these considerations in mind, the Yocto Project kernel and development team strives to attain these goals:

- Allow the end user to leverage community best practices to seamlessly manage the development, build and debug cycles.

- Create a platform for performing integration and collaboration with the thousands of upstream development projects that exist.

- Provide mechanisms that support many different work flows, front-ends and management techniques.

- Deliver the most up-to-date kernel possible while still ensuring that the baseline kernel is the most stable official release.

- Include major technological features as part of Yocto Project's upward revision strategy.

- Present a kernel Git repository that, similar to the upstream `kernel.org` tree, has a clear and continuous history.

- Deliver a key set of supported kernel types, where each type is tailored to meet a specific use (e.g. networking, consumer, devices, and so forth).

- Employ a Git branching strategy that, from a developer's point of view, results in a linear path from the baseline `kernel.org`, through a select group of features and ends with their BSP-specific commits.

## Yocto Project Kernel Development and Maintenance Overview

The Yocto Project kernel, like other kernels, is based off the Linux kernel release from . At the beginning of a major development cycle, the Yocto Project team chooses its Yocto Project kernel based on factors like release timing, the anticipated release timing of final upstream `kernel.org` versions, and Yocto Project feature requirements. Typically, the kernel chosen is in the final stages of development by the community. In other words, the kernel is in the release candidate or "rc" phase and not yet a final release. But, by being in the final stages of external development, the team knows that the `kernel.org` final release will clearly be within the early stages of the Yocto Project development window.

This balance allows the team to deliver the most up-to-date kernel as possible, while still ensuring that the team has a stable official release for the baseline kernel version.

The ultimate source for the Yocto Project kernel is a released kernel from `kernel.org`. In addition to a foundational kernel from `kernel.org`, the released Yocto Project kernel contains a mix of important new mainline developments, non-mainline developments (when there is no alternative), Board Support Package (BSP) developments, and custom features. These additions result in a commercially released Yocto Project kernel that caters to specific embedded designer needs for targeted hardware.

Once a Yocto Project kernel is officially released, the Yocto Project team goes into their next development cycle, or upward revision (uprev) cycle, while still continuing maintenance on the released kernel. It is important to note that the most sustainable and stable way to include feature development upstream is through a kernel uprev process. Back-porting hundreds of individual fixes and minor features from various kernel versions is not sustainable and can easily compromise quality.

During the uprev cycle, the Yocto Project team uses an ongoing analysis of kernel development, BSP support, and release timing to select the best possible `kernel.org` version. The team continually monitors community kernel development to look for significant features of interest. The team does consider back-porting large features if they have a significant advantage. User or community demand can also trigger a back-port or creation of new functionality in the Yocto Project baseline kernel during the uprev cycle.

Generally speaking, every new kernel both adds features and introduces new bugs. These consequences are the basic properties of upstream kernel development and are managed by the Yocto Project team's kernel strategy. It is the Yocto Project team's policy to not back-port minor features to the released kernel. They only consider back-porting significant technological jumps - and, that is done after a complete gap analysis. The reason for this policy is that back-porting any small to medium sized change from an evolving kernel can easily create mismatches, incompatibilities and very subtle errors.

These policies result in both a stable and a cutting edge kernel that mixes forward ports of existing features and significant and critical new functionality. Forward porting functionality in the Yocto Project kernel can be thought of as a "micro uprev." The many “micro uprevs” produce a kernel version with a mix of important new mainline, non-mainline, BSP developments and feature integrations. This kernel gives insight into new features and allows focused amounts of testing to be done on the kernel, which prevents surprises when selecting the next major uprev. The quality of these cutting edge kernels is evolving and the kernels are used in leading edge feature and BSP development.

## Kernel Architecture

This section describes the architecture of the Yocto Project kernel and provides information on the mechanisms used to achieve that architecture.

### Overview

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 the upstream `kernel.org`.

You can think of the Yocto Project kernel as consisting of a baseline 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 source code manager (SCM) Git. For information on Git as applied to the Yocto Project, see the "Git" section in the Yocto Project Development Manual.

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 kernel.

The following illustration shows the conceptual Yocto Project kernel.

In the illustration, the "Kernel.org Branch Point" marks the specific spot (or release) from which the Yocto Project kernel is created. From this point "up" 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 up the tree. Placing these common features in the tree this way means features don't have to be duplicated along individual branches of the structure.

From the Yocto Project Baseline Kernel, branch points represent specific functionality for individual 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 a real-time kernel.

In this example structure, the real-time kernel branch has common features for all real-time 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 kernel needed for any given set of requirements.

### 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 not 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.

### Source Code Manager - Git

The Source Code Manager (SCM) is Git. This SCM is the obvious mechanism for meeting the previously mentioned goals. Not only is it the SCM for `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 Development Manual. These referenced sections overview Git and describe a minimal set of commands that allow 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 Master" in order to use it with the Yocto Project.

## Kernel Configuration

Kernel configuration, along with kernel features, defines how a Linux Yocto kernel image is built. Through configuration settings, you can customize a Linux Yocto kernel to be specific to particular hardware. For example, you can specify sound support or networking support. This section describes basic concepts behind Kernel configuration within the Yocto Project and references you to other areas for specific configuration applications.

Conceptually, Linux Yocto kernel configuration occurs similarly to that needed for any Linux kernel. The Linux Yocto kernel build process uses a `.config` file, which is created through the Linux Kernel Coinfiguration (LKC) tool. You can directly set various configurations in the `.config` file by using the `menuconfig` tool as built by BitBake. You can also define configurations in the file by using configuration fragments.

It is not recommended that you edit the `.config` file directly.

Here are some brief descriptions of the ways you can affect the `.config` file:

- The `menuconfig` Tool: One of many front-ends that allows you to define kernel configurations. Some others are `make config`, `make nconfig`, and `make gconfig`. In the Yocto Project environment, you must use BitBake to build the `menuconfig` tool before you can use it to define configurations:

           $ bitbake linux-yocto -c menuconfig

  After the tool is built, you can interact with it normally. You can see how `menuconfig` is used to change a simple kernel configuration in the "Changing the `CONFIG_SMP` Configuration Using `menuconfig`" section of The Yocto Project Development Manual. For general information on `menuconfig`, see .

- Configuration Fragments: A file with a list of kernel options just as they would appear syntactically in the `.config` file. Configuration fragments are typically logical groupings and are assembled by the Yocto Project build system to produce input used by the LKC that ultimately generates the `.config` file.

  The `KERNEL_FEATURES` variable can be used to list configuration fragments. For further discussion on applying configuration fragments, see the "Linux Kernel Configuration" section in the Yocto Project Board Support Package (BSP) Guide.

## Kernel Tools

Since most standard workflows involve moving forward with an existing tree by continuing to add and alter the underlying baseline, the tools that manage the Yocto Project's kernel construction are largely hidden from the developer to present a simplified view of the kernel for ease of use.

Fundamentally, the kernel tools that manage and construct the Yocto Project kernel accomplish the following:

- Group patches into named, reusable features.

- Allow top-down control of included features.

- Bind kernel configurations to kernel patches and features.

- Present a seamless Git repository that blends Yocto Project value with the `kernel.org` history and development.