diff options
| author | Richard Purdie <richard.purdie@linuxfoundation.org> | 2025-11-07 13:31:53 +0000 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2025-11-07 13:31:53 +0000 |
| commit | 8c22ff0d8b70d9b12f0487ef696a7e915b9e3173 (patch) | |
| tree | efdc32587159d0050a69009bdf2330a531727d95 /documentation/kernel-dev/intro.rst | |
| parent | d412d2747595c1cc4a5e3ca975e3adc31b2f7891 (diff) | |
| download | poky-8c22ff0d8b70d9b12f0487ef696a7e915b9e3173.tar.gz | |
The poky repository master branch is no longer being updated.
You can either:
a) switch to individual clones of bitbake, openembedded-core, meta-yocto and yocto-docs
b) use the new bitbake-setup
You can find information about either approach in our documentation:
https://docs.yoctoproject.org/
Note that "poky" the distro setting is still available in meta-yocto as
before and we continue to use and maintain that.
Long live Poky!
Some further information on the background of this change can be found
in: https://lists.openembedded.org/g/openembedded-architecture/message/2179
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev/intro.rst')
| -rw-r--r-- | documentation/kernel-dev/intro.rst | 178 |
1 files changed, 0 insertions, 178 deletions
diff --git a/documentation/kernel-dev/intro.rst b/documentation/kernel-dev/intro.rst deleted file mode 100644 index 7df342f8d5..0000000000 --- a/documentation/kernel-dev/intro.rst +++ /dev/null | |||
| @@ -1,178 +0,0 @@ | |||
| 1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
| 2 | |||
| 3 | ************ | ||
| 4 | Introduction | ||
| 5 | ************ | ||
| 6 | |||
| 7 | Overview | ||
| 8 | ======== | ||
| 9 | |||
| 10 | Regardless of how you intend to make use of the Yocto Project, chances | ||
| 11 | are you will work with the Linux kernel. This manual describes how to | ||
| 12 | set up your build host to support kernel development, introduces the | ||
| 13 | kernel development process, provides background information on the Yocto | ||
| 14 | Linux kernel :term:`Metadata`, describes | ||
| 15 | common tasks you can perform using the kernel tools, shows you how to | ||
| 16 | use the kernel Metadata needed to work with the kernel inside the Yocto | ||
| 17 | Project, and provides insight into how the Yocto Project team develops | ||
| 18 | and maintains Yocto Linux kernel Git repositories and Metadata. | ||
| 19 | |||
| 20 | Each Yocto Project release has a set of Yocto Linux kernel recipes, | ||
| 21 | whose Git repositories you can view in the Yocto | ||
| 22 | :yocto_git:`Source Repositories <>` under the "Yocto Linux Kernel" | ||
| 23 | heading. New recipes for the release track the latest Linux kernel | ||
| 24 | upstream developments from https://www.kernel.org and introduce | ||
| 25 | newly-supported platforms. Previous recipes in the release are refreshed | ||
| 26 | and supported for at least one additional Yocto Project release. As they | ||
| 27 | align, these previous releases are updated to include the latest from | ||
| 28 | the Long Term Support Initiative (LTSI) project. You can learn more | ||
| 29 | about Yocto Linux kernels and LTSI in the | ||
| 30 | ":ref:`kernel-dev/concepts-appx:yocto project kernel development and maintenance`" section. | ||
| 31 | |||
| 32 | Also included is a Yocto Linux kernel development recipe | ||
| 33 | (``linux-yocto-dev.bb``) should you want to work with the very latest in | ||
| 34 | upstream Yocto Linux kernel development and kernel Metadata development. | ||
| 35 | |||
| 36 | .. note:: | ||
| 37 | |||
| 38 | For more on Yocto Linux kernels, see the | ||
| 39 | ":ref:`kernel-dev/concepts-appx:yocto project kernel development and maintenance`" | ||
| 40 | section. | ||
| 41 | |||
| 42 | The Yocto Project also provides a powerful set of kernel tools for | ||
| 43 | managing Yocto Linux kernel sources and configuration data. You can use | ||
| 44 | these tools to make a single configuration change, apply multiple | ||
| 45 | patches, or work with your own kernel sources. | ||
| 46 | |||
| 47 | In particular, the kernel tools allow you to generate configuration | ||
| 48 | fragments that specify only what you must, and nothing more. | ||
| 49 | Configuration fragments only need to contain the highest level visible | ||
| 50 | ``CONFIG`` options as presented by the Yocto Linux kernel ``menuconfig`` | ||
| 51 | system. Contrast this against a complete Yocto Linux kernel ``.config`` | ||
| 52 | file, which includes all the automatically selected ``CONFIG`` options. | ||
| 53 | This efficiency reduces your maintenance effort and allows you to | ||
| 54 | further separate your configuration in ways that make sense for your | ||
| 55 | project. A common split separates policy and hardware. For example, all | ||
| 56 | your kernels might support the ``proc`` and ``sys`` filesystems, but | ||
| 57 | only specific boards require sound, USB, or specific drivers. Specifying | ||
| 58 | these configurations individually allows you to aggregate them together | ||
| 59 | as needed, but maintains them in only one place. Similar logic applies | ||
| 60 | to separating source changes. | ||
| 61 | |||
| 62 | If you do not maintain your own kernel sources and need to make only | ||
| 63 | minimal changes to the sources, the released recipes provide a vetted | ||
| 64 | base upon which to layer your changes. Doing so allows you to benefit | ||
| 65 | from the continual kernel integration and testing performed during | ||
| 66 | development of the Yocto Project. | ||
| 67 | |||
| 68 | If, instead, you have a very specific Linux kernel source tree and are | ||
| 69 | unable to align with one of the official Yocto Linux kernel recipes, | ||
| 70 | you have a way to use the Yocto Project Linux kernel tools with your | ||
| 71 | own kernel sources. | ||
| 72 | |||
| 73 | The remainder of this manual provides instructions for completing | ||
| 74 | specific Linux kernel development tasks. These instructions assume you | ||
| 75 | are comfortable working with :oe_wiki:`BitBake </Bitbake>` recipes and basic | ||
| 76 | open-source development tools. Understanding these concepts will | ||
| 77 | facilitate the process of working with the kernel recipes. If you find | ||
| 78 | you need some additional background, please be sure to review and | ||
| 79 | understand the following documentation: | ||
| 80 | |||
| 81 | - :doc:`/brief-yoctoprojectqs/index` document. | ||
| 82 | |||
| 83 | - :doc:`/overview-manual/index`. | ||
| 84 | |||
| 85 | - :ref:`devtool | ||
| 86 | workflow <sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow>` | ||
| 87 | as described in the Yocto Project Application Development and the | ||
| 88 | Extensible Software Development Kit (eSDK) manual. | ||
| 89 | |||
| 90 | - The ":ref:`dev-manual/layers:understanding and creating layers`" | ||
| 91 | section in the Yocto Project Development Tasks Manual. | ||
| 92 | |||
| 93 | - The ":ref:`kernel-dev/intro:kernel modification workflow`" section. | ||
| 94 | |||
| 95 | Kernel Modification Workflow | ||
| 96 | ============================ | ||
| 97 | |||
| 98 | Kernel modification involves changing the Yocto Project kernel, which | ||
| 99 | could involve changing configuration options as well as adding new | ||
| 100 | kernel recipes. Configuration changes can be added in the form of | ||
| 101 | configuration fragments, while recipe modification comes through the | ||
| 102 | kernel's ``recipes-kernel`` area in a kernel layer you create. | ||
| 103 | |||
| 104 | This section presents a high-level overview of the Yocto Project kernel | ||
| 105 | modification workflow. The illustration and accompanying list provide | ||
| 106 | general information and references for further information. | ||
| 107 | |||
| 108 | .. image:: figures/kernel-dev-flow.png | ||
| 109 | :width: 100% | ||
| 110 | |||
| 111 | #. *Set up Your Host Development System to Support Development Using the | ||
| 112 | Yocto Project*: See the ":doc:`/dev-manual/start`" section in | ||
| 113 | the Yocto Project Development Tasks Manual for options on how to get | ||
| 114 | a build host ready to use the Yocto Project. | ||
| 115 | |||
| 116 | #. *Set Up Your Host Development System for Kernel Development:* It is | ||
| 117 | recommended that you use ``devtool`` for kernel | ||
| 118 | development. Alternatively, you can use traditional kernel | ||
| 119 | development methods with the Yocto Project. Either way, there are | ||
| 120 | steps you need to take to get the development environment ready. | ||
| 121 | |||
| 122 | Using ``devtool`` requires that you have a clean build | ||
| 123 | of the image. For | ||
| 124 | more information, see the | ||
| 125 | ":ref:`kernel-dev/common:getting ready to develop using ``devtool```" | ||
| 126 | section. | ||
| 127 | |||
| 128 | Using traditional kernel development requires that you have the | ||
| 129 | kernel source available in an isolated local Git repository. For more | ||
| 130 | information, see the | ||
| 131 | ":ref:`kernel-dev/common:getting ready for traditional kernel development`" | ||
| 132 | section. | ||
| 133 | |||
| 134 | #. *Make Changes to the Kernel Source Code if applicable:* Modifying the | ||
| 135 | kernel does not always mean directly changing source files. However, | ||
| 136 | if you have to do this, you make the changes to the files in the | ||
| 137 | Yocto's :term:`Build Directory` if you are using ``devtool``. For more | ||
| 138 | information, see the | ||
| 139 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | ||
| 140 | section. | ||
| 141 | |||
| 142 | If you are using traditional kernel development, you edit the source | ||
| 143 | files in the kernel's local Git repository. For more information, see the | ||
| 144 | ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" | ||
| 145 | section. | ||
| 146 | |||
| 147 | #. *Make Kernel Configuration Changes if Applicable:* If your situation | ||
| 148 | calls for changing the kernel's configuration, you can use | ||
| 149 | :ref:`menuconfig <kernel-dev/common:using \`\`menuconfig\`\`>`, | ||
| 150 | which allows you to | ||
| 151 | interactively develop and test the configuration changes you are | ||
| 152 | making to the kernel. Saving changes you make with ``menuconfig`` | ||
| 153 | updates the kernel's ``.config`` file. | ||
| 154 | |||
| 155 | .. note:: | ||
| 156 | |||
| 157 | Try to resist the temptation to directly edit an existing ``.config`` | ||
| 158 | file, which is found in the :term:`Build Directory` among the source code | ||
| 159 | used for the build. Doing so, can produce unexpected results when | ||
| 160 | the OpenEmbedded build system regenerates the configuration file. | ||
| 161 | |||
| 162 | Once you are satisfied with the configuration changes made using | ||
| 163 | ``menuconfig`` and you have saved them, you can directly compare the | ||
| 164 | resulting ``.config`` file against an existing original and gather | ||
| 165 | those changes into a | ||
| 166 | :ref:`configuration fragment file <kernel-dev/common:creating configuration fragments>` to be | ||
| 167 | referenced from within the kernel's ``.bbappend`` file. | ||
| 168 | |||
| 169 | Additionally, if you are working in a BSP layer and need to modify | ||
| 170 | the BSP's kernel's configuration, you can use ``menuconfig``. | ||
| 171 | |||
| 172 | #. *Rebuild the Kernel Image With Your Changes:* Rebuilding the kernel | ||
| 173 | image applies your changes. Depending on your target hardware, you | ||
| 174 | can verify your changes on actual hardware or perhaps QEMU. | ||
| 175 | |||
| 176 | The remainder of this developer's guide covers common tasks typically | ||
| 177 | used during kernel development, advanced Metadata usage, and Yocto Linux | ||
| 178 | kernel maintenance concepts. | ||
