From 09209eec235a35b7089db987561c12e9bd023237 Mon Sep 17 00:00:00 2001 From: Andrew Geissler Date: Sun, 13 Dec 2020 08:44:15 -0600 Subject: 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 Change-Id: I65f2f1c9d44433f3e62609240012c42256679b51 --- poky/documentation/kernel-dev/intro.rst | 180 ++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 poky/documentation/kernel-dev/intro.rst (limited to 'poky/documentation/kernel-dev/intro.rst') diff --git a/poky/documentation/kernel-dev/intro.rst b/poky/documentation/kernel-dev/intro.rst new file mode 100644 index 000000000..c95d2f7cb --- /dev/null +++ b/poky/documentation/kernel-dev/intro.rst @@ -0,0 +1,180 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +************ +Introduction +************ + +Overview +======== + +Regardless of how you intend to make use of the Yocto Project, chances +are you will work with the Linux kernel. This manual describes how to +set up your build host to support kernel development, introduces the +kernel development process, provides background information on the Yocto +Linux kernel :term:`Metadata`, describes +common tasks you can perform using the kernel tools, shows you how to +use the kernel Metadata needed to work with the kernel inside the Yocto +Project, and provides insight into how the Yocto Project team develops +and maintains Yocto Linux kernel Git repositories and Metadata. + +Each Yocto Project release has a set of Yocto Linux kernel recipes, +whose Git repositories you can view in the Yocto +:yocto_git:`Source Repositories <>` under the "Yocto Linux Kernel" +heading. New recipes for the release track the latest Linux kernel +upstream developments from https://www.kernel.org and introduce +newly-supported platforms. Previous recipes in the release are refreshed +and supported for at least one additional Yocto Project release. As they +align, these previous releases are updated to include the latest from +the Long Term Support Initiative (LTSI) project. You can learn more +about Yocto Linux kernels and LTSI in the +":ref:`kernel-dev/concepts-appx:yocto project kernel development and maintenance`" section. + +Also included is a Yocto Linux kernel development recipe +(``linux-yocto-dev.bb``) should you want to work with the very latest in +upstream Yocto Linux kernel development and kernel Metadata development. + +.. note:: + + For more on Yocto Linux kernels, see the + ":ref:`kernel-dev/concepts-appx:yocto project kernel development and maintenance`" + section. + +The Yocto Project also provides a powerful set of kernel tools for +managing Yocto Linux kernel sources and configuration data. You can use +these tools to make a single configuration change, apply multiple +patches, or work with your own kernel sources. + +In particular, the kernel tools allow you to generate configuration +fragments that specify only what you must, and nothing more. +Configuration fragments only need to contain the highest level visible +``CONFIG`` options as presented by the Yocto Linux kernel ``menuconfig`` +system. Contrast this against a complete Yocto Linux kernel ``.config`` +file, which includes all the automatically selected ``CONFIG`` options. +This efficiency reduces your maintenance effort and allows you to +further separate your configuration in ways that make sense for your +project. A common split separates policy and hardware. For example, all +your kernels might support the ``proc`` and ``sys`` filesystems, but +only specific boards require sound, USB, or specific drivers. Specifying +these configurations individually allows you to aggregate them together +as needed, but maintains them in only one place. Similar logic applies +to separating source changes. + +If you do not maintain your own kernel sources and need to make only +minimal changes to the sources, the released recipes provide a vetted +base upon which to layer your changes. Doing so allows you to benefit +from the continual kernel integration and testing performed during +development of the Yocto Project. + +If, instead, you have a very specific Linux kernel source tree and are +unable to align with one of the official Yocto Linux kernel recipes, an +alternative exists by which you can use the Yocto Project Linux kernel +tools with your own kernel sources. + +The remainder of this manual provides instructions for completing +specific Linux kernel development tasks. These instructions assume you +are comfortable working with +`BitBake `__ recipes and basic +open-source development tools. Understanding these concepts will +facilitate the process of working with the kernel recipes. If you find +you need some additional background, please be sure to review and +understand the following documentation: + +- :doc:`/brief-yoctoprojectqs/index` document. + +- :doc:`/overview-manual/index`. + +- :ref:`devtool + workflow ` + as described in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + +- The ":ref:`dev-manual/common-tasks:understanding and creating layers`" + section in the Yocto Project Development Tasks Manual. + +- The "`Kernel Modification + Workflow <#kernel-modification-workflow>`__" section. + +Kernel Modification Workflow +============================ + +Kernel modification involves changing the Yocto Project kernel, which +could involve changing configuration options as well as adding new +kernel recipes. Configuration changes can be added in the form of +configuration fragments, while recipe modification comes through the +kernel's ``recipes-kernel`` area in a kernel layer you create. + +This section presents a high-level overview of the Yocto Project kernel +modification workflow. The illustration and accompanying list provide +general information and references for further information. + +.. image:: figures/kernel-dev-flow.png + :align: center + +1. *Set up Your Host Development System to Support Development Using the + Yocto Project*: See the ":doc:`/dev-manual/start`" section in + the Yocto Project Development Tasks Manual for options on how to get + a build host ready to use the Yocto Project. + +2. *Set Up Your Host Development System for Kernel Development:* It is + recommended that you use ``devtool`` and an extensible SDK for kernel + development. Alternatively, you can use traditional kernel + development methods with the Yocto Project. Either way, there are + steps you need to take to get the development environment ready. + + Using ``devtool`` and the eSDK requires that you have a clean build + of the image and that you are set up with the appropriate eSDK. For + more information, see the + ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" + section. + + Using traditional kernel development requires that you have the + kernel source available in an isolated local Git repository. For more + information, see the + ":ref:`kernel-dev/common:getting ready for traditional kernel development`" + section. + +3. *Make Changes to the Kernel Source Code if applicable:* Modifying the + kernel does not always mean directly changing source files. However, + if you have to do this, you make the changes to the files in the + eSDK's Build Directory if you are using ``devtool``. For more + information, see the + ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" + section. + + If you are using traditional kernel development, you edit the source + files in the kernel's local Git repository. For more information, see the + ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" + section. + +4. *Make Kernel Configuration Changes if Applicable:* If your situation + calls for changing the kernel's configuration, you can use + :ref:`menuconfig `, + which allows you to + interactively develop and test the configuration changes you are + making to the kernel. Saving changes you make with ``menuconfig`` + updates the kernel's ``.config`` file. + + .. note:: + + Try to resist the temptation to directly edit an existing ``.config`` + file, which is found in the Build Directory among the source code + used for the build. Doing so, can produce unexpected results when + the OpenEmbedded build system regenerates the configuration file. + + Once you are satisfied with the configuration changes made using + ``menuconfig`` and you have saved them, you can directly compare the + resulting ``.config`` file against an existing original and gather + those changes into a + :ref:`configuration fragment file ` to be + referenced from within the kernel's ``.bbappend`` file. + + Additionally, if you are working in a BSP layer and need to modify + the BSP's kernel's configuration, you can use ``menuconfig``. + +5. *Rebuild the Kernel Image With Your Changes:* Rebuilding the kernel + image applies your changes. Depending on your target hardware, you + can verify your changes on actual hardware or perhaps QEMU. + +The remainder of this developer's guide covers common tasks typically +used during kernel development, advanced Metadata usage, and Yocto Linux +kernel maintenance concepts. -- cgit v1.2.3