diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 87819903bb..c069ddfb08 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -188,7 +188,7 @@ to source changes. and "cfg" are subdirectories within the meta/cfg/kernel-cache directory. For more information, see the - "Metadata Syntax" section. + "Kernel Metadata Syntax" section. The processing of the these variables has evolved some between the 0.9 and 1.3 releases of the Yocto Project and associated @@ -421,24 +421,27 @@ value when changing the content of files not explicitly listed in the SRC_URI. In-Tree Metadata - When stored in-tree, the metadata files reside in the - "meta" directory of the Linux kernel sources. - They may be present in the same branch as the sources, - such as "master", or in their own orphan branch, - typically named "meta". - An orphan branch in Git is a branch with unique history and - content to the other branches in the repository. - This is useful to track metadata changes independently from the - sources of the Linux kernel, while still keeping them - together in the same repository. + 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 + in-tree Metadata as residing below the meta/cfg/kernel-cache directory. - By way of example, a trivial tree of metadata stored in a custom - Linux kernel Git repository might look like the following: + Following is an example that shows how a trivial tree of Metadata + is stored in a custom Linux kernel Git repository: meta/ `-- cfg @@ -450,20 +453,21 @@ value when changing the content of files not explicitly listed in the SRC_URI. - To use a specific branch for the metadata, specify the branch - in the KMETA variable in your Linux kernel - recipe, for example: + To use a branch different from where the sources reside, + specify the branch in the KMETA variable + in your Linux kernel recipe. + Here is an example: KMETA = "meta" To use the same branch as the sources, set - KMETA to the empty string: + KMETA to an empty string: KMETA = "" If you are working with your own sources and want to create an - orphan meta branch, you can do so using the - following commands from within your Linux kernel Git repository: + orphan meta branch, use these commands + from within your Linux kernel Git repository: $ git checkout --orphan meta $ git rm -rf . @@ -515,32 +519,33 @@ git repository: -
- Metadata Syntax +
+ Kernel Metadata Syntax - The Yocto Project Linux kernel tools metadata consists of three - primary types of files: scc + The kernel Metadata consists of three primary types of files: + scc scc stands for Series Configuration Control, but the naming has less significance in the current implementation of the tooling than it had in the past. - Consider it to be a description file. + Consider scc files to be description files. description files, configuration fragments, and patches. The scc files define variables and include or otherwise reference any of the three file types. - The description files are used to aggregate all types of metadata into + The description files are used to aggregate all types of kernel + Metadata into what ultimately describes the sources and the configuration required to build a Linux kernel tailored to a specific machine. The scc description files are used to define two - fundamental types of metadata: + fundamental types of kernel Metadata: Features Board Support Packages (BSPs) @@ -549,12 +554,12 @@ git repository: Features aggregate sources in the form of patches and configuration - in the form of configuration fragments into a modular reusable unit. - Features are used to implement conceptually separate metadata - descriptions like pure configuration fragments, simple patches, - complex features, and kernel types (ktypes). - Kernel types define general kernel features and policy to be reused - in the BSPs. + fragments into a modular reusable unit. + You can use features to implement conceptually separate kernel + Metadata descriptions such as pure configuration fragments, + simple patches, complex features, and kernel types. + Kernel types define general + kernel features and policy to be reused in the BSPs. @@ -563,10 +568,11 @@ git repository: - While the metadata syntax does not enforce any logical separation of - configuration fragments, patches, features or kernel types, best - practices dictate a logical separation of these types of meta-data. - The following metadata file hierarchy is recommended: + While the kernel Metadata syntax does not enforce any logical + separation of configuration fragments, patches, features or kernel + types, best practices dictate a logical separation of these types + of Metadata. + The following Metadata file hierarchy is recommended: <base>/ bsp/ @@ -578,44 +584,55 @@ git repository: - The bsp directory should contain the - BSP descriptions, described in detail in section 3.3.5. - The remaining directories all contain "features"; the separation - is meant to aid in conceptualizing their intended usage. - A simple guide to determine where your scc - description file should go is as follows. - If it contains only configuration fragments, it belongs in - cfg. - If it contains only source-code fixes, it belongs in - patches. - If it encapsulates a major feature, often combining sources and - configurations, it belongs in features. - If it aggregates non-hardware configuration and patches - in order to define a base kernel policy or major kernel type to - be reused across multiple BSPs, it belongs in - ktypes. + The bsp directory contains the + BSP descriptions. + The remaining directories all contain "features". + Separating bsp from the rest of the structure + aids conceptualizing intended usage. - The lines between these can easily become blurred, especially as - out-of-tree features are slowly merged upstream over time. - Also remember that this is purely logical organization and has - no impact on the functionality of the metadata as - all of cfg, features, - patches, and ktypes, - contain "features" as far as the Yocto Project Linux kernel + Use these guidelines to help place your scc + description files within the structure: + + If your file contains + only configuration fragments, place the file in + cfg. + If your file contains + only source-code fixes, place the file in + patches. + If your file encapsulates + a major feature, often combining sources and configurations, + place the file in features. + + If your file aggregates + non-hardware configuration and patches in order to define a + base kernel policy or major kernel type to be reused across + multiple BSPs, place the file in ktypes. + + + + + + These distinctions can easily become blurred - especially as + out-of-tree features slowly merge upstream over time. + Also, remember that how the description files are placed is + a purely logical organization and has no impact on the functionality + of the kernel Metadata. + There is no impact because all of cfg, + features, patches, and + ktypes, contain "features" as far as the kernel tools are concerned. - Paths used in metadata files are relative to + Paths used in kernel Metadata files are relative to <base>, which is either FILESEXTRAPATHS - if you are creating metadata in recipe-space as described in - section "Recipe-Space Metadata", + if you are creating Metadata in + recipe-space, or meta/cfg/kernel-cache/ if you are creating - metadata in-tree as described in - the "In-Tree Metadata" section. + Metadata in-tree.