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