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>
This commit is contained in:
scott-lenovo
Richard Purdie
parent
545f79bfdd
commit
d176d86a4c
|
|
@ -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>
|
||||
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
|
||||
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>
|
||||
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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue