diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index f14ed69586..768b66450b 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -368,7 +368,7 @@ described in the following sections applies equally. .scc files by the include, patch, or kconf commands. Because of this, it is necessary to bump the recipe - PR + PR value when changing the content of files not explicitly listed in the SRC_URI. @@ -499,6 +499,174 @@ git repository: + + +
+ Metadata Syntax + + + The Yocto Project Linux kernel tools 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. + + + 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 + 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: + + Features + Board Support Packages (BSPs) + + + + + 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. + + + + BSPs define hardware-specific features and aggregate them with kernel + types to form the final description of what will be assembled and built. + + + + 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: + + <base>/ + bsp/ + cfg/ + features/ + ktypes/ + patches/ + + + + + 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 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 + tools are concerned. + + + + Paths used in 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", + or meta/cfg/kernel-cache/ if you are creating + metadata in-tree as described in + the "In-Tree Metadata" section. + + + + Original text: + +The Yocto Project Linux kernel tools meta-data consists of three primary types +of files: scc* 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 meta-data 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 meta-data: + o Features + o BSPs + +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 meta-data 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. + +BSPs define hardware-specific features and aggregate them with kernel types to +form the final description of what will be assembled and built. + +While the meta-data 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 +meta-data file hierarchy is recommended: + + <base>/ + bsp/ + cfg/ + features/ + ktypes/ + patches/ + +The bsp directory should contain the BSP descriptions, described in detail in +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 line 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 meta-data as +all of cfg, features, patches, and ktypes, contain "features" as far as the +Yocto Project Linux kernel tools are concerned. + +Paths used in meta-data files are relative to <base> which is either +FILESEXTRAPATHS if you are creating meta-data in recipe-space (see 3.2.1), or +meta/cfg/kernel-cache/ if you are creating meta-data in-tree (see 3.2.2). + +* 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. + + + + + +