diff options
Diffstat (limited to 'documentation/kernel-dev/intro.rst')
-rw-r--r-- | documentation/kernel-dev/intro.rst | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/documentation/kernel-dev/intro.rst b/documentation/kernel-dev/intro.rst new file mode 100644 index 0000000000..2b60616df4 --- /dev/null +++ b/documentation/kernel-dev/intro.rst | |||
@@ -0,0 +1,180 @@ | |||
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, an | ||
70 | alternative exists by which you can use the Yocto Project Linux kernel | ||
71 | tools with your 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 | ||
76 | `BitBake <https://openembedded.org/wiki/Bitbake>`__ recipes and basic | ||
77 | open-source development tools. Understanding these concepts will | ||
78 | facilitate the process of working with the kernel recipes. If you find | ||
79 | you need some additional background, please be sure to review and | ||
80 | understand the following documentation: | ||
81 | |||
82 | - :doc:`/brief-yoctoprojectqs/index` document. | ||
83 | |||
84 | - :doc:`/overview-manual/index`. | ||
85 | |||
86 | - :ref:`devtool | ||
87 | workflow <sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow>` | ||
88 | as described in the Yocto Project Application Development and the | ||
89 | Extensible Software Development Kit (eSDK) manual. | ||
90 | |||
91 | - The ":ref:`dev-manual/common-tasks:understanding and creating layers`" | ||
92 | section in the Yocto Project Development Tasks Manual. | ||
93 | |||
94 | - The "`Kernel Modification | ||
95 | Workflow <#kernel-modification-workflow>`__" section. | ||
96 | |||
97 | Kernel Modification Workflow | ||
98 | ============================ | ||
99 | |||
100 | Kernel modification involves changing the Yocto Project kernel, which | ||
101 | could involve changing configuration options as well as adding new | ||
102 | kernel recipes. Configuration changes can be added in the form of | ||
103 | configuration fragments, while recipe modification comes through the | ||
104 | kernel's ``recipes-kernel`` area in a kernel layer you create. | ||
105 | |||
106 | This section presents a high-level overview of the Yocto Project kernel | ||
107 | modification workflow. The illustration and accompanying list provide | ||
108 | general information and references for further information. | ||
109 | |||
110 | .. image:: figures/kernel-dev-flow.png | ||
111 | :align: center | ||
112 | |||
113 | 1. *Set up Your Host Development System to Support Development Using the | ||
114 | Yocto Project*: See the ":doc:`/dev-manual/start`" section in | ||
115 | the Yocto Project Development Tasks Manual for options on how to get | ||
116 | a build host ready to use the Yocto Project. | ||
117 | |||
118 | 2. *Set Up Your Host Development System for Kernel Development:* It is | ||
119 | recommended that you use ``devtool`` and an extensible SDK for kernel | ||
120 | development. Alternatively, you can use traditional kernel | ||
121 | development methods with the Yocto Project. Either way, there are | ||
122 | steps you need to take to get the development environment ready. | ||
123 | |||
124 | Using ``devtool`` and the eSDK requires that you have a clean build | ||
125 | of the image and that you are set up with the appropriate eSDK. For | ||
126 | more information, see the | ||
127 | ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" | ||
128 | section. | ||
129 | |||
130 | Using traditional kernel development requires that you have the | ||
131 | kernel source available in an isolated local Git repository. For more | ||
132 | information, see the | ||
133 | ":ref:`kernel-dev/common:getting ready for traditional kernel development`" | ||
134 | section. | ||
135 | |||
136 | 3. *Make Changes to the Kernel Source Code if applicable:* Modifying the | ||
137 | kernel does not always mean directly changing source files. However, | ||
138 | if you have to do this, you make the changes to the files in the | ||
139 | eSDK's Build Directory if you are using ``devtool``. For more | ||
140 | information, see the | ||
141 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | ||
142 | section. | ||
143 | |||
144 | If you are using traditional kernel development, you edit the source | ||
145 | files in the kernel's local Git repository. For more information, see the | ||
146 | ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" | ||
147 | section. | ||
148 | |||
149 | 4. *Make Kernel Configuration Changes if Applicable:* If your situation | ||
150 | calls for changing the kernel's configuration, you can use | ||
151 | :ref:`menuconfig <kernel-dev/common:using \`\`menuconfig\`\`>`, | ||
152 | which allows you to | ||
153 | interactively develop and test the configuration changes you are | ||
154 | making to the kernel. Saving changes you make with ``menuconfig`` | ||
155 | updates the kernel's ``.config`` file. | ||
156 | |||
157 | .. note:: | ||
158 | |||
159 | Try to resist the temptation to directly edit an existing ``.config`` | ||
160 | file, which is found in the Build Directory among the source code | ||
161 | used for the build. Doing so, can produce unexpected results when | ||
162 | the OpenEmbedded build system regenerates the configuration file. | ||
163 | |||
164 | Once you are satisfied with the configuration changes made using | ||
165 | ``menuconfig`` and you have saved them, you can directly compare the | ||
166 | resulting ``.config`` file against an existing original and gather | ||
167 | those changes into a | ||
168 | :ref:`configuration fragment file <kernel-dev/common:creating configuration fragments>` to be | ||
169 | referenced from within the kernel's ``.bbappend`` file. | ||
170 | |||
171 | Additionally, if you are working in a BSP layer and need to modify | ||
172 | the BSP's kernel's configuration, you can use ``menuconfig``. | ||
173 | |||
174 | 5. *Rebuild the Kernel Image With Your Changes:* Rebuilding the kernel | ||
175 | image applies your changes. Depending on your target hardware, you | ||
176 | can verify your changes on actual hardware or perhaps QEMU. | ||
177 | |||
178 | The remainder of this developer's guide covers common tasks typically | ||
179 | used during kernel development, advanced Metadata usage, and Yocto Linux | ||
180 | kernel maintenance concepts. | ||