summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-12-18 10:32:14 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-01-16 15:59:05 +0000
commit974ef52d5677ac3e1d61750391a35412835b8844 (patch)
tree773c7e02d686881bb71a718bf1d3993a779ed4ac /documentation
parent494e9ef06b945d197b82a57bdf52e7837b8a305a (diff)
downloadpoky-974ef52d5677ac3e1d61750391a35412835b8844.tar.gz
kernel-dev: Rough text in for new chapter. Makefile edited.
The raw text for the second chapter is in by section. This has no formatting whatsoever. I also edited the Makefile so that the new "Common Tasks" chapter would make as part of the manual. (From yocto-docs rev: 68bcc1e977fbdd7b1a4b448171d1149edc72db51) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml698
-rw-r--r--documentation/kernel-dev/kernel-dev.xml2
2 files changed, 346 insertions, 354 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index 1290994257..a94ad6fd85 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -2,388 +2,380 @@
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > 3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4 4
5<chapter id='kernel-concepts'> 5<chapter id='kernel-dev-common'>
6 6
7<title>Yocto Project Kernel Concepts</title> 7<title>Common Tasks</title>
8 8
9<section id='concepts-org'> 9<para>
10 <title>Introduction</title> 10 This chapter describes common tasks you need to do when working
11 <para> 11 on the Yocto Project Linux kernel.
12 This chapter provides conceptual information about the kernel: 12</para>
13 <itemizedlist> 13
14 <listitem><para>Kernel Goals</para></listitem> 14 <section id='preparing-a-layer'>
15 <listitem><para>Kernel Development and Maintenance Overview</para></listitem> 15 <title>Preparing a Layer</title>
16 <listitem><para>Kernel Architecture</para></listitem>
17 <listitem><para>Kernel Tools</para></listitem>
18 </itemizedlist>
19 </para>
20</section>
21
22 <section id='kernel-goals'>
23 <title>Kernel Goals</title>
24 <para>
25 The complexity of embedded kernel design has increased dramatically.
26 Whether it is managing multiple implementations of a particular feature or tuning and
27 optimizing board specific features, both flexibility and maintainability are key concerns.
28 The Linux kernels available through the Yocto Project are presented with the embedded
29 developer's needs in mind and have evolved to assist in these key concerns.
30 For example, prior methods such as applying hundreds of patches to an extracted
31 tarball have been replaced with proven techniques that allow easy inspection,
32 bisection and analysis of changes.
33 Application of these techniques also creates a platform for performing integration and
34 collaboration with the thousands of upstream development projects.
35 </para>
36 <para>
37 With all these considerations in mind, the Yocto Project's kernel and development team
38 strives to attain these goals:
39 <itemizedlist>
40 <listitem><para>Allow the end user to leverage community best practices to seamlessly
41 manage the development, build and debug cycles.</para></listitem>
42 <listitem><para>Create a platform for performing integration and collaboration with the
43 thousands of upstream development projects that exist.</para></listitem>
44 <listitem><para>Provide mechanisms that support many different work flows, front-ends and
45 management techniques.</para></listitem>
46 <listitem><para>Deliver the most up-to-date kernel possible while still ensuring that
47 the baseline kernel is the most stable official release.</para></listitem>
48 <listitem><para>Include major technological features as part of the Yocto Project's
49 upward revision strategy.</para></listitem>
50 <listitem><para>Present a kernel Git repository that, similar to the upstream
51 <filename>kernel.org</filename> tree,
52 has a clear and continuous history.</para></listitem>
53 <listitem><para>Deliver a key set of supported kernel types, where each type is tailored
54 to meet a specific use (e.g. networking, consumer, devices, and so forth).</para></listitem>
55 <listitem><para>Employ a Git branching strategy that, from a developer's point of view,
56 results in a linear path from the baseline <filename>kernel.org</filename>,
57 through a select group of features and
58 ends with their BSP-specific commits.</para></listitem>
59 </itemizedlist>
60 </para>
61 </section>
62 16
63 <section id='kernel-big-picture'>
64 <title>Yocto Project Kernel Development and Maintenance Overview</title>
65 <para>
66 Kernels available through the Yocto Project, like other kernels, are based off the Linux
67 kernel releases from <ulink url='http://www.kernel.org'></ulink>.
68 At the beginning of a major development cycle, the Yocto Project team
69 chooses its kernel based on factors such as release timing, the anticipated release
70 timing of final upstream <filename>kernel.org</filename> versions, and Yocto Project
71 feature requirements.
72 Typically, the kernel chosen is in the
73 final stages of development by the community.
74 In other words, the kernel is in the release
75 candidate or "rc" phase and not yet a final release.
76 But, by being in the final stages of external development, the team knows that the
77 <filename>kernel.org</filename> final release will clearly be within the early stages of
78 the Yocto Project development window.
79 </para>
80 <para>
81 This balance allows the team to deliver the most up-to-date kernel
82 possible, while still ensuring that the team has a stable official release for
83 the baseline Linux kernel version.
84 </para>
85 <para>
86 The ultimate source for kernels available through the Yocto Project are released kernels
87 from <filename>kernel.org</filename>.
88 In addition to a foundational kernel from <filename>kernel.org</filename>, the
89 kernels available contain a mix of important new mainline
90 developments, non-mainline developments (when there is no alternative),
91 Board Support Package (BSP) developments,
92 and custom features.
93 These additions result in a commercially released Yocto Project Linux kernel that caters
94 to specific embedded designer needs for targeted hardware.
95 </para>
96 <para>
97 Once a kernel is officially released, the Yocto Project team goes into
98 their next development cycle, or upward revision (uprev) cycle, while still
99 continuing maintenance on the released kernel.
100 It is important to note that the most sustainable and stable way
101 to include feature development upstream is through a kernel uprev process.
102 Back-porting hundreds of individual fixes and minor features from various
103 kernel versions is not sustainable and can easily compromise quality.
104 </para>
105 <para>
106 During the uprev cycle, the Yocto Project team uses an ongoing analysis of
107 kernel development, BSP support, and release timing to select the best
108 possible <filename>kernel.org</filename> version.
109 The team continually monitors community kernel
110 development to look for significant features of interest.
111 The team does consider back-porting large features if they have a significant advantage.
112 User or community demand can also trigger a back-port or creation of new
113 functionality in the Yocto Project baseline kernel during the uprev cycle.
114 </para>
115 <para>
116 Generally speaking, every new kernel both adds features and introduces new bugs.
117 These consequences are the basic properties of upstream kernel development and are
118 managed by the Yocto Project team's kernel strategy.
119 It is the Yocto Project team's policy to not back-port minor features to the released kernel.
120 They only consider back-porting significant technological jumps - and, that is done
121 after a complete gap analysis.
122 The reason for this policy is that back-porting any small to medium sized change
123 from an evolving kernel can easily create mismatches, incompatibilities and very
124 subtle errors.
125 </para>
126 <para> 17 <para>
127 These policies result in both a stable and a cutting 18 Customizing recipes is best done in a layer with bbappend files. Layers also
128 edge kernel that mixes forward ports of existing features and significant and critical 19provide a convenient mechanism to create your own recipes. This guide assumes
129 new functionality. 20you will be working from within a layer independent from those released with the
130 Forward porting functionality in the kernels available through the Yocto Project kernel 21Yocto Project. For details on how to create and work with layers, refer to
131 can be thought of as a "micro uprev." 22section 5.1 Understanding and Creating Layers in the Yocto Project Development
132 The many “micro uprevs” produce a kernel version with a mix of 23Manual.
133 important new mainline, non-mainline, BSP developments and feature integrations. 24
134 This kernel gives insight into new features and allows focused 25(Kernel specific directions in 5.7.4)
135 amounts of testing to be done on the kernel, which prevents
136 surprises when selecting the next major uprev.
137 The quality of these cutting edge kernels is evolving and the kernels are used in leading edge
138 feature and BSP development.
139 </para> 26 </para>
140 </section> 27 </section>
141 28
142 <section id='kernel-architecture'> 29 <section id='modifying-an-existing-recipe'>
143 <title>Kernel Architecture</title> 30 <title>Modifying an Existing Recipe</title>
31
144 <para> 32 <para>
145 This section describes the architecture of the kernels available through the 33 In many cases, you can customize an existing linux-yocto recipe to meet the
146 Yocto Project and provides information 34needs of your project. Each release of the Yocto Project provides a few Linux
147 on the mechanisms used to achieve that architecture. 35kernel recipes to choose from. To get started, prepare a layer and a bbappend
36file corresponding to the recipe you wish to modify.
37
38See [New example in Dev Manual] for instructions to create a minimal layer.
39
40The bbappend will typical be located at the following location relative to the
41layer (if modifying the linux-yocto_3.4.bb recipe):
42
43 recipes-kernel/linux/linux-yocto_3.4.bbappend
44
45And should contain the following text initially:
46
47 FILESEXTRAPATHS := "${THISDIR}/${PN}"
48
49The ${PN} will expand to "linux-yocto" in this example. Any new files added to
50modify the recipe should then be added to the following path within the layer:
51
52 recipes-kernel/linux/linux-yocto/
53
54NOTE: If you are working on a new machine BSP, be sure to refer to the Yocto
55Project Board Support Package Developer's Guide.
56
148 </para> 57 </para>
149 58
150 <section id='architecture-overview'> 59 <section id='applying-patches'>
151 <title>Overview</title> 60 <title>Applying Patches</title>
152 <para> 61
153 As mentioned earlier, a key goal of the Yocto Project is to present the
154 developer with
155 a kernel that has a clear and continuous history that is visible to the user.
156 The architecture and mechanisms used achieve that goal in a manner similar to the
157 upstream <filename>kernel.org</filename>.
158 </para>
159 <para>
160 You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with
161 added features logically structured on top of the baseline.
162 The features are tagged and organized by way of a branching strategy implemented by the
163 source code manager (SCM) Git.
164 For information on Git as applied to the Yocto Project, see the
165 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the
166 Yocto Project Development Manual.
167 </para>
168 <para>
169 The result is that the user has the ability to see the added features and
170 the commits that make up those features.
171 In addition to being able to see added features, the user can also view the history of what
172 made up the baseline kernel.
173 </para>
174 <para>
175 The following illustration shows the conceptual Yocto Project kernel.
176 </para>
177 <para>
178 <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
179 </para>
180 <para>
181 In the illustration, the "Kernel.org Branch Point"
182 marks the specific spot (or release) from
183 which the Yocto Project kernel is created.
184 From this point "up" in the tree, features and differences are organized and tagged.
185 </para>
186 <para>
187 The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel
188 type and BSP that is organized further up the tree.
189 Placing these common features in the
190 tree this way means features don't have to be duplicated along individual branches of the
191 structure.
192 </para>
193 <para>
194 From the Yocto Project Baseline Kernel, branch points represent specific functionality
195 for individual BSPs as well as real-time kernels.
196 The illustration represents this through three BSP-specific branches and a real-time
197 kernel branch.
198 Each branch represents some unique functionality for the BSP or a real-time kernel.
199 </para>
200 <para>
201 In this example structure, the real-time kernel branch has common features for all
202 real-time kernels and contains
203 more branches for individual BSP-specific real-time kernels.
204 The illustration shows three branches as an example.
205 Each branch points the way to specific, unique features for a respective real-time
206 kernel as they apply to a given BSP.
207 </para>
208 <para> 62 <para>
209 The resulting tree structure presents a clear path of markers (or branches) to the 63 If you have a patch, or a small series of patches, to apply to the Linux kernel
210 developer that, for all practical purposes, is the kernel needed for any given set 64source, you can do so just as you would with any other recipe. You first copy
211 of requirements. 65the patches to the path added to FILESEXTRAPATHS in the bbappend file as
66described in 2.2 and then reference them in the SRC_URI.
67
68For example, you can apply a three patch series by adding the following lines to
69your linux-yocto bbappend file in your layer:
70
71 SRC_URI += "file://0001-first-change.patch"
72 SRC_URI += "file://0002-first-change.patch"
73 SRC_URI += "file://0003-first-change.patch"
74
75At the next build, bitbake will detect the change in the recipe and fetch and
76apply the patches before rebuilding the Linux kernel.
212 </para> 77 </para>
213 </section> 78 </section>
214 79
215 <section id='branching-and-workflow'> 80 <section id='changing-the-configuration'>
216 <title>Branching Strategy and Workflow</title> 81 <title>Changing the Configuration</title>
217 <para> 82
218 The Yocto Project team creates kernel branches at points where functionality is
219 no longer shared and thus, needs to be isolated.
220 For example, board-specific incompatibilities would require different functionality
221 and would require a branch to separate the features.
222 Likewise, for specific kernel features, the same branching strategy is used.
223 </para>
224 <para>
225 This branching strategy results in a tree that has features organized to be specific
226 for particular functionality, single kernel types, or a subset of kernel types.
227 This strategy also results in not having to store the same feature twice
228 internally in the tree.
229 Rather, the kernel team stores the unique differences required to apply the
230 feature onto the kernel type in question.
231 <note>
232 The Yocto Project team strives to place features in the tree such that they can be
233 shared by all boards and kernel types where possible.
234 However, during development cycles or when large features are merged,
235 the team cannot always follow this practice.
236 In those cases, the team uses isolated branches to merge features.
237 </note>
238 </para>
239 <para>
240 BSP-specific code additions are handled in a similar manner to kernel-specific additions.
241 Some BSPs only make sense given certain kernel types.
242 So, for these types, the team creates branches off the end of that kernel type for all
243 of the BSPs that are supported on that kernel type.
244 From the perspective of the tools that create the BSP branch, the BSP is really no
245 different than a feature.
246 Consequently, the same branching strategy applies to BSPs as it does to features.
247 So again, rather than store the BSP twice, the team only stores the unique
248 differences for the BSP across the supported multiple kernels.
249 </para>
250 <para>
251 While this strategy can result in a tree with a significant number of branches, it is
252 important to realize that from the developer's point of view, there is a linear
253 path that travels from the baseline <filename>kernel.org</filename>, through a select
254 group of features and ends with their BSP-specific commits.
255 In other words, the divisions of the kernel are transparent and are not relevant
256 to the developer on a day-to-day basis.
257 From the developer's perspective, this path is the "master" branch.
258 The developer does not need to be aware of the existence of any other branches at all.
259 Of course, there is value in the existence of these branches
260 in the tree, should a person decide to explore them.
261 For example, a comparison between two BSPs at either the commit level or at the line-by-line
262 code <filename>diff</filename> level is now a trivial operation.
263 </para>
264 <para>
265 Working with the kernel as a structured tree follows recognized community best practices.
266 In particular, the kernel as shipped with the product, should be
267 considered an "upstream source" and viewed as a series of
268 historical and documented modifications (commits).
269 These modifications represent the development and stabilization done
270 by the Yocto Project kernel development team.
271 </para>
272 <para> 83 <para>
273 Because commits only change at significant release points in the product life cycle, 84 Making wholesale or incremental changes to the Linux kernel config can be made
274 developers can work on a branch created 85by including a defconfig or configuration fragments in the SRC_URI.
275 from the last relevant commit in the shipped Yocto Project kernel. 86
276 As mentioned previously, the structure is transparent to the developer 87If you have a complete Linux kernel .config file you want to use, copy it as
277 because the kernel tree is left in this state after cloning and building the kernel. 88"defconfig" to the ${FILES} directory and add the following line to your
89linux-yocto bbappend file in your layer:
90
91 SRC_URI += "file://defconfig"
92
93Generally speaking, the preferred approach is to determine the incremental
94change you want to make and add that as a fragment. For example, if you wanted
95to add support for a basic serial console, create a file named "8250.cfg" in the
96${FILES} directory with the following content (without indentation):
97
98 CONFIG_SERIAL_8250=y
99 CONFIG_SERIAL_8250_CONSOLE=y
100 CONFIG_SERIAL_8250_PCI=y
101 CONFIG_SERIAL_8250_NR_UARTS=4
102 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
103 CONFIG_SERIAL_CORE=y
104 CONFIG_SERIAL_CORE_CONSOLE=y
105
106Then include this configuration fragment in the SRC_URI:
107
108 SRC_URI += "file://8250.cfg"
109
110At the next build, bitbake will detect the change in the recipe and fetch and
111apply the new configuration before rebuilding the Linux kernel.
278 </para> 112 </para>
279 </section> 113 </section>
114 </section>
115
116 <section id='iterative-development'>
117 <title>Iterative Development</title>
118
119 <para>
120 If you do not have existing patches or configuration files, you can easily
121generate them from within the bitbake build environment, as will be described
122below. As you do, running previously completed bitbake tasks will cause bitbake
123to invalidate the tasks that follow them in the build sequence, causing them to
124rebuild at the next invocation of the build. Throughout this section, be sure to
125substitute "linux-yocto" with the name of the Linux kernel recipe you are
126working with.
127 </para>
128
129 <section id='generating-configuration-files'>
130 <title>Generating Configuration Files</title>
280 131
281 <section id='source-code-manager-git'>
282 <title>Source Code Manager - Git</title>
283 <para> 132 <para>
284 The Source Code Manager (SCM) is Git. 133 You can manipulate the config used to build a linux-yocto recipe with the
285 This SCM is the obvious mechanism for meeting the previously mentioned goals. 134"menuconfig" command.
286 Not only is it the SCM for <filename>kernel.org</filename> but, 135
287 Git continues to grow in popularity and supports many different work flows, 136 $ bitbake linux-yocto -c menuconfig
288 front-ends and management techniques. 137
138This will start the Linux kernel configuration tool, allowing you to prepare a
139new .config for the build. When you exit, be sure to save the changes when
140prompted. The resulting .config file will be located in the ${WORKDIR} under
141the linux-${MACHINE}-${KTYPE}-build directory. You can use this in its entirety
142as the defconfig file described in 2.2.2.
143
144Better still, would be to use the "menuconfig" command and take the difference
145of the new .config file with the previous one to generate a configuration
146fragment. To do this, be sure to complete a build at least through the kernel
147configuration task:
148
149 $ bitbake linux-yocto -c kernel_configme -f
150
151Then make a copy of the .config file, calling it "config.orig", for example. Run
152the "menuconfig" command as described above. Finally, prepare a configuration
153fragment from the difference between the files. Ultimately you want a list of
154Linux kernel CONFIG_ assignments, and not something in diff format. Something
155like the following will do that automatically (but plan on reviewing the output
156as you can usually remove some of the defaults):
157
158 $ diff -Nurp config.orig .config | sed -n "s/^\+//p" > frag.cfg
159
160You can use the output as a configuration fragment described in 2.2.2. This
161method can also be used to define a BSP configuration fragment (See 3.3.5).
162
163The Yocto Project kernel tools provide some configuration validation tools which
164will warn when a configuration you requested does not appear in the final
165config, or when you override a policy configuration in a hardware configuration
166fragment. You can run these tools with the following command:
167
168 $ bitbake linux-yocto -c kernel_configcheck -f
169
170 ...
171
172 NOTE: validating kernel configuration
173 This BSP sets 3 invalid/obsolete kernel options.
174 These config options are not offered anywhere within this kernel.
175 The full list can be found in your kernel src dir at:
176 meta/cfg/standard/mybsp/invalid.cfg
177
178 This BSP sets 21 kernel options that are possibly non-hardware related.
179 The full list can be found in your kernel src dir at:
180 meta/cfg/standard/mybsp/specified_non_hdw.cfg
181
182 WARNING: There were 2 hardware options requested that do not
183 have a corresponding value present in the final ".config" file.
184 This probably means you aren't getting the config you wanted.
185 The full list can be found in your kernel src dir at:
186 meta/cfg/standard/mybsp/mismatch.cfg
187
188The various problems that you can encounter are described in the output along
189with where to find the offending configuration items. You can use these logs to
190adjust your configuration files and repeat the "kernel_configme" and
191"kernel_configcheck" commands until no warnings are produced.
289 </para> 192 </para>
193 </section>
194
195 <section id='modifying-source-code'>
196 <title>Modifying Source Code</title>
197
290 <para> 198 <para>
291 You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>. 199 You can experiment with source code changes and create a simple patch without
292 You can also get an introduction to Git as it applies to the Yocto Project in the 200leaving the bitbake environment. To get started, be sure to complete a build at
293 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" 201least through the kernel configuration task:
294 section in the Yocto Project Development Manual. 202
295 These referenced sections overview Git and describe a minimal set of 203 $ bitbake linux-yocto -c kernel_configme -f
296 commands that allows you to be functional using Git. 204
297 <note> 205This step will ensure you have the sources prepared and the configuration
298 You can use as much, or as little, of what Git has to offer to accomplish what 206completed. You will find the sources in the ${WORKDIR}/linux directory.
299 you need for your project. 207
300 You do not have to be a "Git Master" in order to use it with the Yocto Project. 208You can edit the sources as you would any other Linux source tree, but keep in
301 </note> 209mind that your changes will be lost if you trigger the fetch task for the
210recipe. Avoid this by not issuing the "cleanall" or "cleansstate", or forcing
211the "fetch" command. Also be sure not to modify the recipe itself while working
212with temporary changes or bitbake may run the fetch command (depending on the
213changes to the recipe).
214
215To test your temporary changes, instruct bitbake to run the compile again. The
216-f option forces the command to run again even though bitbake may think it has
217already done so:
218
219 $ bitbake linux-yocto -c compile -f
220
221If the compile fails, you can update the sources and repeat the compile
222command. Once it compiles successfully, you can inspect and test the resulting
223build (kernel, modules, etc.) from the build directory at
224${WORKDIR}/linux-${MACHINE}-${KTYPE}-build. Alternatively, you can run the
225deploy command to place the kernel image in the tmp/deploy/images directory:
226
227 $ bitbake linux-yocto -c deploy
228
229And of course, you can run through all the remaining installation and packaging
230steps by issuing:
231
232 $ bitbake linux-yocto
233
234For rapid iterative development, the edit-compile-repeat loop is preferable to
235rebuilding the entire recipe as the installation and packaging tasks are very
236time consuming.
237
238Once you are happy with your modifications, you can make these permanent by
239generating patches and applying them to the SRC_URI as described in section
2402.2.1 Applying Patches. If you are not familiar with generating patches, refer
241to the Yocto Project Development Manual, section 5.7.3 Creating the Patch.
302 </para> 242 </para>
303 </section> 243 </section>
304 </section> 244 </section>
305 245
306 <section id='kernel-configuration'> 246 <section id='working-with-your-own-sources'>
307 <title>Kernel Configuration</title> 247 <title>Working With Your Own Sources</title>
308 <para>
309 Kernel configuration, along with kernel features, defines how a kernel
310 image is built for the Yocto Project.
311 Through configuration settings, you can customize a Yocto Project kernel to be
312 specific to particular hardware.
313 For example, you can specify sound support or networking support.
314 This section describes basic concepts behind Kernel configuration within the
315 Yocto Project and references you to other areas for specific configuration
316 applications.
317 </para>
318 248
319 <para> 249 <para>
320 Conceptually, configuration of a Yocto Project kernel occurs similarly to that needed for any 250 If you find yourself unable to work with one of the Linux kernel versions
321 Linux kernel. 251supported by existing linux-yocto recipes, you can still make use of the Yocto
322 The build process for a Yocto Project kernel uses a <filename>.config</filename> file, which 252Project Linux kernel tooling while working with your own sources. You will not
323 is created through the Linux Kernel Configuration (LKC) tool. 253be able to leverage the existing meta-data and stabilization work of the
324 You can directly set various configurations in the 254linux-yocto sources, but you will be able to manage your own meta-data in the
325 <filename>.config</filename> file by using the <filename>menuconfig</filename> 255same format as the linux-yocto sources which will facilitate converging with
326 tool as built by BitBake. 256linux-yocto on a future mutually-supported kernel version.
327 You can also define configurations in the file by using configuration fragments. 257
328 <note> 258The linux-yocto-custom recipe, located in the poky repository at:
329 It is not recommended that you edit the <filename>.config</filename> file directly. 259
330 </note> 260 meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
331 Here are some brief descriptions of the ways you can affect the 261
332 <filename>.config</filename> file: 262is provided as an example recipe which uses kernel.org sources and the Yocto
333 <itemizedlist> 263Project Linux kernel tools for managing meta-data. To get started, copy this
334 <listitem><para><emphasis>The <filename>menuconfig</filename> Tool:</emphasis> 264recipe to your layer and provide it with a meaningful name, such as
335 One of many front-ends that allows you to define kernel configurations. 265linux-yocto-myproject_3.5.bb, where 3.5 is the base version of the Linux kernel
336 Some others are <filename>make config</filename>, 266you will be working with. In the same directory, create a matching directory,
337 <filename>make nconfig</filename>, and <filename>make gconfig</filename>. 267e.g. linux-yocto-myproject to store your patches and configuration files.
338 In the Yocto Project environment, you must use BitBake to build the 268
339 <filename>menuconfig</filename> tool before you can use it to define 269Edit the following variables in the recipe as appropriate for your project:
340 configurations: 270
341 <literallayout class='monospaced'> 271 o SRC_URI
342 $ bitbake linux-yocto -c menuconfig 272 o LINUX_VERSION
343 </literallayout> 273 o LINUX_VERSION_EXTENSION
344 After the tool is built, you can interact with it normally. 274 o SRCREV
345 You can see how <filename>menuconfig</filename> is used to change a simple 275 o PR
346 kernel configuration in the 276 o PV
347 "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>" 277 o COMPATIBLE_MACHINE
348 section of the Yocto Project Development Manual. 278
349 For general information on <filename>menuconfig</filename>, see 279The SRC_URI should be a git repository, using one of the supported git fetcher
350 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>. 280protocols (file, git, http, etc.). The skeleton recipe provides an example
351 </para></listitem> 281SRC_URI as a syntax reference.
352 <listitem><para><emphasis>Configuration Fragments:</emphasis> A file with a 282
353 list of kernel options just as they would appear syntactically in the 283Set LINUX_VERSION to the Linux kernel version you are using, such as "3.6.3".
354 <filename>.config</filename> file. 284
355 Configuration fragments are typically logical groupings and are assembled 285LINUX_VERSION_EXTENSION is used to define the Linux kernel CONFIG_LOCALVERSION
356 by the OpenEmbedded build system to produce input used by the LKC 286which will be compiled in to the resulting kernel and visible via the uname
357 that ultimately generates the <filename>.config</filename> file.</para> 287command.
358 <para>The 288
359 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink></filename> 289Set SRCREV to the commit ID you wish to build from.
360 variable can be used to list configuration fragments. 290
361 For further discussion on applying configuration fragments, see the 291Treat the PR as you would the PR of any other recipe. Increment it to indicate
362 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-kernel'>Linux Kernel Configuration</ulink>" 292to the build system that the recipe has changed.
363 section in the Yocto Project Board Support Package (BSP) Guide. 293
364 </para></listitem> 294The default PV assignment is typically adequate. It combines the LINUX_VERSION
365 </itemizedlist> 295with the SCM revision (from the SRCPV variable) and results in a string
296something like:
297
298"3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2"
299
300While lengthy, this extra verbosity helps ensure you are building from the exact
301sources you intend.
302
303Finally, the default COMPATIBLE_MACHINE assignment for linux-yocto-custom is set
304to a regular expression matching only the empty string, "(^$)". This will
305trigger an explicit build failure. You must change it to match a list of the
306machines supported by your new recipe, such as "(qemux86|qemux86-64)"
307
308With that in place, you can continue to customize this recipe as you would the
309existing linux-yocto recipes. See Section 2.2 Modifying an Existing Recipe for
310details.
366 </para> 311 </para>
367 </section> 312 </section>
368 313
369 <section id='kernel-tools'> 314 <section id='incorporating-out-of-tree-modules'>
370 <title>Kernel Tools</title> 315 <title>Incorporating Out-of-Tree Modules</title>
371 <para> 316
372 Since most standard workflows involve moving forward with an existing tree by
373 continuing to add and alter the underlying baseline, the tools that manage
374 the Yocto Project's kernel construction are largely hidden from the developer to
375 present a simplified view of the kernel for ease of use.
376 </para>
377 <para> 317 <para>
378 Fundamentally, the kernel tools that manage and construct the 318 While it is always preferable to work with sources integrated into the Linux
379 Yocto Project kernel accomplish the following: 319kernel sources, if you have need of an external kernel module, the hello-mod
380 <itemizedlist> 320recipe is available as a template to create your own out-of-tree Linux kernel
381 <listitem><para>Group patches into named, reusable features.</para></listitem> 321module recipe. It is available in the poky repository at:
382 <listitem><para>Allow top-down control of included features.</para></listitem> 322
383 <listitem><para>Bind kernel configurations to kernel patches and features.</para></listitem> 323 meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
384 <listitem><para>Present a seamless Git repository that blends Yocto Project value 324
385 with the <filename>kernel.org</filename> history and development.</para></listitem> 325To get started, copy this recipe to your layer and provide it with a meaningful name, such as
386 </itemizedlist> 326mymodule_1.0.bb. In the same directory, create a directory named "files" where
327you can store any source files, patches, or other files necessary for building
328the module which do not come with the sources. Finally, update the recipe as
329appropriate for the module. Typically you will need to set the following
330variables:
331
332 o DESCRIPTION
333 o LICENSE*
334 o SRC_URI
335 o PV
336
337Depending on the build system used by the module sources, you may need to make
338adjustments. For example, a typical module Makefile will look much like that
339provided with hello-mod:
340
341 obj-m := hello.o
342
343 SRC := $(shell pwd)
344
345 all:
346 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
347
348 modules_install:
349 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
350 ...
351
352The important point to note here is the KERNEL_SRC variable. The module bbclass
353class sets this, as well as KERNEL_PATH, to ${STAGING_KERNEL_DIR} with the
354necessary Linux kernel build information to build modules. If your module
355Makefile uses a different variable, you may want to override the do_compile()
356step, or create a patch to the Makefile to work with the more typical KERNEL_SRC
357or KERNEL_PATH variables.
358
359After you have prepared the recipe, you will likely want to include the module
360in your images. To do this, see the documentation for the following variables in
361the Yocto Project Reference Manual and set one of them as appropriate in your
362machine config file:
363
364 MACHINE_ESSENTIAL_EXTRA_RDEPENDS
365 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS
366 MACHINE_EXTRA_RDEPENDS
367 MACHINE_EXTRA_RRECOMMENDS
368
369As modules are often not required for boot and may be excluded from certain
370build configurations, the following allows for the most flexibility:
371
372 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
373
374Where the value is derived by appending the module filename without the .ko
375extension to the string "kernel-module-".
376
377As it is an RRECOMMENDS (and not an RDEPENDS) variable, the build will not fail
378if this module is not available to include in the image.
387 </para> 379 </para>
388 </section> 380 </section>
389</chapter> 381</chapter>
diff --git a/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml
index ab8f45366c..1bbd0feb45 100644
--- a/documentation/kernel-dev/kernel-dev.xml
+++ b/documentation/kernel-dev/kernel-dev.xml
@@ -59,9 +59,9 @@
59 59
60 <xi:include href="kernel-dev-intro.xml"/> 60 <xi:include href="kernel-dev-intro.xml"/>
61 61
62<!--
63 <xi:include href="kernel-dev-common.xml"/> 62 <xi:include href="kernel-dev-common.xml"/>
64 63
64<!--
65 <xi:include href="kernel-dev-advanced.xml"/> 65 <xi:include href="kernel-dev-advanced.xml"/>
66 66
67 <xi:include href="kernel-dev-examples.xml"/> 67 <xi:include href="kernel-dev-examples.xml"/>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-10 04:03:48 +0000