poky: subtree update:c67f57c09e..c6bc20857c
Adrian Freihofer (2):
oe-publish-sdk: fix layers init via ssh
oe-publish-sdk: add --keep-orig option
Alexander Kanavin (68):
meta-selftest: correct the virgl test for 5.8 kernels
bison: upgrade 3.6.4 -> 3.7.1
util-linux: upgrade 2.35.2 -> 2.36
python3-numpy: upgrade 1.19.0 -> 1.19.1
python3-setuptools: upgrade 49.3.1 -> 49.6.0
rsync: upgrade 3.2.2 -> 3.2.3
util-linux: merge .inc into .bb
acpica: upgrade 20200528 -> 20200717
asciidoc: upgrade 9.0.1 -> 9.0.2
cryptodev: upgrade 1.10 -> 1.11
diffoscope: upgrade 153 -> 156
epiphany: upgrade 3.36.3 -> 3.36.4
font-alias: upgrade 1.0.3 -> 1.0.4
gtk+3: upgrade 3.24.21 -> 3.24.22
libcheck: upgrade 0.15.0 -> 0.15.2
libinput: upgrade 1.16.0 -> 1.16.1
libpipeline: upgrade 1.5.2 -> 1.5.3
libx11: upgrade 1.6.9 -> 1.6.11
linux-firmware: upgrade 20200619 -> 20200721
man-pages: upgrade 5.07 -> 5.08
mc: upgrade 4.8.24 -> 4.8.25
mesa: upgrade 20.1.4 -> 20.1.5
piglit: upgrade to latest revision
re2c: upgrade 2.0 -> 2.0.2
sysstat: upgrade 12.2.2 -> 12.4.0
vala: upgrade 0.48.7 -> 0.48.9
bootchart2: update 0.14.8 -> 0.14.9
harfbuzz: convert to meson, enable gobject introspection
pango: update 1.44.7 -> 1.46.0
boost: update 1.73.0 -> 1.74.0
xev: update 1.2.3 -> 1.2.4
wpebackend-fdo: update 1.6.1 -> 1.7.1
gpgme: update 1.13.1 -> 1.14.0
libpsl: update 0.21.0 -> 0.21.1.
gettext: update 0.20.2 -> 0.21
cmake: update 3.17.3 -> 3.18.1
linux-firmware: update 20200721 -> 20200817
meson: update 0.55.0 -> 0.55.1
systemd-boot: bump version to 246.2
json-glib: inherit upstream-version-is-even
packagegroup-core-device-devel: remove
oeqa/x32lib: rework to use readelf from the host
oeqa/multilib: rework to use readelf from the host
oeqa/multilib: un-skip the connman test
poky.conf: do not install packagegroup-core-device-devel into qemu images
glib-2.0: update 2.64.4 -> 2.64.5
cmake: upgrade 3.18.1 -> 3.18.2
libxcrypt: upgrade 4.4.16 -> 4.4.17
debianutils: upgrade 4.11 -> 4.11.1
enchant2: upgrade 2.2.8 -> 2.2.9
harfbuzz: upgrade 2.7.1 -> 2.7.2
libmpc: upgrade 1.1.0 -> 1.2.0
librepo: upgrade 1.12.0 -> 1.12.1
libuv: upgrade 1.38.1 -> 1.39.0
msmtp: upgrade 1.8.11 -> 1.8.12
ninja: upgrade 1.10.0 -> 1.10.1
p11-kit: upgrade 0.23.20 -> 0.23.21
pango: upgrade 1.46.0 -> 1.46.1
re2c: upgrade 2.0.2 -> 2.0.3
resolvconf: upgrade 1.82 -> 1.83
stress-ng: upgrade 0.11.18 -> 0.11.19
gnu-config: update to latest revision
nasm: update 2.15.03 -> 2.15.05
libva-utils: fix upstream version check
gnupg: update 2.2.21 -> 2.2.22
libx11: update 1.6.11 -> 1.6.12
mesa: update 20.1.5 -> 20.1.6
xserver-xorg: update 1.20.8 -> 1.20.9
Andrey Zhizhikin (1):
insane: check for missing update-alternatives inherit
Anibal Limon (1):
recipes-kernel: linux-firmware add qcom-venus-{5.2,5.4} packages
Aníbal Limón (1):
recipes-graphics/xorg-xserver: Add patch to fix segfault when probe
Armin Kuster (2):
bind: update to 9.11.22 ESV
core-image-sato: qemumips use 512 mem
Bruce Ashfield (30):
linux-yocto/5.4: update to v5.4.59
linux-yocto/5.8: update to v5.8.2
yocto-bsp: update to v5.4.56
yocto-bsp: update to v5.4.58
qemu: bump default reference kernel to v5.8
linux-yocto/5.8: fix perf and virtio_scsi warnings
linux-yocto-rt/5.8: fix lttng-modules build
linux-yocto/5.8: selftests/bpf: Prevent runqslower from racing on building bpftool
linux-yocto/5.8: disable CONFIG_NFS_DISABLE_UDP_SUPPORT
poky: set preferred version for linux-yocto to be v5.8
poky-tiny: set preferred version to 5.8
poky: add preferred version for linux-yocto-rt
linux-yocto/5.8: update to v5.8.3
linux-yocto/5.4: update to v5.4.60
kernel: config cleanups for 5.8+
linux-yocto/5.4: update to v5.4.61
linux-yocto/5.8: update to v5.8.4
linux-yocto/5.8: disable IKHEADERS in default builds
kernel-yocto: allow promotion of configuration warnings to errors
kernel-yocto: checksum all modifications to available kernel fragments directories
lttng-modules/devupstream: bump to latest 2.12 commits
linux-yocto-dev: bump to v5.9+
linux-yocto/5.8: update to v5.8.5
kernel-devsrc: account for HOSTCC and HOSTCXX
linux-yocto/config: netfilter: Enable nat for ipv4 and ipv6
linux-yocto/5.8: update to v5.8.8
linux-yocto/5.4: update to v5.4.64
linux-yocto/config: configuration warning cleanup
linux-yocto/5.8: update to v5.8.9
linux-yocto/5.4: update to v5.4.65
Changhyeok Bae (2):
iw: upgrade 5.4 -> 5.8
iputils: upgrade s20190709 -> s20200821
Chris Laplante (12):
bitbake: compat.py: remove file since it no longer actually implements anything
bitbake: COW: formatting
bitbake: COW: migrate test suite into tests/cow
cve-update-db-native: add progress handler
cve-check/cve-update-db-native: use lockfile to fix usage under multiconfig
cve-update-db-native: use context manager for cve_f
cve-check: avoid FileNotFoundError if no do_cve_check task has run
bitbake: utils: process_profilelog: use context manager
bitbake: utils: fix UnboundLocalError when _print_exception raises
cve-update-db-native: be less magical about checking whether the cve-check class is enabled
cve-update-db-native: move -journal checking into do_fetch
cve-update-db-native: remove unused variable
Christophe GUIBOUT (1):
initramfs-framework: support kernel cmdline with double quotes
Denys Dmytriyenko (2):
weston: upgrade 8.0.0 -> 9.0.0
cryptodev: bump 1 commit past 1.11 to fix 5.9-rc1+
Diego Sueiro (2):
license_image.bbclass: Create symlink to the image license manifest dir
license_image.bbclass: Fix symlink to the image license manifest dir creation
Douglas Royds (1):
tcmode-default: Drop gcc-cross-initial, gcc-crosssdk-initial references
Frazer Clews (1):
bitbake: lib: fix most undefined code picked up by pylint
Geoff Parker (1):
systemd-serialgetty: Replace sed quoting using ' with " to allow var expansion
Jacob Kroon (1):
gcc10: Don't default back to -fcommon
Jean-Francois Dagenais (1):
bitbake: siggen: clean_basepath: remove recipe full path when virtual:xyz present
Jens Rehsack (1):
lttng-modules: backport patches from 2.12.x to fix 5.4.64+ and 5.8.9+ builds
Joe Slater (1):
pseudo: fix renaming to self
Jon Mason (4):
cortex-m0plus.inc: change file permissions
tune-cortexa55.inc: clean-up ARMv8.2a uses
tune-cortexa57-cortexa53.inc: add CRC and set march
tune-cortexa*: Cleanups
Joshua Watt (8):
wic: Add 512 Byte alignment to --offset
oeqa: runtime_tests: Extra GPG debugging
oeqa: sdk: Capture stderr output
oeqa: reproducible: Fix test not producing diffs
diffoscope: upgrade 156 -> 158
bitbake: bitbake: Add parsing torture test
bitbake: cooker: Block SIGINT in worker processes
sphinx: dev-manual: Clarify that virtual providers do not apply to runtime dependencies
Kai Kang (1):
dhcpcd: 9.1.4 -> 9.2.0
Kevin Hao (1):
meta-yocto-bsp: Bump to the v5.8 kernel
Khairul Rohaizzat Jamaluddin (1):
wic/bootimg-efi: IMAGE_EFI_BOOT_FILES variable added to separate bootimg-efi and bootimg-partition
Khem Raj (24):
gcc-cross-canadian: Install gcc/g++ wrappers for musl
uninative: Upgrade to 2.9
packagegroup-core-tools-profile: Disable lttng-modules for riscv64
lttng-modules: Disable on riscv64
kexec-tools: Fix build with -fno-common on ppc
lttng-tools: Do not build for riscv64
util-linux: Allow update alternatives for additional apps
lttng-tools: lttng-ust works on riscv64
json-glib: Backport a build fix with clang
rpcbind: Use update-alternatives for rpcinfo
go: Upgrade to 1.15 major release
weston-init: Redefine weston service and add socket activation option
musl: Upgrade to latest master
libucontext: Recognise riscv32 architecture
linuxloader.bbclass: Define riscv32 ldso for musl
populate_sdk_ext: Do not assume local.conf will always exist
weston: plane_add_prop() calls break musl atomic modesetting
weston-init: Enable RDP screen share
weston-init: Do not use fbdev backend
weston-init: Select drm/fbdev backends for qemu machines
oeqa/weston: Fix tests to run with systemd
core-image-weston: Bump qemu memory to 512M
go: Update to 1.15.2 minor release
bind: Inherit update-alternatives
Mark Hatle (6):
package_tar.bbclass: Sync to the other package_* classes
kernel.bbclass: Remove do_install[prefunc] no longer needed
buildhistory.bbclass: Rework to use read_subpackage_metadata
kernel.bbclass: Move away from calling package_get_auto_pr
package.bbclass: hash equivalency and pr service
bitbake: process.py: Handle SystemExit exception to eliminate backtrace
Mark Morton (1):
sphinx: test-manual code block, link, and format update
Martin Jansa (7):
devtool: expand SRC_URI when guessing recipe update mode
image-artifact-names: introduce new bbclass and move some variables into it
kernel.bbclass: use bash variables like imageType, base_name without {}
kernel.bbclass: eliminate (initramfs_)symlink_name variables
kernel.bbclass: use camelCase notation for bash variables in do_deploy
*-initramfs: don't use .rootfs IMAGE_NAME_SUFFIX
bitbake.conf: use ${TCMODE}-${TCLIBC} directory for CACHE
Matt Madison (1):
image.bbclass: fix REPRODUCIBLE_TIMESTAMP_ROOTFS reference
Michael Gloff (2):
sysvinit rc: Use PSPLASH_FIFO_DIR for progress fifo
sysvinit: Remove ${B} assignment
Michael Tretter (1):
devtool: deploy-target: Fix size calculation for hard links
Ming Liu (2):
systemd: split systemd specific udev rules into its own package
libubootenv: inherit uboot-config
Mingli Yu (3):
qemu: always define unknown_lock_type
qemu: override DEBUG_BUILD
bison: remove the parallel build patch
Naveen Saini (1):
lib/oe/recipeutils.py: add support for BBFILES_DYNAMIC
Nicolas Dechesne (73):
linux-libc-headers: kernel headers are installed in STAGING_KERNEL_BUILDDIR
bitbake: sphinx: add initial build infrastructure
bitbake: sphinx: initial sphinx support
bitbake: sphinx: bitbake-user-manual: use builtin sphinx glossary
bitbake: sphinx: switch to readthedocs theme
bitbake: sphinx: override theme CSS
bitbake: sphinx: fixup for links
bitbake: sphinx: fix links inside notes
bitbake: sphinx: fixes all remaining warnings
bitbake: sphinx: Makefile.sphinx: add clean and publish targets
bitbake: sphinx: tweak html output a bit
bitbake: sphinx: add SPDX headers
bitbake: sphinx: index: move the boilerplate at the end of the page
bitbake: sphinx: conf: enable extlinks extension
bitbake: sphinx: add releases page
bitbake: sphinx: bitbake-user-manual: insert additional blank line after title
bitbake: sphinx: last manual round of fixes/improvements
bitbake: sphinx: update style for important, caution and warnings
bitbake: sphinx: remove leading '/'
bitbake: sphinx: theme_override: properly set font for verbatim text
bitbake: bitbake-user-manual: fix bad links
sphinx: add initial build infrastructure
sphinx: initial sphinx support
sphinx: ref-variables: use builtin sphinx glossary
sphinx: overview-manual: add figures
sphinx: switch to readthedocs theme
sphinx: Add SPDX license headers
sphinx: add CSS theme override
sphinx: bsp-guide: add figures
sphinx: add Yocto project logo
sphinx: conf: update copyright
sphinx: conf: add substitutions/global variables
sphinx: add boilerplate file
sphinx: add boilerplate to manuals
sphinx: ref-manual: add revision history table
sphinx: add a general index
sphinx: conf.py: enable sphinx.ext.autosectionlabel
sphinx: ref-manual: use builtin glossary for the Terms section
sphinx: fix internal links
sphinx: ref-manual: fix typo
sphinx: fix custom term links
sphinx: manual updates for some links
sphinx: dev-manual add figures
sphinx: kernel-dev: add figures
sphinx: profile-manual: add figures
sphinx: fix up bold text for informalexample container
sphinx: ref-manual: add figures
sphinx: sdk-manual: add figures
sphinx: test-manual: add figures
sphinx: toaster-manual: add figures
sphinx: add links for Yocto project website
sphinx: fix links when the link text should be displayed
sphinx: add links to terms in the BitBake glossary
sphinx: add links to section in the Bitbake manual
sphinx: setup extlink for docs.yoctoproject.org
sphinx: enable intersphinx extension
sphinx: insert blank below between title and toc
sphinx: fix up terms related to kernel-fitimage
sphinx: conf: a few rendering tweaks
sphinx: makefile: add publish target
sphinx: conf: include CSS/JS files, the proper way
sphinx: convert 'what I wish I'd known'
sphinx: convert 'transitioning to a custom environment'
sphinx: ref-manual: fix heading for oe-init-build-env
sphinx: brief-yoctoprojectqs: fix up all remaining rendering issues
sphinx: Makefile.sphinx improvements
sphinx: convert bsp-guide
sphinx: remove leading '/'
sphinx: update style for important, caution and warnings
sphinx: profile-manual: convert profile-manual
sphinx: theme_override: properly set font for verbatim text
sphinx: theme_override: add tying-it-together admonition
sphinx: conf: exclude adt-manual/*.rst
Oleksandr Kravchuk (1):
ell: update to 0.33
Ovidiu Panait (1):
libxml2: Fix CVE-2020-24977
Peter A. Bigot (2):
bluez5: fix builds that require ell support
timezone: include leap second data in tzdata-core
Peter Bergin (1):
systemd: avoid failing if no udev rules provided
Pierre-Jean Texier (2):
libubootenv: upgrade 0.3 -> 0.3.1
diffoscope: upgrade 158 -> 160
Quentin Schulz (16):
sphinx: brief-yoctoprojectqs: remove redundant welcome
sphinx: brief-yoctoprojectqs: fix ambiguous note for cyclone5 example
sphinx: brief-yoctoprojectqs: add missing boilerplate
sphinx: overview-manual: add link to AUH how-to section
sphinx: overview-manual: fix bitbake basic explanation
sphinx: brief-yoctoprojectqs: add note on branch consistency between layers
sphinx: what-i-wish-id-known: update "don't be fooled by doc search results"
sphinx: overview-manual: remove highlight in bold section
sphinx: replace special quotes with single and double quotes
sphinx: fix incorrect indentations
sphinx: brief-yoctoprojectqs: put other distros note after Ubuntu-specific packages
sphinx: fix a few typos or missing/too many words
sphinx: "highlight" some variables, tasks or files
sphinx: fix or add missing links and remove mention of Eclipse workflow
ref-manual: examples: hello-autotools: upgrade to 2.10
ref-manual: examples: libxpm: add relative path to .inc
Rahul Kumar (1):
systemd-serialgetty: Fix sed expression quoting
Rasmus Villemoes (1):
kernel.bbclass: run do_symlink_kernsrc before do_patch
Richard Purdie (74):
nativesdk-sdk-provides-dummy: Add /bin/sh
bitbake: fetch2/wget: Remove buffering parameter
bitbake: cooker: Ensure parse_quit thread is closed down
bitbake: cooker: Explictly shut down the sync thread
bitbake: fetch2: Drop cups.org from wget status checks
bitbake: build/msg: Cleanup verbose option handling
bitbake: cooker/cookerdata/main: Improve loglevel handling
bitbake: cookerdata: Ensure UI options are updated to the server
bitbake: cooker/cookerdata: Ensure UI event log is updated from commandline
bitbake: cooker: Defer configuration init to after UI connection
bitbake: server/process: Move the socket code to server process only
bitbake: main/server/process: Drop configuration object passing
bitbake: cooker: Ensure BB_ORIGENV is updated by changes to configuration.env
bitbake: server/process: Log extra threads at exit
bitbake: server/process: Add bitbake-server and exec() a new server process
bitbake: runqueue: Don't use sys.argv
bitbake: cooker: Ensure cooker's enviroment is updated on updateConfig
connman-gnome/matchbox-desktop: Remove file:// globbing
selftest/recipetool: Drop globbing SRC_URI test, no longer supported
local.conf.sample: Document memory resident bitbake
bitbake: fetch2: Drop globbing supprt in file:// SRC_URIs
bitbake: server/process: Use sys.executable for bitbake-server
bitbake: process: Avoid bb.utils.timeout
bitbake: utils: Drop broken timeout function
bitbake: server/process: Fix typo in code causing tracebacks
oeqa/selftest: Apply patch to fix cpio build with -fno-common
runqemu: Show an error for conflicting graphics options
lttng: Move platform logic to dedicated inc file
patchelf: upgrade 0.11 -> 0.12
build-appliance/packagegroup-core-base-utils: Replace dhcp-client/dhcp-server with dhcpcd/kea
selftest/prservice: Improve test failure message
iputils: Adapt ${PN}-tftpd package dependency to PACKAGECONFIG
bitbake: process/knotty: Improve early exception handling
bitbake: cooker/cookerdata: Use BBHandledException, not sys.exit()
bitbake: cookerdata: Fix exception raise statements
bitbake: process: Avoid printing binary strings for leftover processes
bitbake: server/process: Ensure logging is flushed
bitbake: server/process: Don't show tracebacks if the lockfile is removed
bitbake: cooker: Ensure parser replacement calls parser final_cleanup
bitbake: cooker: Assign a name to the sync thread to aid debugging
bitbake: server/process: Ensure we don't keep looping if some other server is started
bitbake: server/process: Prefix the log data with pid/time information
bitbake: server/process: Note when commands complete in logs
bitbake: cooker: Ensure parser is cleaned up
runqemu: Add a hook to allow it to renice
bitbake: cooker: Avoid parser deadlocks
bitbake: cooker: Ensure parser worker signal handlers are default
selftest/signing: Ensure build path relocation is safe
oeqa/concurrencytest: Improve builddir path manipulations
bitbake: cooker/command: Fix disconnection handling
bitbake: tinfoil: Ensure sockets don't leak even when exceptions occur
bitbake: tests/fetch: Move away from problematic freedesktop.org urls
bitbake: sphinx: Enhance the sphinx experience/nagivation with:
bitbake: sphinx: theme_override: Use bold for emphasis text
Revert "qemu: always define unknown_lock_type"
Revert "core-image-sato: qemumips use 512 mem"
sphinx: Organize top level docs
sphinx: releases.rst: Add index/links to docs for previous releases
sphinx: boilerplate.rst: Drop versions notes as we have better navigation now
sphinx: boilerplate.rst: Sphinx puts the copyright elsewhere
sphinx: history: Move revision history to its own section
sphinx: manuals: Move boilerplate after toctree
sphinx: Add support for multiple docs version
sphinx: index.rst: Fix links
sphinx: ref-system-requirements: Improve formatting of the notes sections, merging them
sphinx: ref-manual links fixes and many other cleanups to import
sphinx: dev-manual: Various URL, code block and other fixes to imported data
sphinx: sdk-manual: Various URL, code block and other fixes to imported data
sphinx: kernel-dev: Various URL, code block and other fixes to imported data
sphinx: theme_override: Use bold for emphasis text
sphinx: ref-tasks: Add populate_sdk_ext task definition
sphinx: ref-manual/migration: Split each release into its own file
sphinx: overview-manual: Various URL, code block and other fixes to imported data
build-appliance-image: Update to master head revision
Robert Yang (3):
bitbake: cooker.py: Save prioritized BBFILES to BBFILES_PRIORITIZED
bitbake: utils.py: get_file_layer(): Exit the loop when file is matched
bitbake: utils.py: get_file_layer(): Improve performance
Ross Burton (25):
package.bbclass: explode the RPROVIDES so we don't think the versions are provides
elfutils: silence a new QA warning
insane: improve gnu-hash-style warning
gdk-pixbuf: add tests PACKAGECONFIG
debianutils: change SRC_URI to use snapshot.debian.org
insane: only load real files as ELF
autoconf: consolidate SRC_URI
autoconf: consolidate DEPENDS
kea: no need to depend on kea-native
kea: don't use PACKAGECONFIG inappropriately
kea: bump to 1.7.10
help2man: rewrite recipe
local.conf.sample.extended: remove help2man reference
curl: add vendors to CVE_PRODUCT to exclude false positives
harfbuzz: update patch status
harfbuzz: fix a build race around hb-version.h
cmake: whitelist CVE-2016-10642
ncurses: remove config.cache
qemu: fix CVE-2020-14364
cve-update-db-native: remove unused import
cve-update-db-native: add more logging when fetching
cve-update-db-native: use fetch task
alsa-plugins: improve .la removal
sato-screenshot: improve .la removal
buildhistory-diff: use BUILDDIR to know where buildhistory is
Saul Wold (1):
gnupg: uprev 2.2.22 -> 2.2.23
Stacy Gaikovaia (2):
bison: uprev from 3.7.1 to 3.7.2
valgrind: fix memcheck vgtests remove fullpath-after flags
Steve Sakoman (1):
xinput-calibrator: change SRC_URI to branch with libinput support
Sumit Garg (1):
insane: fix gnu-hash-style check
TeohJayShen (1):
oeqa/runtime: add test for matchbox-terminal
Tim Orling (1):
sphinx: toaster-manual: fix vars, links, code blocks
Vijai Kumar K (2):
image_types_wic: Add ASSUME_PROVIDED to WICVARS
wic: misc: Add /bin to the list of searchpaths
Yanfei Xu (1):
kernel-yocto: only replace leading -I in include paths
Yi Zhao (1):
glib-networking: add ptest
Zhixiong Chi (1):
gnutls: CVE-2020-24659
akuster (8):
log4cplus: move meta-oe pkg to core
kea: Move from meta-networking
maintainers.inc: Add me as kea & log4plus maintainer.
dhcpcd: Move from meta-network as OE-Core needs a client
maintainers.inc: Add me as dhcpcd maintainer
dhcp: remove from core
bind: Add 9.16.x
bind: 9.11 remove
hongxu (1):
sysstat: fix installed-vs-shipped QA Issue in systemd
zangrc (4):
libcap:upgrade 2.42 -> 2.43
libcap-ng:upgrade 0.7.10 -> 0.7.11
libgpg-error:upgrade 1.38 -> 1.39
at-spi2-core:upgrade 2.36.0 -> 2.36.1
Signed-off-by: Andrew Geissler <geissonator@yahoo.com>
Change-Id: I5542f5eea751a2641342e945725fd687cd74bebe
diff --git a/poky/documentation/kernel-dev/kernel-dev-common.rst b/poky/documentation/kernel-dev/kernel-dev-common.rst
new file mode 100644
index 0000000..d4b60a9
--- /dev/null
+++ b/poky/documentation/kernel-dev/kernel-dev-common.rst
@@ -0,0 +1,2078 @@
+.. SPDX-License-Identifier: CC-BY-2.0-UK
+
+************
+Common Tasks
+************
+
+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.
+
+Preparing the Build Host to Work on the Kernel
+==============================================
+
+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 ":doc:`../dev-manual/dev-manual-start`" section in
+the Yocto Project Development Tasks Manual. Part of preparing the system
+is creating a local Git repository of the
+:term:`Source Directory` (``poky``) on your system. Follow the steps in the
+":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
+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 "
+ Checking Out by Branch in Poky
+ " and "
+ Checking Out by Tag in Poky
+ " sections in the Yocto Project Development Tasks Manual for more
+ information.
+
+Kernel development is best accomplished using
+:ref:`devtool <sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow>`
+and not through traditional kernel workflow methods. The remainder of
+this section provides information for both scenarios.
+
+Getting Ready to Develop Using ``devtool``
+------------------------------------------
+
+Follow these steps to prepare to update the kernel image using
+``devtool``. Completing this procedure leaves you with a clean kernel
+image and ready to make modifications as described in the "
+:ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`"
+section:
+
+1. *Initialize the BitBake Environment:* Before building an extensible
+ SDK, you need to initialize the BitBake build environment by sourcing
+ the build environment script (i.e. :ref:`structure-core-script`):
+ ::
+
+ $ cd ~/poky
+ $ source oe-init-build-env
+
+ .. note::
+
+ The previous commands assume the
+ Source Repositories
+ (i.e.
+ poky
+ ) have been cloned using Git and the local repository is named
+ "poky".
+
+2. *Prepare Your local.conf File:* By default, the
+ :term:`MACHINE` 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
+ ``MACHINE`` variable appropriately in your ``conf/local.conf`` file
+ found in the
+ :term:`Build Directory` (i.e.
+ ``~/poky/build`` in this example).
+
+ Also, since you are preparing to work on the kernel image, you need
+ to set the
+ :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
+ variable to include kernel modules.
+
+ In this example we wish to build for qemux86 so we must set the
+ ``MACHINE`` variable to "qemux86" and also add the "kernel-modules".
+ As described we do this by appending to ``conf/local.conf``:
+ ::
+
+ MACHINE = "qemux86"
+ MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
+
+3. *Create a Layer for Patches:* You need to create a layer to hold
+ patches created for the kernel image. You can use the
+ ``bitbake-layers create-layer`` command as follows:
+ ::
+
+ $ cd ~/poky/build
+ $ bitbake-layers create-layer ../../meta-mylayer
+ NOTE: Starting bitbake server...
+ Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
+ $
+
+ .. note::
+
+ For background information on working with common and BSP layers,
+ see the "
+ Understanding and Creating Layers
+ " section in the Yocto Project Development Tasks Manual and the "
+ BSP Layers
+ " section in the Yocto Project Board Support (BSP) Developer's
+ Guide, respectively. For information on how to use the
+ bitbake-layers create-layer
+ command to quickly set up a layer, see the "
+ Creating a General Layer Using the
+ bitbake-layers
+ Script
+ " section in the Yocto Project Development Tasks Manual.
+
+4. *Inform the BitBake Build Environment About Your Layer:* As directed
+ when you created your layer, you need to add the layer to the
+ :term:`BBLAYERS` variable in the
+ ``bblayers.conf`` file as follows:
+ ::
+
+ $ cd ~/poky/build
+ $ bitbake-layers add-layer ../../meta-mylayer
+ NOTE: Starting bitbake server...
+ $
+
+5. *Build the Extensible SDK:* Use BitBake to build the extensible SDK
+ specifically for use with images to be run using QEMU:
+ ::
+
+ $ cd ~/poky/build
+ $ bitbake core-image-minimal -c populate_sdk_ext
+
+ Once
+ the build finishes, you can find the SDK installer file (i.e.
+ ``*.sh`` file) in the following directory:
+ ~/poky/build/tmp/deploy/sdk For this example, the installer file is
+ named
+ ``poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-DISTRO.sh``
+
+6. *Install the Extensible SDK:* Use the following command to install
+ the SDK. For this example, install the SDK in the default
+ ``~/poky_sdk`` directory:
+ ::
+
+ $ cd ~/poky/build/tmp/deploy/sdk
+ $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-3.1.2.sh
+ Poky (Yocto Project Reference Distro) Extensible SDK installer version 3.1.2
+ ============================================================================
+ 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
+
+
+7. *Set Up a New Terminal to Work With the Extensible SDK:* You must set
+ up a new terminal to work with the SDK. You cannot use the same
+ BitBake shell used to build the installer.
+
+ After opening a new shell, run the SDK environment setup script as
+ directed by the output from installing the SDK:
+ ::
+
+ $ 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.
+
+ .. 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.
+
+8. *Build the Clean Image:* The final step in preparing to work on the
+ kernel is to build an initial image using ``devtool`` in the new
+ terminal you just set up and initialized for SDK work:
+ ::
+
+ $ 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
+
+ If you were
+ building for actual hardware and not for emulation, you could flash
+ the image to a USB stick on ``/dev/sdd`` and boot your device. For an
+ example that uses a Minnowboard, see the
+ `TipsAndTricks/KernelDevelopmentWithEsdk <https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk>`__
+ Wiki page.
+
+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
+":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`"
+section.
+
+Getting Ready for Traditional Kernel Development
+------------------------------------------------
+
+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.
+
+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 ":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`"
+section:
+
+1. *Initialize the BitBake Environment:* Before you can do anything
+ using BitBake, you need to initialize the BitBake build environment
+ by sourcing the build environment script (i.e.
+ :ref:`structure-core-script`).
+ Also, for this example, be sure that the local branch you have
+ checked out for ``poky`` is the Yocto Project &DISTRO_NAME; branch. If
+ you need to checkout out the &DISTRO_NAME; branch, see the
+ ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`"
+ section in the Yocto Project Development Tasks Manual.
+ ::
+
+ $ cd ~/poky
+ $ git branch
+ master
+ * &DISTRO_NAME;
+ $ source oe-init-build-env
+
+ .. note::
+
+ The previous commands assume the
+ Source Repositories
+ (i.e.
+ poky
+ ) have been cloned using Git and the local repository is named
+ "poky".
+
+2. *Prepare Your local.conf File:* By default, the
+ :term:`MACHINE` 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
+ ``MACHINE`` variable appropriately in your ``conf/local.conf`` file
+ found in the
+ :term:`Build Directory` (i.e.
+ ``~/poky/build`` in this example).
+
+ Also, since you are preparing to work on the kernel image, you need
+ to set the
+ :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
+ variable to include kernel modules.
+
+ In this example we wish to build for qemux86 so we must set the
+ ``MACHINE`` variable to "qemux86" and also add the "kernel-modules".
+ As described we do this by appending to ``conf/local.conf``:
+ ::
+
+ MACHINE = "qemux86"
+ MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
+
+3. *Create a Layer for Patches:* You need to create a layer to hold
+ patches created for the kernel image. You can use the
+ ``bitbake-layers create-layer`` command as follows:
+ ::
+
+ $ cd ~/poky/build
+ $ bitbake-layers create-layer ../../meta-mylayer
+ NOTE: Starting bitbake server...
+ Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
+
+ .. note::
+
+ For background information on working with common and BSP layers,
+ see the "
+ Understanding and Creating Layers
+ " section in the Yocto Project Development Tasks Manual and the "
+ BSP Layers
+ " section in the Yocto Project Board Support (BSP) Developer's
+ Guide, respectively. For information on how to use the
+ bitbake-layers create-layer
+ command to quickly set up a layer, see the "
+ Creating a General Layer Using the
+ bitbake-layers
+ Script
+ " section in the Yocto Project Development Tasks Manual.
+
+4. *Inform the BitBake Build Environment About Your Layer:* As directed
+ when you created your layer, you need to add the layer to the
+ :term:`BBLAYERS` variable in the
+ ``bblayers.conf`` file as follows:
+ ::
+
+ $ cd ~/poky/build
+ $ bitbake-layers add-layer ../../meta-mylayer
+ NOTE: Starting bitbake server ...
+ $
+
+5. *Create a Local Copy of the Kernel Git Repository:* You can find Git
+ repositories of supported Yocto Project kernels organized under
+ "Yocto Linux Kernel" in the Yocto Project Source Repositories at
+ :yocto_git:`/`.
+
+ For simplicity, it is recommended that you create your copy of the
+ kernel Git repository outside of the
+ :term:`Source Directory`, which is
+ usually named ``poky``. Also, be sure you are in the
+ ``standard/base`` branch.
+
+ The following commands show how to create a local copy of the
+ ``linux-yocto-4.12`` kernel and be in the ``standard/base`` branch.
+
+ .. note::
+
+ The
+ linux-yocto-4.12
+ kernel can be used with the Yocto Project 2.4 release and forward.
+ You cannot use the
+ linux-yocto-4.12
+ kernel with releases prior to Yocto Project 2.4:
+
+ ::
+
+ $ 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.
+
+6. *Create a Local Copy of the Kernel Cache Git Repository:* For
+ simplicity, it is recommended that you create your copy of the kernel
+ cache Git repository outside of the
+ :term:`Source Directory`, which is
+ usually named ``poky``. Also, for this example, be sure you are in
+ the ``yocto-4.12`` branch.
+
+ The following commands show how to create a local copy of the
+ ``yocto-kernel-cache`` and be in the ``yocto-4.12`` branch:
+ ::
+
+ $ 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.
+
+At this point, you are ready to start making modifications to the kernel
+using traditional kernel development steps. For a continued example, see
+the "`Using Traditional Kernel Development to Patch the
+Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__"
+section.
+
+Creating and Preparing a Layer
+==============================
+
+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 :term:`BitBake`
+append files (``.bbappend``) and provides a convenient mechanism to
+create your own recipe files (``.bb``) as well as store and use kernel
+patch files. For background information on working with layers, see the
+":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
+section in the Yocto Project Development Tasks Manual.
+
+.. note::
+
+ The Yocto Project comes with many tools that simplify tasks you need
+ to perform. One such tool is the
+ bitbake-layers create-layer
+ command, which simplifies creating a new layer. See the "
+ Creating a General Layer Using the
+ bitbake-layers
+ Script
+ " section in the Yocto Project Development Tasks Manual for
+ information on how to use this script to quick set up a new layer.
+
+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 ``mylayer`` in your
+home directory:
+
+1. *Create Structure*: Create the layer's structure:
+ ::
+
+ $ 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
+
+ The ``conf`` directory holds your configuration files, while the
+ ``recipes-kernel`` directory holds your append file and eventual
+ patch files.
+
+2. *Create the Layer Configuration File*: Move to the
+ ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as
+ follows:
+ ::
+
+ # 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"
+
+ Notice ``mylayer`` as part of the last three statements.
+
+3. *Create the Kernel Recipe Append File*: Move to the
+ ``meta-mylayer/recipes-kernel/linux`` directory and create the
+ kernel's append file. This example uses the ``linux-yocto-4.12``
+ kernel. Thus, the name of the append file is
+ ``linux-yocto_4.12.bbappend``:
+ ::
+
+ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+
+ SRC_URI_append = " file://patch-file-one"
+ SRC_URI_append = " file://patch-file-two"
+ SRC_URI_append = " file://patch-file-three"
+
+ The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
+ enable the OpenEmbedded build system to find patch files. For more
+ information on using append files, see the
+ ":ref:`dev-manual/dev-manual-common-tasks:using .bbappend files in your layer`"
+ section in the Yocto Project Development Tasks Manual.
+
+Modifying an Existing Recipe
+============================
+
+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 :term:`Source Directory` in
+``meta/recipes-kernel/linux``.
+
+Modifying an existing recipe can consist of the following:
+
+- Creating the append file
+
+- Applying patches
+
+- Changing the configuration
+
+Before modifying an existing recipe, be sure that you have created a
+minimal, custom layer from which you can work. See the "`Creating and
+Preparing a Layer <#creating-and-preparing-a-layer>`__" section for
+information.
+
+Creating the Append File
+------------------------
+
+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 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe,
+the append file will typically be located as follows within your custom
+layer:
+::
+
+ your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend
+
+The append file should initially extend the
+:term:`FILESPATH` search path by
+prepending the directory that contains your files to the
+:term:`FILESEXTRAPATHS`
+variable as follows:
+::
+
+ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+
+The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``
+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 ``FILESPATH`` as described above, you must place the files in
+your layer in the following area:
+::
+
+ your-layer/recipes-kernel/linux/linux-yocto/
+
+.. note::
+
+ If you are working on a new machine Board Support Package (BSP), be
+ sure to refer to the
+ Yocto Project Board Support Package (BSP) Developer's Guide
+ .
+
+As an example, consider the following append file used by the BSPs in
+``meta-yocto-bsp``:
+::
+
+ meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend
+
+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 ``meta-yocto-bsp`` layer upstream.
+::
+
+ 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"
+
+This append file
+contains statements used to support several BSPs that ship with the
+Yocto Project. The file defines machines using the
+:term:`COMPATIBLE_MACHINE`
+variable and uses the
+:term:`KMACHINE` 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 :term:`KBRANCH` variable to
+ensure the build process uses the appropriate kernel branch.
+
+Although this particular example does not use it, the
+:term:`KERNEL_FEATURES`
+variable could be used to enable features specific to the kernel. The
+append file points to specific commits in the
+:term:`Source Directory` Git repository and
+the ``meta`` Git repository branches to identify the exact kernel needed
+to build the BSP.
+
+One thing missing in this particular BSP, which you will typically need
+when developing a BSP, is the kernel configuration file (``.config``)
+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 :term:`SRC_URI` statement in
+the append file.
+
+For example, suppose you had some configuration options in a file called
+``network_configs.cfg``. You can place that file inside a directory
+named ``linux-yocto`` and then add a ``SRC_URI`` 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.
+::
+
+ SRC_URI += "file://network_configs.cfg"
+
+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 ``SRC_URI`` statement like
+the following in your append file:
+::
+
+ SRC_URI += "file://myconfig.cfg \
+ file://eth.cfg \
+ file://gfx.cfg"
+
+Another variable you can use in your kernel recipe append file is the
+:term:`FILESEXTRAPATHS`
+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.
+
+.. note::
+
+ 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 ``meta`` 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 ``meta`` branch for your BSP. The configuration
+ options will likely end up in that location anyway if the BSP gets
+ added to the Yocto Project.
+
+ In general, however, the Yocto Project maintainers take care of
+ moving the ``SRC_URI``-specified configuration options to the
+ kernel's ``meta`` 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.
+
+Applying Patches
+----------------
+
+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
+:term:`FILESEXTRAPATHS` in
+your ``.bbappend`` file as described in the previous section, and then
+reference them in :term:`SRC_URI`
+statements.
+
+For example, you can apply a three-patch series by adding the following
+lines to your linux-yocto ``.bbappend`` file in your layer:
+::
+
+ SRC_URI += "file://0001-first-change.patch"
+ SRC_URI += "file://0002-second-change.patch"
+ SRC_URI += "file://0003-third-change.patch"
+
+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.
+
+For a detailed example showing how to patch the kernel using
+``devtool``, see the
+":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`"
+and
+":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`"
+sections.
+
+Changing the Configuration
+--------------------------
+
+You can make wholesale or incremental changes to the final ``.config``
+file used for the eventual Linux kernel configuration by including a
+``defconfig`` file and by specifying configuration fragments in the
+:term:`SRC_URI` to be applied to that
+file.
+
+If you have a complete, working Linux kernel ``.config`` file you want
+to use for the configuration, as before, copy that file to the
+appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux``
+directory, and rename the copied file to "defconfig". Then, add the
+following lines to the linux-yocto ``.bbappend`` file in your layer:
+::
+
+ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+ SRC_URI += "file://defconfig"
+
+The ``SRC_URI`` tells the build system how to search
+for the file, while the
+:term:`FILESEXTRAPATHS`
+extends the :term:`FILESPATH`
+variable (search directories) to include the ``${PN}`` directory you
+created to hold the configuration changes.
+
+.. note::
+
+ The build system applies the configurations from the
+ defconfig
+ file before applying any subsequent configuration fragments. The
+ final kernel configuration is a combination of the configurations in
+ the
+ defconfig
+ 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.
+
+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 ``8250.cfg`` in the ``${PN}`` directory
+with the following content (without indentation):
+::
+
+ 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
+
+Next, include this
+configuration fragment and extend the ``FILESPATH`` variable in your
+``.bbappend`` file:
+::
+
+ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+ SRC_URI += "file://8250.cfg"
+
+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.
+
+For a detailed example showing how to configure the kernel, see the
+"`Configuring the Kernel <#configuring-the-kernel>`__" section.
+
+Using an "In-Tree" ``defconfig`` File
+--------------------------------------
+
+It might be desirable to have kernel configuration fragment support
+through a ``defconfig`` file that is pulled from the kernel source tree
+for the configured machine. By default, the OpenEmbedded build system
+looks for ``defconfig`` files in the layer used for Metadata, which is
+"out-of-tree", and then configures them using the following:
+::
+
+ SRC_URI += "file://defconfig"
+
+If you do not want to maintain copies of
+``defconfig`` 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
+:term:`SRC_URI` through, for example,
+append files, you can direct the OpenEmbedded build system to use a
+``defconfig`` file that is "in-tree".
+
+To specify an "in-tree" ``defconfig`` file, use the following statement
+form:
+::
+
+ KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file
+
+Here is an example
+that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2"
+and provides the path to the "in-tree" ``defconfig`` file to be used for
+a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset:
+::
+
+ KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig"
+
+Aside from modifying your kernel recipe and providing your own
+``defconfig`` file, you need to be sure no files or statements set
+``SRC_URI`` to use a ``defconfig`` other than your "in-tree" file (e.g.
+a kernel's ``linux-``\ machine\ ``.inc`` file). In other words, if the
+build system detects a statement that identifies an "out-of-tree"
+``defconfig`` file, that statement will override your
+``KBUILD_DEFCONFIG`` variable.
+
+See the
+:term:`KBUILD_DEFCONFIG`
+variable description for more information.
+
+Using ``devtool`` to Patch the Kernel
+=====================================
+
+The steps in this procedure show you how you can patch the kernel using
+the extensible SDK and ``devtool``.
+
+.. note::
+
+ Before attempting this procedure, be sure you have performed the
+ steps to get ready for updating the kernel as described in the "
+ Getting Ready to Develop Using
+ devtool
+ " section.
+
+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.
+
+This example creates a simple patch by adding some QEMU emulator console
+output at boot time through ``printk`` statements in the kernel's
+``calibrate.c`` 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 ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devtool\`\``" Section.
+
+1. *Check Out the Kernel Source Files:* First you must use ``devtool``
+ 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
+ step
+ in the "
+ Getting Ready to Develop Using
+ devtool
+ " section for more information.
+
+ Use the following ``devtool`` command to check out the code:
+ ::
+
+ $ devtool modify linux-yocto
+
+ .. note::
+
+ During the checkout operation, a bug exists that could cause
+ errors such as the following to appear:
+ ::
+
+ ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
+ be3a89ce7c47178880ba7bf6293d7404 for
+ /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
+
+
+ You can safely ignore these messages. The source code is correctly
+ checked out.
+
+2. *Edit the Source Files* Follow these steps to make some simple
+ changes to the source files:
+
+ 1. *Change the working directory*: In the previous step, the output
+ noted where you can find the source files (e.g.
+ ``~/poky_sdk/workspace/sources/linux-yocto``). Change to where the
+ kernel source code is before making your edits to the
+ ``calibrate.c`` file:
+ ::
+
+ $ cd ~/poky_sdk/workspace/sources/linux-yocto
+
+ 2. *Edit the source file*: Edit the ``init/calibrate.c`` file to have
+ the following changes:
+ ::
+
+ 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)) {
+ .
+ .
+ .
+
+3. *Build the Updated Kernel Source:* To build the updated kernel
+ source, use ``devtool``:
+ ::
+
+ $ devtool build linux-yocto
+
+4. *Create the Image With the New Kernel:* Use the
+ ``devtool build-image`` 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
+ TipsAndTricks/KernelDevelopmentWithEsdk
+ Wiki Page.
+
+ ::
+
+ $ cd ~
+ $ devtool build-image core-image-minimal
+
+5. *Test the New Image:* For this example, you can run the new image
+ using QEMU to verify your changes:
+
+ 1. *Boot the image*: Boot the modified image in the QEMU emulator
+ using this command:
+ ::
+
+ $ runqemu qemux86
+
+ 2. *Verify the changes*: Log into the machine using ``root`` with no
+ password and then use the following shell command to scroll
+ through the console's boot output.
+ ::
+
+ # dmesg | less
+
+ You should see
+ the results of your ``printk`` statements as part of the output
+ when you scroll down the console window.
+
+6. *Stage and commit your changes*: Within your eSDK terminal, change
+ your working directory to where you modified the ``calibrate.c`` file
+ and use these Git commands to stage and commit your changes:
+ ::
+
+ $ cd ~/poky_sdk/workspace/sources/linux-yocto
+ $ git status
+ $ git add init/calibrate.c
+ $ git commit -m "calibrate: Add printk example"
+
+7. *Export the Patches and Create an Append File:* To export your
+ commits as patches and create a ``.bbappend`` file, use the following
+ command in the terminal used to work with the extensible SDK. This
+ example uses the previously established layer named ``meta-mylayer``.
+
+ .. note::
+
+ See Step 3 of the "
+ Getting Ready to Develop Using devtool
+ " section for information on setting up this layer.
+
+ $ devtool finish linux-yocto ~/meta-mylayer
+
+ Once the command
+ finishes, the patches and the ``.bbappend`` file are located in the
+ ``~/meta-mylayer/recipes-kernel/linux`` directory.
+
+8. *Build the Image With Your Modified Kernel:* You can now build an
+ image that includes your kernel patches. Execute the following
+ command from your
+ :term:`Build Directory` in the terminal
+ set up to run BitBake:
+ ::
+
+ $ cd ~/poky/build
+ $ bitbake core-image-minimal
+
+Using Traditional Kernel Development to Patch the Kernel
+========================================================
+
+The steps in this procedure show you how you can patch the kernel using
+traditional kernel development (i.e. not using ``devtool`` and the
+extensible SDK as described in the
+":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`"
+section).
+
+.. note::
+
+ Before attempting this procedure, be sure you have performed the
+ steps to get ready for updating the kernel as described in the "
+ Getting Ready for Traditional Kernel Development
+ " section.
+
+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.
+
+The example in this section creates a simple patch by adding some QEMU
+emulator console output at boot time through ``printk`` statements in
+the kernel's ``calibrate.c`` 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 "`Getting Ready for Traditional Kernel
+Development <#getting-ready-for-traditional-kernel-development>`__"
+Section.
+
+1. *Edit the Source Files* 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 "`Getting Ready for
+ Traditional Kernel
+ Development <#getting-ready-for-traditional-kernel-development>`__"
+ section, use the following commands to edit the ``calibrate.c`` file:
+
+ 1. *Change the working directory*: 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
+ ``calibrate.c`` file:
+ ::
+
+ $ cd ~/linux-yocto-4.12/init
+
+ 2. *Edit the source file*: Edit the ``calibrate.c`` file to have the
+ following changes:
+ ::
+
+ 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)) {
+ .
+ .
+ .
+
+2. *Stage and Commit Your Changes:* Use standard Git commands to stage
+ and commit the changes you just made:
+ ::
+
+ $ git add calibrate.c
+ $ git commit -m "calibrate.c - Added some printk statements"
+
+ If you do not
+ stage and commit your changes, the OpenEmbedded Build System will not
+ pick up the changes.
+
+3. *Update Your local.conf File to Point to Your Source Files:* In
+ addition to your ``local.conf`` file specifying to use
+ "kernel-modules" and the "qemux86" machine, it must also point to the
+ updated kernel source files. Add
+ :term:`SRC_URI` and
+ :term:`SRCREV` statements similar
+ to the following to your ``local.conf``:
+ ::
+
+ $ cd ~/poky/build/conf
+
+ Add the following to the ``local.conf``:
+ ::
+
+ SRC_URI_pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \
+ git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
+ SRCREV_meta_qemux86 = "${AUTOREV}"
+ SRCREV_machine_qemux86 = "${AUTOREV}"
+
+ .. note::
+
+ Be sure to replace
+ path-to
+ 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
+ standard/base
+ and the machine is "qemux86".
+
+4. *Build the Image:* With the source modified, your changes staged and
+ committed, and the ``local.conf`` file pointing to the kernel files,
+ you can now use BitBake to build the image:
+ ::
+
+ $ cd ~/poky/build
+ $ bitbake core-image-minimal
+
+5. *Boot the image*: Boot the modified image in the QEMU emulator using
+ this command. When prompted to login to the QEMU console, use "root"
+ with no password:
+ ::
+
+ $ cd ~/poky/build
+ $ runqemu qemux86
+
+6. *Look for Your Changes:* As QEMU booted, you might have seen your
+ changes rapidly scroll by. If not, use these commands to see your
+ changes:
+ ::
+
+ # dmesg | less
+
+ You should see the results of your
+ ``printk`` statements as part of the output when you scroll down the
+ console window.
+
+7. *Generate the Patch File:* Once you are sure that your patch works
+ correctly, you can generate a ``*.patch`` file in the kernel source
+ repository:
+ ::
+
+ $ cd ~/linux-yocto-4.12/init
+ $ git format-patch -1
+ 0001-calibrate.c-Added-some-printk-statements.patch
+
+8. *Move the Patch File to Your Layer:* 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 ``meta-mylayer``. For this example,
+ the layer created earlier is located in your home directory as
+ ``meta-mylayer``. When the layer was created using the
+ ``yocto-create`` 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:
+ ::
+
+ $ cd ~/meta-mylayer
+ $ mkdir recipes-kernel
+ $ mkdir recipes-kernel/linux
+ $ mkdir recipes-kernel/linux/linux-yocto
+
+ Once you have created this
+ hierarchy in your layer, you can move the patch file using the
+ following command:
+ ::
+
+ $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto
+
+9. *Create the Append File:* Finally, you need to create the
+ ``linux-yocto_4.12.bbappend`` file and insert statements that allow
+ the OpenEmbedded build system to find the patch. The append file
+ needs to be in your layer's ``recipes-kernel/linux`` directory and it
+ must be named ``linux-yocto_4.12.bbappend`` and have the following
+ contents:
+ ::
+
+ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+ SRC_URI_append = "file://0001-calibrate.c-Added-some-printk-statements.patch"
+
+ The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
+ enable the OpenEmbedded build system to find the patch file.
+
+ For more information on append files and patches, see the "`Creating
+ the Append File <#creating-the-append-file>`__" and "`Applying
+ Patches <#applying-patches>`__" sections. You can also see the
+ ":ref:`dev-manual/dev-manual-common-tasks:using .bbappend files in your layer`"
+ section in the Yocto Project Development Tasks Manual.
+
+ .. note::
+
+ To build
+ core-image-minimal
+ again and see the effects of your patch, you can essentially
+ eliminate the temporary source files saved in
+ poky/build/tmp/work/...
+ and residual effects of the build by entering the following
+ sequence of commands:
+ ::
+
+ $ cd ~/poky/build
+ $ bitbake -c cleanall yocto-linux
+ $ bitbake core-image-minimal -c cleanall
+ $ bitbake core-image-minimal
+ $ runqemu qemux86
+
+
+Configuring the Kernel
+======================
+
+Configuring the Yocto Project kernel consists of making sure the
+``.config`` file has all the right information in it for the image you
+are building. You can use the ``menuconfig`` tool and configuration
+fragments to make sure your ``.config`` file is just how you need it.
+You can also save known configurations in a ``defconfig`` file that the
+build system can use for kernel configuration.
+
+This section describes how to use ``menuconfig``, create and use
+configuration fragments, and how to interactively modify your
+``.config`` file to create the leanest kernel configuration file
+possible.
+
+For more information on kernel configuration, see the "`Changing the
+Configuration <#changing-the-configuration>`__" section.
+
+Using ``menuconfig``
+---------------------
+
+The easiest way to define kernel configurations is to set them through
+the ``menuconfig`` tool. This tool provides an interactive method with
+which to set kernel configurations. For general information on
+``menuconfig``, see http://en.wikipedia.org/wiki/Menuconfig.
+
+To use the ``menuconfig`` tool in the Yocto Project development
+environment, you must do the following:
+
+- Because you launch ``menuconfig`` using BitBake, you must be sure to
+ set up your environment by running the
+ :ref:`structure-core-script` script found in
+ the :term:`Build Directory`.
+
+- You must be sure of the state of your build's configuration in the
+ :term:`Source Directory`.
+
+- Your build host must have the following two packages installed:
+ ::
+
+ libncurses5-dev
+ libtinfo-dev
+
+The following commands initialize the BitBake environment, run the
+:ref:`ref-tasks-kernel_configme`
+task, and launch ``menuconfig``. These commands assume the Source
+Directory's top-level folder is ``~/poky``:
+::
+
+ $ cd poky
+ $ source oe-init-build-env
+ $ bitbake linux-yocto -c kernel_configme -f
+ $ bitbake linux-yocto -c menuconfig
+
+Once ``menuconfig`` 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
+``.config`` configuration file.
+
+.. note::
+
+ You can use the entire
+ .config
+ file as the
+ defconfig
+ file. For information on
+ defconfig
+ files, see the "
+ Changing the Configuration
+ ", "
+ Using an In-Tree
+ defconfig
+ File
+ , and "
+ Creating a
+ defconfig
+ File
+ " sections.
+
+Consider an example that configures the "CONFIG_SMP" setting for the
+``linux-yocto-4.12`` kernel.
+
+.. note::
+
+ The OpenEmbedded build system recognizes this kernel as
+ linux-yocto
+ through Metadata (e.g.
+ PREFERRED_VERSION
+ \_linux-yocto ?= "12.4%"
+ ).
+
+Once ``menuconfig`` 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.
+
+Saving the selections updates the ``.config`` 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 ``tmp/work/``. The actual ``.config`` is located in the
+area where the specific kernel is built. For example, if you were
+building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel
+and you were building a QEMU image targeted for ``x86`` architecture,
+the ``.config`` file would be:
+::
+
+ poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
+ ...967-r0/linux-qemux86-standard-build/.config
+
+.. 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.
+
+Within the ``.config`` file, you can see the kernel settings. For
+example, the following entry shows that symmetric multi-processor
+support is not set:
+::
+
+ # CONFIG_SMP is not set
+
+A good method to isolate changed configurations is to use a combination
+of the ``menuconfig`` tool and simple shell commands. Before changing
+configurations with ``menuconfig``, copy the existing ``.config`` and
+rename it to something else, use ``menuconfig`` 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
+ .config
+ file and do not just rename it. The build system needs an existing
+ .config
+ file from which to work.
+
+Creating a ``defconfig`` File
+------------------------------
+
+A ``defconfig`` file in the context of the Yocto Project is often a
+``.config`` file that is copied from a build or a ``defconfig`` taken
+from the kernel tree and moved into recipe space. You can use a
+``defconfig`` file to retain a known set of kernel configurations from
+which the OpenEmbedded build system can draw to create the final
+``.config`` file.
+
+.. note::
+
+ Out-of-the-box, the Yocto Project never ships a
+ defconfig
+ or
+ .config
+ file. The OpenEmbedded build system creates the final
+ .config
+ file used to configure the kernel.
+
+To create a ``defconfig``, start with a complete, working Linux kernel
+``.config`` file. Copy that file to the appropriate
+``${``\ :term:`PN`\ ``}`` directory in
+your layer's ``recipes-kernel/linux`` directory, and rename the copied
+file to "defconfig" (e.g.
+``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then,
+add the following lines to the linux-yocto ``.bbappend`` file in your
+layer:
+::
+
+ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+ SRC_URI += "file://defconfig"
+
+The :term:`SRC_URI` tells the build system how to search for the file, while the
+:term:`FILESEXTRAPATHS` extends the :term:`FILESPATH`
+variable (search directories) to include the ``${PN}`` directory you
+created to hold the configuration changes.
+
+.. note::
+
+ The build system applies the configurations from the
+ defconfig
+ file before applying any subsequent configuration fragments. The
+ final kernel configuration is a combination of the configurations in
+ the
+ defconfig
+ 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.
+
+For more information on configuring the kernel, see the "`Changing the
+Configuration <#changing-the-configuration>`__" section.
+
+.. _creating-config-fragments:
+
+Creating Configuration Fragments
+--------------------------------
+
+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 ``defconfig`` file. Thus, the final kernel
+configuration is a combination of the configurations in the
+``defconfig`` file and then any configuration fragments you provide. The
+build system applies fragments on top of and after applying the existing
+defconfig file configurations.
+
+Syntactically, the configuration statement is identical to what would
+appear in the ``.config`` file, which is in the :term:`Build Directory`.
+
+.. note::
+
+ For more information about where the
+ .config
+ file is located, see the example in the
+ ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``"
+ section.
+
+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 ``my_smp.cfg`` that enables
+multi-processor support within the kernel:
+::
+
+ $ echo "CONFIG_SMP=y" >> my_smp.cfg
+
+.. note::
+
+ All configuration fragment files must use the
+ .cfg
+ extension in order for the OpenEmbedded build system to recognize
+ them as a configuration fragment.
+
+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 ``menuconfig`` tool.
+
+To create a configuration fragment using this method, follow these
+steps:
+
+1. *Complete a Build Through Kernel Configuration:* Complete a build at
+ least through the kernel configuration task as follows:
+ ::
+
+ $ bitbake linux-yocto -c kernel_configme -f
+
+ This step ensures that you create a
+ ``.config`` 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 ``menuconfig``.
+
+2. *Launch menuconfig:* Run the ``menuconfig`` command:
+ ::
+
+ $ bitbake linux-yocto -c menuconfig
+
+3. *Create the Configuration Fragment:* Run the ``diffconfig`` command
+ to prepare a configuration fragment. The resulting file
+ ``fragment.cfg`` is placed in the
+ ``${``\ :term:`WORKDIR`\ ``}``
+ directory:
+ ::
+
+ $ bitbake linux-yocto -c diffconfig
+
+The ``diffconfig`` command creates a file that is a list of Linux kernel
+``CONFIG_`` assignments. See the "`Changing the
+Configuration <#changing-the-configuration>`__" 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 "
+ BSP Descriptions
+ " section for more information.
+
+Where do you put your configuration fragment files? You can place these
+files in an area pointed to by
+:term:`SRC_URI` as directed by your
+``bblayers.conf`` 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 ``myconfig.cfg``. If you put that file inside a
+directory named ``linux-yocto`` 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:
+::
+
+ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+ SRC_URI += "file://myconfig.cfg"
+
+As mentioned earlier, you can group related configurations into multiple
+files and name them all in the ``SRC_URI`` 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
+``SRC_URI`` statement like the following in your append file:
+::
+
+ SRC_URI += "file://myconfig.cfg \
+ file://eth.cfg \
+ file://gfx.cfg"
+
+Validating Configuration
+------------------------
+
+You can use the
+:ref:`ref-tasks-kernel_configcheck`
+task to provide configuration validation:
+::
+
+ $ bitbake linux-yocto -c kernel_configcheck -f
+
+Running this task produces warnings for when a
+requested configuration does not appear in the final ``.config`` file or
+when you override a policy configuration in a hardware configuration
+fragment.
+
+In order to run this task, you must have an existing ``.config`` file.
+See the ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``" section for
+information on how to create a configuration file.
+
+Following is sample output from the ``do_kernel_configcheck`` task:
+::
+
+ 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.
+
+.. note::
+
+ The previous output example has artificial line breaks to make it
+ more readable.
+
+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
+:ref:`ref-tasks-kernel_configme`
+and
+:ref:`ref-tasks-kernel_configcheck`
+tasks until they produce no warnings.
+
+For more information on how to use the ``menuconfig`` tool, see the
+:ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\`` section.
+
+Fine-Tuning the Kernel Configuration File
+-----------------------------------------
+
+You can make sure the ``.config`` 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.
+
+As part of the kernel build process, the ``do_kernel_configcheck`` task
+runs. This task validates the kernel configuration by checking the final
+``.config`` file against the input files. During the check, the task
+produces warning messages for the following issues:
+
+- Requested options that did not make the final ``.config`` file.
+
+- Configuration items that appear twice in the same configuration
+ fragment.
+
+- Configuration items tagged as "required" that were overridden.
+
+- A board overrides a non-board specific option.
+
+- Listed options not valid for the kernel being processed. In other
+ words, the option does not appear anywhere.
+
+.. note::
+
+ The
+ do_kernel_configcheck
+ task can also optionally report if an option is overridden during
+ processing.
+
+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.
+
+To streamline the configuration, do the following:
+
+1. *Use a Working Configuration:* Start with a full configuration that
+ you know works. Be sure the configuration builds and boots
+ successfully. Use this configuration file as your baseline.
+
+2. *Run Configure and Check Tasks:* Separately run the
+ ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks:
+ ::
+
+ $ bitbake linux-yocto -c kernel_configme -f
+ $ bitbake linux-yocto -c kernel_configcheck -f
+
+3. *Process the Results:* Take the resulting list of files from the
+ ``do_kernel_configcheck`` task warnings and do the following:
+
+ - Drop values that are redefined in the fragment but do not change
+ the final ``.config`` file.
+
+ - Analyze and potentially drop values from the ``.config`` file that
+ override required configurations.
+
+ - Analyze and potentially remove non-board specific options.
+
+ - Remove repeated and invalid options.
+
+4. *Re-Run Configure and Check Tasks:* After you have worked through the
+ output of the kernel configuration audit, you can re-run the
+ ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks to see the
+ results of your changes. If you have more issues, you can deal with
+ them as described in the previous step.
+
+Iteratively working through steps two through four eventually yields a
+minimal, streamlined configuration file. Once you have the best
+``.config``, you can build the Linux Yocto kernel.
+
+Expanding Variables
+===================
+
+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 ``bitbake -e`` command. The output is long and is more
+easily managed in a text file, which allows for easy searches:
+::
+
+ $ bitbake -e virtual/kernel > some_text_file
+
+Within the text file, you can see
+exactly how each variable is expanded and used by the OpenEmbedded build
+system.
+
+Working with a "Dirty" Kernel Version String
+============================================
+
+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:
+
+1. *Discover the Uncommitted Changes:* 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:
+ ::
+
+ $ git status
+
+2. *Commit the Changes:* You should commit those changes to the kernel
+ source tree regardless of whether or not you will save, export, or
+ use the changes:
+ ::
+
+ $ git add
+ $ git commit -s -a -m "getting rid of -dirty"
+
+3. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the
+ kernel.
+
+ 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 ``devtool``, see the
+ ":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`"
+ section. For
+ information on building the kernel image when using Bitbake, see the
+ "`Using Traditional Kernel Development to Patch the
+ Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__"
+ section.
+
+Working With Your Own Sources
+=============================
+
+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 :term:`Metadata` 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.
+
+To help you use your own sources, the Yocto Project provides a
+linux-yocto custom recipe (``linux-yocto-custom.bb``) that uses
+``kernel.org`` sources and the Yocto Project Linux kernel tools for
+managing kernel Metadata. You can find this recipe in the ``poky`` Git
+repository of the Yocto Project :yocto_git:`Source Repository <>`
+at:
+::
+
+ poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
+
+Here are some basic steps you can use to work with your own sources:
+
+1. *Create a Copy of the Kernel Recipe:* Copy the
+ ``linux-yocto-custom.bb`` 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. ``linux-yocto-myproject_4.12.bb``,
+ where "4.12" is the base version of the Linux kernel with which you
+ would be working).
+
+2. *Create a Directory for Your Patches:* In the same directory inside
+ your layer, create a matching directory to store your patches and
+ configuration files (e.g. ``linux-yocto-myproject``).
+
+3. *Ensure You Have Configurations:* Make sure you have either a
+ ``defconfig`` file or configuration fragment files in your layer.
+ When you use the ``linux-yocto-custom.bb`` recipe, you must specify a
+ configuration. If you do not have a ``defconfig`` file, you can run
+ the following:
+ ::
+
+ $ make defconfig
+
+ After running the command, copy the
+ resulting ``.config`` file to the ``files`` directory in your layer
+ as "defconfig" and then add it to the
+ :term:`SRC_URI` variable in the
+ recipe.
+
+ Running the ``make defconfig`` 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.
+
+ To use non-x86 ``defconfig`` files, you need to be more specific and
+ find one that matches your board (i.e. for arm, you look in
+ ``arch/arm/configs`` and use the one that is the best starting point
+ for your board).
+
+4. *Edit the Recipe:* Edit the following variables in your recipe as
+ appropriate for your project:
+
+ - :term:`SRC_URI`: The
+ ``SRC_URI`` should specify a Git repository that uses one of the
+ supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``,
+ and so forth). The ``SRC_URI`` variable should also specify either
+ a ``defconfig`` file or some configuration fragment files. The
+ skeleton recipe provides an example ``SRC_URI`` as a syntax
+ reference.
+
+ - :term:`LINUX_VERSION`:
+ The Linux kernel version you are using (e.g. "4.12").
+
+ - :term:`LINUX_VERSION_EXTENSION`:
+ The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the
+ resulting kernel and visible through the ``uname`` command.
+
+ - :term:`SRCREV`: The commit ID
+ from which you want to build.
+
+ - :term:`PR`: 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.
+
+ - :term:`PV`: The default ``PV``
+ assignment is typically adequate. It combines the
+ ``LINUX_VERSION`` with the Source Control Manager (SCM) revision
+ as derived from the :term:`SRCPV`
+ variable. The combined results are a string with the following
+ form:
+ 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
+ While lengthy, the extra verbosity in ``PV`` helps ensure you are
+ using the exact sources from which you intend to build.
+
+ - :term:`COMPATIBLE_MACHINE`:
+ 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 ``qemux86`` and ``qemux86-64`` machines, use the
+ following form: COMPATIBLE_MACHINE = "qemux86|qemux86-64"
+
+5. *Customize Your Recipe as Needed:* Provide further customizations to
+ your recipe as needed just as you would customize an existing
+ linux-yocto recipe. See the "`Modifying an Existing
+ Recipe <#modifying-an-existing-recipe>`__" section for information.
+
+Working with Out-of-Tree Modules
+================================
+
+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.
+
+Building Out-of-Tree Modules on the Target
+------------------------------------------
+
+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.
+
+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 ``kernel-dev`` package is installed by default on
+all ``*.sdk`` images and the ``kernel-devsrc`` package is installed on
+many of the ``*.sdk`` 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.
+
+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 ``/usr/src/kernel``
+directory. Next, ``make`` the scripts:
+::
+
+ # cd /usr/src/kernel
+ # make scripts
+
+Because all SDK image recipes include ``dev-pkgs``, the
+``kernel-dev`` packages will be installed as part of the SDK image and
+the ``kernel-devsrc`` 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.
+
+Incorporating Out-of-Tree Modules
+---------------------------------
+
+While it is always preferable to work with sources integrated into the
+Linux kernel sources, if you need an external kernel module, the
+``hello-mod.bb`` recipe is available as a template from which you can
+create your own out-of-tree Linux kernel module recipe.
+
+This template recipe is located in the ``poky`` Git repository of the
+Yocto Project :yocto_git:`Source Repository <>` at:
+::
+
+ poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
+
+To get started, copy this recipe to your layer and give it a meaningful
+name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new
+directory named ``files`` 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:
+
+- :term:`DESCRIPTION`
+
+- :term:`LICENSE* <LICENSE>`
+
+- :term:`SRC_URI`
+
+- :term:`PV`
+
+Depending on the build system used by the module sources, you might need
+to make some adjustments. For example, a typical module ``Makefile``
+looks much like the one provided with the ``hello-mod`` template:
+::
+
+ obj-m := hello.o
+
+ SRC := $(shell pwd)
+
+ all:
+ $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
+
+ modules_install:
+ $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
+ ...
+
+The important point to note here is the :term:`KERNEL_SRC` variable. The
+:ref:`module <ref-classes-module>` class sets this variable and the
+:term:`KERNEL_PATH` variable to
+``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build
+information to build modules. If your module ``Makefile`` uses a
+different variable, you might want to override the
+:ref:`ref-tasks-compile` step, or
+create a patch to the ``Makefile`` to work with the more typical
+``KERNEL_SRC`` or ``KERNEL_PATH`` variables.
+
+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:
+
+- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
+
+- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
+
+- :term:`MACHINE_EXTRA_RDEPENDS`
+
+- :term:`MACHINE_EXTRA_RRECOMMENDS`
+
+Modules are often not required for boot and can be excluded from certain
+build configurations. The following allows for the most flexibility:
+::
+
+ MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
+
+The value is
+derived by appending the module filename without the ``.ko`` extension
+to the string "kernel-module-".
+
+Because the variable is
+:term:`RRECOMMENDS` and not a
+:term:`RDEPENDS` variable, the build
+will not fail if this module is not available to include in the image.
+
+Inspecting Changes and Commits
+==============================
+
+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.
+
+What Changed in a Kernel?
+-------------------------
+
+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,
+ kernel.org
+ 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
+ .
+
+To see a full range of the changes, use the ``git whatchanged`` command
+and specify a commit range for the branch (commit\ ``..``\ commit).
+
+Here is an example that looks at what has changed in the ``emenlow``
+branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the
+commit associated with the ``standard/base`` branch, while the upper
+commit range is the commit associated with the ``standard/emenlow``
+branch.
+::
+
+ $ git whatchanged origin/standard/base..origin/standard/emenlow
+
+To see short, one line summaries of changes use the ``git log`` command:
+::
+
+ $ git log --oneline origin/standard/base..origin/standard/emenlow
+
+Use this command to see code differences for the changes:
+::
+
+ $ git diff origin/standard/base..origin/standard/emenlow
+
+Use this command to see the commit log messages and the text
+differences:
+::
+
+ $ git show origin/standard/base..origin/standard/emenlow
+
+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 ``Documents`` directory:
+::
+
+ $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
+
+Showing a Particular Feature or Branch Change
+---------------------------------------------
+
+Tags in the Yocto Project kernel tree divide changes for significant
+features or branches. The ``git show`` tag command shows changes based
+on a tag. Here is an example that shows ``systemtap`` changes:
+::
+
+ $ git show systemtap
+
+You can use the ``git branch --contains`` tag command to
+show the branches that contain a particular feature. This command shows
+the branches that contain the ``systemtap`` feature:
+::
+
+ $ git branch --contains systemtap
+
+Adding Recipe-Space Kernel Features
+===================================
+
+You can add kernel features in the
+`recipe-space <#recipe-space-metadata>`__ by using the
+:term:`KERNEL_FEATURES`
+variable and by specifying the feature's ``.scc`` file path in the
+:term:`SRC_URI` 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
+``SRC_URI`` statement.
+
+You add a kernel feature by providing the feature as part of the
+``KERNEL_FEATURES`` variable and by providing the path to the feature's
+``.scc`` file, which is relative to the root of the kernel Metadata. The
+OpenEmbedded build system searches all forms of kernel Metadata on the
+``SRC_URI`` 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 "`Kernel Metadata
+Location <#kernel-metadata-location>`__" section for additional
+information.
+
+When you specify the feature's ``.scc`` file on the ``SRC_URI``
+statement, the OpenEmbedded build system adds the directory of that
+``.scc`` file along with all its subdirectories to the kernel feature
+search path. Because subdirectories are searched, you can reference a
+single ``.scc`` file in the ``SRC_URI`` statement to reference multiple
+kernel features.
+
+Consider the following example that adds the "test.scc" feature to the
+build.
+
+1. *Create the Feature File:* Create a ``.scc`` file and locate it just
+ as you would any other patch file, ``.cfg`` file, or fetcher item you
+ specify in the ``SRC_URI`` statement.
+
+ .. note::
+
+ - You must add the directory of the ``.scc`` file to the
+ fetcher's search path in the same manner as you would add a
+ ``.patch`` file.
+
+ - You can create additional ``.scc`` files beneath the directory
+ that contains the file you are adding. All subdirectories are
+ searched during the build as potential feature directories.
+
+ Continuing with the example, suppose the "test.scc" feature you are
+ adding has a ``test.scc`` file in the following directory:
+ ::
+
+ my_recipe
+ |
+ +-linux-yocto
+ |
+ +-test.cfg
+ +-test.scc
+
+ In this example, the
+ ``linux-yocto`` directory has both the feature ``test.scc`` file and
+ a similarly named configuration fragment file ``test.cfg``.
+
+2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
+ recipe's ``SRC_URI`` statement:
+ ::
+
+ SRC_URI_append = " file://test.scc"
+
+ The leading space before the path is important as the path is
+ appended to the existing path.
+
+3. *Specify the Feature as a Kernel Feature:* Use the
+ ``KERNEL_FEATURES`` statement to specify the feature as a kernel
+ feature:
+ ::
+
+ KERNEL_FEATURES_append = " test.scc"
+
+ 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
+ test.scc
+ file.