diff options
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-intro.rst')
-rw-r--r-- | documentation/kernel-dev/kernel-dev-intro.rst | 178 |
1 files changed, 178 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..0f87f8cf1d --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-intro.rst | |||
@@ -0,0 +1,178 @@ | |||
1 | ************ | ||
2 | Introduction | ||
3 | ************ | ||
4 | |||
5 | .. _kernel-dev-overview: | ||
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 `Metadata <&YOCTO_DOCS_REF_URL;#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 `Source | ||
22 | Repositories <&YOCTO_GIT_URL;>`__ under the "Yocto Linux Kernel" | ||
23 | heading. New recipes for the release track the latest Linux kernel | ||
24 | upstream developments from ` <http://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 "`Yocto Project Kernel | ||
30 | Development and Maintenance <#kernel-big-picture>`__" 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 | 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 <http://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 | - `Yocto Project Quick Build <&YOCTO_DOCS_BRIEF_URL;>`__ document. | ||
83 | |||
84 | - `Yocto Project Overview and Concepts Manual <&YOCTO_DOCS_OM_URL;>`__. | ||
85 | |||
86 | - ```devtool`` | ||
87 | workflow <&YOCTO_DOCS_SDK_URL;#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 "`Understanding and Creating | ||
92 | Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" | ||
93 | section in the Yocto Project Development Tasks Manual. | ||
94 | |||
95 | - The "`Kernel Modification | ||
96 | Workflow <#kernel-modification-workflow>`__" section. | ||
97 | |||
98 | Kernel Modification Workflow | ||
99 | ============================ | ||
100 | |||
101 | Kernel modification involves changing the Yocto Project kernel, which | ||
102 | could involve changing configuration options as well as adding new | ||
103 | kernel recipes. Configuration changes can be added in the form of | ||
104 | configuration fragments, while recipe modification comes through the | ||
105 | kernel's ``recipes-kernel`` area in a kernel layer you create. | ||
106 | |||
107 | This section presents a high-level overview of the Yocto Project kernel | ||
108 | modification workflow. The illustration and accompanying list provide | ||
109 | general information and references for further information. | ||
110 | |||
111 | 1. *Set up Your Host Development System to Support Development Using the | ||
112 | Yocto Project*: See the "`Setting Up the Development Host to Use the | ||
113 | Yocto Project <&YOCTO_DOCS_DEV_URL;#dev-manual-start>`__" section in | ||
114 | the Yocto Project Development Tasks Manual for options on how to get | ||
115 | a build host ready to use the Yocto Project. | ||
116 | |||
117 | 2. *Set Up Your Host Development System for Kernel Development:* It is | ||
118 | recommended that you use ``devtool`` and an extensible SDK for kernel | ||
119 | development. Alternatively, you can use traditional kernel | ||
120 | development methods with the Yocto Project. Either way, there are | ||
121 | steps you need to take to get the development environment ready. | ||
122 | |||
123 | Using ``devtool`` and the eSDK requires that you have a clean build | ||
124 | of the image and that you are set up with the appropriate eSDK. For | ||
125 | more information, see the "`Getting Ready to Develop Using | ||
126 | ``devtool`` <#getting-ready-to-develop-using-devtool>`__" 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 "`Getting Ready for Traditional Kernel | ||
131 | Development <#getting-ready-for-traditional-kernel-development>`__" | ||
132 | section. | ||
133 | |||
134 | 3. *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 | eSDK's Build Directory if you are using ``devtool``. For more | ||
138 | information, see the "`Using ``devtool`` to Patch the | ||
139 | Kernel <#using-devtool-to-patch-the-kernel>`__" section. | ||
140 | |||
141 | If you are using traditional kernel development, you edit the source | ||
142 | files in the kernel's local Git repository. For more information, see | ||
143 | the "`Using Traditional Kernel Development to Patch the | ||
144 | Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__" | ||
145 | section. | ||
146 | |||
147 | 4. *Make Kernel Configuration Changes if Applicable:* If your situation | ||
148 | calls for changing the kernel's configuration, you can use | ||
149 | ```menuconfig`` <#using-menuconfig>`__, which allows you to | ||
150 | interactively develop and test the configuration changes you are | ||
151 | making to the kernel. Saving changes you make with ``menuconfig`` | ||
152 | updates the kernel's ``.config`` file. | ||
153 | |||
154 | .. note:: | ||
155 | |||
156 | Try to resist the temptation to directly edit an existing | ||
157 | .config | ||
158 | file, which is found in the 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 `configuration fragment | ||
166 | file <#creating-config-fragments>`__ to be referenced from within the | ||
167 | 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 | 5. *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. | ||