diff options
| author | Andrew Geissler <geissonator@yahoo.com> | 2020-12-13 17:44:15 +0300 |
|---|---|---|
| committer | Andrew Geissler <geissonator@yahoo.com> | 2020-12-15 21:53:47 +0300 |
| commit | 09209eec235a35b7089db987561c12e9bd023237 (patch) | |
| tree | 2d3580484ffacafe11b72e9abaab50a428dd617d /poky/documentation/kernel-dev/kernel-dev-common.rst | |
| parent | f7ba29eda266e04f867e4338b6b8b10c1969419c (diff) | |
| download | openbmc-09209eec235a35b7089db987561c12e9bd023237.tar.xz | |
poky: subtree update:0ac99625bf..796be0593a
Alexander Kanavin (31):
netbase: upgrade 6.1 -> 6.2
meson: upgrade 0.55.1 -> 0.56.0
vulkan-samples: update to latest revision
libcap: update 2.44 -> 2.45
bind: upgrade 9.16.7 -> 9.16.9
quota: upgrade 4.05 -> 4.06
pango: upgrade 1.46.2 -> 1.48.0
elfutils: upgrade 0.181 -> 0.182
ifupdown: upgrade 0.8.35 -> 0.8.36
createrepo-c: upgrade 0.16.1 -> 0.16.2
acpica: upgrade 20200925 -> 20201113
grep: upgrade 3.5 -> 3.6
man-pages: upgrade 5.08 -> 5.09
stress-ng: upgrade 0.11.23 -> 0.11.24
libhandy: upgrade 1.0.1 -> 1.0.2
piglit: upgrade to latest revision
xkbcomp: upgrade 1.4.3 -> 1.4.4
lz4: upgrade 1.9.2 -> 1.9.3
bison: upgrade 3.7.3 -> 3.7.4
python3-setuptools-scm: fix upstream version check
cantarell-fonts: update 0.0.25 -> 0.201
meta/lib/oe/reproducible.py: gitsm:// works just as fine as git:// for timestamps
llvm: fix reproducibility
ruby: fix reproducibility
webkitgtk: fix reproducibility
ffmpeg: fix reproducibility
piglit: fix reproducibility
serf: do not install the static library
llvm: sort the lists in generated source reproducibibly
kea: fix reproducibility
poky.conf: do not write current date into distro version, use git hash instead
Andrej Valek (1):
kernel-dummy: fix executing unexpected tasks
Anuj Mittal (1):
releases.rst: add gatesgarth to current releases
Brett Warren (1):
libffi: add patch to revert clang VFP workaround
Chandana kalluri (1):
populate_sdk_ext: use SDK_CUSTOM_TEPLATECONF variable to enable custom templateconf.cfg
Changqing Li (1):
buildtools-tarball: add wic dependency into extended buildtools
Diego Sueiro (2):
modutils-initscripts: Fix modules.dep creation when USE_DEPMOD="0"
initscripts: Change execution order between checkroot and modutils
Dmitry Baryshkov (2):
linux-firmware: upgrade 20201022 -> 20201118
linux-firmware: package ath11k firmware
Fabio Berton (1):
mesa: Update 20.2.1 -> 20.2.4
Gratian Crisan (1):
kernel-module-split.bbclass: fix kernel modules getting marked as CONFFILES
Jack Mitchell (3):
Revert "connman: set service to conflict with systemd-networkd"
systemd-conf: add PACKAGECONFIG to enable/disable auto ethernet DHCP
systemd-conf: match ethernet interfaces by type rather than globbing
Joshua Watt (2):
bitbake: hashserv: client: Fix AF_UNIX path length limits
bitbake: hashserv: Fix broken AF_UNIX path length limit
Kai Kang (2):
systemd-systemctl-native: capable to call without argument
systemd.bbclass: update command to check systemctl available
Kevin Hao (1):
tune-octeontx2.inc: Add tune for Marvell OCTEON TX2 core
Li Wang (2):
qemu: CVE-2020-29129 CVE-2020-29130
qemu: CVE-2020-25624
Luca Boccassi (1):
dbus: move messagebus user to dbus-common package
Michael Halstead (1):
releases: conf: add link to 3.1.4, update to include 3.1.4
Nicolas Dechesne (19):
sphinx: add .vscode in .gitignore
{dev,kernel,sdk}-manual: replace hardcoded release version with &DISTRO;
sphinx: replace bitbake labels with references to corresponding title
brief-yoctoprojectqs: replace labels with references to section title
dev-manual: replace labels with references to section title
ref-manual: replace labels with references to section title
sdk-manual: replace labels with references to section title
overview-manual: remove unused labels
dev-manual: remove unused labels
sphinx: rename top level document in each manual
sphinx: use absolute paths for :doc: references
test-manual: remove 'test-manual' from filenames
toaster-manual: remove 'toaster-manual' from filenames
dev-manual: remove 'dev-manual' from filenames
kernel-dev: remove 'kernel-dev' from filenames
profile-manual: remove 'profile-manual' from filenames
overview-manual: remove 'overview-manual' from filenames
sdk-manual: remove 'sdk' from filenames
ref-manual: remove 'ref' from filenames
Paul Barker (5):
documentation: Simplify yocto_wiki links
documentation: Simplify yocto_git links
ref-manual: Simplify oe_git links
poky.conf: Add opensuseleap-15.2 and fedora-33 to tested distros
poky.conf: Drop fedora-30 from tested distros
Peter Kjellerstedt (2):
pseudo: Simplify pseudo_client_ignore_path_chroot()
bitbake.conf: Add all layers (from BBLAYERS) to PSEUDO_IGNORE_PATHS
Richard Purdie (8):
lz4: Use the new branch naming from upstream
Revert "bitbake.conf: Add all layers (from BBLAYERS) to PSEUDO_IGNORE_PATHS"
build-appliance-image: Update to master head revision
bitbake: Revert "fetch2: use relative symlinks for anything pulled from PREMIRRORS"
build-appliance-image: Update to master head revision
metadata_scm: Fix signature handling of METADATA_REVISION and METADATA_BRANCH
poky: Set SDK_VERSION explicitly
build-appliance-image: Update to master head revision
Ross Burton (9):
oeqa/devtool: use Yocto mirror for pv-1.5.3 tarball
image_types: remove obsolete tar comment
image_types: sort tarball file listings
package_manager/ipk: neaten OPKGLIBDIR logic
ldconfig-native: don't write auxiliary cache
package_manager/ipk: improve remove_packaging_data
oeqa/selftest/containerimage: update for improved cleanup
coreutils: add SUSE-specific issues to CVE whitelist
bitbake: msg: use safe YAML loader
Sinan Kaya (1):
poky-tiny: enable section removal
Tomasz Dziendzielski (1):
pseudo: Update to print PSEUDO_LOGFILE in abort message on path mismatches
sangeeta jain (1):
meta/lib/oeqa/manual/oe-core.json: Update test_bitbake_devshell
zangrc (3):
libinput: upgrade 1.16.3 -> 1.16.4
lighttpd: upgrade 1.4.55 -> 1.4.56
sysstat: upgrade 12.4.0 -> 12.4.1
Signed-off-by: Andrew Geissler <geissonator@yahoo.com>
Change-Id: I65f2f1c9d44433f3e62609240012c42256679b51
Diffstat (limited to 'poky/documentation/kernel-dev/kernel-dev-common.rst')
| -rw-r--r-- | poky/documentation/kernel-dev/kernel-dev-common.rst | 2029 |
1 files changed, 0 insertions, 2029 deletions
diff --git a/poky/documentation/kernel-dev/kernel-dev-common.rst b/poky/documentation/kernel-dev/kernel-dev-common.rst deleted file mode 100644 index 72d9d7879..000000000 --- a/poky/documentation/kernel-dev/kernel-dev-common.rst +++ /dev/null @@ -1,2029 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-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 - ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" and - ":ref:`dev-manual/dev-manual-start: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 - :ref:`overview-manual/overview-manual-development-environment:yocto project 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 - ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" - section in the Yocto Project Development Tasks Manual and the - ":ref:`bsp-guide/bsp: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 - ":ref:`dev-manual/dev-manual-common-tasks: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 - :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </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_NO_CAP; - $ source oe-init-build-env - - .. note:: - - The previous commands assume the - :ref:`overview-manual/overview-manual-development-environment:yocto project 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 - ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" - section in the Yocto Project Development Tasks Manual and the - ":ref:`bsp-guide/bsp: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 - ":ref:`dev-manual/dev-manual-common-tasks: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 - ":ref:`dev-manual/dev-manual-common-tasks: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.patch" - SRC_URI_append = " file://patch-file-two.patch" - SRC_URI_append = " file://patch-file-three.patch" - - 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: - -- :ref:`kernel-dev/kernel-dev-common:creating the append file` - -- :ref:`kernel-dev/kernel-dev-common:applying patches` - -- :ref:`kernel-dev/kernel-dev-common: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: - -.. code-block:: none - - 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 :doc:`../bsp-guide/bsp-guide`. - -As an example, consider the following append file used by the BSPs in -``meta-yocto-bsp``: - -.. code-block:: none - - 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 - ":ref:`kernel-dev/kernel-dev-common: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 - ":ref:`kernel-dev/kernel-dev-common: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: - - .. code-block:: none - - 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 - :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </wiki/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. - - .. code-block:: none - - # 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``. - :: - - $ devtool finish linux-yocto ~/meta-mylayer - - .. note:: - - See Step 3 of the - ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devtool\`\``" - section for information on setting up this layer. - - 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 - ":ref:`kernel-dev/kernel-dev-common: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: - - .. code-block:: none - - # 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 https://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 - ":ref:`kernel-dev/kernel-dev-common:changing the configuration`", - ":ref:`kernel-dev/kernel-dev-common:using an "in-tree" \`\`defconfig\`\` file`", - and ":ref:`kernel-dev/kernel-dev-common: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. :term:`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: - -.. code-block:: none - - 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 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 ":ref:`kernel-dev/kernel-dev-advanced: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: - -.. code-block:: none - - 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 :ref:`ref-tasks-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 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: - -.. code-block:: none - - # 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: - -.. code-block:: none - - 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 :yocto_git:`/`. - -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 -:ref:`recipe-space <kernel-dev/kernel-dev-advanced: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 -":ref:`kernel-dev/kernel-dev-advanced: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. |