diff options
author | scott-lenovo <scott-lenovo@ubuntu.(none)> | 2013-01-08 07:51:34 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2013-01-16 15:59:16 +0000 |
commit | d176d86a4c4f3eea54bc8da8c61338e2ef39d68c (patch) | |
tree | 06d7567b04b52071472dc9e9e93d0aaab066e0a1 /documentation/kernel-dev/kernel-dev-advanced.xml | |
parent | 545f79bfdd85c98c4a5901334e77534b49ccc631 (diff) | |
download | openembedded-core-contrib-d176d86a4c4f3eea54bc8da8c61338e2ef39d68c.tar.gz |
kernel-dev: edits to the "Kernel Metadata Syntax" section.
First real re-write of this section.
(From yocto-docs rev: 41c79da0832c0b290b21cc2aff87091d7243fafa)
Signed-off-by: scott-lenovo <scott-lenovo@ubuntu.(none)>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-advanced.xml')
-rw-r--r-- | documentation/kernel-dev/kernel-dev-advanced.xml | 147 |
1 files changed, 82 insertions, 65 deletions
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 <filename>meta/cfg/kernel-cache</filename> directory. For more information, see the - "<link linkend='metadata-syntax'>Metadata Syntax</link>" section. + "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section. <note> 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. <title>In-Tree Metadata</title> <para> - 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 + <filename>meta</filename> directory of the Linux kernel sources. + The <filename>meta</filename> directory can be present in the + same repository branch as the sources, + such as "master", or <filename>meta</filename> can be its own + orphan branch. + <note> + 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. + </note> For the purposes of this document, we will discuss all - in-tree metadata as residing below the + in-tree Metadata as residing below the <filename>meta/cfg/kernel-cache</filename> directory. </para> <para> - 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: <literallayout class='monospaced'> meta/ `-- cfg @@ -450,20 +453,21 @@ value when changing the content of files not explicitly listed in the SRC_URI. </para> <para> - To use a specific branch for the metadata, specify the branch - in the <filename>KMETA</filename> variable in your Linux kernel - recipe, for example: + To use a branch different from where the sources reside, + specify the branch in the <filename>KMETA</filename> variable + in your Linux kernel recipe. + Here is an example: <literallayout class='monospaced'> KMETA = "meta" </literallayout> To use the same branch as the sources, set - <filename>KMETA</filename> to the empty string: + <filename>KMETA</filename> to an empty string: <literallayout class='monospaced'> KMETA = "" </literallayout> If you are working with your own sources and want to create an - orphan <filename>meta</filename> branch, you can do so using the - following commands from within your Linux kernel Git repository: + orphan <filename>meta</filename> branch, use these commands + from within your Linux kernel Git repository: <literallayout class='monospaced'> $ git checkout --orphan meta $ git rm -rf . @@ -515,32 +519,33 @@ git repository: </section> </section> -<section id='metadata-syntax'> - <title>Metadata Syntax</title> +<section id='kernel-metadata-syntax'> + <title>Kernel Metadata Syntax</title> <para> - The Yocto Project Linux kernel tools metadata consists of three - primary types of files: <filename>scc</filename> + The kernel Metadata consists of three primary types of files: + <filename>scc</filename> <footnote> <para> <filename>scc</filename> 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 <filename>scc</filename> files to be description files. </para> </footnote> description files, configuration fragments, and patches. The <filename>scc</filename> 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. </para> <para> The <filename>scc</filename> description files are used to define two - fundamental types of metadata: + fundamental types of kernel Metadata: <itemizedlist> <listitem><para>Features</para></listitem> <listitem><para>Board Support Packages (BSPs)</para></listitem> @@ -549,12 +554,12 @@ git repository: <para> 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. + <link linkend='kernel-types'>Kernel types</link> define general + kernel features and policy to be reused in the BSPs. </para> <para> @@ -563,10 +568,11 @@ git repository: </para> <para> - 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: <literallayout class='monospaced'> <base>/ bsp/ @@ -578,44 +584,55 @@ git repository: </para> <para> - The <filename>bsp</filename> 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 <filename>scc</filename> - description file should go is as follows. - If it contains only configuration fragments, it belongs in - <filename>cfg</filename>. - If it contains only source-code fixes, it belongs in - <filename>patches</filename>. - If it encapsulates a major feature, often combining sources and - configurations, it belongs in <filename>features</filename>. - 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 - <filename>ktypes</filename>. + The <filename>bsp</filename> directory contains the + <link linkend='bsp-descriptions'>BSP descriptions</link>. + The remaining directories all contain "features". + Separating <filename>bsp</filename> from the rest of the structure + aids conceptualizing intended usage. + </para> + + <para> + Use these guidelines to help place your <filename>scc</filename> + description files within the structure: + <itemizedlist> + <listitem><para>If your file contains + only configuration fragments, place the file in + <filename>cfg</filename>.</para></listitem> + <listitem><para>If your file contains + only source-code fixes, place the file in + <filename>patches</filename>.</para></listitem> + <listitem><para>If your file encapsulates + a major feature, often combining sources and configurations, + place the file in <filename>features</filename>. + </para></listitem> + <listitem><para>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 <filename>ktypes</filename>. + </para></listitem> + </itemizedlist> </para> <para> - 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 <filename>cfg</filename>, <filename>features</filename>, - <filename>patches</filename>, and <filename>ktypes</filename>, - contain "features" as far as the Yocto Project Linux kernel + 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 <filename>cfg</filename>, + <filename>features</filename>, <filename>patches</filename>, and + <filename>ktypes</filename>, contain "features" as far as the kernel tools are concerned. </para> <para> - Paths used in metadata files are relative to + Paths used in kernel Metadata files are relative to <filename><base></filename>, which is either <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - if you are creating metadata in recipe-space as described in - section "<link linkend='recipe-space-metadata'>Recipe-Space Metadata</link>", + if you are creating Metadata in + <link linkend='recipe-space-metadata'>recipe-space</link>, or <filename>meta/cfg/kernel-cache/</filename> if you are creating - metadata in-tree as described in - the "<link linkend='in-tree-metadata'>In-Tree Metadata</link>" section. + Metadata <link linkend='in-tree-metadata'>in-tree</link>. </para> <para> |