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