diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 4fdb853f92..9e15f178a6 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -29,8 +29,8 @@ source Git repositories. This Metadata defines Board Support Packages (BSPs) that correspond to definitions in linux-yocto recipes for the same BSPs. - A BSP consists of an aggregation of kernel policy and hardware-specific - feature enablements. + A BSP consists of an aggregation of kernel policy and enabled + hardware-specific features. The BSP can be influenced from within the linux-yocto recipe. Linux kernel source that contains kernel Metadata is said to be @@ -171,8 +171,8 @@ Kernel Metadata Location - Kernel Metadata can be defined in either the kernel recipe - (recipe-space) or in the kernel tree (in-tree). + Kernel Metadata always exists outside of the kernel tree either + defined in a kernel recipe (recipe-space) or outside of the recipe. Where you choose to define the Metadata depends on what you want to do and how you intend to work. Regardless of where you define the kernel Metadata, the syntax used @@ -195,10 +195,10 @@ Conversely, if you are actively developing a kernel and are already maintaining a Linux kernel Git repository of your own, you might find - it more convenient to work with the kernel Metadata in the same - repository as the Linux kernel sources. - This method can make iterative development of the Linux kernel - more efficient outside of the BitBake environment. + it more convenient to work with kernel Metadata kept outside the + recipe-space. + Working with Metadata in this area can make iterative development of + the Linux kernel more efficient outside of the BitBake environment.
@@ -249,38 +249,52 @@
-
- In-Tree Metadata +
+ Metadata Outside the Recipe-Space - When stored in-tree, the kernel Metadata files reside in the - meta directory of the Linux kernel sources. - The meta directory can be present in the - same repository branch as the sources, - such as "master", or meta can be its own - orphan branch. - - An orphan branch in Git is a branch with unique history and - content to the other branches in the repository. - Orphan branches are useful to track Metadata changes - independently from the sources of the Linux kernel, while - still keeping them together in the same repository. - - For the purposes of this document, we will discuss all - in-tree Metadata as residing below the - meta/cfg/kernel-cache directory. + When stored outside of the recipe-space, the kernel Metadata + files reside in a separate repository. + The OpenEmbedded build system adds the Metadata to the build as + a "ktype=meta" repository through the + SRC_URI + variable. + As an example, consider the following SRC_URI + statement from the linux-yocto_4.4.bb + kernel recipe: + + SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.4.git;name=machine;branch=${KBRANCH}; \ + git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.4;destsuffix=${KMETA}" + + ${KMETA}, in this context, is simply used to + name the directory into which the Git fetcher places the Metadata. + This behavior is no different than any multi-repository + SRC_URI statement used in a recipe. + + You can keep kernel Metadata in a "kernel-cache", which is a + directory containing configuration fragments. + As with any Metadata kept outside the recipe-space, you simply + need to use the SRC_URI statement with the + "type=kmeta" attribute. + Doing so makes the kernel Metadata available during the + configuration phase. + + + - If you modify the Metadata in the linux-yocto - meta branch, you must not forget to update - the + If you modify the Metadata, you must not forget to update the SRCREV statements in the kernel's recipe. In particular, you need to update the @@ -437,7 +450,7 @@ if you are creating Metadata in recipe-space, or meta/cfg/kernel-cache/ if you are creating - Metadata in-tree. + Metadata outside of the recipe-space.