diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index 6618a7c906..380200a633 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -273,11 +273,13 @@
Paths used in kernel Metadata files are relative to
- <base>, which is either
+ base, which is either
FILESEXTRAPATHS
if you are creating Metadata in
recipe-space,
- or yocto-kernel-cache/cfg if you are creating
+ or the top level of
+ yocto-kernel-cache
+ if you are creating
Metadata outside of the recipe-space.
@@ -294,12 +296,18 @@
- The Symmetric Multi-Processing (SMP) fragment included in the
- linux-yocto-3.19 Git repository
- consists of the following two files:
+ As an example, consider the Symmetric Multi-Processing (SMP)
+ fragment used with the linux-yocto-4.12
+ kernel as defined outside of the recipe space (i.e.
+ yocto-kernel-cache).
+ This Metadata consists of two files: smp.scc
+ and smp.cfg.
+ You can find these files in the cfg directory
+ of the yocto-4.12 branch in the
+ yocto-kernel-cache Git repository:
cfg/smp.scc:
- define KFEATURE_DESCRIPTION "Enable SMP"
+ define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
define KFEATURE_COMPATIBILITY all
kconf hardware smp.cfg
@@ -310,20 +318,27 @@
# Increase default NR_CPUS from 8 to 64 so that platform with
# more than 8 processors can be all activated at boot time
CONFIG_NR_CPUS=64
+ # The following is nedded when setting NR_CPUS to something
+ # greater than 8 on x86 architectures, it should be automatically
+ # disregarded by Kconfig when using a different arch
+ CONFIG_X86_BIGSMP=y
- You can find information on configuration fragment files in the
+ You can find general information on configuration fragment files in
+ the
"Creating Configuration Fragments"
section.
+ Within the smp.scc file, the
KFEATURE_DESCRIPTION
- provides a short description of the fragment.
+ statement provides a short description of the fragment.
Higher level kernel tools use this description.
- The kconf command is used to include the
+ Also within the smp.scc file, the
+ kconf command includes the
actual configuration fragment in an .scc
file, and the "hardware" keyword identifies the fragment as
being hardware enabling, as opposed to general policy,
@@ -355,26 +370,71 @@
Patch descriptions are very similar to configuration fragment
descriptions, which are described in the previous section.
However, instead of a .cfg file, these
- descriptions work with source patches.
+ descriptions work with source patches (i.e.
+ .patch files).
- A typical patch includes a description file and the patch itself:
+ A typical patch includes a description file and the patch itself.
+ As an example, consider the build patches used with the
+ linux-yocto-4.12 kernel as defined outside of
+ the recipe space (i.e. yocto-kernel-cache).
+ This Metadata consists of several files:
+ build.scc and a set of
+ *.patch files.
+ You can find these files in the patches/build
+ directory of the yocto-4.12 branch in the
+ yocto-kernel-cache Git repository.
+
+
+
+ The following listings show the build.scc
+ file and part of the
+ modpost-mask-trivial-warnings.patch file:
- patches/mypatch.scc:
- patch mypatch.patch
+ patches/build/build.scc:
+ patch arm-serialize-build-targets.patch
+ patch powerpc-serialize-image-targets.patch
+ patch kbuild-exclude-meta-directory-from-distclean-processi.patch
- patches/mypatch.patch:
- typical-patch
+ # applied by kgit
+ # patch kbuild-add-meta-files-to-the-ignore-li.patch
+
+ patch modpost-mask-trivial-warnings.patch
+ patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
+
+ patches/build/modpost-mask-trivial-warnings.patch:
+ From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
+ From: Paul Gortmaker <paul.gortmaker@windriver.com>
+ Date: Sun, 25 Jan 2009 17:58:09 -0500
+ Subject: [PATCH] modpost: mask trivial warnings
+
+ Newer HOSTCC will complain about various stdio fcns because
+ .
+ .
+ .
+ char *dump_write = NULL, *files_source = NULL;
+ int opt;
+ --
+ 2.10.1
+
+ generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
- You can create the typical .patch
- file using diff -Nurp or
- git format-patch.
+ The description file can include multiple patch statements where
+ each statement handles a single patch.
+ In the example build.scc file, five patch
+ statements exist for the five patches in the directory.
- The description file can include multiple patch statements,
- one per patch.
+ You can create a typical .patch file using
+ diff -Nurp or
+ git format-patch commands.
+ For information on how to create patches, see the
+ "Using devtool to Patch the Kernel"
+ and
+ "Using Traditional Kernel Development to Patch the Kernel"
+ sections.
@@ -383,26 +443,23 @@
Features are complex kernel Metadata types that consist
- of configuration fragments (kconf), patches
- (patch), and possibly other feature
- description files (include).
-
-
-
- Here is an example that shows a feature description file:
+ of configuration fragments, patches, and possibly other feature
+ description files.
+ As an example, consider the following generic listing:
- features/myfeature.scc
- define KFEATURE_DESCRIPTION "Enable myfeature"
+ features/myfeature.scc
+ define KFEATURE_DESCRIPTION "Enable myfeature"
- patch 0001-myfeature-core.patch
- patch 0002-myfeature-interface.patch
+ patch 0001-myfeature-core.patch
+ patch 0002-myfeature-interface.patch
- include cfg/myfeature_dependency.scc
- kconf non-hardware myfeature.cfg
+ include cfg/myfeature_dependency.scc
+ kconf non-hardware myfeature.cfg
This example shows how the patch and
kconf commands are used as well as
- how an additional feature description file is included.
+ how an additional feature description file is included with
+ the include command.
@@ -422,21 +479,47 @@
A kernel type defines a high-level kernel policy by
aggregating non-hardware configuration fragments with
- patches you want to use when building a Linux kernels of a
- specific type.
+ patches you want to use when building a Linux kernel of a
+ specific type (e.g. a real-time kernel).
Syntactically, kernel types are no different than features
as described in the "Features"
section.
- The LINUX_KERNEL_TYPE variable in the kernel
- recipe selects the kernel type.
- See the "Using Kernel Metadata in a Recipe"
- section for more information.
+ The
+ LINUX_KERNEL_TYPE
+ variable in the kernel recipe selects the kernel type.
+ For example, in the linux-yocto_4.12.bb
+ kernel recipe found in
+ poky/meta/recipes-kernel/linux, a
+ require
+ directive includes the
+ poky/meta/recipes-kernel/linux/linux-yocto.inc
+ file, which has the following statement that defines the default
+ kernel type:
+
+ LINUX_KERNEL_TYPE ??= "standard"
+
- As an example, the linux-yocto-3.19
- tree defines three kernel types: "standard",
- "tiny", and "preempt-rt":
+ Another example would be the real-time kernel (i.e.
+ linux-yocto-rt_4.12.bb).
+ This kernel recipe directly sets the kernel type as follows:
+
+ LINUX_KERNEL_TYPE = "preempt-rt"
+
+
+ You can find kernel recipes in the
+ meta/recipes-kernel/linux directory of the
+ Source Directory
+ (e.g. poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb).
+ See the "Using Kernel Metadata in a Recipe"
+ section for more information.
+
+
+
+
+ Three kernel types ("standard", "tiny", and "preempt-rt") are
+ supported for Linux Yocto kernels:
"standard":
Includes the generic Linux kernel policy of the Yocto
@@ -463,29 +546,40 @@
- The "standard" kernel type is defined by
- standard.scc:
+ For any given kernel type, the Metadata is defined by the
+ .scc (e.g. standard.scc).
+ Here is a partial listing for the standard.scc
+ file, which is found in the ktypes/standard
+ directory of the yocto-kernel-cache Git
+ repository:
# Include this kernel type fragment to get the standard features and
# configuration values.
- # Include all standard features
- include standard-nocfg.scc
+ # Note: if only the features are desired, but not the configuration
+ # then this should be included as:
+ # include ktypes/standard/standard.scc nocfg
+ # if no chained configuration is desired, include it as:
+ # include ktypes/standard/standard.scc nocfg inherit
+
+
+
+ include ktypes/base/base.scc
+ branch standard
kconf non-hardware standard.cfg
- # individual cfg block section
- include cfg/fs/devtmpfs.scc
- include cfg/fs/debugfs.scc
- include cfg/fs/btrfs.scc
- include cfg/fs/ext2.scc
- include cfg/fs/ext3.scc
- include cfg/fs/ext4.scc
+ include features/kgdb/kgdb.scc
+ .
+ .
+ .
- include cfg/net/ipv6.scc
- include cfg/net/ip_nf.scc
include cfg/net/ip6_nf.scc
include cfg/net/bridge.scc
+
+ include cfg/systemd.scc
+
+ include features/rfkill/rfkill.scc
@@ -531,9 +625,9 @@
- This section provides a BSP description structural overview along
- with aggregation concepts as well as a detailed example using
- a BSP supported by the Yocto Project (i.e. Minnow Board).
+ This section overviews the BSP description structure, the
+ aggregation concepts, and presents a detailed example using
+ a BSP supported by the Yocto Project (i.e. BeagleBone Board).
@@ -541,7 +635,7 @@
For simplicity, consider the following top-level BSP
- description file.
+ description files for the BeagleBone board.
Top-level BSP descriptions files employ both a structure
and naming convention for consistency.
The naming convention for the file is as follows:
@@ -549,31 +643,30 @@
bsp_name-kernel_type.scc
Here are some example top-level BSP filenames for the
- Minnow Board BSP, which is supported by the Yocto Project:
+ BeagleBone Board BSP, which is supported by the Yocto Project:
- minnow-standard.scc
- minnow-preempt-rt.scc
- minnow-tiny.scc
+ beaglebone-standard.scc
+ beaglebone-preempt-rt.scc
Each file uses the BSP name followed by the kernel type.
- is simple BSP description file whose name has the
- form
- mybsp-standard
- and supports the mybsp machine using
- a standard kernel:
+ Examine the beaglebone-standard.scc
+ file:
- define KMACHINE mybsp
+ define KMACHINE beaglebone
define KTYPE standard
- define KARCH i386
+ define KARCH arm
- include ktypes/standard
+ include ktypes/standard/standard.scc
+ branch beaglebone
- include mybsp.scc
+ include beaglebone.scc
- kconf hardware mybsp-extra.cfg
+ # default policy for standard kernels
+ include features/latencytop/latencytop.scc
+ include features/profiling/profiling.scc
Every top-level BSP description file should define the
KMACHINE,
@@ -583,19 +676,20 @@
These variables allow the OpenEmbedded build system to identify
the description as meeting the criteria set by the recipe being
built.
- This simple example supports the "mybsp" machine for the "standard"
- kernel and the "i386" architecture.
+ This example supports the "beaglebone" machine for the
+ "standard" kernel and the "arm" architecture.
Be aware that a hard link between the
- KTYPE variable and a kernel type description
- file does not exist.
- Thus, if you do not have kernel types defined in your kernel
- Metadata, you only need to ensure that the kernel recipe's
+ KTYPE variable and a kernel type
+ description file does not exist.
+ Thus, if you do not have the kernel type defined in your kernel
+ Metadata as it is here, you only need to ensure that the
LINUX_KERNEL_TYPE
- variable and the KTYPE variable in the
- BSP description file match.
+ variable in the kernel recipe and the
+ KTYPE variable in the BSP descriptionn
+ file match.
Future versions of the tooling make the specification of
KTYPE in the BSP optional.
@@ -608,13 +702,12 @@
"standard".
In the previous example, this is done using the following:
- include ktypes/standard
+ include ktypes/standard/standard.scc
- In the previous example, ktypes/standard.scc
- aggregates all the configuration fragments, patches, and
- features that make up your standard kernel policy.
- See the "Kernel Types" section
- for more information.
+ This file aggregates all the configuration fragments, patches,
+ and features that make up your standard kernel policy.
+ See the "Kernel Types"
+ section for more information.
@@ -622,6 +715,10 @@
kernel for mybsp, use the following:
include mybsp.scc
+
+ You can see that in the BeagleBone example with the following:
+
+ include beaglebone.scc
For information on how to break a complete
.config file into the various
@@ -637,6 +734,23 @@
kconf hardware mybsp-extra.cfg
+ The BeagleBone example does not include these types of
+ configurations.
+ However, the Malta 32-bit board does ("mti-malta32").
+ Here is the mti-malta32-le-standard.scc
+ file:
+
+ define KMACHINE mti-malta32-le
+ define KMACHINE qemumipsel
+ define KTYPE standard
+ define KARCH mips
+
+ include ktypes/standard/standard.scc
+ branch mti-malta32
+
+ include mti-malta32.scc
+ kconf hardware mti-malta32-le.cfg
+
@@ -647,14 +761,15 @@
Many real-world examples are more complex.
Like any other .scc file, BSP
descriptions can aggregate features.
- Consider the Minnow BSP definition from the
- linux-yocto-4.4 in the
- Yocto Project
- Source Repositories
- (i.e.
- yocto-kernel-cache/bsp/minnow):
+ Consider the Minnow BSP definition given the
+ linux-yocto-4.4 branch of the
+ yocto-kernel-cache (i.e.
+ yocto-kernel-cache/bsp/minnow/minnow.scc):
+
+ Although the Minnow Board BSP is unused, the Metadata
+ remains and is being used here just as an example.
+
- minnow.scc:
include cfg/x86.scc
include features/eg20t/eg20t.scc
include cfg/dmaengine.scc
@@ -690,9 +805,8 @@
"minnow" description files for the supported kernel types
(i.e. "standard", "preempt-rt", and "tiny").
Consider the "minnow" description for the "standard" kernel
- type:
+ type (i.e. minnow-standard.scc:
- minnow-standard.scc:
define KMACHINE minnow
define KTYPE standard
define KARCH i386
@@ -727,9 +841,8 @@
Now consider the "minnow" description for the "tiny" kernel
- type:
+ type (i.e. minnow-tiny.scc:
- minnow-tiny.scc:
define KMACHINE minnow
define KTYPE tiny
define KARCH i386
@@ -749,10 +862,12 @@
Notice again the three critical variables:
- KMACHINE, KTYPE,
- and KARCH.
- Of these variables, only the KTYPE has changed.
- It is now set to "tiny".
+ KMACHINE,
+ KTYPE,
+ and
+ KARCH.
+ Of these variables, only KTYPE
+ has changed to specify the "tiny" kernel type.