diff options
author | Andrew Geissler <geissonator@yahoo.com> | 2020-10-16 18:22:50 +0300 |
---|---|---|
committer | Andrew Geissler <geissonator@yahoo.com> | 2020-10-19 20:45:27 +0300 |
commit | af5e4ef732faedf66c6dc1756432e9de2ac72988 (patch) | |
tree | 8f49154a7382b1beb2c3a2b50a6e7c632484fa25 /poky/documentation/kernel-dev | |
parent | 36fe5df200a94e3ce82ba2dcad16c0a4127f6d46 (diff) | |
download | openbmc-af5e4ef732faedf66c6dc1756432e9de2ac72988.tar.xz |
poky: subtree update:b23aa6b753..ad30a6d470
Armin Kuster (1):
timezone: update to 2020b
Bruce Ashfield (7):
linux-yocto/5.4: fix kprobes build warning
linux-yocto/5.4: update to v5.4.67
linux-yocto/5.8: update to v5.8.11
linux-yocto/5.4: update to v5.4.68
linux-yocto/5.8: update to v5.8.12
linux-yocto/5.4: update to v5.4.69
linux-yocto/5.8: update to v5.8.13
Fabio Berton (1):
weston-init: Add environment file support for systemd unit file
Jon Mason (5):
armv8/tunes: Move TUNECONFLICTS
armv8/tunes: reference parent's TUNE_FEATURES
armv8/tunes: Add tunes for supported ARMv8a cores
armv8/tunes: Add tunes for supported ARMv8.2a cores
tune-cortexa32: fix cortexa32 tune
Joshua Watt (2):
classes/sanity: Bump minimum python version to 3.5
classes/waf: Add build and install arguments
Khem Raj (3):
systemd: Use ROOTPREFIX without suffixed slash in systemd.pc.in
musl: Update to master
strace: Fix value of IPPROTO_MAX
Martin Jansa (3):
base.bbclass: use os.path.normpath instead of just comparing WORKDIR and S as strings
mtd-utils: don't use trailing slash in S
base.bbclass: warn when there is trailing slash in S or B variables
Michael Thalmeier (1):
IMAGE_LOCALES_ARCHIVE: add option to prevent locale archive creation
Naoki Hayama (3):
uninative: Fix typo in error message
local.conf.sample: Fix comment typo
local.conf.sample.extended: Fix comment typo
Naveen Saini (2):
linux-yocto: update genericx86* SRCREV for 5.4
linux-yocto: update genericx86* SRCREV for 5.8
Nicolas Dechesne (8):
bitbake: docs: ref-variables: add links to terms in glossary
bitbake: docs: sphinx: replace special quotes with double quotes
bitbake: docs: update README file after migrationg to Sphinx
bitbake: docs: sphinx: report errors when dependencies are not met
bitbake: sphinx: remove DocBook files
bitbake: sphinx: rename Makefile.sphinx
sphinx: remove DocBook files
sphinx: rename Makefile.sphinx
Peter Kjellerstedt (1):
tune-cortexa65.inc: Correct TUNE_FEATURES_tune-cortexa65
Quentin Schulz (4):
docs: ref-manual: ref-variables: fix one-letter pointer links in glossary
docs: ref-manual: ref-variables: fix alphabetical order in glossary
docs: ref-manual: ref-variables: add links to terms in glossary
bitbake: docs: static: theme_overrides.css: fix responsive design on <640px screens
Richard Purdie (25):
glibc: do_stash_locale must not delete files from ${D}
libtools-cross/shadow-sysroot: Use nopackages inherit
pseudo: Ignore mismatched inodes from the db
pseudo: Add support for ignoring paths from the pseudo DB
pseudo: Abort on mismatch patch
psuedo: Add tracking of linked files for fds
pseudo: Fix xattr segfault
pseudo: Add may unlink patch
pseudo: Add pathfix patch
base/bitbake.conf: Enable pseudo path filtering
wic: Handle new PSEUDO_IGNORE_PATHS variable
pseudo: Fix statx function usage
bitbake.conf: Extend PSEUDO_IGNORE_PATHS to ${COREBASE}/meta
docs: Fix license CC-BY-2.0-UK -> CC-BY-SA-2.0-UK
abi_version,sanity: Tell users TMPDIR must be clean after pseudo changes
pseudo: Update to account for patches merged on branch
pseudo: Upgrade to include mkostemp64 wrapper
poky.conf: Drop OELAYOUT_ABI poking
bitbake: command: Ensure exceptions inheriting from BBHandledException are visible
bitbake: tinfoil: When sending commands we need to process events
scripts/oe-build-perf-report: Allow operation with no buildstats
oe-build-perf-report: Ensure correct data is shown for multiple branch options
skeleton/baremetal-helloworld: Fix trailing slash
oeqa/selftest/runtime_test: Exclude gpg directory from pseudo database
bitbake: process: Show command exceptions in the server log as well
Ross Burton (10):
bjam-native: don't do debug builds
coreutils: improve coreutils-ptest RDEPENDS
parted: improve ptest
devtool: remove unused variable
selftest: skip npm tests if nodejs-native isn't available
selftest: add test for recipes with patches in overrides
devtool: fix modify with patches in override directories
boost: build a standalone boost.build
boost: don't specify gcc version
boost: consolidate and update library list
Usama Arif (1):
kernel-fitimage: generate openssl RSA keys for signing fitimage
Victor Kamensky (2):
qemu: add 34Kf-64tlb fictitious cpu type
qemumips: use 34Kf-64tlb CPU emulation
Yann Dirson (1):
rngd: fix --debug to also filter syslog() calls
Yoann Congal (1):
bitbake-bblayers/create: Make the example recipe print its message
Signed-off-by: Andrew Geissler <geissonator@yahoo.com>
Change-Id: I7139cb04b43f722a2118df5346a7a22a13c6a240
Diffstat (limited to 'poky/documentation/kernel-dev')
17 files changed, 8 insertions, 6583 deletions
diff --git a/poky/documentation/kernel-dev/history.rst b/poky/documentation/kernel-dev/history.rst index 3ffb7eacb..761b506ac 100644 --- a/poky/documentation/kernel-dev/history.rst +++ b/poky/documentation/kernel-dev/history.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK *********************** Manual Revision History diff --git a/poky/documentation/kernel-dev/kernel-dev-advanced.rst b/poky/documentation/kernel-dev/kernel-dev-advanced.rst index 36133caae..eeb8f8792 100644 --- a/poky/documentation/kernel-dev/kernel-dev-advanced.rst +++ b/poky/documentation/kernel-dev/kernel-dev-advanced.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK ******************************************************* Working with Advanced Metadata (``yocto-kernel-cache``) diff --git a/poky/documentation/kernel-dev/kernel-dev-advanced.xml b/poky/documentation/kernel-dev/kernel-dev-advanced.xml deleted file mode 100644 index 37177966b..000000000 --- a/poky/documentation/kernel-dev/kernel-dev-advanced.xml +++ /dev/null @@ -1,1257 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<chapter id='kernel-dev-advanced'> -<title>Working with Advanced Metadata (<filename>yocto-kernel-cache</filename>)</title> - -<section id='kernel-dev-advanced-overview'> - <title>Overview</title> - - <para> - In addition to supporting configuration fragments and patches, the - Yocto Project kernel tools also support rich - <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> that you can - use to define complex policies and Board Support Package (BSP) support. - The purpose of the Metadata and the tools that manage it is - to help you manage the complexity of the configuration and sources - used to support multiple BSPs and Linux kernel types. - </para> - - <para> - Kernel Metadata exists in many places. - One area in the Yocto Project - <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> - is the <filename>yocto-kernel-cache</filename> Git repository. - You can find this repository grouped under the "Yocto Linux Kernel" - heading in the - <ulink url='&YOCTO_GIT_URL;'>Yocto Project Source Repositories</ulink>. - </para> - - <para> - Kernel development tools ("kern-tools") exist also in the Yocto - Project Source Repositories under the "Yocto Linux Kernel" heading - in the <filename>yocto-kernel-tools</filename> Git repository. - The recipe that builds these tools is - <filename>meta/recipes-kernel/kern-tools/kern-tools-native_git.bb</filename> - in the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> - (e.g. <filename>poky</filename>). - </para> -</section> - -<section id='using-kernel-metadata-in-a-recipe'> - <title>Using Kernel Metadata in a Recipe</title> - - <para> - As mentioned in the introduction, the Yocto Project contains kernel - Metadata, which is located in the - <filename>yocto-kernel-cache</filename> Git repository. - This Metadata defines Board Support Packages (BSPs) that - correspond to definitions in linux-yocto recipes for corresponding BSPs. - A BSP consists of an aggregation of kernel policy and enabled - hardware-specific features. - The BSP can be influenced from within the linux-yocto recipe. - <note> - A Linux kernel recipe that contains kernel Metadata (e.g. - inherits from the <filename>linux-yocto.inc</filename> file) - is said to be a "linux-yocto style" recipe. - </note> - </para> - - <para> - Every linux-yocto style recipe must define the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> - variable. - This variable is typically set to the same value as the - <filename>MACHINE</filename> variable, which is used by - <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>. - However, in some cases, the variable might instead refer to the - underlying platform of the <filename>MACHINE</filename>. - </para> - - <para> - Multiple BSPs can reuse the same <filename>KMACHINE</filename> - name if they are built using the same BSP description. - Multiple Corei7-based BSPs could share the same "intel-corei7-64" - value for <filename>KMACHINE</filename>. - It is important to realize that <filename>KMACHINE</filename> is - just for kernel mapping, while <filename>MACHINE</filename> - is the machine type within a BSP Layer. - Even with this distinction, however, these two variables can hold - the same value. - See the <link linkend='bsp-descriptions'>BSP Descriptions</link> - section for more information. - </para> - - <para> - Every linux-yocto style recipe must also indicate the Linux kernel - source repository branch used to build the Linux kernel. - The <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> - variable must be set to indicate the branch. - <note> - You can use the <filename>KBRANCH</filename> value to define an - alternate branch typically with a machine override as shown here - from the <filename>meta-yocto-bsp</filename> layer: - <literallayout class='monospaced'> - KBRANCH_edgerouter = "standard/edgerouter" - </literallayout> - </note> - </para> - - <para> - The linux-yocto style recipes can optionally define the following - variables: - <literallayout class='monospaced'> - KERNEL_FEATURES - LINUX_KERNEL_TYPE - </literallayout> - </para> - - <para> - <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> - defines the kernel type to be - used in assembling the configuration. - If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>, - it defaults to "standard". - Together with <filename>KMACHINE</filename>, - <filename>LINUX_KERNEL_TYPE</filename> defines the search - arguments used by the kernel tools to find the - appropriate description within the kernel Metadata with which to - build out the sources and configuration. - The linux-yocto recipes define "standard", "tiny", and "preempt-rt" - kernel types. - See the "<link linkend='kernel-types'>Kernel Types</link>" section - for more information on kernel types. - </para> - - <para> - During the build, the kern-tools search for the BSP description - file that most closely matches the <filename>KMACHINE</filename> - and <filename>LINUX_KERNEL_TYPE</filename> variables passed in from the - recipe. - The tools use the first BSP description it finds that match - both variables. - If the tools cannot find a match, they issue a warning. - </para> - - <para> - The tools first search for the <filename>KMACHINE</filename> and - then for the <filename>LINUX_KERNEL_TYPE</filename>. - If the tools cannot find a partial match, they will use the - sources from the <filename>KBRANCH</filename> and any configuration - specified in the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. - </para> - - <para> - You can use the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> - variable - to include features (configuration fragments, patches, or both) that - are not already included by the <filename>KMACHINE</filename> and - <filename>LINUX_KERNEL_TYPE</filename> variable combination. - For example, to include a feature specified as - "features/netfilter/netfilter.scc", - specify: - <literallayout class='monospaced'> - KERNEL_FEATURES += "features/netfilter/netfilter.scc" - </literallayout> - To include a feature called "cfg/sound.scc" just for the - <filename>qemux86</filename> machine, specify: - <literallayout class='monospaced'> - KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" - </literallayout> - The value of the entries in <filename>KERNEL_FEATURES</filename> - are dependent on their location within the kernel Metadata itself. - The examples here are taken from the - <filename>yocto-kernel-cache</filename> repository. - Each branch of this repository contains "features" and "cfg" - subdirectories at the top-level. - For more information, see the - "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" - section. - </para> -</section> - -<section id='kernel-metadata-syntax'> - <title>Kernel Metadata Syntax</title> - - <para> - 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 <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 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 kernel Metadata: - <itemizedlist> - <listitem><para>Features</para></listitem> - <listitem><para>Board Support Packages (BSPs)</para></listitem> - </itemizedlist> - </para> - - <para> - Features aggregate sources in the form of patches and configuration - 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> - BSPs define hardware-specific features and aggregate them with kernel - types to form the final description of what will be assembled and built. - </para> - - <para> - 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'> - <replaceable>base</replaceable>/ - bsp/ - cfg/ - features/ - ktypes/ - patches/ - </literallayout> - </para> - - <para> - 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 the - <filename>cfg</filename> directory.</para></listitem> - <listitem><para>If your file contains - only source-code fixes, place the file in the - <filename>patches</filename> directory.</para></listitem> - <listitem><para>If your file encapsulates - a major feature, often combining sources and configurations, - place the file in <filename>features</filename> directory. - </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> - directory. - </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 kernel Metadata files are relative to - <replaceable>base</replaceable>, which is either - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - if you are creating Metadata in - <link linkend='recipe-space-metadata'>recipe-space</link>, - or the top level of - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/'><filename>yocto-kernel-cache</filename></ulink> - if you are creating - <link linkend='metadata-outside-the-recipe-space'>Metadata outside of the recipe-space</link>. - </para> - - <section id='configuration'> - <title>Configuration</title> - - <para> - The simplest unit of kernel Metadata is the configuration-only - feature. - This feature consists of one or more Linux kernel configuration - parameters in a configuration fragment file - (<filename>.cfg</filename>) and a <filename>.scc</filename> file - that describes the fragment. - </para> - - <para> - As an example, consider the Symmetric Multi-Processing (SMP) - fragment used with the <filename>linux-yocto-4.12</filename> - kernel as defined outside of the recipe space (i.e. - <filename>yocto-kernel-cache</filename>). - This Metadata consists of two files: <filename>smp.scc</filename> - and <filename>smp.cfg</filename>. - You can find these files in the <filename>cfg</filename> directory - of the <filename>yocto-4.12</filename> branch in the - <filename>yocto-kernel-cache</filename> Git repository: - <literallayout class='monospaced'> - cfg/smp.scc: - define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds" - define KFEATURE_COMPATIBILITY all - - kconf hardware smp.cfg - - cfg/smp.cfg: - CONFIG_SMP=y - CONFIG_SCHED_SMT=y - # 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 needed 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 - </literallayout> - You can find general information on configuration fragment files in - the - "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>" - section. - </para> - - <para> - Within the <filename>smp.scc</filename> file, the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink> - statement provides a short description of the fragment. - Higher level kernel tools use this description. - </para> - - <para> - Also within the <filename>smp.scc</filename> file, the - <filename>kconf</filename> command includes the - actual configuration fragment in an <filename>.scc</filename> - file, and the "hardware" keyword identifies the fragment as - being hardware enabling, as opposed to general policy, - which would use the "non-hardware" keyword. - The distinction is made for the benefit of the configuration - validation tools, which warn you if a hardware fragment - overrides a policy set by a non-hardware fragment. - <note> - The description file can include multiple - <filename>kconf</filename> statements, one per fragment. - </note> - </para> - - <para> - As described in the - "<link linkend='validating-configuration'>Validating Configuration</link>" - section, you can use the following BitBake command to audit your - configuration: - <literallayout class='monospaced'> - $ bitbake linux-yocto -c kernel_configcheck -f - </literallayout> - </para> - </section> - - <section id='patches'> - <title>Patches</title> - - <para> - Patch descriptions are very similar to configuration fragment - descriptions, which are described in the previous section. - However, instead of a <filename>.cfg</filename> file, these - descriptions work with source patches (i.e. - <filename>.patch</filename> files). - </para> - - <para> - A typical patch includes a description file and the patch itself. - As an example, consider the build patches used with the - <filename>linux-yocto-4.12</filename> kernel as defined outside of - the recipe space (i.e. <filename>yocto-kernel-cache</filename>). - This Metadata consists of several files: - <filename>build.scc</filename> and a set of - <filename>*.patch</filename> files. - You can find these files in the <filename>patches/build</filename> - directory of the <filename>yocto-4.12</filename> branch in the - <filename>yocto-kernel-cache</filename> Git repository. - </para> - - <para> - The following listings show the <filename>build.scc</filename> - file and part of the - <filename>modpost-mask-trivial-warnings.patch</filename> file: - <literallayout class='monospaced'> - 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 - - # 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) - </literallayout> - The description file can include multiple patch statements where - each statement handles a single patch. - In the example <filename>build.scc</filename> file, five patch - statements exist for the five patches in the directory. - </para> - - <para> - You can create a typical <filename>.patch</filename> file using - <filename>diff -Nurp</filename> or - <filename>git format-patch</filename> commands. - For information on how to create patches, see the - "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" - and - "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" - sections. - </para> - </section> - - <section id='features'> - <title>Features</title> - - <para> - Features are complex kernel Metadata types that consist - of configuration fragments, patches, and possibly other feature - description files. - As an example, consider the following generic listing: - <literallayout class='monospaced'> - features/<replaceable>myfeature</replaceable>.scc - define KFEATURE_DESCRIPTION "Enable <replaceable>myfeature</replaceable>" - - patch 0001-<replaceable>myfeature</replaceable>-core.patch - patch 0002-<replaceable>myfeature</replaceable>-interface.patch - - include cfg/<replaceable>myfeature</replaceable>_dependency.scc - kconf non-hardware <replaceable>myfeature</replaceable>.cfg - </literallayout> - This example shows how the <filename>patch</filename> and - <filename>kconf</filename> commands are used as well as - how an additional feature description file is included with - the <filename>include</filename> command. - </para> - - <para> - Typically, features are less granular than configuration - fragments and are more likely than configuration fragments - and patches to be the types of things you want to specify - in the <filename>KERNEL_FEATURES</filename> variable of the - Linux kernel recipe. - See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>" - section earlier in the manual. - </para> - </section> - - <section id='kernel-types'> - <title>Kernel Types</title> - - <para> - 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 kernel of a - specific type (e.g. a real-time kernel). - Syntactically, kernel types are no different than features - as described in the "<link linkend='features'>Features</link>" - section. - The - <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> - variable in the kernel recipe selects the kernel type. - For example, in the <filename>linux-yocto_4.12.bb</filename> - kernel recipe found in - <filename>poky/meta/recipes-kernel/linux</filename>, a - <ulink url='&YOCTO_DOCS_BB_URL;#require-inclusion'><filename>require</filename></ulink> - directive includes the - <filename>poky/meta/recipes-kernel/linux/linux-yocto.inc</filename> - file, which has the following statement that defines the default - kernel type: - <literallayout class='monospaced'> - LINUX_KERNEL_TYPE ??= "standard" - </literallayout> - </para> - - <para> - Another example would be the real-time kernel (i.e. - <filename>linux-yocto-rt_4.12.bb</filename>). - This kernel recipe directly sets the kernel type as follows: - <literallayout class='monospaced'> - LINUX_KERNEL_TYPE = "preempt-rt" - </literallayout> - <note> - You can find kernel recipes in the - <filename>meta/recipes-kernel/linux</filename> directory of the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> - (e.g. <filename>poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>). - See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>" - section for more information. - </note> - </para> - - <para> - Three kernel types ("standard", "tiny", and "preempt-rt") are - supported for Linux Yocto kernels: - <itemizedlist> - <listitem><para>"standard": - Includes the generic Linux kernel policy of the Yocto - Project linux-yocto kernel recipes. - This policy includes, among other things, which file - systems, networking options, core kernel features, and - debugging and tracing options are supported. - </para></listitem> - <listitem><para>"preempt-rt": - Applies the <filename>PREEMPT_RT</filename> - patches and the configuration options required to - build a real-time Linux kernel. - This kernel type inherits from the "standard" kernel type. - </para></listitem> - <listitem><para>"tiny": - Defines a bare minimum configuration meant to serve as a - base for very small Linux kernels. - The "tiny" kernel type is independent from the "standard" - configuration. - Although the "tiny" kernel type does not currently include - any source changes, it might in the future. - </para></listitem> - </itemizedlist> - </para> - - <para> - For any given kernel type, the Metadata is defined by the - <filename>.scc</filename> (e.g. <filename>standard.scc</filename>). - Here is a partial listing for the <filename>standard.scc</filename> - file, which is found in the <filename>ktypes/standard</filename> - directory of the <filename>yocto-kernel-cache</filename> Git - repository: - <literallayout class='monospaced'> - # Include this kernel type fragment to get the standard features and - # configuration values. - - # 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 - - include features/kgdb/kgdb.scc - . - . - . - - include cfg/net/ip6_nf.scc - include cfg/net/bridge.scc - - include cfg/systemd.scc - - include features/rfkill/rfkill.scc - </literallayout> - </para> - - <para> - As with any <filename>.scc</filename> file, a - kernel type definition can aggregate other - <filename>.scc</filename> files with - <filename>include</filename> commands. - These definitions can also directly pull in - configuration fragments and patches with the - <filename>kconf</filename> and <filename>patch</filename> - commands, respectively. - </para> - - <note> - It is not strictly necessary to create a kernel type - <filename>.scc</filename> file. - The Board Support Package (BSP) file can implicitly define - the kernel type using a <filename>define - <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'>KTYPE</ulink> myktype</filename> - line. - See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>" - section for more information. - </note> - </section> - - <section id='bsp-descriptions'> - <title>BSP Descriptions</title> - - <para> - BSP descriptions (i.e. <filename>*.scc</filename> files) - combine kernel types with hardware-specific features. - The hardware-specific Metadata is typically defined - independently in the BSP layer, and then aggregated with each - supported kernel type. - <note> - For BSPs supported by the Yocto Project, the BSP description - files are located in the <filename>bsp</filename> directory - of the - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink> - repository organized under the "Yocto Linux Kernel" heading - in the - <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>. - </note> - </para> - - <para> - 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). - For complete information on BSP layer file hierarchy, see the - <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. - </para> - - <section id='bsp-description-file-overview'> - <title>Overview</title> - - <para> - For simplicity, consider the following root BSP layer - description files for the BeagleBone board. - These files employ both a structure and naming convention - for consistency. - The naming convention for the file is as follows: - <literallayout class='monospaced'> - <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc - </literallayout> - Here are some example root layer BSP filenames for the - BeagleBone Board BSP, which is supported by the Yocto Project: - <literallayout class='monospaced'> - beaglebone-standard.scc - beaglebone-preempt-rt.scc - </literallayout> - Each file uses the root name (i.e "beaglebone") BSP name - followed by the kernel type. - </para> - - <para> - Examine the <filename>beaglebone-standard.scc</filename> - file: - <literallayout class='monospaced'> - define KMACHINE beaglebone - define KTYPE standard - define KARCH arm - - include ktypes/standard/standard.scc - branch beaglebone - - include beaglebone.scc - - # default policy for standard kernels - include features/latencytop/latencytop.scc - include features/profiling/profiling.scc - </literallayout> - Every top-level BSP description file should define the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>, - and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink> - variables. - These variables allow the OpenEmbedded build system to identify - the description as meeting the criteria set by the recipe being - built. - This example supports the "beaglebone" machine for the - "standard" kernel and the "arm" architecture. - </para> - - <para> - Be aware that a hard link between the - <filename>KTYPE</filename> 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 - <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> - variable in the kernel recipe and the - <filename>KTYPE</filename> variable in the BSP description - file match. - </para> - - <para> - To separate your kernel policy from your hardware configuration, - you include a kernel type (<filename>ktype</filename>), such as - "standard". - In the previous example, this is done using the following: - <literallayout class='monospaced'> - include ktypes/standard/standard.scc - </literallayout> - This file aggregates all the configuration fragments, patches, - and features that make up your standard kernel policy. - See the "<link linkend='kernel-types'>Kernel Types</link>" - section for more information. - </para> - - <para> - To aggregate common configurations and features specific to the - kernel for <replaceable>mybsp</replaceable>, use the following: - <literallayout class='monospaced'> - include <replaceable>mybsp</replaceable>.scc - </literallayout> - You can see that in the BeagleBone example with the following: - <literallayout class='monospaced'> - include beaglebone.scc - </literallayout> - For information on how to break a complete - <filename>.config</filename> file into the various - configuration fragments, see the - "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>" - section. - </para> - - <para> - Finally, if you have any configurations specific to the - hardware that are not in a <filename>*.scc</filename> file, - you can include them as follows: - <literallayout class='monospaced'> - kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg - </literallayout> - The BeagleBone example does not include these types of - configurations. - However, the Malta 32-bit board does ("mti-malta32"). - Here is the <filename>mti-malta32-le-standard.scc</filename> - file: - <literallayout class='monospaced'> - 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 - </literallayout> - </para> - </section> - - <section id='bsp-description-file-example-minnow'> - <title>Example</title> - - <para> - Many real-world examples are more complex. - Like any other <filename>.scc</filename> file, BSP - descriptions can aggregate features. - Consider the Minnow BSP definition given the - <filename>linux-yocto-4.4</filename> branch of the - <filename>yocto-kernel-cache</filename> (i.e. - <filename>yocto-kernel-cache/bsp/minnow/minnow.scc</filename>): - <note> - Although the Minnow Board BSP is unused, the Metadata - remains and is being used here just as an example. - </note> - <literallayout class='monospaced'> - include cfg/x86.scc - include features/eg20t/eg20t.scc - include cfg/dmaengine.scc - include features/power/intel.scc - include cfg/efi.scc - include features/usb/ehci-hcd.scc - include features/usb/ohci-hcd.scc - include features/usb/usb-gadgets.scc - include features/usb/touchscreen-composite.scc - include cfg/timer/hpet.scc - include features/leds/leds.scc - include features/spi/spidev.scc - include features/i2c/i2cdev.scc - include features/mei/mei-txe.scc - - # Earlyprintk and port debug requires 8250 - kconf hardware cfg/8250.cfg - - kconf hardware minnow.cfg - kconf hardware minnow-dev.cfg - </literallayout> - </para> - - <para> - The <filename>minnow.scc</filename> description file includes - a hardware configuration fragment - (<filename>minnow.cfg</filename>) specific to the Minnow - BSP as well as several more general configuration - fragments and features enabling hardware found on the - machine. - This <filename>minnow.scc</filename> description file is then - included in each of the three - "minnow" description files for the supported kernel types - (i.e. "standard", "preempt-rt", and "tiny"). - Consider the "minnow" description for the "standard" kernel - type (i.e. <filename>minnow-standard.scc</filename>: - <literallayout class='monospaced'> - define KMACHINE minnow - define KTYPE standard - define KARCH i386 - - include ktypes/standard - - include minnow.scc - - # Extra minnow configs above the minimal defined in minnow.scc - include cfg/efi-ext.scc - include features/media/media-all.scc - include features/sound/snd_hda_intel.scc - - # The following should really be in standard.scc - # USB live-image support - include cfg/usb-mass-storage.scc - include cfg/boot-live.scc - - # Basic profiling - include features/latencytop/latencytop.scc - include features/profiling/profiling.scc - - # Requested drivers that don't have an existing scc - kconf hardware minnow-drivers-extra.cfg - </literallayout> - The <filename>include</filename> command midway through the file - includes the <filename>minnow.scc</filename> description that - defines all enabled hardware for the BSP that is common to - all kernel types. - Using this command significantly reduces duplication. - </para> - - <para> - Now consider the "minnow" description for the "tiny" kernel - type (i.e. <filename>minnow-tiny.scc</filename>): - <literallayout class='monospaced'> - define KMACHINE minnow - define KTYPE tiny - define KARCH i386 - - include ktypes/tiny - - include minnow.scc - </literallayout> - As you might expect, the "tiny" description includes quite a - bit less. - In fact, it includes only the minimal policy defined by the - "tiny" kernel type and the hardware-specific configuration - required for booting the machine along with the most basic - functionality of the system as defined in the base "minnow" - description file. - </para> - - <para> - Notice again the three critical variables: - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>, - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>. - Of these variables, only <filename>KTYPE</filename> - has changed to specify the "tiny" kernel type. - </para> - </section> - </section> -</section> - -<section id='kernel-metadata-location'> - <title>Kernel Metadata Location</title> - - <para> - Kernel Metadata always exists outside of the kernel tree either - defined in a kernel recipe (recipe-space) or outside of the recipe. - Where you choose to define the Metadata depends on what you want - to do and how you intend to work. - Regardless of where you define the kernel Metadata, the syntax used - applies equally. - </para> - - <para> - If you are unfamiliar with the Linux kernel and only wish - to apply a configuration and possibly a couple of patches provided to - you by others, the recipe-space method is recommended. - This method is also a good approach if you are working with Linux kernel - sources you do not control or if you just do not want to maintain a - Linux kernel Git repository on your own. - For partial information on how you can define kernel Metadata in - the recipe-space, see the - "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>" - section. - </para> - - <para> - Conversely, if you are actively developing a kernel and are already - maintaining a Linux kernel Git repository of your own, you might find - it more convenient to work with kernel Metadata kept outside the - recipe-space. - Working with Metadata in this area can make iterative development of - the Linux kernel more efficient outside of the BitBake environment. - </para> - - <section id='recipe-space-metadata'> - <title>Recipe-Space Metadata</title> - - <para> - When stored in recipe-space, the kernel Metadata files reside in a - directory hierarchy below - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>. - For a linux-yocto recipe or for a Linux kernel recipe derived - by copying and modifying - <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename> - to a recipe in your layer, <filename>FILESEXTRAPATHS</filename> - is typically set to - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>. - See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>" - section for more information. - </para> - - <para> - Here is an example that shows a trivial tree of kernel Metadata - stored in recipe-space within a BSP layer: - <literallayout class='monospaced'> - meta-<replaceable>my_bsp_layer</replaceable>/ - `-- recipes-kernel - `-- linux - `-- linux-yocto - |-- bsp-standard.scc - |-- bsp.cfg - `-- standard.cfg - </literallayout> - </para> - - <para> - When the Metadata is stored in recipe-space, you must take - steps to ensure BitBake has the necessary information to decide - what files to fetch and when they need to be fetched again. - It is only necessary to specify the <filename>.scc</filename> - files on the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. - BitBake parses them and fetches any files referenced in the - <filename>.scc</filename> files by the <filename>include</filename>, - <filename>patch</filename>, or <filename>kconf</filename> commands. - Because of this, it is necessary to bump the recipe - <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> - value when changing the content of files not explicitly listed - in the <filename>SRC_URI</filename>. - </para> - - <para> - If the BSP description is in recipe space, you cannot simply list - the <filename>*.scc</filename> in the <filename>SRC_URI</filename> - statement. - You need to use the following form from your kernel append file: - <literallayout class='monospaced'> - SRC_URI_append_<replaceable>myplatform</replaceable> = " \ - file://<replaceable>myplatform</replaceable>;type=kmeta;destsuffix=<replaceable>myplatform</replaceable> \ - " - </literallayout> - </para> - </section> - - <section id='metadata-outside-the-recipe-space'> - <title>Metadata Outside the Recipe-Space</title> - - <para> - When stored outside of the recipe-space, the kernel Metadata - files reside in a separate repository. - The OpenEmbedded build system adds the Metadata to the build as - a "type=kmeta" repository through the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - variable. - As an example, consider the following <filename>SRC_URI</filename> - statement from the <filename>linux-yocto_4.12.bb</filename> - kernel recipe: - <literallayout class='monospaced'> - SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \ - git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" - </literallayout> - <filename>${KMETA}</filename>, in this context, is simply used to - name the directory into which the Git fetcher places the Metadata. - This behavior is no different than any multi-repository - <filename>SRC_URI</filename> statement used in a recipe (e.g. - see the previous section). - </para> - - <para> - You can keep kernel Metadata in a "kernel-cache", which is a - directory containing configuration fragments. - As with any Metadata kept outside the recipe-space, you simply - need to use the <filename>SRC_URI</filename> statement with the - "type=kmeta" attribute. - Doing so makes the kernel Metadata available during the - configuration phase. - </para> - - <para> - If you modify the Metadata, you must not forget to update the - <filename>SRCREV</filename> statements in the kernel's recipe. - In particular, you need to update the - <filename>SRCREV_meta</filename> variable to match the commit in - the <filename>KMETA</filename> branch you wish to use. - Changing the data in these branches and not updating the - <filename>SRCREV</filename> statements to match will cause the - build to fetch an older commit. - </para> - </section> -</section> - -<section id='organizing-your-source'> - <title>Organizing Your Source</title> - - <para> - Many recipes based on the <filename>linux-yocto-custom.bb</filename> - recipe use Linux kernel sources that have only a single - branch - "master". - This type of repository structure is fine for linear development - supporting a single machine and architecture. - However, if you work with multiple boards and architectures, - a kernel source repository with multiple branches is more - efficient. - For example, suppose you need a series of patches for one board to boot. - Sometimes, these patches are works-in-progress or fundamentally wrong, - yet they are still necessary for specific boards. - In these situations, you most likely do not want to include these - patches in every kernel you build (i.e. have the patches as part of - the lone "master" branch). - It is situations like these that give rise to multiple branches used - within a Linux kernel sources Git repository. - </para> - - <para> - Repository organization strategies exist that maximize source reuse, - remove redundancy, and logically order your changes. - This section presents strategies for the following cases: - <itemizedlist> - <listitem><para>Encapsulating patches in a feature description - and only including the patches in the BSP descriptions of - the applicable boards.</para></listitem> - <listitem><para>Creating a machine branch in your - kernel source repository and applying the patches on that - branch only.</para></listitem> - <listitem><para>Creating a feature branch in your - kernel source repository and merging that branch into your - BSP when needed.</para></listitem> - </itemizedlist> - </para> - - <para> - The approach you take is entirely up to you - and depends on what works best for your development model. - </para> - - <section id='encapsulating-patches'> - <title>Encapsulating Patches</title> - - <para> - if you are reusing patches from an external tree and are not - working on the patches, you might find the encapsulated feature - to be appropriate. - Given this scenario, you do not need to create any branches in the - source repository. - Rather, you just take the static patches you need and encapsulate - them within a feature description. - Once you have the feature description, you simply include that into - the BSP description as described in the - "<link linkend='bsp-descriptions'>BSP Descriptions</link>" - section. - </para> - - <para> - You can find information on how to create patches and BSP - descriptions in the "<link linkend='patches'>Patches</link>" and - "<link linkend='bsp-descriptions'>BSP Descriptions</link>" - sections. - </para> - </section> - - <section id='machine-branches'> - <title>Machine Branches</title> - - <para> - When you have multiple machines and architectures to support, - or you are actively working on board support, it is more - efficient to create branches in the repository based on - individual machines. - Having machine branches allows common source to remain in the - "master" branch with any features specific to a machine stored - in the appropriate machine branch. - This organization method frees you from continually reintegrating - your patches into a feature. - </para> - - <para> - Once you have a new branch, you can set up your kernel Metadata - to use the branch a couple different ways. - In the recipe, you can specify the new branch as the - <filename>KBRANCH</filename> to use for the board as - follows: - <literallayout class='monospaced'> - KBRANCH = "mynewbranch" - </literallayout> - Another method is to use the <filename>branch</filename> command - in the BSP description: - <literallayout class='monospaced'> - mybsp.scc: - define KMACHINE mybsp - define KTYPE standard - define KARCH i386 - include standard.scc - - branch mynewbranch - - include mybsp-hw.scc - </literallayout> - </para> - - <para> - If you find yourself with numerous branches, you might consider - using a hierarchical branching system similar to what the - Yocto Linux Kernel Git repositories use: - <literallayout class='monospaced'> - <replaceable>common</replaceable>/<replaceable>kernel_type</replaceable>/<replaceable>machine</replaceable> - </literallayout> - </para> - - <para> - If you had two kernel types, "standard" and "small" for - instance, three machines, and <replaceable>common</replaceable> - as <filename>mydir</filename>, the branches in your - Git repository might look like this: - <literallayout class='monospaced'> - mydir/base - mydir/standard/base - mydir/standard/machine_a - mydir/standard/machine_b - mydir/standard/machine_c - mydir/small/base - mydir/small/machine_a - </literallayout> - </para> - - <para> - This organization can help clarify the branch relationships. - In this case, <filename>mydir/standard/machine_a</filename> - includes everything in <filename>mydir/base</filename> and - <filename>mydir/standard/base</filename>. - The "standard" and "small" branches add sources specific to those - kernel types that for whatever reason are not appropriate for the - other branches. - <note> - The "base" branches are an artifact of the way Git manages - its data internally on the filesystem: Git will not allow you - to use <filename>mydir/standard</filename> and - <filename>mydir/standard/machine_a</filename> because it - would have to create a file and a directory named "standard". - </note> - </para> - </section> - - <section id='feature-branches'> - <title>Feature Branches</title> - - <para> - When you are actively developing new features, it can be more - efficient to work with that feature as a branch, rather than - as a set of patches that have to be regularly updated. - The Yocto Project Linux kernel tools provide for this with - the <filename>git merge</filename> command. - </para> - - <para> - To merge a feature branch into a BSP, insert the - <filename>git merge</filename> command after any - <filename>branch</filename> commands: - <literallayout class='monospaced'> - mybsp.scc: - define KMACHINE mybsp - define KTYPE standard - define KARCH i386 - include standard.scc - - branch mynewbranch - git merge myfeature - - include mybsp-hw.scc - </literallayout> - </para> - </section> -</section> - -<section id='scc-reference'> - <title>SCC Description File Reference</title> - - <para> - This section provides a brief reference for the commands you can use - within an SCC description file (<filename>.scc</filename>): - <itemizedlist> - <listitem><para> - <filename>branch [ref]</filename>: - Creates a new branch relative to the current branch - (typically <filename>${KTYPE}</filename>) using - the currently checked-out branch, or "ref" if specified. - </para></listitem> - <listitem><para> - <filename>define</filename>: - Defines variables, such as - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>, - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>. - </para></listitem> - <listitem><para> - <filename>include SCC_FILE</filename>: - Includes an SCC file in the current file. - The file is parsed as if you had inserted it inline. - </para></listitem> - <listitem><para> - <filename>kconf [hardware|non-hardware] CFG_FILE</filename>: - Queues a configuration fragment for merging into the final - Linux <filename>.config</filename> file.</para></listitem> - <listitem><para> - <filename>git merge GIT_BRANCH</filename>: - Merges the feature branch into the current branch. - </para></listitem> - <listitem><para> - <filename>patch PATCH_FILE</filename>: - Applies the patch to the current Git branch. - </para></listitem> - </itemizedlist> - </para> -</section> - -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/poky/documentation/kernel-dev/kernel-dev-common.rst b/poky/documentation/kernel-dev/kernel-dev-common.rst index d4b60a9dc..64235f380 100644 --- a/poky/documentation/kernel-dev/kernel-dev-common.rst +++ b/poky/documentation/kernel-dev/kernel-dev-common.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK ************ Common Tasks diff --git a/poky/documentation/kernel-dev/kernel-dev-common.xml b/poky/documentation/kernel-dev/kernel-dev-common.xml deleted file mode 100644 index 8e8a6dbed..000000000 --- a/poky/documentation/kernel-dev/kernel-dev-common.xml +++ /dev/null @@ -1,2730 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<chapter id='kernel-dev-common'> -<title>Common Tasks</title> - - <para> - This chapter presents several common tasks you perform when you - work with the Yocto Project Linux kernel. - These tasks include preparing your host development system for - kernel development, preparing a layer, modifying an existing recipe, - patching the kernel, configuring the kernel, iterative development, - working with your own sources, and incorporating out-of-tree modules. - <note> - The examples presented in this chapter work with the Yocto Project - 2.4 Release and forward. - </note> - </para> - - <section id='preparing-the-build-host-to-work-on-the-kernel'> - <title>Preparing the Build Host to Work on the Kernel</title> - - <para> - Before you can do any kernel development, you need to be - sure your build host is set up to use the Yocto Project. - For information on how to get set up, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>" - section in the Yocto Project Development Tasks Manual. - Part of preparing the system is creating a local Git - repository of the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> - (<filename>poky</filename>) on your system. - Follow the steps in the - "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>" - section in the Yocto Project Development Tasks Manual to set up your - Source Directory. - <note> - Be sure you check out the appropriate development branch or - you create your local branch by checking out a specific tag - to get the desired version of Yocto Project. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>" - and - "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>" - sections in the Yocto Project Development Tasks Manual for more - information. - </note> - </para> - - <para> - Kernel development is best accomplished using - <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink> - and not through traditional kernel workflow methods. - The remainder of this section provides information for both - scenarios. - </para> - - <section id='getting-ready-to-develop-using-devtool'> - <title>Getting Ready to Develop Using <filename>devtool</filename></title> - - <para> - Follow these steps to prepare to update the kernel image using - <filename>devtool</filename>. - Completing this procedure leaves you with a clean kernel image - and ready to make modifications as described in the - "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" - section: - <orderedlist> - <listitem><para> - <emphasis>Initialize the BitBake Environment:</emphasis> - Before building an extensible SDK, you need to - initialize the BitBake build environment by sourcing the - build environment script - (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>): - <literallayout class='monospaced'> - $ cd ~/poky - $ source oe-init-build-env - </literallayout> - <note> - The previous commands assume the - <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> - (i.e. <filename>poky</filename>) have been cloned - using Git and the local repository is named - "poky". - </note> - </para></listitem> - <listitem><para> - <emphasis>Prepare Your <filename>local.conf</filename> File:</emphasis> - By default, the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable is set to "qemux86-64", which is fine if you are - building for the QEMU emulator in 64-bit mode. - However, if you are not, you need to set the - <filename>MACHINE</filename> variable appropriately in - your <filename>conf/local.conf</filename> file found in - the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> - (i.e. <filename>~/poky/build</filename> in this - example).</para> - - <para>Also, since you are preparing to work on the - kernel image, you need to set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> - variable to include kernel modules.</para> - - <para>In this example we wish to build for qemux86 so - we must set the <filename>MACHINE</filename> variable - to "qemux86" and also add the "kernel-modules". As described - we do this by appending to <filename>conf/local.conf</filename>: - <literallayout class='monospaced'> - MACHINE = "qemux86" - MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Create a Layer for Patches:</emphasis> - You need to create a layer to hold patches created - for the kernel image. - You can use the - <filename>bitbake-layers create-layer</filename> - command as follows: - <literallayout class='monospaced'> - $ cd ~/poky/build - $ bitbake-layers create-layer ../../meta-mylayer - NOTE: Starting bitbake server... - Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' - $ - </literallayout> - <note> - For background information on working with - common and BSP layers, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" - section in the Yocto Project Development Tasks - Manual and the - "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" - section in the Yocto Project Board Support (BSP) - Developer's Guide, respectively. - For information on how to use the - <filename>bitbake-layers create-layer</filename> - command to quickly set up a layer, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" - section in the Yocto Project Development Tasks - Manual. - </note> - </para></listitem> - <listitem><para> - <emphasis>Inform the BitBake Build Environment About - Your Layer:</emphasis> - As directed when you created your layer, you need to - add the layer to the - <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> - variable in the <filename>bblayers.conf</filename> file - as follows: - <literallayout class='monospaced'> - $ cd ~/poky/build - $ bitbake-layers add-layer ../../meta-mylayer - NOTE: Starting bitbake server... - $ - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Build the Extensible SDK:</emphasis> - Use BitBake to build the extensible SDK specifically - for use with images to be run using QEMU: - <literallayout class='monospaced'> - $ cd ~/poky/build - $ bitbake core-image-minimal -c populate_sdk_ext - </literallayout> - Once the build finishes, you can find the SDK installer - file (i.e. <filename>*.sh</filename> file) in the - following directory: - <literallayout class='monospaced'> - ~/poky/build/tmp/deploy/sdk - </literallayout> - For this example, the installer file is named - <filename>poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh</filename> - </para></listitem> - <listitem><para> - <emphasis>Install the Extensible SDK:</emphasis> - Use the following command to install the SDK. - For this example, install the SDK in the default - <filename>~/poky_sdk</filename> directory: - <literallayout class='monospaced'> - $ cd ~/poky/build/tmp/deploy/sdk - $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh - Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO; - ============================================================================ - Enter target directory for SDK (default: ~/poky_sdk): - You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y - Extracting SDK......................................done - Setting it up... - Extracting buildtools... - Preparing build system... - Parsing recipes: 100% |#################################################################| Time: 0:00:52 - Initializing tasks: 100% |############## ###############################################| Time: 0:00:04 - Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00 - Parsing recipes: 100% |#################################################################| Time: 0:00:33 - Initializing tasks: 100% |##############################################################| Time: 0:00:00 - done - SDK has been successfully set up and is ready to be used. - Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. - $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux - </literallayout> - </para></listitem> - <listitem><para id='setting-up-the-esdk-terminal'> - <emphasis>Set Up a New Terminal to Work With the - Extensible SDK:</emphasis> - You must set up a new terminal to work with the SDK. - You cannot use the same BitBake shell used to build the - installer.</para> - - <para>After opening a new shell, run the SDK environment - setup script as directed by the output from installing - the SDK: - <literallayout class='monospaced'> - $ source ~/poky_sdk/environment-setup-i586-poky-linux - "SDK environment now set up; additionally you may now run devtool to perform development tasks. - Run devtool --help for further details. - </literallayout> - <note> - If you get a warning about attempting to use the - extensible SDK in an environment set up to run - BitBake, you did not use a new shell. - </note> - </para></listitem> - <listitem><para> - <emphasis>Build the Clean Image:</emphasis> - The final step in preparing to work on the kernel is to - build an initial image using - <filename>devtool</filename> in the new terminal you - just set up and initialized for SDK work: - <literallayout class='monospaced'> - $ devtool build-image - Parsing recipes: 100% |##########################################| Time: 0:00:05 - Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors. - WARNING: No packages to add, building image core-image-minimal unmodified - Loading cache: 100% |############################################| Time: 0:00:00 - Loaded 1299 entries from dependency cache. - NOTE: Resolving any missing task queue dependencies - Initializing tasks: 100% |#######################################| Time: 0:00:07 - Checking sstate mirror object availability: 100% |###############| Time: 0:00:00 - NOTE: Executing SetScene Tasks - NOTE: Executing RunQueue Tasks - NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded. - NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86 - </literallayout> - If you were building for actual hardware and not for - emulation, you could flash the image to a USB stick - on <filename>/dev/sdd</filename> and boot your device. - For an example that uses a Minnowboard, see the - <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink> - Wiki page. - </para></listitem> - </orderedlist> - </para> - - <para> - At this point you have set up to start making modifications to - the kernel by using the extensible SDK. - For a continued example, see the - "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" - section. - </para> - </section> - - <section id='getting-ready-for-traditional-kernel-development'> - <title>Getting Ready for Traditional Kernel Development</title> - - <para> - Getting ready for traditional kernel development using the Yocto - Project involves many of the same steps as described in the - previous section. - However, you need to establish a local copy of the kernel source - since you will be editing these files. - </para> - - <para> - Follow these steps to prepare to update the kernel image using - traditional kernel development flow with the Yocto Project. - Completing this procedure leaves you ready to make modifications - to the kernel source as described in the - "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" - section: - <orderedlist> - <listitem><para> - <emphasis>Initialize the BitBake Environment:</emphasis> - Before you can do anything using BitBake, you need to - initialize the BitBake build environment by sourcing the - build environment script - (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>). - Also, for this example, be sure that the local branch - you have checked out for <filename>poky</filename> is - the Yocto Project &DISTRO_NAME; branch. - If you need to checkout out the &DISTRO_NAME; branch, - see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking out by Branch in Poky</ulink>" - section in the Yocto Project Development Tasks Manual. - <literallayout class='monospaced'> - $ cd ~/poky - $ git branch - master - * &DISTRO_NAME; - $ source oe-init-build-env - </literallayout> - <note> - The previous commands assume the - <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> - (i.e. <filename>poky</filename>) have been cloned - using Git and the local repository is named - "poky". - </note> - </para></listitem> - <listitem><para> - <emphasis>Prepare Your <filename>local.conf</filename> - File:</emphasis> - By default, the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable is set to "qemux86-64", which is fine if you are - building for the QEMU emulator in 64-bit mode. - However, if you are not, you need to set the - <filename>MACHINE</filename> variable appropriately in - your <filename>conf/local.conf</filename> file found - in the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> - (i.e. <filename>~/poky/build</filename> in this - example).</para> - - <para>Also, since you are preparing to work on the - kernel image, you need to set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> - variable to include kernel modules.</para> - - <para>In this example we wish to build for qemux86 so - we must set the <filename>MACHINE</filename> variable - to "qemux86" and also add the "kernel-modules". As described - we do this by appending to <filename>conf/local.conf</filename>: - <literallayout class='monospaced'> - MACHINE = "qemux86" - MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Create a Layer for Patches:</emphasis> - You need to create a layer to hold patches created - for the kernel image. - You can use the - <filename>bitbake-layers create-layer</filename> - command as follows: - <literallayout class='monospaced'> - $ cd ~/poky/build - $ bitbake-layers create-layer ../../meta-mylayer - NOTE: Starting bitbake server... - Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' - </literallayout> - <note> - For background information on working with - common and BSP layers, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" - section in the Yocto Project Development Tasks - Manual and the - "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" - section in the Yocto Project Board Support (BSP) - Developer's Guide, respectively. - For information on how to use the - <filename>bitbake-layers create-layer</filename> - command to quickly set up a layer, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" - section in the Yocto Project Development Tasks - Manual. - </note> - </para></listitem> - <listitem><para> - <emphasis>Inform the BitBake Build Environment About - Your Layer:</emphasis> - As directed when you created your layer, you need to add - the layer to the - <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> - variable in the <filename>bblayers.conf</filename> file - as follows: - <literallayout class='monospaced'> - $ cd ~/poky/build - $ bitbake-layers add-layer ../../meta-mylayer - NOTE: Starting bitbake server ... - $ - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Create a Local Copy of the Kernel Git - Repository:</emphasis> - You can find Git repositories of supported Yocto Project - kernels organized under "Yocto Linux Kernel" in the - Yocto Project Source Repositories at - <ulink url='&YOCTO_GIT_URL;'></ulink>. - </para> - - <para> - For simplicity, it is recommended that you create your - copy of the kernel Git repository outside of the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>, - which is usually named <filename>poky</filename>. - Also, be sure you are in the - <filename>standard/base</filename> branch. - </para> - - <para> - The following commands show how to create a local copy - of the <filename>linux-yocto-4.12</filename> kernel and - be in the <filename>standard/base</filename> branch. - <note> - The <filename>linux-yocto-4.12</filename> kernel - can be used with the Yocto Project 2.4 release - and forward. - You cannot use the - <filename>linux-yocto-4.12</filename> kernel with - releases prior to Yocto Project 2.4: - </note> - <literallayout class='monospaced'> - $ cd ~ - $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base - Cloning into 'linux-yocto-4.12'... - remote: Counting objects: 6097195, done. - remote: Compressing objects: 100% (901026/901026), done. - remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256) - Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done. - Resolving deltas: 100% (5152604/5152604), done. - Checking connectivity... done. - Checking out files: 100% (59846/59846), done. - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Create a Local Copy of the Kernel Cache Git - Repository:</emphasis> - For simplicity, it is recommended that you create your - copy of the kernel cache Git repository outside of the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>, - which is usually named <filename>poky</filename>. - Also, for this example, be sure you are in the - <filename>yocto-4.12</filename> branch. - </para> - - <para> - The following commands show how to create a local copy - of the <filename>yocto-kernel-cache</filename> and - be in the <filename>yocto-4.12</filename> branch: - <literallayout class='monospaced'> - $ cd ~ - $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12 - Cloning into 'yocto-kernel-cache'... - remote: Counting objects: 22639, done. - remote: Compressing objects: 100% (9761/9761), done. - remote: Total 22639 (delta 12400), reused 22586 (delta 12347) - Receiving objects: 100% (22639/22639), 22.34 MiB | 6.27 MiB/s, done. - Resolving deltas: 100% (12400/12400), done. - Checking connectivity... done. - </literallayout> - </para></listitem> - </orderedlist> - </para> - - <para> - At this point, you are ready to start making modifications to - the kernel using traditional kernel development steps. - For a continued example, see the - "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" - section. - </para> - </section> - </section> - - <section id='creating-and-preparing-a-layer'> - <title>Creating and Preparing a Layer</title> - - <para> - If you are going to be modifying kernel recipes, it is recommended - that you create and prepare your own layer in which to do your - work. - Your layer contains its own - <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> - append files (<filename>.bbappend</filename>) and provides a - convenient mechanism to create your own recipe files - (<filename>.bb</filename>) as well as store and use kernel - patch files. - For background information on working with layers, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" - section in the Yocto Project Development Tasks Manual. - <note><title>Tip</title> - The Yocto Project comes with many tools that simplify - tasks you need to perform. - One such tool is the - <filename>bitbake-layers create-layer</filename> - command, which simplifies creating a new layer. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" - section in the Yocto Project Development Tasks Manual for - information on how to use this script to quick set up a - new layer. - </note> - </para> - - <para> - To better understand the layer you create for kernel development, - the following section describes how to create a layer - without the aid of tools. - These steps assume creation of a layer named - <filename>mylayer</filename> in your home directory: - <orderedlist> - <listitem><para> - <emphasis>Create Structure</emphasis>: - Create the layer's structure: - <literallayout class='monospaced'> - $ cd $HOME - $ mkdir meta-mylayer - $ mkdir meta-mylayer/conf - $ mkdir meta-mylayer/recipes-kernel - $ mkdir meta-mylayer/recipes-kernel/linux - $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto - </literallayout> - The <filename>conf</filename> directory holds your - configuration files, while the - <filename>recipes-kernel</filename> directory holds your - append file and eventual patch files. - </para></listitem> - <listitem><para> - <emphasis>Create the Layer Configuration File</emphasis>: - Move to the <filename>meta-mylayer/conf</filename> - directory and create the <filename>layer.conf</filename> - file as follows: - <literallayout class='monospaced'> - # We have a conf and classes directory, add to BBPATH - BBPATH .= ":${LAYERDIR}" - - # We have recipes-* directories, add to BBFILES - BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ - ${LAYERDIR}/recipes-*/*/*.bbappend" - - BBFILE_COLLECTIONS += "mylayer" - BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" - BBFILE_PRIORITY_mylayer = "5" - </literallayout> - Notice <filename>mylayer</filename> as part of the last - three statements. - </para></listitem> - <listitem><para> - <emphasis>Create the Kernel Recipe Append File</emphasis>: - Move to the - <filename>meta-mylayer/recipes-kernel/linux</filename> - directory and create the kernel's append file. - This example uses the - <filename>linux-yocto-4.12</filename> kernel. - Thus, the name of the append file is - <filename>linux-yocto_4.12.bbappend</filename>: - <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - - SRC_URI_append = " file://<replaceable>patch-file-one</replaceable>" - SRC_URI_append = " file://<replaceable>patch-file-two</replaceable>" - SRC_URI_append = " file://<replaceable>patch-file-three</replaceable>" - </literallayout> - The - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statements enable the OpenEmbedded build system to find - patch files. - For more information on using append files, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" - section in the Yocto Project Development Tasks Manual. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='modifying-an-existing-recipe'> - <title>Modifying an Existing Recipe</title> - - <para> - In many cases, you can customize an existing linux-yocto recipe to - meet the needs of your project. - Each release of the Yocto Project provides a few Linux - kernel recipes from which you can choose. - These are located in the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> - in <filename>meta/recipes-kernel/linux</filename>. - </para> - - <para> - Modifying an existing recipe can consist of the following: - <itemizedlist> - <listitem><para>Creating the append file</para></listitem> - <listitem><para>Applying patches</para></listitem> - <listitem><para>Changing the configuration</para></listitem> - </itemizedlist> - </para> - - <para> - Before modifying an existing recipe, be sure that you have created - a minimal, custom layer from which you can work. - See the - "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>" - section for information. - </para> - - <section id='creating-the-append-file'> - <title>Creating the Append File</title> - - <para> - You create this file in your custom layer. - You also name it accordingly based on the linux-yocto recipe - you are using. - For example, if you are modifying the - <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename> - recipe, the append file will typically be located as follows - within your custom layer: - <literallayout class='monospaced'> - <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.12.bbappend - </literallayout> - The append file should initially extend the - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> - search path by prepending the directory that contains your - files to the - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - variable as follows: - <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - </literallayout> - The path <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> - expands to "linux-yocto" in the current directory for this - example. - If you add any new files that modify the kernel recipe and you - have extended <filename>FILESPATH</filename> as - described above, you must place the files in your layer in the - following area: - <literallayout class='monospaced'> - <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto/ - </literallayout> - <note>If you are working on a new machine Board Support Package - (BSP), be sure to refer to the - <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. - </note> - </para> - - <para> - As an example, consider the following append file - used by the BSPs in <filename>meta-yocto-bsp</filename>: - <literallayout class='monospaced'> - meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend - </literallayout> - The following listing shows the file. - Be aware that the actual commit ID strings in this - example listing might be different than the actual strings - in the file from the <filename>meta-yocto-bsp</filename> - layer upstream. - <literallayout class='monospaced'> - KBRANCH_genericx86 = "standard/base" - KBRANCH_genericx86-64 = "standard/base" - - KMACHINE_genericx86 ?= "common-pc" - KMACHINE_genericx86-64 ?= "common-pc-64" - KBRANCH_edgerouter = "standard/edgerouter" - KBRANCH_beaglebone = "standard/beaglebone" - - SRCREV_machine_genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" - SRCREV_machine_genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" - SRCREV_machine_edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" - SRCREV_machine_beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" - - - COMPATIBLE_MACHINE_genericx86 = "genericx86" - COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" - COMPATIBLE_MACHINE_edgerouter = "edgerouter" - COMPATIBLE_MACHINE_beaglebone = "beaglebone" - - LINUX_VERSION_genericx86 = "4.12.7" - LINUX_VERSION_genericx86-64 = "4.12.7" - LINUX_VERSION_edgerouter = "4.12.10" - LINUX_VERSION_beaglebone = "4.12.10" - </literallayout> - This append file contains statements used to support - several BSPs that ship with the Yocto Project. - The file defines machines using the - <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink> - variable and uses the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> - variable to ensure the machine name used by the OpenEmbedded - build system maps to the machine name used by the Linux Yocto - kernel. - The file also uses the optional - <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> - variable to ensure the build process uses the - appropriate kernel branch. - </para> - - <para> - Although this particular example does not use it, the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> - variable could be used to enable features specific to - the kernel. - The append file points to specific commits in the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> - Git repository and the <filename>meta</filename> Git repository - branches to identify the exact kernel needed to build the - BSP. - </para> - - <para> - One thing missing in this particular BSP, which you will - typically need when developing a BSP, is the kernel - configuration file (<filename>.config</filename>) for your BSP. - When developing a BSP, you probably have a kernel configuration - file or a set of kernel configuration files that, when taken - together, define the kernel configuration for your BSP. - You can accomplish this definition by putting the configurations - in a file or a set of files inside a directory located at the - same level as your kernel's append file and having the same - name as the kernel's main recipe file. - With all these conditions met, simply reference those files in - the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statement in the append file. - </para> - - <para> - For example, suppose you had some configuration options - in a file called <filename>network_configs.cfg</filename>. - You can place that file inside a directory named - <filename>linux-yocto</filename> and then add - a <filename>SRC_URI</filename> statement such as the - following to the append file. - When the OpenEmbedded build system builds the kernel, the - configuration options are picked up and applied. - <literallayout class='monospaced'> - SRC_URI += "file://network_configs.cfg" - </literallayout> - </para> - - <para> - To group related configurations into multiple files, you - perform a similar procedure. - Here is an example that groups separate configurations - specifically for Ethernet and graphics into their own - files and adds the configurations by using a - <filename>SRC_URI</filename> statement like the following - in your append file: - <literallayout class='monospaced'> - SRC_URI += "file://myconfig.cfg \ - file://eth.cfg \ - file://gfx.cfg" - </literallayout> - </para> - - <para> - Another variable you can use in your kernel recipe append - file is the - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - variable. - When you use this statement, you are extending the locations - used by the OpenEmbedded system to look for files and - patches as the recipe is processed. - </para> - - <note> - <para> - Other methods exist to accomplish grouping and defining - configuration options. - For example, if you are working with a local clone of the - kernel repository, you could checkout the kernel's - <filename>meta</filename> branch, make your changes, and - then push the changes to the local bare clone of the - kernel. - The result is that you directly add configuration options - to the <filename>meta</filename> branch for your BSP. - The configuration options will likely end up in that - location anyway if the BSP gets added to the Yocto Project. - </para> - - <para> - In general, however, the Yocto Project maintainers take - care of moving the <filename>SRC_URI</filename>-specified - configuration options to the kernel's - <filename>meta</filename> branch. - Not only is it easier for BSP developers to not have to - worry about putting those configurations in the branch, - but having the maintainers do it allows them to apply - 'global' knowledge about the kinds of common configuration - options multiple BSPs in the tree are typically using. - This allows for promotion of common configurations into - common features. - </para> - </note> - </section> - - <section id='applying-patches'> - <title>Applying Patches</title> - - <para> - If you have a single patch or a small series of patches - that you want to apply to the Linux kernel source, you - can do so just as you would with any other recipe. - You first copy the patches to the path added to - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - in your <filename>.bbappend</filename> file as described in - the previous section, and then reference them in - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statements. - </para> - - <para> - For example, you can apply a three-patch series by adding the - following lines to your linux-yocto - <filename>.bbappend</filename> file in your layer: - <literallayout class='monospaced'> - SRC_URI += "file://0001-first-change.patch" - SRC_URI += "file://0002-second-change.patch" - SRC_URI += "file://0003-third-change.patch" - </literallayout> - The next time you run BitBake to build the Linux kernel, - BitBake detects the change in the recipe and fetches and - applies the patches before building the kernel. - </para> - - <para> - For a detailed example showing how to patch the kernel using - <filename>devtool</filename>, see the - "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" - and - "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" - sections. - </para> - </section> - - <section id='changing-the-configuration'> - <title>Changing the Configuration</title> - - <para> - You can make wholesale or incremental changes to the final - <filename>.config</filename> file used for the eventual - Linux kernel configuration by including a - <filename>defconfig</filename> file and by specifying - configuration fragments in the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - to be applied to that file. - </para> - - <para> - If you have a complete, working Linux kernel - <filename>.config</filename> - file you want to use for the configuration, as before, copy - that file to the appropriate <filename>${PN}</filename> - directory in your layer's - <filename>recipes-kernel/linux</filename> directory, - and rename the copied file to "defconfig". - Then, add the following lines to the linux-yocto - <filename>.bbappend</filename> file in your layer: - <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - SRC_URI += "file://defconfig" - </literallayout> - The <filename>SRC_URI</filename> tells the build system how to - search for the file, while the - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - extends the - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> - variable (search directories) to include the - <filename>${PN}</filename> directory you created to hold the - configuration changes. - </para> - - <note> - The build system applies the configurations from the - <filename>defconfig</filename> file before applying any - subsequent configuration fragments. - The final kernel configuration is a combination of the - configurations in the <filename>defconfig</filename> file and - any configuration fragments you provide. - You need to realize that if you have any configuration - fragments, the build system applies these on top of and - after applying the existing <filename>defconfig</filename> - file configurations. - </note> - - <para> - Generally speaking, the preferred approach is to determine the - incremental change you want to make and add that as a - configuration fragment. - For example, if you want to add support for a basic serial - console, create a file named <filename>8250.cfg</filename> in - the <filename>${PN}</filename> directory with the following - content (without indentation): - <literallayout class='monospaced'> - CONFIG_SERIAL_8250=y - CONFIG_SERIAL_8250_CONSOLE=y - CONFIG_SERIAL_8250_PCI=y - CONFIG_SERIAL_8250_NR_UARTS=4 - CONFIG_SERIAL_8250_RUNTIME_UARTS=4 - CONFIG_SERIAL_CORE=y - CONFIG_SERIAL_CORE_CONSOLE=y - </literallayout> - Next, include this configuration fragment and extend the - <filename>FILESPATH</filename> variable in your - <filename>.bbappend</filename> file: - <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - SRC_URI += "file://8250.cfg" - </literallayout> - The next time you run BitBake to build the Linux kernel, BitBake - detects the change in the recipe and fetches and applies the - new configuration before building the kernel. - </para> - - <para> - For a detailed example showing how to configure the kernel, - see the - "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" - section. - </para> - </section> - - <section id='using-an-in-tree-defconfig-file'> - <title>Using an "In-Tree" <filename>defconfig</filename> File</title> - - <para> - It might be desirable to have kernel configuration fragment - support through a <filename>defconfig</filename> file that - is pulled from the kernel source tree for the configured - machine. - By default, the OpenEmbedded build system looks for - <filename>defconfig</filename> files in the layer used for - Metadata, which is "out-of-tree", and then configures them - using the following: - <literallayout class='monospaced'> - SRC_URI += "file://defconfig" - </literallayout> - If you do not want to maintain copies of - <filename>defconfig</filename> files in your layer but would - rather allow users to use the default configuration from the - kernel tree and still be able to add configuration fragments - to the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - through, for example, append files, you can direct the - OpenEmbedded build system to use a - <filename>defconfig</filename> file that is "in-tree". - </para> - - <para> - To specify an "in-tree" <filename>defconfig</filename> file, - use the following statement form: - <literallayout class='monospaced'> - KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable> - </literallayout> - Here is an example that assigns the - <filename>KBUILD_DEFCONFIG</filename> variable based on - "raspberrypi2" and provides the path to the "in-tree" - <filename>defconfig</filename> file - to be used for a Raspberry Pi 2, - which is based on the Broadcom 2708/2709 chipset: - <literallayout class='monospaced'> - KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig" - </literallayout> - </para> - - <para> - Aside from modifying your kernel recipe and providing your own - <filename>defconfig</filename> file, you need to be sure no - files or statements set <filename>SRC_URI</filename> to use a - <filename>defconfig</filename> other than your "in-tree" - file (e.g. a kernel's - <filename>linux-</filename><replaceable>machine</replaceable><filename>.inc</filename> - file). - In other words, if the build system detects a statement - that identifies an "out-of-tree" - <filename>defconfig</filename> file, that statement - will override your - <filename>KBUILD_DEFCONFIG</filename> variable. - </para> - - <para> - See the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG'><filename>KBUILD_DEFCONFIG</filename></ulink> - variable description for more information. - </para> - </section> - </section> - - <section id="using-devtool-to-patch-the-kernel"> - <title>Using <filename>devtool</filename> to Patch the Kernel</title> - - <para> - The steps in this procedure show you how you can patch the - kernel using the extensible SDK and <filename>devtool</filename>. - <note> - Before attempting this procedure, be sure you have performed - the steps to get ready for updating the kernel as described - in the - "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" - section. - </note> - </para> - - <para> - Patching the kernel involves changing or adding configurations - to an existing kernel, changing or adding recipes to the kernel - that are needed to support specific hardware features, or even - altering the source code itself. - </para> - - <para> - This example creates a simple patch by adding some QEMU emulator - console output at boot time through <filename>printk</filename> - statements in the kernel's <filename>calibrate.c</filename> source - code file. - Applying the patch and booting the modified image causes the added - messages to appear on the emulator's console. - The example is a continuation of the setup procedure found in - the - "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" - Section. - <orderedlist> - <listitem><para> - <emphasis>Check Out the Kernel Source Files:</emphasis> - First you must use <filename>devtool</filename> to checkout - the kernel source code in its workspace. - Be sure you are in the terminal set up to do work - with the extensible SDK. - <note> - See this - <link linkend='setting-up-the-esdk-terminal'>step</link> - in the - "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" - section for more information. - </note> - Use the following <filename>devtool</filename> command - to check out the code: - <literallayout class='monospaced'> - $ devtool modify linux-yocto - </literallayout> - <note> - During the checkout operation, a bug exists that could - cause errors such as the following to appear: - <literallayout class='monospaced'> - ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus - be3a89ce7c47178880ba7bf6293d7404 for - /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack - </literallayout> - You can safely ignore these messages. - The source code is correctly checked out. - </note> - </para></listitem> - <listitem><para> - <emphasis>Edit the Source Files</emphasis> - Follow these steps to make some simple changes to the source - files: - <orderedlist> - <listitem><para> - <emphasis>Change the working directory</emphasis>: - In the previous step, the output noted where you can find - the source files (e.g. - <filename>~/poky_sdk/workspace/sources/linux-yocto</filename>). - Change to where the kernel source code is before making - your edits to the <filename>calibrate.c</filename> file: - <literallayout class='monospaced'> - $ cd ~/poky_sdk/workspace/sources/linux-yocto - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Edit the source file</emphasis>: - Edit the <filename>init/calibrate.c</filename> file to have - the following changes: - <literallayout class='monospaced'> - void calibrate_delay(void) - { - unsigned long lpj; - static bool printed; - int this_cpu = smp_processor_id(); - - printk("*************************************\n"); - printk("* *\n"); - printk("* HELLO YOCTO KERNEL *\n"); - printk("* *\n"); - printk("*************************************\n"); - - if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { - . - . - . - </literallayout> - </para></listitem> - </orderedlist> - </para></listitem> - <listitem><para> - <emphasis>Build the Updated Kernel Source:</emphasis> - To build the updated kernel source, use - <filename>devtool</filename>: - <literallayout class='monospaced'> - $ devtool build linux-yocto - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Create the Image With the New Kernel:</emphasis> - Use the <filename>devtool build-image</filename> command - to create a new image that has the new kernel. - <note> - If the image you originally created resulted in a Wic - file, you can use an alternate method to create the new - image with the updated kernel. - For an example, see the steps in the - <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink> - Wiki Page. - </note> - <literallayout class='monospaced'> - $ cd ~ - $ devtool build-image core-image-minimal - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Test the New Image:</emphasis> - For this example, you can run the new image using QEMU - to verify your changes: - <orderedlist> - <listitem><para> - <emphasis>Boot the image</emphasis>: - Boot the modified image in the QEMU emulator - using this command: - <literallayout class='monospaced'> - $ runqemu qemux86 - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Verify the changes</emphasis>: - Log into the machine using <filename>root</filename> - with no password and then use the following shell - command to scroll through the console's boot output. - <literallayout class='monospaced'> - # dmesg | less - </literallayout> - You should see the results of your - <filename>printk</filename> statements - as part of the output when you scroll down the - console window. - </para></listitem> - </orderedlist> - </para></listitem> - <listitem><para> - <emphasis>Stage and commit your changes</emphasis>: - Within your eSDK terminal, change your working directory to - where you modified the <filename>calibrate.c</filename> - file and use these Git commands to stage and commit your - changes: - <literallayout class='monospaced'> - $ cd ~/poky_sdk/workspace/sources/linux-yocto - $ git status - $ git add init/calibrate.c - $ git commit -m "calibrate: Add printk example" - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Export the Patches and Create an Append File:</emphasis> - To export your commits as patches and create a - <filename>.bbappend</filename> file, use the following - command in the terminal used to work with the extensible - SDK. - This example uses the previously established layer named - <filename>meta-mylayer</filename>. - <note> - See Step 3 of the - "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using devtool</link>" - section for information on setting up this layer. - </note> - <literallayout class='monospaced'> - $ devtool finish linux-yocto ~/meta-mylayer - </literallayout> - Once the command finishes, the patches and the - <filename>.bbappend</filename> file are located in the - <filename>~/meta-mylayer/recipes-kernel/linux</filename> - directory. - </para></listitem> - <listitem><para> - <emphasis>Build the Image With Your Modified Kernel:</emphasis> - You can now build an image that includes your kernel - patches. - Execute the following command from your - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> - in the terminal set up to run BitBake: - <literallayout class='monospaced'> - $ cd ~/poky/build - $ bitbake core-image-minimal - </literallayout> - </para></listitem> - </orderedlist> - </para> - </section> - - <section id="using-traditional-kernel-development-to-patch-the-kernel"> - <title>Using Traditional Kernel Development to Patch the Kernel</title> - - <para> - The steps in this procedure show you how you can patch the - kernel using traditional kernel development (i.e. not using - <filename>devtool</filename> and the extensible SDK as - described in the - "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" - section). - <note> - Before attempting this procedure, be sure you have performed - the steps to get ready for updating the kernel as described - in the - "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" - section. - </note> - </para> - - <para> - Patching the kernel involves changing or adding configurations - to an existing kernel, changing or adding recipes to the kernel - that are needed to support specific hardware features, or even - altering the source code itself. - </para> - - <para> - The example in this section creates a simple patch by adding some - QEMU emulator console output at boot time through - <filename>printk</filename> statements in the kernel's - <filename>calibrate.c</filename> source code file. - Applying the patch and booting the modified image causes the added - messages to appear on the emulator's console. - The example is a continuation of the setup procedure found in - the - "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" - Section. - <orderedlist> - <listitem><para> - <emphasis>Edit the Source Files</emphasis> - Prior to this step, you should have used Git to create a - local copy of the repository for your kernel. - Assuming you created the repository as directed in the - "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" - section, use the following commands to edit the - <filename>calibrate.c</filename> file: - <orderedlist> - <listitem><para> - <emphasis>Change the working directory</emphasis>: - You need to locate the source files in the - local copy of the kernel Git repository: - Change to where the kernel source code is before making - your edits to the <filename>calibrate.c</filename> file: - <literallayout class='monospaced'> - $ cd ~/linux-yocto-4.12/init - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Edit the source file</emphasis>: - Edit the <filename>calibrate.c</filename> file to have - the following changes: - <literallayout class='monospaced'> - void calibrate_delay(void) - { - unsigned long lpj; - static bool printed; - int this_cpu = smp_processor_id(); - - printk("*************************************\n"); - printk("* *\n"); - printk("* HELLO YOCTO KERNEL *\n"); - printk("* *\n"); - printk("*************************************\n"); - - if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { - . - . - . - </literallayout> - </para></listitem> - </orderedlist> - </para></listitem> - <listitem><para> - <emphasis>Stage and Commit Your Changes:</emphasis> - Use standard Git commands to stage and commit the changes - you just made: - <literallayout class='monospaced'> - $ git add calibrate.c - $ git commit -m "calibrate.c - Added some printk statements" - </literallayout> - If you do not stage and commit your changes, the OpenEmbedded - Build System will not pick up the changes. - </para></listitem> - <listitem><para> - <emphasis>Update Your <filename>local.conf</filename> File - to Point to Your Source Files:</emphasis> - In addition to your <filename>local.conf</filename> file - specifying to use "kernel-modules" and the "qemux86" - machine, it must also point to the updated kernel source - files. - Add - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> - statements similar to the following to your - <filename>local.conf</filename>: - <literallayout class='monospaced'> - $ cd ~/poky/build/conf - </literallayout> - Add the following to the <filename>local.conf</filename>: - <literallayout class='monospaced'> - SRC_URI_pn-linux-yocto = "git:///<replaceable>path-to</replaceable>/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ - git:///<replaceable>path-to</replaceable>/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" - SRCREV_meta_qemux86 = "${AUTOREV}" - SRCREV_machine_qemux86 = "${AUTOREV}" - </literallayout> - <note> - Be sure to replace - <replaceable>path-to</replaceable> with the pathname - to your local Git repositories. - Also, you must be sure to specify the correct branch - and machine types. - For this example, the branch is - <filename>standard/base</filename> and the machine is - "qemux86". - </note> - </para></listitem> - <listitem><para> - <emphasis>Build the Image:</emphasis> - With the source modified, your changes staged and - committed, and the <filename>local.conf</filename> file - pointing to the kernel files, you can now use BitBake to - build the image: - <literallayout class='monospaced'> - $ cd ~/poky/build - $ bitbake core-image-minimal - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Boot the image</emphasis>: - Boot the modified image in the QEMU emulator - using this command. - When prompted to login to the QEMU console, use "root" - with no password: - <literallayout class='monospaced'> - $ cd ~/poky/build - $ runqemu qemux86 - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Look for Your Changes:</emphasis> - As QEMU booted, you might have seen your changes rapidly - scroll by. - If not, use these commands to see your changes: - <literallayout class='monospaced'> - # dmesg | less - </literallayout> - You should see the results of your - <filename>printk</filename> statements - as part of the output when you scroll down the - console window. - </para></listitem> - <listitem><para> - <emphasis>Generate the Patch File:</emphasis> - Once you are sure that your patch works correctly, you - can generate a <filename>*.patch</filename> file in the - kernel source repository: - <literallayout class='monospaced'> - $ cd ~/linux-yocto-4.12/init - $ git format-patch -1 - 0001-calibrate.c-Added-some-printk-statements.patch - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Move the Patch File to Your Layer:</emphasis> - In order for subsequent builds to pick up patches, you - need to move the patch file you created in the previous - step to your layer <filename>meta-mylayer</filename>. - For this example, the layer created earlier is located - in your home directory as <filename>meta-mylayer</filename>. - When the layer was created using the - <filename>yocto-create</filename> script, no additional - hierarchy was created to support patches. - Before moving the patch file, you need to add additional - structure to your layer using the following commands: - <literallayout class='monospaced'> - $ cd ~/meta-mylayer - $ mkdir recipes-kernel - $ mkdir recipes-kernel/linux - $ mkdir recipes-kernel/linux/linux-yocto - </literallayout> - Once you have created this hierarchy in your layer, you can - move the patch file using the following command: - <literallayout class='monospaced'> - $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Create the Append File:</emphasis> - Finally, you need to create the - <filename>linux-yocto_4.12.bbappend</filename> file and - insert statements that allow the OpenEmbedded build - system to find the patch. - The append file needs to be in your layer's - <filename>recipes-kernel/linux</filename> - directory and it must be named - <filename>linux-yocto_4.12.bbappend</filename> and have - the following contents: - <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - - SRC_URI_append = " file://0001-calibrate.c-Added-some-printk-statements.patch" - </literallayout> - The - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statements enable the OpenEmbedded build system to find - the patch file.</para> - - <para>For more information on append files and patches, - see the - "<link linkend='creating-the-append-file'>Creating the Append File</link>" - and - "<link linkend='applying-patches'>Applying Patches</link>" - sections. - You can also see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer"</ulink>" - section in the Yocto Project Development Tasks Manual. - <note> - To build <filename>core-image-minimal</filename> - again and see the effects of your patch, you can - essentially eliminate the temporary source files - saved in <filename>poky/build/tmp/work/...</filename> - and residual effects of the build by entering the - following sequence of commands: - <literallayout class='monospaced'> - $ cd ~/poky/build - $ bitbake -c cleanall yocto-linux - $ bitbake core-image-minimal -c cleanall - $ bitbake core-image-minimal - $ runqemu qemux86 - </literallayout> - </note> - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='configuring-the-kernel'> - <title>Configuring the Kernel</title> - - <para> - Configuring the Yocto Project kernel consists of making sure the - <filename>.config</filename> file has all the right information - in it for the image you are building. - You can use the <filename>menuconfig</filename> tool and - configuration fragments to make sure your - <filename>.config</filename> file is just how you need it. - You can also save known configurations in a - <filename>defconfig</filename> file that the build system can use - for kernel configuration. - </para> - - <para> - This section describes how to use <filename>menuconfig</filename>, - create and use configuration fragments, and how to interactively - modify your <filename>.config</filename> file to create the - leanest kernel configuration file possible. - </para> - - <para> - For more information on kernel configuration, see the - "<link linkend='changing-the-configuration'>Changing the Configuration</link>" - section. - </para> - - <section id='using-menuconfig'> - <title>Using <filename>menuconfig</filename></title> - - <para> - The easiest way to define kernel configurations is to set - them through the <filename>menuconfig</filename> tool. - This tool provides an interactive method with which - to set kernel configurations. - For general information on <filename>menuconfig</filename>, see - <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>. - </para> - - <para> - To use the <filename>menuconfig</filename> tool in the Yocto - Project development environment, you must do the following: - <itemizedlist> - <listitem><para> - Because you launch <filename>menuconfig</filename> - using BitBake, you must be sure to set up your - environment by running the - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - script found in the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. - </para></listitem> - <listitem><para> - You must be sure of the state of your build's - configuration in the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. - </para></listitem> - <listitem><para> - Your build host must have the following two packages - installed: - <literallayout class='monospaced'> - libncurses5-dev - libtinfo-dev - </literallayout> - </para></listitem> - </itemizedlist> - </para> - - <para> - The following commands initialize the BitBake environment, - run the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink> - task, and launch <filename>menuconfig</filename>. - These commands assume the Source Directory's top-level folder - is <filename>~/poky</filename>: - <literallayout class='monospaced'> - $ cd poky - $ source oe-init-build-env - $ bitbake linux-yocto -c kernel_configme -f - $ bitbake linux-yocto -c menuconfig - </literallayout> - Once <filename>menuconfig</filename> comes up, its standard - interface allows you to interactively examine and configure - all the kernel configuration parameters. - After making your changes, simply exit the tool and save your - changes to create an updated version of the - <filename>.config</filename> configuration file. - <note> - You can use the entire <filename>.config</filename> file - as the <filename>defconfig</filename> file. - For information on <filename>defconfig</filename> files, - see the - "<link linkend='changing-the-configuration'>Changing the Configuration</link>", - "<link linkend='using-an-in-tree-defconfig-file'>Using an In-Tree <filename>defconfig</filename> File</link>, - and - "<link linkend='creating-a-defconfig-file'>Creating a <filename>defconfig</filename> File</link>" - sections. - </note> - </para> - - <para> - Consider an example that configures the "CONFIG_SMP" setting - for the <filename>linux-yocto-4.12</filename> kernel. - <note> - The OpenEmbedded build system recognizes this kernel as - <filename>linux-yocto</filename> through Metadata (e.g. - <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink><filename>_linux-yocto ?= "12.4%"</filename>). - </note> - Once <filename>menuconfig</filename> launches, use the - interface to navigate through the selections to find the - configuration settings in which you are interested. - For this example, you deselect "CONFIG_SMP" by clearing the - "Symmetric Multi-Processing Support" option. - Using the interface, you can find the option under - "Processor Type and Features". - To deselect "CONFIG_SMP", use the arrow keys to - highlight "Symmetric Multi-Processing Support" and enter "N" - to clear the asterisk. - When you are finished, exit out and save the change. - </para> - - <para> - Saving the selections updates the <filename>.config</filename> - configuration file. - This is the file that the OpenEmbedded build system uses to - configure the kernel during the build. - You can find and examine this file in the Build Directory in - <filename>tmp/work/</filename>. - The actual <filename>.config</filename> is located in the - area where the specific kernel is built. - For example, if you were building a Linux Yocto kernel based - on the <filename>linux-yocto-4.12</filename> kernel and you - were building a QEMU image targeted for - <filename>x86</filename> architecture, the - <filename>.config</filename> file would be: - <literallayout class='monospaced'> - poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18... - ...967-r0/linux-qemux86-standard-build/.config - </literallayout> - <note> - The previous example directory is artificially split and - many of the characters in the actual filename are omitted - in order to make it more readable. - Also, depending on the kernel you are using, the exact - pathname might differ. - </note> - </para> - - <para> - Within the <filename>.config</filename> file, you can see the - kernel settings. - For example, the following entry shows that symmetric - multi-processor support is not set: - <literallayout class='monospaced'> - # CONFIG_SMP is not set - </literallayout> - </para> - - <para> - A good method to isolate changed configurations is to use a - combination of the <filename>menuconfig</filename> tool and - simple shell commands. - Before changing configurations with - <filename>menuconfig</filename>, copy the existing - <filename>.config</filename> and rename it to something else, - use <filename>menuconfig</filename> to make as many changes as - you want and save them, then compare the renamed configuration - file against the newly created file. - You can use the resulting differences as your base to create - configuration fragments to permanently save in your kernel - layer. - <note> - Be sure to make a copy of the <filename>.config</filename> - file and do not just rename it. - The build system needs an existing - <filename>.config</filename> file from which to work. - </note> - </para> - </section> - - <section id='creating-a-defconfig-file'> - <title>Creating a <filename>defconfig</filename> File</title> - - <para> - A <filename>defconfig</filename> file in the context of - the Yocto Project is often a <filename>.config</filename> - file that is copied from a build or a - <filename>defconfig</filename> taken from the kernel tree - and moved into recipe space. - You can use a <filename>defconfig</filename> file - to retain a known set of kernel configurations from which the - OpenEmbedded build system can draw to create the final - <filename>.config</filename> file. - <note> - Out-of-the-box, the Yocto Project never ships a - <filename>defconfig</filename> or - <filename>.config</filename> file. - The OpenEmbedded build system creates the final - <filename>.config</filename> file used to configure the - kernel. - </note> - </para> - - <para> - To create a <filename>defconfig</filename>, start with a - complete, working Linux kernel <filename>.config</filename> - file. - Copy that file to the appropriate - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> - directory in your layer's - <filename>recipes-kernel/linux</filename> directory, and rename - the copied file to "defconfig" (e.g. - <filename>~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig</filename>). - Then, add the following lines to the linux-yocto - <filename>.bbappend</filename> file in your layer: - <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - SRC_URI += "file://defconfig" - </literallayout> - The - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - tells the build system how to search for the file, while the - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - extends the - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> - variable (search directories) to include the - <filename>${PN}</filename> directory you created to hold the - configuration changes. - <note> - The build system applies the configurations from the - <filename>defconfig</filename> file before applying any - subsequent configuration fragments. - The final kernel configuration is a combination of the - configurations in the <filename>defconfig</filename> - file and any configuration fragments you provide. - You need to realize that if you have any configuration - fragments, the build system applies these on top of and - after applying the existing defconfig file configurations. - </note> - For more information on configuring the kernel, see the - "<link linkend='changing-the-configuration'>Changing the Configuration</link>" - section. - </para> - </section> - - <section id='creating-config-fragments'> - <title>Creating Configuration Fragments</title> - - <para> - Configuration fragments are simply kernel options that - appear in a file placed where the OpenEmbedded build system - can find and apply them. - The build system applies configuration fragments after - applying configurations from a <filename>defconfig</filename> - file. - Thus, the final kernel configuration is a combination of the - configurations in the <filename>defconfig</filename> - file and then any configuration fragments you provide. - The build system applies fragments on top of and - after applying the existing defconfig file configurations. - </para> - - <para> - Syntactically, the configuration statement is identical to - what would appear in the <filename>.config</filename> file, - which is in the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. - <note> - For more information about where the - <filename>.config</filename> file is located, see the - example in the - "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>" - section. - </note> - </para> - - <para> - It is simple to create a configuration fragment. - One method is to use shell commands. - For example, issuing the following from the shell creates a - configuration fragment file named - <filename>my_smp.cfg</filename> that enables multi-processor - support within the kernel: - <literallayout class='monospaced'> - $ echo "CONFIG_SMP=y" >> my_smp.cfg - </literallayout> - <note> - All configuration fragment files must use the - <filename>.cfg</filename> extension in order for the - OpenEmbedded build system to recognize them as a - configuration fragment. - </note> - </para> - - <para> - Another method is to create a configuration fragment using the - differences between two configuration files: one previously - created and saved, and one freshly created using the - <filename>menuconfig</filename> tool. - </para> - - <para> - To create a configuration fragment using this method, follow - these steps: - <orderedlist> - <listitem><para> - <emphasis>Complete a Build Through Kernel Configuration:</emphasis> - Complete a build at least through the kernel - configuration task as follows: - <literallayout class='monospaced'> - $ bitbake linux-yocto -c kernel_configme -f - </literallayout> - This step ensures that you create a - <filename>.config</filename> file from a known state. - Because situations exist where your build state might - become unknown, it is best to run this task prior - to starting <filename>menuconfig</filename>. - </para></listitem> - <listitem><para> - <emphasis>Launch <filename>menuconfig</filename>:</emphasis> - Run the <filename>menuconfig</filename> command: - <literallayout class='monospaced'> - $ bitbake linux-yocto -c menuconfig - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Create the Configuration Fragment:</emphasis> - Run the <filename>diffconfig</filename> - command to prepare a configuration fragment. - The resulting file <filename>fragment.cfg</filename> - is placed in the - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> directory: - <literallayout class='monospaced'> - $ bitbake linux-yocto -c diffconfig - </literallayout> - </para></listitem> - </orderedlist> - </para> - - <para> - The <filename>diffconfig</filename> command creates a file - that is a list of Linux kernel <filename>CONFIG_</filename> - assignments. - See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>" - section for additional information on how to use the output - as a configuration fragment. - <note> - You can also use this method to create configuration - fragments for a BSP. - See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>" - section for more information. - </note> - </para> - - <para> - Where do you put your configuration fragment files? - You can place these files in an area pointed to by - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - as directed by your <filename>bblayers.conf</filename> file, - which is located in your layer. - The OpenEmbedded build system picks up the configuration and - adds it to the kernel's configuration. - For example, suppose you had a set of configuration options - in a file called <filename>myconfig.cfg</filename>. - If you put that file inside a directory named - <filename>linux-yocto</filename> that resides in the same - directory as the kernel's append file within your layer - and then add the following statements to the kernel's append - file, those configuration options will be picked up and applied - when the kernel is built: - <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - SRC_URI += "file://myconfig.cfg" - </literallayout> - </para> - - <para> - As mentioned earlier, you can group related configurations - into multiple files and name them all in the - <filename>SRC_URI</filename> statement as well. - For example, you could group separate configurations - specifically for Ethernet and graphics into their own files - and add those by using a <filename>SRC_URI</filename> statement - like the following in your append file: - <literallayout class='monospaced'> - SRC_URI += "file://myconfig.cfg \ - file://eth.cfg \ - file://gfx.cfg" - </literallayout> - </para> - </section> - - <section id='validating-configuration'> - <title>Validating Configuration</title> - - <para> - You can use the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink> - task to provide configuration validation: - <literallayout class='monospaced'> - $ bitbake linux-yocto -c kernel_configcheck -f - </literallayout> - Running this task produces warnings for when a - requested configuration does not appear in the final - <filename>.config</filename> file or when you override a - policy configuration in a hardware configuration fragment. - </para> - - <para> - In order to run this task, you must have an existing - <filename>.config</filename> file. - See the - "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>" - section for information on how to create a configuration file. - </para> - - <para> - Following is sample output from the - <filename>do_kernel_configcheck</filename> task: - <literallayout class='monospaced'> - Loading cache: 100% |########################################################| Time: 0:00:00 - Loaded 1275 entries from dependency cache. - NOTE: Resolving any missing task queue dependencies - - Build Configuration: - . - . - . - - NOTE: Executing SetScene Tasks - NOTE: Executing RunQueue Tasks - WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck: - [kernel config]: specified values did not make it into the kernel's final configuration: - - ---------- CONFIG_X86_TSC ----------------- - Config: CONFIG_X86_TSC - From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg - Requested value: CONFIG_X86_TSC=y - Actual value: - - - ---------- CONFIG_X86_BIGSMP ----------------- - Config: CONFIG_X86_BIGSMP - From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg - /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig - Requested value: # CONFIG_X86_BIGSMP is not set - Actual value: - - - ---------- CONFIG_NR_CPUS ----------------- - Config: CONFIG_NR_CPUS - From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg - /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg - /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig - Requested value: CONFIG_NR_CPUS=8 - Actual value: CONFIG_NR_CPUS=1 - - - ---------- CONFIG_SCHED_SMT ----------------- - Config: CONFIG_SCHED_SMT - From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg - /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig - Requested value: CONFIG_SCHED_SMT=y - Actual value: - - - - NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded. - - Summary: There were 3 WARNING messages shown. - </literallayout> - <note> - The previous output example has artificial line breaks - to make it more readable. - </note> - </para> - - <para> - The output describes the various problems that you can - encounter along with where to find the offending configuration - items. - You can use the information in the logs to adjust your - configuration files and then repeat the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink> - tasks until they produce no warnings. - </para> - - <para> - For more information on how to use the - <filename>menuconfig</filename> tool, see the - "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>" - section. - </para> - </section> - - <section id='fine-tuning-the-kernel-configuration-file'> - <title>Fine-Tuning the Kernel Configuration File</title> - - <para> - You can make sure the <filename>.config</filename> file is as - lean or efficient as possible by reading the output of the - kernel configuration fragment audit, noting any issues, making - changes to correct the issues, and then repeating. - </para> - - <para> - As part of the kernel build process, the - <filename>do_kernel_configcheck</filename> task runs. - This task validates the kernel configuration by checking the - final <filename>.config</filename> file against the input - files. - During the check, the task produces warning messages for the - following issues: - <itemizedlist> - <listitem><para> - Requested options that did not make the final - <filename>.config</filename> file. - </para></listitem> - <listitem><para> - Configuration items that appear twice in the same - configuration fragment. - </para></listitem> - <listitem><para> - Configuration items tagged as "required" that were - overridden. - </para></listitem> - <listitem><para> - A board overrides a non-board specific option. - </para></listitem> - <listitem><para> - Listed options not valid for the kernel being - processed. - In other words, the option does not appear anywhere. - </para></listitem> - </itemizedlist> - <note> - The <filename>do_kernel_configcheck</filename> task can - also optionally report if an option is overridden during - processing. - </note> - </para> - - <para> - For each output warning, a message points to the file - that contains a list of the options and a pointer to the - configuration fragment that defines them. - Collectively, the files are the key to streamlining the - configuration. - </para> - - <para> - To streamline the configuration, do the following: - <orderedlist> - <listitem><para> - <emphasis>Use a Working Configuration:</emphasis> - Start with a full configuration that you - know works. - Be sure the configuration builds and boots - successfully. - Use this configuration file as your baseline. - </para></listitem> - <listitem><para> - <emphasis>Run Configure and Check Tasks:</emphasis> - Separately run the - <filename>do_kernel_configme</filename> and - <filename>do_kernel_configcheck</filename> tasks: - <literallayout class='monospaced'> - $ bitbake linux-yocto -c kernel_configme -f - $ bitbake linux-yocto -c kernel_configcheck -f - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Process the Results:</emphasis> - Take the resulting list of files from the - <filename>do_kernel_configcheck</filename> task - warnings and do the following: - <itemizedlist> - <listitem><para> - Drop values that are redefined in the fragment - but do not change the final - <filename>.config</filename> file. - </para></listitem> - <listitem><para> - Analyze and potentially drop values from the - <filename>.config</filename> file that override - required configurations. - </para></listitem> - <listitem><para> - Analyze and potentially remove non-board - specific options. - </para></listitem> - <listitem><para> - Remove repeated and invalid options. - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para> - <emphasis>Re-Run Configure and Check Tasks:</emphasis> - After you have worked through the output of the kernel - configuration audit, you can re-run the - <filename>do_kernel_configme</filename> and - <filename>do_kernel_configcheck</filename> tasks to - see the results of your changes. - If you have more issues, you can deal with them as - described in the previous step. - </para></listitem> - </orderedlist> - </para> - - <para> - Iteratively working through steps two through four eventually - yields a minimal, streamlined configuration file. - Once you have the best <filename>.config</filename>, you can - build the Linux Yocto kernel. - </para> - </section> - </section> - - <section id='expanding-variables'> - <title>Expanding Variables</title> - - <para> - Sometimes it is helpful to determine what a variable expands - to during a build. - You can do examine the values of variables by examining the - output of the <filename>bitbake -e</filename> command. - The output is long and is more easily managed in a text file, - which allows for easy searches: - <literallayout class='monospaced'> - $ bitbake -e virtual/kernel > <replaceable>some_text_file</replaceable> - </literallayout> - Within the text file, you can see exactly how each variable is - expanded and used by the OpenEmbedded build system. - </para> - </section> - - <section id='working-with-a-dirty-kernel-version-string'> - <title>Working with a "Dirty" Kernel Version String</title> - - <para> - If you build a kernel image and the version string has a - "+" or a "-dirty" at the end, uncommitted modifications exist - in the kernel's source directory. - Follow these steps to clean up the version string: - <orderedlist> - <listitem><para> - <emphasis>Discover the Uncommitted Changes:</emphasis> - Go to the kernel's locally cloned Git repository - (source directory) and use the following Git command - to list the files that have been changed, added, or - removed: - <literallayout class='monospaced'> - $ git status - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Commit the Changes:</emphasis> - You should commit those changes to the kernel source - tree regardless of whether or not you will save, - export, or use the changes: - <literallayout class='monospaced'> - $ git add - $ git commit -s -a -m "getting rid of -dirty" - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Rebuild the Kernel Image:</emphasis> - Once you commit the changes, rebuild the kernel.</para> - - <para>Depending on your particular kernel development - workflow, the commands you use to rebuild the - kernel might differ. - For information on building the kernel image when - using <filename>devtool</filename>, see the - "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" - section. - For information on building the kernel image when - using Bitbake, see the - "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" - section. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='working-with-your-own-sources'> - <title>Working With Your Own Sources</title> - - <para> - If you cannot work with one of the Linux kernel - versions supported by existing linux-yocto recipes, you can - still make use of the Yocto Project Linux kernel tooling by - working with your own sources. - When you use your own sources, you will not be able to - leverage the existing kernel - <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> and - stabilization work of the linux-yocto sources. - However, you will be able to manage your own Metadata in the same - format as the linux-yocto sources. - Maintaining format compatibility facilitates converging with - linux-yocto on a future, mutually-supported kernel version. - </para> - - <para> - To help you use your own sources, the Yocto Project provides a - linux-yocto custom recipe - (<filename>linux-yocto-custom.bb</filename>) that uses - <filename>kernel.org</filename> sources - and the Yocto Project Linux kernel tools for managing - kernel Metadata. - You can find this recipe in the - <filename>poky</filename> Git repository of the - Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink> - at: - <literallayout class="monospaced"> - poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb - </literallayout> - </para> - - <para> - Here are some basic steps you can use to work with your own - sources: - <orderedlist> - <listitem><para> - <emphasis>Create a Copy of the Kernel Recipe:</emphasis> - Copy the <filename>linux-yocto-custom.bb</filename> - recipe to your layer and give it a meaningful name. - The name should include the version of the Yocto Linux - kernel you are using (e.g. - <filename>linux-yocto-myproject_4.12.bb</filename>, - where "4.12" is the base version of the Linux kernel - with which you would be working). - </para></listitem> - <listitem><para> - <emphasis>Create a Directory for Your Patches:</emphasis> - In the same directory inside your layer, create a matching - directory to store your patches and configuration files - (e.g. <filename>linux-yocto-myproject</filename>). - </para></listitem> - <listitem><para> - <emphasis>Ensure You Have Configurations:</emphasis> - Make sure you have either a <filename>defconfig</filename> - file or configuration fragment files in your layer. - When you use the <filename>linux-yocto-custom.bb</filename> - recipe, you must specify a configuration. - If you do not have a <filename>defconfig</filename> file, - you can run the following: - <literallayout class='monospaced'> - $ make defconfig - </literallayout> - After running the command, copy the resulting - <filename>.config</filename> file to the - <filename>files</filename> directory in your layer - as "defconfig" and then add it to the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - variable in the recipe.</para> - - <para>Running the <filename>make defconfig</filename> - command results in the default configuration for your - architecture as defined by your kernel. - However, no guarantee exists that this configuration is - valid for your use case, or that your board will even boot. - This is particularly true for non-x86 architectures.</para> - - <para>To use non-x86 <filename>defconfig</filename> files, - you need to be more specific and find one that matches your - board (i.e. for arm, you look in - <filename>arch/arm/configs</filename> and use the one that - is the best starting point for your board). - </para></listitem> - <listitem><para> - <emphasis>Edit the Recipe:</emphasis> - Edit the following variables in your recipe as appropriate - for your project: - <itemizedlist> - <listitem><para> - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>: - The <filename>SRC_URI</filename> should specify - a Git repository that uses one of the supported Git - fetcher protocols (i.e. <filename>file</filename>, - <filename>git</filename>, <filename>http</filename>, - and so forth). - The <filename>SRC_URI</filename> variable should - also specify either a <filename>defconfig</filename> - file or some configuration fragment files. - The skeleton recipe provides an example - <filename>SRC_URI</filename> as a syntax reference. - </para></listitem> - <listitem><para> - <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>: - The Linux kernel version you are using (e.g. - "4.12"). - </para></listitem> - <listitem><para> - <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>: - The Linux kernel - <filename>CONFIG_LOCALVERSION</filename> that is - compiled into the resulting kernel and visible - through the <filename>uname</filename> command. - </para></listitem> - <listitem><para> - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>: - The commit ID from which you want to build. - </para></listitem> - <listitem><para> - <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>: - Treat this variable the same as you would in any - other recipe. - Increment the variable to indicate to the - OpenEmbedded build system that the recipe has - changed. - </para></listitem> - <listitem><para> - <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>: - The default <filename>PV</filename> assignment is - typically adequate. - It combines the <filename>LINUX_VERSION</filename> - with the Source Control Manager (SCM) revision - as derived from the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink> - variable. - The combined results are a string with the - following form: - <literallayout class='monospaced'> - 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 - </literallayout> - While lengthy, the extra verbosity in - <filename>PV</filename> helps ensure you are using - the exact sources from which you intend to build. - </para></listitem> - <listitem><para> - <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>: - A list of the machines supported by your new recipe. - This variable in the example recipe is set - by default to a regular expression that matches - only the empty string, "(^$)". - This default setting triggers an explicit build - failure. - You must change it to match a list of the machines - that your new recipe supports. - For example, to support the - <filename>qemux86</filename> and - <filename>qemux86-64</filename> machines, use - the following form: - <literallayout class='monospaced'> - COMPATIBLE_MACHINE = "qemux86|qemux86-64" - </literallayout> - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para> - <emphasis>Customize Your Recipe as Needed:</emphasis> - Provide further customizations to your recipe - as needed just as you would customize an existing - linux-yocto recipe. - See the - "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>" - section for information. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='working-with-out-of-tree-modules'> - <title>Working with Out-of-Tree Modules</title> - - <para> - This section describes steps to build out-of-tree modules on - your target and describes how to incorporate out-of-tree modules - in the build. - </para> - - <section id='building-out-of-tree-modules-on-the-target'> - <title>Building Out-of-Tree Modules on the Target</title> - - <para> - While the traditional Yocto Project development model would be - to include kernel modules as part of the normal build - process, you might find it useful to build modules on the - target. - This could be the case if your target system is capable - and powerful enough to handle the necessary compilation. - Before deciding to build on your target, however, you should - consider the benefits of using a proper cross-development - environment from your build host. - </para> - - <para> - If you want to be able to build out-of-tree modules on - the target, there are some steps you need to take - on the target that is running your SDK image. - Briefly, the <filename>kernel-dev</filename> package - is installed by default on all - <filename>*.sdk</filename> images and the - <filename>kernel-devsrc</filename> package is installed - on many of the <filename>*.sdk</filename> images. - However, you need to create some scripts prior to - attempting to build the out-of-tree modules on the target - that is running that image. - </para> - - <para> - Prior to attempting to build the out-of-tree modules, - you need to be on the target as root and you need to - change to the <filename>/usr/src/kernel</filename> directory. - Next, <filename>make</filename> the scripts: - <literallayout class='monospaced'> - # cd /usr/src/kernel - # make scripts - </literallayout> - Because all SDK image recipes include - <filename>dev-pkgs</filename>, the - <filename>kernel-dev</filename> packages will be installed - as part of the SDK image and the - <filename>kernel-devsrc</filename> packages will be installed - as part of applicable SDK images. - The SDK uses the scripts when building out-of-tree - modules. - Once you have switched to that directory and created the - scripts, you should be able to build your out-of-tree modules - on the target. - </para> - </section> - - <section id='incorporating-out-of-tree-modules'> - <title>Incorporating Out-of-Tree Modules</title> - - <para> - While it is always preferable to work with sources integrated - into the Linux kernel sources, if you need an external kernel - module, the <filename>hello-mod.bb</filename> recipe is - available as a template from which you can create your - own out-of-tree Linux kernel module recipe. - </para> - - <para> - This template recipe is located in the - <filename>poky</filename> Git repository of the - Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink> - at: - <literallayout class="monospaced"> - poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb - </literallayout> - </para> - - <para> - To get started, copy this recipe to your layer and give it a - meaningful name (e.g. <filename>mymodule_1.0.bb</filename>). - In the same directory, create a new directory named - <filename>files</filename> where you can store any source files, - patches, or other files necessary for building - the module that do not come with the sources. - Finally, update the recipe as needed for the module. - Typically, you will need to set the following variables: - <itemizedlist> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> - </para></listitem> - </itemizedlist> - </para> - - <para> - Depending on the build system used by the module sources, - you might need to make some adjustments. - For example, a typical module <filename>Makefile</filename> - looks much like the one provided with the - <filename>hello-mod</filename> template: - <literallayout class='monospaced'> - obj-m := hello.o - - SRC := $(shell pwd) - - all: - $(MAKE) -C $(KERNEL_SRC) M=$(SRC) - - modules_install: - $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install - ... - </literallayout> - </para> - - <para> - The important point to note here is the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink> - variable. - The - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-module'><filename>module</filename></ulink> - class sets this variable and the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink> - variable to - <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename> - with the necessary Linux kernel build information to build - modules. - If your module <filename>Makefile</filename> uses a different - variable, you might want to override the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink> - step, or create a patch to - the <filename>Makefile</filename> to work with the more typical - <filename>KERNEL_SRC</filename> or - <filename>KERNEL_PATH</filename> variables. - </para> - - <para> - After you have prepared your recipe, you will likely want to - include the module in your images. - To do this, see the documentation for the following variables in - the Yocto Project Reference Manual and set one of them - appropriately for your machine configuration file: - <itemizedlist> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink> - </para></listitem> - </itemizedlist> - </para> - - <para> - Modules are often not required for boot and can be excluded from - certain build configurations. - The following allows for the most flexibility: - <literallayout class='monospaced'> - MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" - </literallayout> - The value is derived by appending the module filename without - the <filename>.ko</filename> extension to the string - "kernel-module-". - </para> - - <para> - Because the variable is - <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> - and not a - <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> - variable, the build will not fail if this module is not - available to include in the image. - </para> - </section> - </section> - - - <section id='inspecting-changes-and-commits'> - <title>Inspecting Changes and Commits</title> - - <para> - A common question when working with a kernel is: - "What changes have been applied to this tree?" - Rather than using "grep" across directories to see what has - changed, you can use Git to inspect or search the kernel tree. - Using Git is an efficient way to see what has changed in the tree. - </para> - - <section id='what-changed-in-a-kernel'> - <title>What Changed in a Kernel?</title> - - <para> - Following are a few examples that show how to use Git - commands to examine changes. - These examples are by no means the only way to see changes. - <note> - In the following examples, unless you provide a commit - range, <filename>kernel.org</filename> history is blended - with Yocto Project kernel changes. - You can form ranges by using branch names from the - kernel tree as the upper and lower commit markers with - the Git commands. - You can see the branch names through the web interface - to the Yocto Project source repositories at - <ulink url='&YOCTO_GIT_URL;'></ulink>. - </note> - To see a full range of the changes, use the - <filename>git whatchanged</filename> command and specify a - commit range for the branch - (<replaceable>commit</replaceable><filename>..</filename><replaceable>commit</replaceable>). - </para> - - <para> - Here is an example that looks at what has changed in the - <filename>emenlow</filename> branch of the - <filename>linux-yocto-3.19</filename> kernel. - The lower commit range is the commit associated with the - <filename>standard/base</filename> branch, while - the upper commit range is the commit associated with the - <filename>standard/emenlow</filename> branch. - <literallayout class='monospaced'> - $ git whatchanged origin/standard/base..origin/standard/emenlow - </literallayout> - </para> - - <para> - To see short, one line summaries of changes use the - <filename>git log</filename> command: - <literallayout class='monospaced'> - $ git log --oneline origin/standard/base..origin/standard/emenlow - </literallayout> - </para> - - <para> - Use this command to see code differences for the changes: - <literallayout class='monospaced'> - $ git diff origin/standard/base..origin/standard/emenlow - </literallayout> - </para> - - <para> - Use this command to see the commit log messages and the - text differences: - <literallayout class='monospaced'> - $ git show origin/standard/base..origin/standard/emenlow - </literallayout> - </para> - - <para> - Use this command to create individual patches for - each change. - Here is an example that that creates patch files for each - commit and places them in your <filename>Documents</filename> - directory: - <literallayout class='monospaced'> - $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow - </literallayout> - </para> - </section> - - <section id='showing-a-particular-feature-or-branch-change'> - <title>Showing a Particular Feature or Branch Change</title> - - <para> - Tags in the Yocto Project kernel tree divide changes for - significant features or branches. - The <filename>git show</filename> <replaceable>tag</replaceable> - command shows changes based on a tag. - Here is an example that shows <filename>systemtap</filename> - changes: - <literallayout class='monospaced'> - $ git show systemtap - </literallayout> - You can use the - <filename>git branch --contains</filename> <replaceable>tag</replaceable> - command to show the branches that contain a particular feature. - This command shows the branches that contain the - <filename>systemtap</filename> feature: - <literallayout class='monospaced'> - $ git branch --contains systemtap - </literallayout> - </para> - </section> - </section> - - <section id='adding-recipe-space-kernel-features'> - <title>Adding Recipe-Space Kernel Features</title> - - <para> - You can add kernel features in the - <link linkend='recipe-space-metadata'>recipe-space</link> by - using the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> - variable and by specifying the feature's <filename>.scc</filename> - file path in the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statement. - When you add features using this method, the OpenEmbedded build - system checks to be sure the features are present. - If the features are not present, the build stops. - Kernel features are the last elements processed for configuring - and patching the kernel. - Therefore, adding features in this manner is a way - to enforce specific features are present and enabled - without needing to do a full audit of any other layer's additions - to the <filename>SRC_URI</filename> statement. - </para> - - <para> - You add a kernel feature by providing the feature as part of the - <filename>KERNEL_FEATURES</filename> variable and by providing the - path to the feature's <filename>.scc</filename> file, which is - relative to the root of the kernel Metadata. - The OpenEmbedded build system searches all forms of kernel - Metadata on the <filename>SRC_URI</filename> statement regardless - of whether the Metadata is in the "kernel-cache", system kernel - Metadata, or a recipe-space Metadata (i.e. part of the kernel - recipe). - See the - "<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>" - section for additional information. - </para> - - <para> - When you specify the feature's <filename>.scc</filename> file - on the <filename>SRC_URI</filename> statement, the OpenEmbedded - build system adds the directory of that - <filename>.scc</filename> file along with all its subdirectories - to the kernel feature search path. - Because subdirectories are searched, you can reference a single - <filename>.scc</filename> file in the - <filename>SRC_URI</filename> statement to reference multiple kernel - features. - </para> - - <para> - Consider the following example that adds the "test.scc" feature - to the build. - <orderedlist> - <listitem><para> - <emphasis>Create the Feature File:</emphasis> - Create a <filename>.scc</filename> file and locate it - just as you would any other patch file, - <filename>.cfg</filename> file, or fetcher item - you specify in the <filename>SRC_URI</filename> - statement. - <note><title>Notes</title> - <itemizedlist> - <listitem><para> - You must add the directory of the - <filename>.scc</filename> file to the fetcher's - search path in the same manner as you would - add a <filename>.patch</filename> file. - </para></listitem> - <listitem><para> - You can create additional - <filename>.scc</filename> files beneath the - directory that contains the file you are - adding. - All subdirectories are searched during the - build as potential feature directories. - </para></listitem> - </itemizedlist> - </note> - Continuing with the example, suppose the "test.scc" - feature you are adding has a - <filename>test.scc</filename> file in the following - directory: - <literallayout class='monospaced'> - <replaceable>my_recipe</replaceable> - | - +-linux-yocto - | - +-test.cfg - +-test.scc - </literallayout> - In this example, the <filename>linux-yocto</filename> - directory has both the feature - <filename>test.scc</filename> file and a similarly - named configuration fragment file - <filename>test.cfg</filename>. - </para></listitem> - <listitem><para> - <emphasis>Add the Feature File to <filename>SRC_URI</filename>:</emphasis> - Add the <filename>.scc</filename> file to the - recipe's <filename>SRC_URI</filename> statement: - <literallayout class='monospaced'> - SRC_URI_append = " file://test.scc" - </literallayout> - The leading space before the path is important as the - path is appended to the existing path. - </para></listitem> - <listitem><para> - <emphasis>Specify the Feature as a Kernel Feature:</emphasis> - Use the <filename>KERNEL_FEATURES</filename> statement - to specify the feature as a kernel feature: - <literallayout class='monospaced'> - KERNEL_FEATURES_append = " test.scc" - </literallayout> - The OpenEmbedded build system processes the kernel feature - when it builds the kernel. - <note> - If other features are contained below "test.scc", - then their directories are relative to the directory - containing the <filename>test.scc</filename> file. - </note> - </para></listitem> - </orderedlist> - </para> - </section> -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/poky/documentation/kernel-dev/kernel-dev-concepts-appx.rst b/poky/documentation/kernel-dev/kernel-dev-concepts-appx.rst index 04cb1172b..5b6ebef5a 100644 --- a/poky/documentation/kernel-dev/kernel-dev-concepts-appx.rst +++ b/poky/documentation/kernel-dev/kernel-dev-concepts-appx.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK ************************ Advanced Kernel Concepts diff --git a/poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml deleted file mode 100644 index bf0c525ca..000000000 --- a/poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml +++ /dev/null @@ -1,622 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<appendix id='kernel-dev-concepts-appx'> -<title>Advanced Kernel Concepts</title> - - <section id='kernel-big-picture'> - <title>Yocto Project Kernel Development and Maintenance</title> - - <para> - Kernels available through the Yocto Project (Yocto Linux kernels), - like other kernels, are based off the Linux kernel releases from - <ulink url='http://www.kernel.org'></ulink>. - At the beginning of a major Linux kernel development cycle, the - Yocto Project team chooses a Linux kernel based on factors such as - release timing, the anticipated release timing of final upstream - <filename>kernel.org</filename> versions, and Yocto Project - feature requirements. - Typically, the Linux kernel chosen is in the final stages of - development by the Linux community. - In other words, the Linux kernel is in the release candidate - or "rc" phase and has yet to reach final release. - But, by being in the final stages of external development, the - team knows that the <filename>kernel.org</filename> final release - will clearly be within the early stages of the Yocto Project - development window. - </para> - - <para> - This balance allows the Yocto Project team to deliver the most - up-to-date Yocto Linux kernel possible, while still ensuring that - the team has a stable official release for the baseline Linux - kernel version. - </para> - - <para> - As implied earlier, the ultimate source for Yocto Linux kernels - are released kernels from <filename>kernel.org</filename>. - In addition to a foundational kernel from - <filename>kernel.org</filename>, the available Yocto Linux kernels - contain a mix of important new mainline developments, non-mainline - developments (when no alternative exists), Board Support Package - (BSP) developments, and custom features. - These additions result in a commercially released Yocto - Project Linux kernel that caters to specific embedded designer - needs for targeted hardware. - </para> - - <para> - You can find a web interface to the Yocto Linux kernels in the - <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> - at - <ulink url='&YOCTO_GIT_URL;'></ulink>. - If you look at the interface, you will see to the left a - grouping of Git repositories titled "Yocto Linux Kernel". - Within this group, you will find several Linux Yocto kernels - developed and included with Yocto Project releases: - <itemizedlist> - <listitem><para> - <emphasis><filename>linux-yocto-4.1</filename>:</emphasis> - The stable Yocto Project kernel to use with the Yocto - Project Release 2.0. - This kernel is based on the Linux 4.1 released kernel. - </para></listitem> - <listitem><para> - <emphasis><filename>linux-yocto-4.4</filename>:</emphasis> - The stable Yocto Project kernel to use with the Yocto - Project Release 2.1. - This kernel is based on the Linux 4.4 released kernel. - </para></listitem> - <listitem><para> - <emphasis><filename>linux-yocto-4.6</filename>:</emphasis> - A temporary kernel that is not tied to any Yocto Project - release. - </para></listitem> - <listitem><para> - <emphasis><filename>linux-yocto-4.8</filename>:</emphasis> - The stable yocto Project kernel to use with the Yocto - Project Release 2.2. - </para></listitem> - <listitem><para> - <emphasis><filename>linux-yocto-4.9</filename>:</emphasis> - The stable Yocto Project kernel to use with the Yocto - Project Release 2.3. - This kernel is based on the Linux 4.9 released kernel. - </para></listitem> - <listitem><para> - <emphasis><filename>linux-yocto-4.10</filename>:</emphasis> - The default stable Yocto Project kernel to use with the - Yocto Project Release 2.3. - This kernel is based on the Linux 4.10 released kernel. - </para></listitem> - <listitem><para> - <emphasis><filename>linux-yocto-4.12</filename>:</emphasis> - The default stable Yocto Project kernel to use with the - Yocto Project Release 2.4. - This kernel is based on the Linux 4.12 released kernel. - </para></listitem> - <listitem><para> - <emphasis><filename>yocto-kernel-cache</filename>:</emphasis> - The <filename>linux-yocto-cache</filename> contains - patches and configurations for the linux-yocto kernel - tree. - This repository is useful when working on the linux-yocto - kernel. - For more information on this "Advanced Kernel Metadata", - see the - "<link linkend='kernel-dev-advanced'>Working With Advanced Metadata (<filename>yocto-kernel-cache</filename>)</link>" - Chapter. - </para></listitem> - <listitem><para> - <emphasis><filename>linux-yocto-dev</filename>:</emphasis> - A development kernel based on the latest upstream release - candidate available. - </para></listitem> - </itemizedlist> - <note><title>Notes</title> - Long Term Support Initiative (LTSI) for Yocto Linux - kernels is as follows: - <itemizedlist> - <listitem><para> - For Yocto Project releases 1.7, 1.8, and 2.0, - the LTSI kernel is - <filename>linux-yocto-3.14</filename>. - </para></listitem> - <listitem><para> - For Yocto Project releases 2.1, 2.2, and 2.3, - the LTSI kernel is <filename>linux-yocto-4.1</filename>. - </para></listitem> - <listitem><para> - For Yocto Project release 2.4, the LTSI kernel is - <filename>linux-yocto-4.9</filename> - </para></listitem> - <listitem><para> - <filename>linux-yocto-4.4</filename> is an LTS - kernel. - </para></listitem> - </itemizedlist> - </note> - </para> - - <para> - Once a Yocto Linux kernel is officially released, the Yocto - Project team goes into their next development cycle, or upward - revision (uprev) cycle, while still continuing maintenance on the - released kernel. - It is important to note that the most sustainable and stable way - to include feature development upstream is through a kernel uprev - process. - Back-porting hundreds of individual fixes and minor features from - various kernel versions is not sustainable and can easily - compromise quality. - </para> - - <para> - During the uprev cycle, the Yocto Project team uses an ongoing - analysis of Linux kernel development, BSP support, and release - timing to select the best possible <filename>kernel.org</filename> - Linux kernel version on which to base subsequent Yocto Linux - kernel development. - The team continually monitors Linux community kernel development - to look for significant features of interest. - The team does consider back-porting large features if they have a - significant advantage. - User or community demand can also trigger a back-port or creation - of new functionality in the Yocto Project baseline kernel during - the uprev cycle. - </para> - - <para> - Generally speaking, every new Linux kernel both adds features and - introduces new bugs. - These consequences are the basic properties of upstream - Linux kernel development and are managed by the Yocto Project - team's Yocto Linux kernel development strategy. - It is the Yocto Project team's policy to not back-port minor - features to the released Yocto Linux kernel. - They only consider back-porting significant technological - jumps ‐ and, that is done after a complete gap analysis. - The reason for this policy is that back-porting any small to - medium sized change from an evolving Linux kernel can easily - create mismatches, incompatibilities and very subtle errors. - </para> - - <para> - The policies described in this section result in both a stable - and a cutting edge Yocto Linux kernel that mixes forward ports of - existing Linux kernel features and significant and critical new - functionality. - Forward porting Linux kernel functionality into the Yocto Linux - kernels available through the Yocto Project can be thought of as - a "micro uprev." - The many "micro uprevs" produce a Yocto Linux kernel version with - a mix of important new mainline, non-mainline, BSP developments - and feature integrations. - This Yocto Linux kernel gives insight into new features and - allows focused amounts of testing to be done on the kernel, - which prevents surprises when selecting the next major uprev. - The quality of these cutting edge Yocto Linux kernels is evolving - and the kernels are used in leading edge feature and BSP - development. - </para> - </section> - - <section id='yocto-linux-kernel-architecture-and-branching-strategies'> - <title>Yocto Linux Kernel Architecture and Branching Strategies</title> - - <para> - As mentioned earlier, a key goal of the Yocto Project is - to present the developer with a kernel that has a clear and - continuous history that is visible to the user. - The architecture and mechanisms, in particular the branching - strategies, used achieve that goal in a manner similar to - upstream Linux kernel development in - <filename>kernel.org</filename>. - </para> - - <para> - You can think of a Yocto Linux kernel as consisting of a - baseline Linux kernel with added features logically structured - on top of the baseline. - The features are tagged and organized by way of a branching - strategy implemented by the Yocto Project team using the - Source Code Manager (SCM) Git. - <note><title>Notes</title> - <itemizedlist> - <listitem><para> - Git is the obvious SCM for meeting the Yocto Linux - kernel organizational and structural goals described - in this section. - Not only is Git the SCM for Linux kernel development in - <filename>kernel.org</filename> but, Git continues to - grow in popularity and supports many different work - flows, front-ends and management techniques. - </para></listitem> - <listitem><para> - You can find documentation on Git at - <ulink url='http://git-scm.com/documentation'></ulink>. - You can also get an introduction to Git as it - applies to the Yocto Project in the - "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>" - section in the Yocto Project Overview and Concepts - Manual. - The latter reference provides an overview of - Git and presents a minimal set of Git commands - that allows you to be functional using Git. - You can use as much, or as little, of what Git - has to offer to accomplish what you need for your - project. - You do not have to be a "Git Expert" in order to - use it with the Yocto Project. - </para></listitem> - </itemizedlist> - </note> - </para> - - <para> - Using Git's tagging and branching features, the Yocto Project - team creates kernel branches at points where functionality is - no longer shared and thus, needs to be isolated. - For example, board-specific incompatibilities would require - different functionality and would require a branch to - separate the features. - Likewise, for specific kernel features, the same branching - strategy is used. - </para> - - <para> - This "tree-like" architecture results in a structure that has - features organized to be specific for particular functionality, - single kernel types, or a subset of kernel types. - Thus, the user has the ability to see the added features and the - commits that make up those features. - In addition to being able to see added features, the user - can also view the history of what made up the baseline - Linux kernel. - </para> - - <para> - Another consequence of this strategy results in not having to - store the same feature twice internally in the tree. - Rather, the kernel team stores the unique differences required - to apply the feature onto the kernel type in question. - <note> - The Yocto Project team strives to place features in the tree - such that features can be shared by all boards and kernel - types where possible. - However, during development cycles or when large features - are merged, the team cannot always follow this practice. - In those cases, the team uses isolated branches to merge - features. - </note> - </para> - - <para> - BSP-specific code additions are handled in a similar manner to - kernel-specific additions. - Some BSPs only make sense given certain kernel types. - So, for these types, the team creates branches off the end - of that kernel type for all of the BSPs that are supported on - that kernel type. - From the perspective of the tools that create the BSP branch, - the BSP is really no different than a feature. - Consequently, the same branching strategy applies to BSPs as - it does to kernel features. - So again, rather than store the BSP twice, the team only - stores the unique differences for the BSP across the supported - multiple kernels. - </para> - - <para> - While this strategy can result in a tree with a significant number - of branches, it is important to realize that from the developer's - point of view, there is a linear path that travels from the - baseline <filename>kernel.org</filename>, through a select - group of features and ends with their BSP-specific commits. - In other words, the divisions of the kernel are transparent and - are not relevant to the developer on a day-to-day basis. - From the developer's perspective, this path is the "master" branch - in Git terms. - The developer does not need to be aware of the existence of any - other branches at all. - Of course, value exists in the having these branches in the tree, - should a person decide to explore them. - For example, a comparison between two BSPs at either the commit - level or at the line-by-line code <filename>diff</filename> level - is now a trivial operation. - </para> - - <para> - The following illustration shows the conceptual Yocto - Linux kernel. - <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" /> - </para> - - <para> - In the illustration, the "Kernel.org Branch Point" marks the - specific spot (or Linux kernel release) from which the - Yocto Linux kernel is created. - From this point forward in the tree, features and differences - are organized and tagged. - </para> - - <para> - The "Yocto Project Baseline Kernel" contains functionality that - is common to every kernel type and BSP that is organized - further along in the tree. - Placing these common features in the tree this way means - features do not have to be duplicated along individual - branches of the tree structure. - </para> - - <para> - From the "Yocto Project Baseline Kernel", branch points represent - specific functionality for individual Board Support Packages - (BSPs) as well as real-time kernels. - The illustration represents this through three BSP-specific - branches and a real-time kernel branch. - Each branch represents some unique functionality for the BSP - or for a real-time Yocto Linux kernel. - </para> - - <para> - In this example structure, the "Real-time (rt) Kernel" branch has - common features for all real-time Yocto Linux kernels and - contains more branches for individual BSP-specific real-time - kernels. - The illustration shows three branches as an example. - Each branch points the way to specific, unique features for a - respective real-time kernel as they apply to a given BSP. - </para> - - <para> - The resulting tree structure presents a clear path of markers - (or branches) to the developer that, for all practical - purposes, is the Yocto Linux kernel needed for any given set of - requirements. - <note> - Keep in mind the figure does not take into account all the - supported Yocto Linux kernels, but rather shows a single - generic kernel just for conceptual purposes. - Also keep in mind that this structure represents the Yocto - Project - <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> - that are either pulled from during the build or established - on the host development system prior to the build by either - cloning a particular kernel's Git repository or by - downloading and unpacking a tarball. - </note> - </para> - - <para> - Working with the kernel as a structured tree follows recognized - community best practices. - In particular, the kernel as shipped with the product, should be - considered an "upstream source" and viewed as a series of - historical and documented modifications (commits). - These modifications represent the development and stabilization - done by the Yocto Project kernel development team. - </para> - - <para> - Because commits only change at significant release points in the - product life cycle, developers can work on a branch created - from the last relevant commit in the shipped Yocto Project Linux - kernel. - As mentioned previously, the structure is transparent to the - developer because the kernel tree is left in this state after - cloning and building the kernel. - </para> - </section> - - <section id='kernel-build-file-hierarchy'> - <title>Kernel Build File Hierarchy</title> - - <para> - Upstream storage of all the available kernel source code is - one thing, while representing and using the code on your host - development system is another. - Conceptually, you can think of the kernel source repositories - as all the source files necessary for all the supported - Yocto Linux kernels. - As a developer, you are just interested in the source files - for the kernel on which you are working. - And, furthermore, you need them available on your host system. - </para> - - <para> - Kernel source code is available on your host system several - different ways: - <itemizedlist> - <listitem><para> - <emphasis>Files Accessed While using <filename>devtool</filename>:</emphasis> - <filename>devtool</filename>, which is available with the - Yocto Project, is the preferred method by which to - modify the kernel. - See the - "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>" - section. - </para></listitem> - <listitem><para> - <emphasis>Cloned Repository:</emphasis> - If you are working in the kernel all the time, you probably - would want to set up your own local Git repository of the - Yocto Linux kernel tree. - For information on how to clone a Yocto Linux kernel - Git repository, see the - "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>" - section. - </para></listitem> - <listitem><para> - <emphasis>Temporary Source Files from a Build:</emphasis> - If you just need to make some patches to the kernel using - a traditional BitBake workflow (i.e. not using the - <filename>devtool</filename>), you can access temporary - kernel source files that were extracted and used during - a kernel build. - </para></listitem> - </itemizedlist> - </para> - - <para> - The temporary kernel source files resulting from a build using - BitBake have a particular hierarchy. - When you build the kernel on your development system, all files - needed for the build are taken from the source repositories - pointed to by the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - variable and gathered in a temporary work area where they are - subsequently used to create the unique kernel. - Thus, in a sense, the process constructs a local source tree - specific to your kernel from which to generate the new kernel - image. - </para> - - <para> - The following figure shows the temporary file structure - created on your host system when you build the kernel using - Bitbake. - This - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> - contains all the source files used during the build. - <imagedata fileref="figures/kernel-overview-2-generic.png" - width="6in" depth="5in" align="center" scale="100" /> - </para> - - <para> - Again, for additional information on the Yocto Project kernel's - architecture and its branching strategy, see the - "<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>" - section. - You can also reference the - "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" - and - "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" - sections for detailed example that modifies the kernel. - </para> - </section> - - <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'> - <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title> - - <para> - This section describes part of the kernel configuration audit - phase that most developers can ignore. - For general information on kernel configuration including - <filename>menuconfig</filename>, <filename>defconfig</filename> - files, and configuration fragments, see the - "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" - section. - </para> - - <para> - During this part of the audit phase, the contents of the final - <filename>.config</filename> file are compared against the - fragments specified by the system. - These fragments can be system fragments, distro fragments, - or user-specified configuration elements. - Regardless of their origin, the OpenEmbedded build system - warns the user if a specific option is not included in the - final kernel configuration. - </para> - - <para> - By default, in order to not overwhelm the user with - configuration warnings, the system only reports missing - "hardware" options as they could result in a boot - failure or indicate that important hardware is not available. - </para> - - <para> - To determine whether or not a given option is "hardware" or - "non-hardware", the kernel Metadata in - <filename>yocto-kernel-cache</filename> contains files that - classify individual or groups of options as either hardware - or non-hardware. - To better show this, consider a situation where the - <filename>yocto-kernel-cache</filename> contains the following - files: - <literallayout class='monospaced'> - yocto-kernel-cache/features/drm-psb/hardware.cfg - yocto-kernel-cache/features/kgdb/hardware.cfg - yocto-kernel-cache/ktypes/base/hardware.cfg - yocto-kernel-cache/bsp/mti-malta32/hardware.cfg - yocto-kernel-cache/bsp/qemu-ppc32/hardware.cfg - yocto-kernel-cache/bsp/qemuarma9/hardware.cfg - yocto-kernel-cache/bsp/mti-malta64/hardware.cfg - yocto-kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg - yocto-kernel-cache/bsp/common-pc/hardware.cfg - yocto-kernel-cache/bsp/common-pc-64/hardware.cfg - yocto-kernel-cache/features/rfkill/non-hardware.cfg - yocto-kernel-cache/ktypes/base/non-hardware.cfg - yocto-kernel-cache/features/aufs/non-hardware.kcf - yocto-kernel-cache/features/ocf/non-hardware.kcf - yocto-kernel-cache/ktypes/base/non-hardware.kcf - yocto-kernel-cache/ktypes/base/hardware.kcf - yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf - </literallayout> - The following list provides explanations for the various - files: - <itemizedlist> - <listitem><para> - <filename>hardware.kcf</filename>: - Specifies a list of kernel Kconfig files that contain - hardware options only. - </para></listitem> - <listitem><para> - <filename>non-hardware.kcf</filename>: - Specifies a list of kernel Kconfig files that contain - non-hardware options only. - </para></listitem> - <listitem><para> - <filename>hardware.cfg</filename>: - Specifies a list of kernel <filename>CONFIG_</filename> - options that are hardware, regardless of whether or not - they are within a Kconfig file specified by a hardware - or non-hardware Kconfig file (i.e. - <filename>hardware.kcf</filename> or - <filename>non-hardware.kcf</filename>). - </para></listitem> - <listitem><para> - <filename>non-hardware.cfg</filename>: - Specifies a list of kernel <filename>CONFIG_</filename> - options that are not hardware, regardless of whether or - not they are within a Kconfig file specified by a - hardware or non-hardware Kconfig file (i.e. - <filename>hardware.kcf</filename> or - <filename>non-hardware.kcf</filename>). - </para></listitem> - </itemizedlist> - Here is a specific example using the - <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>: - <literallayout class='monospaced'> - CONFIG_SERIAL_8250 - CONFIG_SERIAL_8250_CONSOLE - CONFIG_SERIAL_8250_NR_UARTS - CONFIG_SERIAL_8250_PCI - CONFIG_SERIAL_CORE - CONFIG_SERIAL_CORE_CONSOLE - CONFIG_VGA_ARB - </literallayout> - The kernel configuration audit automatically detects these - files (hence the names must be exactly the ones discussed here), - and uses them as inputs when generating warnings about the - final <filename>.config</filename> file. - </para> - - <para> - A user-specified kernel Metadata repository, or recipe space - feature, can use these same files to classify options that are - found within its <filename>.cfg</filename> files as hardware - or non-hardware, to prevent the OpenEmbedded build system from - producing an error or warning when an option is not in the - final <filename>.config</filename> file. - </para> - </section> -</appendix> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/poky/documentation/kernel-dev/kernel-dev-customization.xsl b/poky/documentation/kernel-dev/kernel-dev-customization.xsl deleted file mode 100644 index 88bf7c678..000000000 --- a/poky/documentation/kernel-dev/kernel-dev-customization.xsl +++ /dev/null @@ -1,28 +0,0 @@ -<?xml version='1.0'?> -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - - <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> - -<!-- - - <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> - - <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> - ---> - - <xsl:include href="../template/permalinks.xsl"/> - <xsl:include href="../template/section.title.xsl"/> - <xsl:include href="../template/component.title.xsl"/> - <xsl:include href="../template/division.title.xsl"/> - <xsl:include href="../template/formal.object.heading.xsl"/> - - <xsl:param name="html.stylesheet" select="'kernel-dev-style.css'" /> - <xsl:param name="chapter.autolabel" select="1" /> - <xsl:param name="appendix.autolabel">A</xsl:param> - <xsl:param name="section.autolabel" select="1" /> - <xsl:param name="section.label.includes.component.label" select="1" /> - -</xsl:stylesheet> diff --git a/poky/documentation/kernel-dev/kernel-dev-faq.rst b/poky/documentation/kernel-dev/kernel-dev-faq.rst index b5e6a84eb..70bf4a2d4 100644 --- a/poky/documentation/kernel-dev/kernel-dev-faq.rst +++ b/poky/documentation/kernel-dev/kernel-dev-faq.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK ********************** Kernel Development FAQ diff --git a/poky/documentation/kernel-dev/kernel-dev-faq.xml b/poky/documentation/kernel-dev/kernel-dev-faq.xml deleted file mode 100644 index d76f0a4e3..000000000 --- a/poky/documentation/kernel-dev/kernel-dev-faq.xml +++ /dev/null @@ -1,143 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<appendix id='kernel-dev-faq'> -<title>Kernel Development FAQ</title> - -<section id='kernel-dev-faq-section'> - <title>Common Questions and Solutions</title> - - <para> - The following lists some solutions for common questions. - - - <qandaset> - <qandaentry> - <question> - <para> - How do I use my own Linux kernel <filename>.config</filename> - file? - </para> - </question> - <answer> - <para> - Refer to the "<link linkend='changing-the-configuration'>Changing the Configuration</link>" - section for information. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para> - How do I create configuration fragments? - </para> - </question> - <answer> - <para> - Refer to the - "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>" - section for information. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para> - How do I use my own Linux kernel sources? - </para> - </question> - <answer> - <para> - Refer to the "<link linkend='working-with-your-own-sources'>Working With Your Own Sources</link>" - section for information. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para> - How do I install/not-install the kernel image on the rootfs? - </para> - </question> - <answer> - <para> - The kernel image (e.g. <filename>vmlinuz</filename>) is provided - by the <filename>kernel-image</filename> package. - Image recipes depend on <filename>kernel-base</filename>. - To specify whether or not the kernel - image is installed in the generated root filesystem, override - <filename>RDEPENDS_kernel-base</filename> to include or not - include "kernel-image".</para> - <para>See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" - section in the Yocto Project Development Tasks Manual - for information on how to use an append file to - override metadata. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para> - How do I install a specific kernel module? - </para> - </question> - <answer> - <para> - Linux kernel modules are packaged individually. - To ensure a specific kernel module is included in an image, - include it in the appropriate machine - <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> - variable.</para> - <para>These other variables are useful for installing specific - modules: - <literallayout class='monospaced'> - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink> - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink> - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink> - </literallayout> - For example, set the following in the <filename>qemux86.conf</filename> - file to include the <filename>ab123</filename> kernel modules - with images built for the <filename>qemux86</filename> machine: - <literallayout class='monospaced'> - MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" - </literallayout> - For more information, see the - "<link linkend='incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</link>" - section. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para> - How do I change the Linux kernel command line? - </para> - </question> - <answer> - <para> - The Linux kernel command line is typically specified in - the machine config using the <filename>APPEND</filename> variable. - For example, you can add some helpful debug information doing - the following: - <literallayout class='monospaced'> - APPEND += "printk.time=y initcall_debug debug" - </literallayout> - </para> - </answer> - </qandaentry> - </qandaset> - </para> -</section> -</appendix> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/poky/documentation/kernel-dev/kernel-dev-intro.rst b/poky/documentation/kernel-dev/kernel-dev-intro.rst index 21d43d5e8..447cddba2 100644 --- a/poky/documentation/kernel-dev/kernel-dev-intro.rst +++ b/poky/documentation/kernel-dev/kernel-dev-intro.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK ************ Introduction diff --git a/poky/documentation/kernel-dev/kernel-dev-intro.xml b/poky/documentation/kernel-dev/kernel-dev-intro.xml deleted file mode 100644 index 7c1ea0e51..000000000 --- a/poky/documentation/kernel-dev/kernel-dev-intro.xml +++ /dev/null @@ -1,260 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<chapter id='kernel-dev-intro'> -<title>Introduction</title> - -<section id='kernel-dev-overview'> - <title>Overview</title> - - <para> - Regardless of how you intend to make use of the Yocto Project, - chances are you will work with the Linux kernel. - This manual describes how to set up your build host to support - kernel development, introduces the kernel development process, - provides background information on the Yocto Linux kernel - <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>, - describes common tasks you can perform using the kernel tools, - shows you how to use the kernel Metadata needed to work with - the kernel inside the Yocto Project, and provides insight into how - the Yocto Project team develops and maintains Yocto Linux kernel - Git repositories and Metadata. - </para> - - <para> - Each Yocto Project release has a set of Yocto Linux kernel recipes, - whose Git repositories you can view in the Yocto - <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under - the "Yocto Linux Kernel" heading. - New recipes for the release track the latest Linux kernel - upstream developments from - <ulink url='http://www.kernel.org'></ulink> and introduce - newly-supported platforms. - Previous recipes in the release are refreshed and supported for at - least one additional Yocto Project release. - As they align, these previous releases are updated to include the - latest from the Long Term Support Initiative (LTSI) project. - You can learn more about Yocto Linux kernels and LTSI in the - "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>" - section. - </para> - - <para> - Also included is a Yocto Linux kernel development recipe - (<filename>linux-yocto-dev.bb</filename>) should you want to work - with the very latest in upstream Yocto Linux kernel development and - kernel Metadata development. - <note> - For more on Yocto Linux kernels, see the - "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link> - section. - </note> - </para> - - <para> - The Yocto Project also provides a powerful set of kernel - tools for managing Yocto Linux kernel sources and configuration data. - You can use these tools to make a single configuration change, - apply multiple patches, or work with your own kernel sources. - </para> - - <para> - In particular, the kernel tools allow you to generate configuration - fragments that specify only what you must, and nothing more. - Configuration fragments only need to contain the highest level - visible <filename>CONFIG</filename> options as presented by the - Yocto Linux kernel <filename>menuconfig</filename> system. - Contrast this against a complete Yocto Linux kernel - <filename>.config</filename> file, which includes all the automatically - selected <filename>CONFIG</filename> options. - This efficiency reduces your maintenance effort and allows you - to further separate your configuration in ways that make sense for - your project. - A common split separates policy and hardware. - For example, all your kernels might support the - <filename>proc</filename> and <filename>sys</filename> filesystems, - but only specific boards require sound, USB, or specific drivers. - Specifying these configurations individually allows you to aggregate - them together as needed, but maintains them in only one place. - Similar logic applies to separating source changes. - </para> - - <para> - If you do not maintain your own kernel sources and need to make - only minimal changes to the sources, the released recipes provide a - vetted base upon which to layer your changes. - Doing so allows you to benefit from the continual kernel - integration and testing performed during development of the - Yocto Project. - </para> - - <para> - If, instead, you have a very specific Linux kernel source tree - and are unable to align with one of the official Yocto Linux kernel - recipes, an alternative exists by which you can use the Yocto - Project Linux kernel tools with your own kernel sources. - </para> - - <para> - The remainder of this manual provides instructions for completing - specific Linux kernel development tasks. - These instructions assume you are comfortable working with - <ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink> - recipes and basic open-source development tools. - Understanding these concepts will facilitate the process of working - with the kernel recipes. - If you find you need some additional background, please be sure to - review and understand the following documentation: - <itemizedlist> - <listitem><para> - <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink> - document. - </para></listitem> - <listitem><para> - <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>. - </para></listitem> - <listitem><para> - <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink> - as described in the Yocto Project Application Development and - the Extensible Software Development Kit (eSDK) manual. - </para></listitem> - <listitem><para> - The - "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" - section in the Yocto Project Development Tasks Manual. - </para></listitem> - <listitem><para> - The - "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>" - section. - </para></listitem> - </itemizedlist> - </para> -</section> - -<section id='kernel-modification-workflow'> - <title>Kernel Modification Workflow</title> - - <para> - Kernel modification involves changing the Yocto Project kernel, - which could involve changing configuration options as well as adding - new kernel recipes. - Configuration changes can be added in the form of configuration - fragments, while recipe modification comes through the kernel's - <filename>recipes-kernel</filename> area in a kernel layer you create. - </para> - - <para> - This section presents a high-level overview of the Yocto Project - kernel modification workflow. - The illustration and accompanying list provide general information - and references for further information. - <imagedata fileref="figures/kernel-dev-flow.png" - width="9in" depth="5in" align="center" scalefit="1" /> - </para> - - <para> - <orderedlist> - <listitem><para> - - - <emphasis>Set up Your Host Development System to Support - Development Using the Yocto Project</emphasis>: - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-start'>Setting Up the Development Host to Use the Yocto Project</ulink>" - section in the Yocto Project Development Tasks Manual for - options on how to get a build host ready to use the Yocto - Project. - </para></listitem> - <listitem><para> - <emphasis>Set Up Your Host Development System for Kernel Development:</emphasis> - It is recommended that you use <filename>devtool</filename> - and an extensible SDK for kernel development. - Alternatively, you can use traditional kernel development - methods with the Yocto Project. - Either way, there are steps you need to take to get the - development environment ready.</para> - - <para>Using <filename>devtool</filename> and the eSDK requires - that you have a clean build of the image and that you are - set up with the appropriate eSDK. - For more information, see the - "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" - section.</para> - - <para>Using traditional kernel development requires that you - have the kernel source available in an isolated local Git - repository. - For more information, see the - "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" - section. - </para></listitem> - <listitem><para> - <emphasis>Make Changes to the Kernel Source Code if - applicable:</emphasis> - Modifying the kernel does not always mean directly - changing source files. - However, if you have to do this, you make the changes to the - files in the eSDK's Build Directory if you are using - <filename>devtool</filename>. - For more information, see the - "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" - section.</para> - - <para>If you are using traditional kernel development, you - edit the source files in the kernel's local Git repository. - For more information, see the - "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" - section. - </para></listitem> - <listitem><para> - <emphasis>Make Kernel Configuration Changes if - Applicable:</emphasis> - If your situation calls for changing the kernel's - configuration, you can use - <link linkend='using-menuconfig'><filename>menuconfig</filename></link>, - which allows you to interactively develop and test the - configuration changes you are making to the kernel. - Saving changes you make with <filename>menuconfig</filename> - updates the kernel's <filename>.config</filename> file. - <note><title>Warning</title> - Try to resist the temptation to directly edit an - existing <filename>.config</filename> file, which is - found in the Build Directory among the source code - used for the build. - Doing so, can produce unexpected results when the - OpenEmbedded build system regenerates the configuration - file. - </note> - Once you are satisfied with the configuration - changes made using <filename>menuconfig</filename> - and you have saved them, you can directly compare the - resulting <filename>.config</filename> file against an - existing original and gather those changes into a - <link linkend='creating-config-fragments'>configuration fragment file</link> - to be referenced from within the kernel's - <filename>.bbappend</filename> file.</para> - - <para>Additionally, if you are working in a BSP layer - and need to modify the BSP's kernel's configuration, - you can use <filename>menuconfig</filename>. - </para></listitem> - <listitem><para> - <emphasis>Rebuild the Kernel Image With Your Changes:</emphasis> - Rebuilding the kernel image applies your changes. - Depending on your target hardware, you can verify your changes - on actual hardware or perhaps QEMU. - </para></listitem> - </orderedlist> - The remainder of this developer's guide covers common tasks typically - used during kernel development, advanced Metadata usage, and Yocto Linux - kernel maintenance concepts. - </para> -</section> - -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/poky/documentation/kernel-dev/kernel-dev-maint-appx.rst b/poky/documentation/kernel-dev/kernel-dev-maint-appx.rst index 5514dac87..17883327d 100644 --- a/poky/documentation/kernel-dev/kernel-dev-maint-appx.rst +++ b/poky/documentation/kernel-dev/kernel-dev-maint-appx.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK ****************** Kernel Maintenance diff --git a/poky/documentation/kernel-dev/kernel-dev-maint-appx.xml b/poky/documentation/kernel-dev/kernel-dev-maint-appx.xml deleted file mode 100644 index 3d9c7c66f..000000000 --- a/poky/documentation/kernel-dev/kernel-dev-maint-appx.xml +++ /dev/null @@ -1,357 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<appendix id='kernel-dev-maint-appx'> -<title>Kernel Maintenance</title> - - <section id='tree-construction'> - <title>Tree Construction</title> - - <para> - This section describes construction of the Yocto Project kernel - source repositories as accomplished by the Yocto Project team to - create Yocto Linux kernel repositories. - These kernel repositories are found under the heading "Yocto Linux - Kernel" at - <ulink url='&YOCTO_GIT_URL;'>&YOCTO_GIT_URL;</ulink> - and are shipped as part of a Yocto Project release. - The team creates these repositories by compiling and executing the - set of feature descriptions for every BSP and feature in the - product. - Those feature descriptions list all necessary patches, - configurations, branches, tags, and feature divisions found in a - Yocto Linux kernel. - Thus, the Yocto Project Linux kernel repository (or tree) and - accompanying Metadata in the - <filename>yocto-kernel-cache</filename> are built. - </para> - - <para> - The existence of these repositories allow you to access and clone a - particular Yocto Project Linux kernel repository and use it to - build images based on their configurations and features. - </para> - - <para> - You can find the files used to describe all the valid features and - BSPs in the Yocto Project Linux kernel in any clone of the Yocto - Project Linux kernel source repository and - <filename>yocto-kernel-cache</filename> Git trees. - For example, the following commands clone the Yocto Project - baseline Linux kernel that branches off - <filename>linux.org</filename> version 4.12 and the - <filename>yocto-kernel-cache</filename>, which contains stores of - kernel Metadata: - <literallayout class='monospaced'> - $ git clone git://git.yoctoproject.org/linux-yocto-4.12 - $ git clone git://git.yoctoproject.org/linux-kernel-cache - </literallayout> - For more information on how to set up a local Git repository of - the Yocto Project Linux kernel files, see the - "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>" - section. - </para> - - <para> - Once you have cloned the kernel Git repository and the - cache of Metadata on your local machine, you can discover the - branches that are available in the repository using the following - Git command: - <literallayout class='monospaced'> - $ git branch -a - </literallayout> - Checking out a branch allows you to work with a particular - Yocto Linux kernel. - For example, the following commands check out the - "standard/beagleboard" branch of the Yocto Linux kernel repository - and the "yocto-4.12" branch of the - <filename>yocto-kernel-cache</filename> repository: - <literallayout class='monospaced'> - $ cd ~/linux-yocto-4.12 - $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard - $ cd ~/linux-kernel-cache - $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12 - </literallayout> - <note> - Branches in the <filename>yocto-kernel-cache</filename> - repository correspond to Yocto Linux kernel versions - (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth). - </note> - Once you have checked out and switched to appropriate branches, - you can see a snapshot of all the kernel source files used to - used to build that particular Yocto Linux kernel for a - particular board. - </para> - - <para> - To see the features and configurations for a particular Yocto - Linux kernel, you need to examine the - <filename>yocto-kernel-cache</filename> Git repository. - As mentioned, branches in the - <filename>yocto-kernel-cache</filename> repository correspond to - Yocto Linux kernel versions (e.g. <filename>yocto-4.12</filename>). - Branches contain descriptions in the form of - <filename>.scc</filename> and <filename>.cfg</filename> files. - </para> - - <para> - You should realize, however, that browsing your local - <filename>yocto-kernel-cache</filename> repository for feature - descriptions and patches is not an effective way to determine what - is in a particular kernel branch. - Instead, you should use Git directly to discover the changes in - a branch. - Using Git is an efficient and flexible way to inspect changes to - the kernel. - <note> - Ground up reconstruction of the complete kernel tree is an - action only taken by the Yocto Project team during an active - development cycle. - When you create a clone of the kernel Git repository, you are - simply making it efficiently available for building and - development. - </note> - </para> - - <para> - The following steps describe what happens when the Yocto Project - Team constructs the Yocto Project kernel source Git repository - (or tree) found at - <ulink url='&YOCTO_GIT_URL;'></ulink> given the - introduction of a new top-level kernel feature or BSP. - The following actions effectively provide the Metadata - and create the tree that includes the new feature, patch, or BSP: - <orderedlist> - <listitem><para> - <emphasis>Pass Feature to the OpenEmbedded Build System:</emphasis> - A top-level kernel feature is passed to the kernel build - subsystem. - Normally, this feature is a BSP for a particular kernel - type. - </para></listitem> - <listitem><para> - <emphasis>Locate Feature:</emphasis> - The file that describes the top-level feature is located - by searching these system directories: - <itemizedlist> - <listitem><para> - The in-tree kernel-cache directories, which are - located in the - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink> - repository organized under the "Yocto Linux Kernel" - heading in the - <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>. - </para></listitem> - <listitem><para> - Areas pointed to by <filename>SRC_URI</filename> - statements found in kernel recipes - </para></listitem> - </itemizedlist> - For a typical build, the target of the search is a - feature description in an <filename>.scc</filename> file - whose name follows this format (e.g. - <filename>beaglebone-standard.scc</filename> and - <filename>beaglebone-preempt-rt.scc</filename>): - <literallayout class='monospaced'> - <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Expand Feature:</emphasis> - Once located, the feature description is either expanded - into a simple script of actions, or into an existing - equivalent script that is already part of the shipped - kernel. - </para></listitem> - <listitem><para> - <emphasis>Append Extra Features:</emphasis> - Extra features are appended to the top-level feature - description. - These features can come from the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> - variable in recipes. - </para></listitem> - <listitem><para> - <emphasis>Locate, Expand, and Append Each Feature:</emphasis> - Each extra feature is located, expanded and appended to - the script as described in step three. - </para></listitem> - <listitem><para> - <emphasis>Execute the Script:</emphasis> - The script is executed to produce files - <filename>.scc</filename> and <filename>.cfg</filename> - files in appropriate directories of the - <filename>yocto-kernel-cache</filename> repository. - These files are descriptions of all the branches, tags, - patches and configurations that need to be applied to the - base Git repository to completely create the - source (build) branch for the new BSP or feature. - </para></listitem> - <listitem><para> - <emphasis>Clone Base Repository:</emphasis> - The base repository is cloned, and the actions - listed in the <filename>yocto-kernel-cache</filename> - directories are applied to the tree. - </para></listitem> - <listitem><para> - <emphasis>Perform Cleanup:</emphasis> - The Git repositories are left with the desired branches - checked out and any required branching, patching and - tagging has been performed. - </para></listitem> - </orderedlist> - </para> - - <para> - The kernel tree and cache are ready for developer consumption to - be locally cloned, configured, and built into a Yocto Project - kernel specific to some target hardware. - <note><title>Notes</title> - <itemizedlist> - <listitem><para> - The generated <filename>yocto-kernel-cache</filename> - repository adds to the kernel as shipped with the Yocto - Project release. - Any add-ons and configuration data are applied to the - end of an existing branch. - The full repository generation that is found in the - official Yocto Project kernel repositories at - <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink> - is the combination of all supported boards and - configurations. - </para></listitem> - <listitem><para> - The technique the Yocto Project team uses is flexible - and allows for seamless blending of an immutable - history with additional patches specific to a - deployment. - Any additions to the kernel become an integrated part - of the branches. - </para></listitem> - <listitem><para> - The full kernel tree that you see on - <ulink url='&YOCTO_GIT_URL;'></ulink> is - generated through repeating the above steps for all - valid BSPs. - The end result is a branched, clean history tree that - makes up the kernel for a given release. - You can see the script (<filename>kgit-scc</filename>) - responsible for this in the - <ulink url='&YOCTO_GIT_URL;/cgit.cgi/yocto-kernel-tools/tree/tools'><filename>yocto-kernel-tools</filename></ulink> - repository. - </para></listitem> - <listitem><para> - The steps used to construct the full kernel tree are - the same steps that BitBake uses when it builds a - kernel image. - </para></listitem> - </itemizedlist> - </note> - </para> - </section> - - <section id='build-strategy'> - <title>Build Strategy</title> - - <para> - Once you have cloned a Yocto Linux kernel repository and the - cache repository (<filename>yocto-kernel-cache</filename>) onto - your development system, you can consider the compilation phase - of kernel development, which is building a kernel image. - Some prerequisites exist that are validated by the build process - before compilation starts: - </para> - - <itemizedlist> - <listitem><para> - The - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - points to the kernel Git repository. - </para></listitem> - <listitem><para> - A BSP build branch with Metadata exists in the - <filename>yocto-kernel-cache</filename> repository. - The branch is based on the Yocto Linux kernel version and - has configurations and features grouped under the - <filename>yocto-kernel-cache/bsp</filename> directory. - For example, features and configurations for the - BeagleBone Board assuming a - <filename>linux-yocto_4.12</filename> kernel reside in the - following area of the <filename>yocto-kernel-cache</filename> - repository: - <literallayout class='monospaced'> - yocto-kernel-cache/bsp/beaglebone - </literallayout> - <note> - In the previous example, the "yocto-4.12" branch is - checked out in the <filename>yocto-kernel-cache</filename> - repository. - </note> - </para></listitem> - </itemizedlist> - - <para> - The OpenEmbedded build system makes sure these conditions exist - before attempting compilation. - Other means, however, do exist, such as as bootstrapping a BSP. - </para> - - <para> - Before building a kernel, the build process verifies the tree - and configures the kernel by processing all of the - configuration "fragments" specified by feature descriptions - in the <filename>.scc</filename> files. - As the features are compiled, associated kernel configuration - fragments are noted and recorded in the series of directories - in their compilation order. - The fragments are migrated, pre-processed and passed to the - Linux Kernel Configuration subsystem (<filename>lkc</filename>) as - raw input in the form of a <filename>.config</filename> file. - The <filename>lkc</filename> uses its own internal dependency - constraints to do the final processing of that information and - generates the final <filename>.config</filename> file that is used - during compilation. - </para> - - <para> - Using the board's architecture and other relevant values from - the board's template, kernel compilation is started and a kernel - image is produced. - </para> - - <para> - The other thing that you notice once you configure a kernel is that - the build process generates a build tree that is separate from - your kernel's local Git source repository tree. - This build tree has a name that uses the following form, where - <filename>${MACHINE}</filename> is the metadata name of the - machine (BSP) and "kernel_type" is one of the Yocto Project - supported kernel types (e.g. "standard"): - <literallayout class='monospaced'> - linux-${MACHINE}-<replaceable>kernel_type</replaceable>-build - </literallayout> - </para> - - <para> - The existing support in the <filename>kernel.org</filename> tree - achieves this default functionality. - </para> - - <para> - This behavior means that all the generated files for a particular - machine or BSP are now in the build tree directory. - The files include the final <filename>.config</filename> file, - all the <filename>.o</filename> files, the <filename>.a</filename> - files, and so forth. - Since each machine or BSP has its own separate - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> - in its own separate branch of the Git repository, you can easily - switch between different builds. - </para> - </section> -</appendix> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/poky/documentation/kernel-dev/kernel-dev-style.css b/poky/documentation/kernel-dev/kernel-dev-style.css deleted file mode 100644 index fc6fbb8de..000000000 --- a/poky/documentation/kernel-dev/kernel-dev-style.css +++ /dev/null @@ -1,991 +0,0 @@ -/* - - SPDX-License-Identifier: CC-BY-2.0-UK - - Generic XHTML / DocBook XHTML CSS Stylesheet. - - Browser wrangling and typographic design by - Oyvind Kolas / pippin@gimp.org - - Customised for Poky by - Matthew Allum / mallum@o-hand.com - - Thanks to: - Liam R. E. Quin - William Skaggs - Jakub Steiner - - Structure - --------- - - The stylesheet is divided into the following sections: - - Positioning - Margins, paddings, width, font-size, clearing. - Decorations - Borders, style - Colors - Colors - Graphics - Graphical backgrounds - Nasty IE tweaks - Workarounds needed to make it work in internet explorer, - currently makes the stylesheet non validating, but up until - this point it is validating. - Mozilla extensions - Transparency for footer - Rounded corners on boxes - -*/ - - - /*************** / - / Positioning / -/ ***************/ - -body { - font-family: Verdana, Sans, sans-serif; - - min-width: 640px; - width: 80%; - margin: 0em auto; - padding: 2em 5em 5em 5em; - color: #333; -} - -h1,h2,h3,h4,h5,h6,h7 { - font-family: Arial, Sans; - color: #00557D; - clear: both; -} - -h1 { - font-size: 2em; - text-align: left; - padding: 0em 0em 0em 0em; - margin: 2em 0em 0em 0em; -} - -h2.subtitle { - margin: 0.10em 0em 3.0em 0em; - padding: 0em 0em 0em 0em; - font-size: 1.8em; - padding-left: 20%; - font-weight: normal; - font-style: italic; -} - -h2 { - margin: 2em 0em 0.66em 0em; - padding: 0.5em 0em 0em 0em; - font-size: 1.5em; - font-weight: bold; -} - -h3.subtitle { - margin: 0em 0em 1em 0em; - padding: 0em 0em 0em 0em; - font-size: 142.14%; - text-align: right; -} - -h3 { - margin: 1em 0em 0.5em 0em; - padding: 1em 0em 0em 0em; - font-size: 140%; - font-weight: bold; -} - -h4 { - margin: 1em 0em 0.5em 0em; - padding: 1em 0em 0em 0em; - font-size: 120%; - font-weight: bold; -} - -h5 { - margin: 1em 0em 0.5em 0em; - padding: 1em 0em 0em 0em; - font-size: 110%; - font-weight: bold; -} - -h6 { - margin: 1em 0em 0em 0em; - padding: 1em 0em 0em 0em; - font-size: 110%; - font-weight: bold; -} - -.authorgroup { - background-color: transparent; - background-repeat: no-repeat; - padding-top: 256px; - background-image: url("figures/kernel-dev-title.png"); - background-position: left top; - margin-top: -256px; - padding-right: 50px; - margin-left: 0px; - text-align: right; - width: 740px; -} - -h3.author { - margin: 0em 0me 0em 0em; - padding: 0em 0em 0em 0em; - font-weight: normal; - font-size: 100%; - color: #333; - clear: both; -} - -.author tt.email { - font-size: 66%; -} - -.titlepage hr { - width: 0em; - clear: both; -} - -.revhistory { - padding-top: 2em; - clear: both; -} - -.toc, -.list-of-tables, -.list-of-examples, -.list-of-figures { - padding: 1.33em 0em 2.5em 0em; - color: #00557D; -} - -.toc p, -.list-of-tables p, -.list-of-figures p, -.list-of-examples p { - padding: 0em 0em 0em 0em; - padding: 0em 0em 0.3em; - margin: 1.5em 0em 0em 0em; -} - -.toc p b, -.list-of-tables p b, -.list-of-figures p b, -.list-of-examples p b{ - font-size: 100.0%; - font-weight: bold; -} - -.toc dl, -.list-of-tables dl, -.list-of-figures dl, -.list-of-examples dl { - margin: 0em 0em 0.5em 0em; - padding: 0em 0em 0em 0em; -} - -.toc dt { - margin: 0em 0em 0em 0em; - padding: 0em 0em 0em 0em; -} - -.toc dd { - margin: 0em 0em 0em 2.6em; - padding: 0em 0em 0em 0em; -} - -div.glossary dl, -div.variablelist dl { -} - -.glossary dl dt, -.variablelist dl dt, -.variablelist dl dt span.term { - font-weight: normal; - width: 20em; - text-align: right; -} - -.variablelist dl dt { - margin-top: 0.5em; -} - -.glossary dl dd, -.variablelist dl dd { - margin-top: -1em; - margin-left: 25.5em; -} - -.glossary dd p, -.variablelist dd p { - margin-top: 0em; - margin-bottom: 1em; -} - - -div.calloutlist table td { - padding: 0em 0em 0em 0em; - margin: 0em 0em 0em 0em; -} - -div.calloutlist table td p { - margin-top: 0em; - margin-bottom: 1em; -} - -div p.copyright { - text-align: left; -} - -div.legalnotice p.legalnotice-title { - margin-bottom: 0em; -} - -p { - line-height: 1.5em; - margin-top: 0em; - -} - -dl { - padding-top: 0em; -} - -hr { - border: solid 1px; -} - - -.mediaobject, -.mediaobjectco { - text-align: center; -} - -img { - border: none; -} - -ul { - padding: 0em 0em 0em 1.5em; -} - -ul li { - padding: 0em 0em 0em 0em; -} - -ul li p { - text-align: left; -} - -table { - width :100%; -} - -th { - padding: 0.25em; - text-align: left; - font-weight: normal; - vertical-align: top; -} - -td { - padding: 0.25em; - vertical-align: top; -} - -p a[id] { - margin: 0px; - padding: 0px; - display: inline; - background-image: none; -} - -a { - text-decoration: underline; - color: #444; -} - -pre { - overflow: auto; -} - -a:hover { - text-decoration: underline; - /*font-weight: bold;*/ -} - -/* This style defines how the permalink character - appears by itself and when hovered over with - the mouse. */ - -[alt='Permalink'] { color: #eee; } -[alt='Permalink']:hover { color: black; } - - -div.informalfigure, -div.informalexample, -div.informaltable, -div.figure, -div.table, -div.example { - margin: 1em 0em; - padding: 1em; - page-break-inside: avoid; -} - - -div.informalfigure p.title b, -div.informalexample p.title b, -div.informaltable p.title b, -div.figure p.title b, -div.example p.title b, -div.table p.title b{ - padding-top: 0em; - margin-top: 0em; - font-size: 100%; - font-weight: normal; -} - -.mediaobject .caption, -.mediaobject .caption p { - text-align: center; - font-size: 80%; - padding-top: 0.5em; - padding-bottom: 0.5em; -} - -.epigraph { - padding-left: 55%; - margin-bottom: 1em; -} - -.epigraph p { - text-align: left; -} - -.epigraph .quote { - font-style: italic; -} -.epigraph .attribution { - font-style: normal; - text-align: right; -} - -span.application { - font-style: italic; -} - -.programlisting { - font-family: monospace; - font-size: 80%; - white-space: pre; - margin: 1.33em 0em; - padding: 1.33em; -} - -.tip, -.warning, -.caution, -.note { - margin-top: 1em; - margin-bottom: 1em; - -} - -/* force full width of table within div */ -.tip table, -.warning table, -.caution table, -.note table { - border: none; - width: 100%; -} - - -.tip table th, -.warning table th, -.caution table th, -.note table th { - padding: 0.8em 0.0em 0.0em 0.0em; - margin : 0em 0em 0em 0em; -} - -.tip p, -.warning p, -.caution p, -.note p { - margin-top: 0.5em; - margin-bottom: 0.5em; - padding-right: 1em; - text-align: left; -} - -.acronym { - text-transform: uppercase; -} - -b.keycap, -.keycap { - padding: 0.09em 0.3em; - margin: 0em; -} - -.itemizedlist li { - clear: none; -} - -.filename { - font-size: medium; - font-family: Courier, monospace; -} - - -div.navheader, div.heading{ - position: absolute; - left: 0em; - top: 0em; - width: 100%; - background-color: #cdf; - width: 100%; -} - -div.navfooter, div.footing{ - position: fixed; - left: 0em; - bottom: 0em; - background-color: #eee; - width: 100%; -} - - -div.navheader td, -div.navfooter td { - font-size: 66%; -} - -div.navheader table th { - /*font-family: Georgia, Times, serif;*/ - /*font-size: x-large;*/ - font-size: 80%; -} - -div.navheader table { - border-left: 0em; - border-right: 0em; - border-top: 0em; - width: 100%; -} - -div.navfooter table { - border-left: 0em; - border-right: 0em; - border-bottom: 0em; - width: 100%; -} - -div.navheader table td a, -div.navfooter table td a { - color: #777; - text-decoration: none; -} - -/* normal text in the footer */ -div.navfooter table td { - color: black; -} - -div.navheader table td a:visited, -div.navfooter table td a:visited { - color: #444; -} - - -/* links in header and footer */ -div.navheader table td a:hover, -div.navfooter table td a:hover { - text-decoration: underline; - background-color: transparent; - color: #33a; -} - -div.navheader hr, -div.navfooter hr { - display: none; -} - - -.qandaset tr.question td p { - margin: 0em 0em 1em 0em; - padding: 0em 0em 0em 0em; -} - -.qandaset tr.answer td p { - margin: 0em 0em 1em 0em; - padding: 0em 0em 0em 0em; -} -.answer td { - padding-bottom: 1.5em; -} - -.emphasis { - font-weight: bold; -} - - - /************* / - / decorations / -/ *************/ - -.titlepage { -} - -.part .title { -} - -.subtitle { - border: none; -} - -/* -h1 { - border: none; -} - -h2 { - border-top: solid 0.2em; - border-bottom: solid 0.06em; -} - -h3 { - border-top: 0em; - border-bottom: solid 0.06em; -} - -h4 { - border: 0em; - border-bottom: solid 0.06em; -} - -h5 { - border: 0em; -} -*/ - -.programlisting { - border: solid 1px; -} - -div.figure, -div.table, -div.informalfigure, -div.informaltable, -div.informalexample, -div.example { - border: 1px solid; -} - - - -.tip, -.warning, -.caution, -.note { - border: 1px solid; -} - -.tip table th, -.warning table th, -.caution table th, -.note table th { - border-bottom: 1px solid; -} - -.question td { - border-top: 1px solid black; -} - -.answer { -} - - -b.keycap, -.keycap { - border: 1px solid; -} - - -div.navheader, div.heading{ - border-bottom: 1px solid; -} - - -div.navfooter, div.footing{ - border-top: 1px solid; -} - - /********* / - / colors / -/ *********/ - -body { - color: #333; - background: white; -} - -a { - background: transparent; -} - -a:hover { - background-color: #dedede; -} - - -h1, -h2, -h3, -h4, -h5, -h6, -h7, -h8 { - background-color: transparent; -} - -hr { - border-color: #aaa; -} - - -.tip, .warning, .caution, .note { - border-color: #fff; -} - - -.tip table th, -.warning table th, -.caution table th, -.note table th { - border-bottom-color: #fff; -} - - -.warning { - background-color: #f0f0f2; -} - -.caution { - background-color: #f0f0f2; -} - -.tip { - background-color: #f0f0f2; -} - -.note { - background-color: #f0f0f2; -} - -.glossary dl dt, -.variablelist dl dt, -.variablelist dl dt span.term { - color: #044; -} - -div.figure, -div.table, -div.example, -div.informalfigure, -div.informaltable, -div.informalexample { - border-color: #aaa; -} - -pre.programlisting { - color: black; - background-color: #fff; - border-color: #aaa; - border-width: 2px; -} - -.guimenu, -.guilabel, -.guimenuitem { - background-color: #eee; -} - - -b.keycap, -.keycap { - background-color: #eee; - border-color: #999; -} - - -div.navheader { - border-color: black; -} - - -div.navfooter { - border-color: black; -} - -.writernotes { - color: red; -} - - - /*********** / - / graphics / -/ ***********/ - -/* -body { - background-image: url("images/body_bg.jpg"); - background-attachment: fixed; -} - -.navheader, -.note, -.tip { - background-image: url("images/note_bg.jpg"); - background-attachment: fixed; -} - -.warning, -.caution { - background-image: url("images/warning_bg.jpg"); - background-attachment: fixed; -} - -.figure, -.informalfigure, -.example, -.informalexample, -.table, -.informaltable { - background-image: url("images/figure_bg.jpg"); - background-attachment: fixed; -} - -*/ -h1, -h2, -h3, -h4, -h5, -h6, -h7{ -} - -/* -Example of how to stick an image as part of the title. - -div.article .titlepage .title -{ - background-image: url("figures/white-on-black.png"); - background-position: center; - background-repeat: repeat-x; -} -*/ - -div.preface .titlepage .title, -div.colophon .title, -div.chapter .titlepage .title, -div.article .titlepage .title -{ -} - -div.section div.section .titlepage .title, -div.sect2 .titlepage .title { - background: none; -} - - -h1.title { - background-color: transparent; - background-repeat: no-repeat; - height: 256px; - text-indent: -9000px; - overflow:hidden; -} - -h2.subtitle { - background-color: transparent; - text-indent: -9000px; - overflow:hidden; - width: 0px; - display: none; -} - - /*************************************** / - / pippin.gimp.org specific alterations / -/ ***************************************/ - -/* -div.heading, div.navheader { - color: #777; - font-size: 80%; - padding: 0; - margin: 0; - text-align: left; - position: absolute; - top: 0px; - left: 0px; - width: 100%; - height: 50px; - background: url('/gfx/heading_bg.png') transparent; - background-repeat: repeat-x; - background-attachment: fixed; - border: none; -} - -div.heading a { - color: #444; -} - -div.footing, div.navfooter { - border: none; - color: #ddd; - font-size: 80%; - text-align:right; - - width: 100%; - padding-top: 10px; - position: absolute; - bottom: 0px; - left: 0px; - - background: url('/gfx/footing_bg.png') transparent; -} -*/ - - - - /****************** / - / nasty ie tweaks / -/ ******************/ - -/* -div.heading, div.navheader { - width:expression(document.body.clientWidth + "px"); -} - -div.footing, div.navfooter { - width:expression(document.body.clientWidth + "px"); - margin-left:expression("-5em"); -} -body { - padding:expression("4em 5em 0em 5em"); -} -*/ - - /**************************************** / - / mozilla vendor specific css extensions / -/ ****************************************/ -/* -div.navfooter, div.footing{ - -moz-opacity: 0.8em; -} - -div.figure, -div.table, -div.informalfigure, -div.informaltable, -div.informalexample, -div.example, -.tip, -.warning, -.caution, -.note { - -moz-border-radius: 0.5em; -} - -b.keycap, -.keycap { - -moz-border-radius: 0.3em; -} -*/ - -table tr td table tr td { - display: none; -} - - -hr { - display: none; -} - -table { - border: 0em; -} - - .photo { - float: right; - margin-left: 1.5em; - margin-bottom: 1.5em; - margin-top: 0em; - max-width: 17em; - border: 1px solid gray; - padding: 3px; - background: white; -} - .seperator { - padding-top: 2em; - clear: both; - } - - #validators { - margin-top: 5em; - text-align: right; - color: #777; - } - @media print { - body { - font-size: 8pt; - } - .noprint { - display: none; - } - } - - -.tip, -.note { - background: #f0f0f2; - color: #333; - padding: 20px; - margin: 20px; -} - -.tip h3, -.note h3 { - padding: 0em; - margin: 0em; - font-size: 2em; - font-weight: bold; - color: #333; -} - -.tip a, -.note a { - color: #333; - text-decoration: underline; -} - -.footnote { - font-size: small; - color: #333; -} - -/* Changes the announcement text */ -.tip h3, -.warning h3, -.caution h3, -.note h3 { - font-size:large; - color: #00557D; -} diff --git a/poky/documentation/kernel-dev/kernel-dev.rst b/poky/documentation/kernel-dev/kernel-dev.rst index 332e089b0..55b42ed99 100644 --- a/poky/documentation/kernel-dev/kernel-dev.rst +++ b/poky/documentation/kernel-dev/kernel-dev.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK ============================================= Yocto Project Linux Kernel Development Manual diff --git a/poky/documentation/kernel-dev/kernel-dev.xml b/poky/documentation/kernel-dev/kernel-dev.xml deleted file mode 100755 index 887ff836f..000000000 --- a/poky/documentation/kernel-dev/kernel-dev.xml +++ /dev/null @@ -1,187 +0,0 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<book id='kernel-dev' lang='en' - xmlns:xi="http://www.w3.org/2003/XInclude" - xmlns="http://docbook.org/ns/docbook" - > - <bookinfo> - - <mediaobject> - <imageobject> - <imagedata fileref='figures/kernel-dev-title.png' - format='SVG' - align='left' scalefit='1' width='100%'/> - </imageobject> - </mediaobject> - - <title> - Yocto Project Linux Kernel Development Manual - </title> - - <authorgroup> - <author> - <affiliation> - <orgname>&ORGNAME;</orgname> - </affiliation> - <email>&ORGEMAIL;</email> - </author> - </authorgroup> - - <revhistory> - <revision> - <revnumber>1.4</revnumber> - <date>April 2013</date> - <revremark>The initial document released with the Yocto Project 1.4 Release.</revremark> - </revision> - <revision> - <revnumber>1.5</revnumber> - <date>October 2013</date> - <revremark>Released with the Yocto Project 1.5 Release.</revremark> - </revision> - <revision> - <revnumber>1.6</revnumber> - <date>April 2014</date> - <revremark>Released with the Yocto Project 1.6 Release.</revremark> - </revision> - <revision> - <revnumber>1.7</revnumber> - <date>October 2014</date> - <revremark>Released with the Yocto Project 1.7 Release.</revremark> - </revision> - <revision> - <revnumber>1.8</revnumber> - <date>April 2015</date> - <revremark>Released with the Yocto Project 1.8 Release.</revremark> - </revision> - <revision> - <revnumber>2.0</revnumber> - <date>October 2015</date> - <revremark>Released with the Yocto Project 2.0 Release.</revremark> - </revision> - <revision> - <revnumber>2.1</revnumber> - <date>April 2016</date> - <revremark>Released with the Yocto Project 2.1 Release.</revremark> - </revision> - <revision> - <revnumber>2.2</revnumber> - <date>October 2016</date> - <revremark>Released with the Yocto Project 2.2 Release.</revremark> - </revision> - <revision> - <revnumber>2.3</revnumber> - <date>May 2017</date> - <revremark>Released with the Yocto Project 2.3 Release.</revremark> - </revision> - <revision> - <revnumber>2.4</revnumber> - <date>October 2017</date> - <revremark>Released with the Yocto Project 2.4 Release.</revremark> - </revision> - <revision> - <revnumber>2.5</revnumber> - <date>May 2018</date> - <revremark>Released with the Yocto Project 2.5 Release.</revremark> - </revision> - <revision> - <revnumber>2.6</revnumber> - <date>November 2018</date> - <revremark>Released with the Yocto Project 2.6 Release.</revremark> - </revision> - <revision> - <revnumber>2.7</revnumber> - <date>May 2019</date> - <revremark>Released with the Yocto Project 2.7 Release.</revremark> - </revision> - <revision> - <revnumber>3.0</revnumber> - <date>October 2019</date> - <revremark>Released with the Yocto Project 3.0 Release.</revremark> - </revision> - <revision> - <revnumber>3.1</revnumber> - <date>&REL_MONTH_YEAR;</date> - <revremark>Released with the Yocto Project 3.1 Release.</revremark> - </revision> - </revhistory> - - <copyright> - <year>©RIGHT_YEAR;</year> - <holder>Linux Foundation</holder> - </copyright> - - <legalnotice> - <para> - Permission is granted to copy, distribute and/or modify this document under - the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. - </para> - <note><title>Manual Notes</title> - <itemizedlist> - <listitem><para> - This version of the - <emphasis>Yocto Project Linux Kernel Development Manual</emphasis> - is for the &YOCTO_DOC_VERSION; release of the - Yocto Project. - To be sure you have the latest version of the manual - for this release, go to the - <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink> - and select the manual from that site. - Manuals from the site are more up-to-date than manuals - derived from the Yocto Project released TAR files. - </para></listitem> - <listitem><para> - If you located this manual through a web search, the - version of the manual might not be the one you want - (e.g. the search might have returned a manual much - older than the Yocto Project version with which you - are working). - You can see all Yocto Project major releases by - visiting the - <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink> - page. - If you need a version of this manual for a different - Yocto Project release, visit the - <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink> - and select the manual set by using the - "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE" - pull-down menus. - </para></listitem> - <listitem> - <para> - To report any inaccuracies or problems with this - (or any other Yocto Project) manual, send an email to - the Yocto Project documentation mailing list at - <filename>docs@lists.yoctoproject.org</filename> or - log into the freenode <filename>#yocto</filename> channel. - </para> - </listitem> - </itemizedlist> - </note> - </legalnotice> - - </bookinfo> - - <xi:include href="kernel-dev-intro.xml"/> - - <xi:include href="kernel-dev-common.xml"/> - - <xi:include href="kernel-dev-advanced.xml"/> - - <xi:include href="kernel-dev-concepts-appx.xml"/> - - <xi:include href="kernel-dev-maint-appx.xml"/> - - <xi:include href="kernel-dev-faq.xml"/> - -<!-- <index id='index'> - <title>Index</title> - </index> ---> - -</book> -<!-- -vim: expandtab tw=80 ts=4 ---> |