summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-common.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-common.xml')
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml858
1 files changed, 858 insertions, 0 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
new file mode 100644
index 0000000000..ef1d0dbc5b
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -0,0 +1,858 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='kernel-dev-common'>
6
7<title>Common Tasks</title>
8
9<para>
10 This chapter presents several common tasks you perform when you
11 work with the Yocto Project Linux kernel.
12 These tasks include preparing a layer, modifying an existing recipe,
13 iterative development, working with your own sources, and incorporating
14 out-of-tree modules.
15 <note>
16 The examples presented in this chapter work with the Yocto Project
17 1.2.2 Release and forward.
18 </note>
19</para>
20
21 <section id='creating-and-preparing-a-layer'>
22 <title>Creating and Preparing a Layer</title>
23
24 <para>
25 If you are going to be modifying kernel recipes, it is recommended
26 that you create and prepare your own layer in which to do your
27 work.
28 Your layer contains its own
29 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
30 append files
31 (<filename>.bbappend</filename>) and provides a convenient
32 mechanism to create your own recipe files
33 (<filename>.bb</filename>).
34 For details on how to create and work with layers, see the following
35 sections in the Yocto Project Development Manual:
36 <itemizedlist>
37 <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" for
38 general information on layers and how to create layers.</para></listitem>
39 <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" for
40 specific instructions on setting up a layer for kernel
41 development.</para></listitem>
42 </itemizedlist>
43 </para>
44 </section>
45
46 <section id='modifying-an-existing-recipe'>
47 <title>Modifying an Existing Recipe</title>
48
49 <para>
50 In many cases, you can customize an existing linux-yocto recipe to
51 meet the needs of your project.
52 Each release of the Yocto Project provides a few Linux
53 kernel recipes from which you can choose.
54 These are located in the
55 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
56 in <filename>meta/recipes-kernel/linux</filename>.
57 </para>
58
59 <para>
60 Modifying an existing recipe can consist of the following:
61 <itemizedlist>
62 <listitem><para>Creating the append file</para></listitem>
63 <listitem><para>Applying patches</para></listitem>
64 <listitem><para>Changing the configuration</para></listitem>
65 </itemizedlist>
66 </para>
67
68 <para>
69 Before modifying an existing recipe, be sure that you have created
70 a minimal, custom layer from which you can work.
71 See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
72 section for some general resources.
73 You can also see the
74 "<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section
75 of the Yocto Project Development Manual for a detailed
76 example.
77 </para>
78
79 <section id='creating-the-append-file'>
80 <title>Creating the Append File</title>
81
82 <para>
83 You create this file in your custom layer.
84 You also name it accordingly based on the linux-yocto recipe
85 you are using.
86 For example, if you are modifying the
87 <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename>
88 recipe, the append file will typical be located as follows
89 within your custom layer:
90 <literallayout class='monospaced'>
91 &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto_3.4.bbappend
92 </literallayout>
93 The append file should initially extend the
94 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
95 search path by prepending the directory that contains your
96 files to the
97 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
98 variable as follows:
99 <literallayout class='monospaced'>
100 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
101 </literallayout>
102 The path <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
103 expands to "linux-yocto" in the current directory for this
104 example.
105 If you add any new files that modify the kernel recipe and you
106 have extended <filename>FILESPATH</filename> as
107 described above, you must place the files in your layer in the
108 following area:
109 <literallayout class='monospaced'>
110 &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto/
111 </literallayout>
112 <note>If you are working on a new machine Board Support Package
113 (BSP), be sure to refer to the
114 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
115 </note>
116 </para>
117 </section>
118
119 <section id='applying-patches'>
120 <title>Applying Patches</title>
121
122 <para>
123 If you have a single patch or a small series of patches
124 that you want to apply to the Linux kernel source, you
125 can do so just as you would with any other recipe.
126 You first copy the patches to the path added to
127 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
128 in your <filename>.bbappend</filename> file as described in
129 the previous section, and then reference them in
130 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
131 statements.
132 </para>
133
134 <para>
135 For example, you can apply a three-patch series by adding the
136 following lines to your linux-yocto <filename>.bbappend</filename>
137 file in your layer:
138 <literallayout class='monospaced'>
139 SRC_URI += "file://0001-first-change.patch"
140 SRC_URI += "file://0002-first-change.patch"
141 SRC_URI += "file://0003-first-change.patch"
142 </literallayout>
143 The next time you run BitBake to build the Linux kernel, BitBake
144 detects the change in the recipe and fetches and applies the patches
145 before building the kernel.
146 </para>
147
148 <para>
149 For a detailed example showing how to patch the kernel, see the
150 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
151 section in the Yocto Project Development Manual.
152 </para>
153 </section>
154
155 <section id='changing-the-configuration'>
156 <title>Changing the Configuration</title>
157
158 <para>
159 You can make wholesale or incremental changes to the Linux
160 kernel <filename>.config</filename> file by including a
161 <filename>defconfig</filename> and by specifying
162 configuration fragments in the
163 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
164 </para>
165
166 <para>
167 If you have a final Linux kernel <filename>.config</filename>
168 file you want to use, copy it to a directory named
169 <filename>files</filename>, which must be in
170 your layer's <filename>recipes-kernel/linux</filename>
171 directory, and name the file "defconfig".
172 Then, add the following lines to your linux-yocto
173 <filename>.bbappend</filename> file in your layer:
174 <literallayout class='monospaced'>
175 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
176 SRC_URI += "file://defconfig"
177 </literallayout>
178 The <filename>SRC_URI</filename> tells the build system how to
179 search for the file, while the
180 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
181 extends the
182 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
183 variable (search directories) to include the
184 <filename>files</filename> directory you created for the
185 configuration changes.
186 </para>
187
188 <note>
189 The build system applies the configurations from the
190 <filename>.config</filename> file before applying any
191 subsequent configuration fragments.
192 The final kernel configuration is a combination of the
193 configurations in the <filename>.config</filename> file and
194 any configuration fragments you provide.
195 You need to realize that if you have any configuration
196 fragments, the build system applies these on top of and
197 after applying the existing <filename>.config</filename>
198 file configurations.
199 </note>
200
201 <para>
202 Generally speaking, the preferred approach is to determine the
203 incremental change you want to make and add that as a
204 configuration fragment.
205 For example, if you want to add support for a basic serial
206 console, create a file named <filename>8250.cfg</filename> in
207 the <filename>files</filename> directory with the following
208 content (without indentation):
209 <literallayout class='monospaced'>
210 CONFIG_SERIAL_8250=y
211 CONFIG_SERIAL_8250_CONSOLE=y
212 CONFIG_SERIAL_8250_PCI=y
213 CONFIG_SERIAL_8250_NR_UARTS=4
214 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
215 CONFIG_SERIAL_CORE=y
216 CONFIG_SERIAL_CORE_CONSOLE=y
217 </literallayout>
218 Next, include this configuration fragment and extend the
219 <filename>FILESPATH</filename> variable in your
220 <filename>.bbappend</filename> file:
221 <literallayout class='monospaced'>
222 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
223 SRC_URI += "file://8250.cfg"
224 </literallayout>
225 The next time you run BitBake to build the Linux kernel, BitBake
226 detects the change in the recipe and fetches and applies the
227 new configuration before building the kernel.
228 </para>
229
230 <para>
231 For a detailed example showing how to configure the kernel,
232 see the
233 "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
234 section in the Yocto Project Development Manual.
235 </para>
236 </section>
237 </section>
238
239 <section id='using-an-iterative-development-process'>
240 <title>Using an Iterative Development Process</title>
241
242 <para>
243 If you do not have existing patches or configuration files,
244 you can iteratively generate them from within the BitBake build
245 environment as described within this section.
246 During an iterative workflow, running a previously completed BitBake
247 task causes BitBake to invalidate the tasks that follow the
248 completed task in the build sequence.
249 Invalidated tasks rebuild the next time you run the build using
250 BitBake.
251 </para>
252
253 <para>
254 As you read this section, be sure to substitute the name
255 of your Linux kernel recipe for the term
256 "linux-yocto".
257 </para>
258
259 <section id='tip-dirty-string'>
260 <title>"-dirty" String</title>
261
262<!--
263 <para>
264 <emphasis>AR - Darrren Hart:</emphasis> This section
265 originated from the old Yocto Project Kernel Architecture
266 and Use Manual.
267 It was decided we need to put it in this section here.
268 Darren needs to figure out where we want it and what part
269 of it we want (all, revision???)
270 </para>
271-->
272
273 <para>
274 If kernel images are being built with "-dirty" on the
275 end of the version string, this simply means that
276 modifications in the source directory have not been committed.
277 <literallayout class='monospaced'>
278 $ git status
279 </literallayout>
280 </para>
281
282 <para>
283 You can use the above Git command to report modified,
284 removed, or added files.
285 You should commit those changes to the tree regardless of
286 whether they will be saved, exported, or used.
287 Once you commit the changes, you need to rebuild the kernel.
288 </para>
289
290 <para>
291 To force a pickup and commit of all such pending changes,
292 enter the following:
293 <literallayout class='monospaced'>
294 $ git add .
295 $ git commit -s -a -m "getting rid of -dirty"
296 </literallayout>
297 </para>
298
299 <para>
300 Next, rebuild the kernel.
301 </para>
302 </section>
303
304 <section id='generating-configuration-files'>
305 <title>Generating Configuration Files</title>
306
307 <para>
308 You can manipulate the <filename>.config</filename> file
309 used to build a linux-yocto recipe with the
310 <filename>menuconfig</filename> command as follows:
311 <literallayout class='monospaced'>
312 $ bitbake linux-yocto -c menuconfig
313 </literallayout>
314 This command starts the Linux kernel configuration tool,
315 which allows you to prepare a new
316 <filename>.config</filename> file for the build.
317 When you exit the tool, be sure to save your changes
318 at the prompt.
319 </para>
320
321 <para>
322 The resulting <filename>.config</filename> file is
323 located in
324 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> under the
325 <filename>linux-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink><filename>}-${<ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>}-build</filename> directory.
326 You can use the entire <filename>.config</filename> file as the
327 <filename>defconfig</filename> file as described in the
328 "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section.
329 </para>
330
331 <para>
332 A better method is to create a configuration fragment using the
333 differences between two configuration files: one previously
334 created and saved, and one freshly created using the
335 <filename>menuconfig</filename> tool.
336 </para>
337
338 <para>
339 To create a configuration fragment using this method, follow
340 these steps:
341 <orderedlist>
342 <listitem><para>Complete a build at least through the kernel
343 configuration task as follows:
344 <literallayout class='monospaced'>
345 $ bitbake linux-yocto -c kernel_configme -f
346 </literallayout></para></listitem>
347 <listitem><para>Run the <filename>menuconfig</filename>
348 command:
349 <literallayout class='monospaced'>
350 $ bitbake linux-yocto -c menuconfig
351 </literallayout></para></listitem>
352 <listitem><para>Run the <filename>diffconfig</filename>
353 command to prepare a configuration fragment.
354 The resulting file <filename>fragment.cfg</filename>
355 will be placed in the
356 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> directory:
357 <literallayout class='monospaced'>
358 $ bitbake linux-yocto -c diffconfig
359 </literallayout></para></listitem>
360 </orderedlist>
361 </para>
362
363 <para>
364 The <filename>diffconfig</filename> command creates a file that is a
365 list of Linux kernel <filename>CONFIG_</filename> assignments.
366 See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
367 section for information on how to use the output as a
368 configuration fragment.
369 <note>
370 You can also use this method to create configuration
371 fragments for a BSP.
372 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
373 section for more information.
374 </note>
375 </para>
376
377 <para>
378 The kernel tools also provide configuration validation.
379 You can use these tools to produce warnings for when a
380 requested configuration does not appear in the final
381 <filename>.config</filename> file or when you override a
382 policy configuration in a hardware configuration fragment.
383 Here is an example with some sample output of the command
384 that runs these tools:
385 <literallayout class='monospaced'>
386 $ bitbake linux-yocto -c kernel_configcheck -f
387
388 ...
389
390 NOTE: validating kernel configuration
391 This BSP sets 3 invalid/obsolete kernel options.
392 These config options are not offered anywhere within this kernel.
393 The full list can be found in your kernel src dir at:
394 meta/cfg/standard/mybsp/invalid.cfg
395
396 This BSP sets 21 kernel options that are possibly non-hardware related.
397 The full list can be found in your kernel src dir at:
398 meta/cfg/standard/mybsp/specified_non_hdw.cfg
399
400 WARNING: There were 2 hardware options requested that do not
401 have a corresponding value present in the final ".config" file.
402 This probably means you are not't getting the config you wanted.
403 The full list can be found in your kernel src dir at:
404 meta/cfg/standard/mybsp/mismatch.cfg
405 </literallayout>
406 </para>
407
408 <para>
409 The output describes the various problems that you can
410 encounter along with where to find the offending configuration
411 items.
412 You can use the information in the logs to adjust your
413 configuration files and then repeat the
414 <filename>kernel_configme</filename> and
415 <filename>kernel_configcheck</filename> commands until
416 they produce no warnings.
417 </para>
418
419 <para>
420 For more information on how to use the
421 <filename>menuconfig</filename> tool, see the
422 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
423 section in the Yocto Project Development Manual.
424 </para>
425 </section>
426
427 <section id='modifying-source-code'>
428 <title>Modifying Source Code</title>
429
430 <para>
431 You can experiment with source code changes and create a
432 simple patch without leaving the BitBake environment.
433 To get started, be sure to complete a build at
434 least through the kernel configuration task:
435 <literallayout class='monospaced'>
436 $ bitbake linux-yocto -c kernel_configme -f
437 </literallayout>
438 Taking this step ensures you have the sources prepared
439 and the configuration completed.
440 You can find the sources in the
441 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/linux</filename> directory.
442 </para>
443
444 <para>
445 You can edit the sources as you would any other Linux source
446 tree.
447 However, keep in mind that you will lose changes if you
448 trigger the <filename>fetch</filename> task for the recipe.
449 You can avoid triggering this task by not issuing BitBake's
450 <filename>cleanall</filename>, <filename>cleansstate</filename>,
451 or forced <filename>fetch</filename> commands.
452 Also, do not modify the recipe itself while working
453 with temporary changes or BitBake might run the
454 <filename>fetch</filename> command depending on the
455 changes to the recipe.
456 </para>
457
458 <para>
459 To test your temporary changes, instruct BitBake to run the
460 <filename>compile</filename> again.
461 The <filename>-f</filename> option forces the command to run
462 even though BitBake might think it has already done so:
463 <literallayout class='monospaced'>
464 $ bitbake linux-yocto -c compile -f
465 </literallayout>
466 If the compile fails, you can update the sources and repeat
467 the <filename>compile</filename>.
468 Once compilation is successful, you can inspect and test
469 the resulting build (i.e. kernel, modules, and so forth) from
470 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
471 <literallayout class='monospaced'>
472 ${WORKDIR}/linux-${MACHINE}-${KTYPE}-build
473 </literallayout>
474 Alternatively, you can run the <filename>deploy</filename>
475 command to place the kernel image in the
476 <filename>tmp/deploy/images</filename> directory:
477 <literallayout class='monospaced'>
478 $ bitbake linux-yocto -c deploy
479 </literallayout>
480 And, of course, you can perform the remaining installation and
481 packaging steps by issuing:
482 <literallayout class='monospaced'>
483 $ bitbake linux-yocto
484 </literallayout>
485 </para>
486
487 <para>
488 For rapid iterative development, the edit-compile-repeat loop
489 described in this section is preferable to rebuilding the
490 entire recipe because the installation and packaging tasks
491 are very time consuming.
492 </para>
493
494 <para>
495 Once you are satisfied with your source code modifications,
496 you can make them permanent by generating patches and
497 applying them to the
498 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
499 statement as described in section
500 "<link linkend='applying-patches'>Applying Patches</link>" section.
501 If you are not familiar with generating patches, refer to the
502 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>"
503 section in the Yocto Project Development Manual.
504 </para>
505 </section>
506 </section>
507
508 <section id='working-with-your-own-sources'>
509 <title>Working With Your Own Sources</title>
510
511 <para>
512 If you cannot work with one of the Linux kernel
513 versions supported by existing linux-yocto recipes, you can
514 still make use of the Yocto Project Linux kernel tooling by
515 working with your own sources.
516 When you use your own sources, you will not be able to
517 leverage the existing kernel
518 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> and
519 stabilization work of the linux-yocto sources.
520 However, you will be able to manage your own Metadata in the same
521 format as the linux-yocto sources.
522 Maintaining format compatibility facilitates converging with
523 linux-yocto on a future, mutually-supported kernel version.
524 </para>
525
526 <para>
527 To help you use your own sources, the Yocto Project provides a
528 linux-yocto custom recipe
529 (<filename>linux-yocto-custom.bb</filename>) that uses
530 <filename>kernel.org</filename> sources
531 and the Yocto Project Linux kernel tools for managing
532 kernel Metadata.
533 You can find this recipe in the
534 <filename>poky</filename> Git repository of the
535 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
536 at:
537 <literallayout class="monospaced">
538 poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
539 </literallayout>
540 </para>
541
542 <para>
543 Here are some basic steps you can use to work with your own sources:
544 <orderedlist>
545 <listitem><para>Copy the <filename>linux-yocto-custom.bb</filename>
546 recipe to your layer and give it a meaningful name.
547 The name should include the version of the Linux kernel you
548 are using (e.g. <filename>linux-yocto-myproject_3.5.bb</filename>,
549 where "3.5" is the base version of the Linux kernel
550 with which you would be working).</para></listitem>
551 <listitem><para>In the same directory inside your layer,
552 create a matching directory
553 to store your patches and configuration files (e.g.
554 <filename>linux-yocto-myproject</filename>).
555 </para></listitem>
556 <listitem><para>Edit the following variables in your recipe
557 as appropriate for your project:
558 <itemizedlist>
559 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>:
560 The <filename>SRC_URI</filename> should be a Git
561 repository that uses one of the supported Git fetcher
562 protocols (i.e. <filename>file</filename>,
563 <filename>git</filename>, <filename>http</filename>,
564 and so forth).
565 The skeleton recipe provides an example
566 <filename>SRC_URI</filename> as a syntax reference.
567 </para></listitem>
568 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
569 The Linux kernel version you are using (e.g.
570 "3.4").</para></listitem>
571 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>:
572 The Linux kernel <filename>CONFIG_LOCALVERSION</filename>
573 that is compiled into the resulting kernel and visible
574 through the <filename>uname</filename> command.
575 </para></listitem>
576 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
577 The commit ID from which you want to build.
578 </para></listitem>
579 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
580 Treat this variable the same as you would in any other
581 recipe.
582 Increment the variable to indicate to the OpenEmbedded
583 build system that the recipe has changed.
584 </para></listitem>
585 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
586 The default <filename>PV</filename> assignment is
587 typically adequate.
588 It combines the <filename>LINUX_VERSION</filename>
589 with the Source Control Manager (SCM) revision
590 as derived from the
591 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>
592 variable.
593 The combined results are a string with
594 the following form:
595 <literallayout class='monospaced'>
596 3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
597 </literallayout>
598 While lengthy, the extra verbosity in <filename>PV</filename>
599 helps ensure you are using the exact
600 sources from which you intend to build.
601 </para></listitem>
602 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
603 A list of the machines supported by your new recipe.
604 This variable in the example recipe is set
605 by default to a regular expression that matches
606 only the empty string, "(^$)".
607 This default setting triggers an explicit build
608 failure.
609 You must change it to match a list of the machines
610 that your new recipe supports.
611 For example, to support the <filename>qemux86</filename>
612 and <filename>qemux86-64</filename> machines, use
613 the following form:
614 <literallayout class='monospaced'>
615 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
616 </literallayout></para></listitem>
617 </itemizedlist></para></listitem>
618 <listitem><para>Provide further customizations to your recipe
619 as needed just as you would customize an existing
620 linux-yocto recipe.
621 See the "<link linkend='modifying-an-existing-recipe'>Modifying
622 an Existing Recipe</link>" section for information.
623 </para></listitem>
624 </orderedlist>
625 </para>
626 </section>
627
628 <section id='incorporating-out-of-tree-modules'>
629 <title>Incorporating Out-of-Tree Modules</title>
630
631 <para>
632 While it is always preferable to work with sources integrated
633 into the Linux kernel sources, if you need an external kernel
634 module, the <filename>hello-mod.bb</filename> recipe is available
635 as a template from which you can create your own out-of-tree
636 Linux kernel module recipe.
637 </para>
638
639 <para>
640 This template recipe is located in the
641 <filename>poky</filename> Git repository of the
642 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
643 at:
644 <literallayout class="monospaced">
645 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
646 </literallayout>
647 </para>
648
649 <para>
650 To get started, copy this recipe to your layer and give it a
651 meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
652 In the same directory, create a directory named
653 <filename>files</filename> where you can store any source files,
654 patches, or other files necessary for building
655 the module that do not come with the sources.
656 Finally, update the recipe as appropriate for the module.
657 Typically you will need to set the following variables:
658 <itemizedlist>
659 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
660 </para></listitem>
661 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
662 </para></listitem>
663 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
664 </para></listitem>
665 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
666 </para></listitem>
667 </itemizedlist>
668 </para>
669
670 <para>
671 Depending on the build system used by the module sources, you might
672 need to make some adjustments.
673 For example, a typical module <filename>Makefile</filename> looks
674 much like the one provided with the <filename>hello-mod</filename>
675 template:
676 <literallayout class='monospaced'>
677 obj-m := hello.o
678
679 SRC := $(shell pwd)
680
681 all:
682 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
683
684 modules_install:
685 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
686 ...
687 </literallayout>
688 </para>
689
690 <para>
691 The important point to note here is the
692 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
693 variable.
694 The class <filename>module.bbclass</filename> sets this variable,
695 as well as the
696 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
697 variable to
698 <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
699 with the necessary Linux kernel build information to build modules.
700 If your module <filename>Makefile</filename> uses a different
701 variable, you might want to override the
702 <filename>do_compile()</filename> step, or create a patch to
703 the <filename>Makefile</filename> to work with the more typical
704 <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename>
705 variables.
706 </para>
707
708 <para>
709 After you have prepared your recipe, you will likely want to
710 include the module in your images.
711 To do this, see the documentation for the following variables in
712 the Yocto Project Reference Manual and set one of them as
713 appropriate in your machine configuration file:
714 <itemizedlist>
715 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
716 </para></listitem>
717 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
718 </para></listitem>
719 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
720 </para></listitem>
721 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
722 </para></listitem>
723 </itemizedlist>
724 </para>
725
726 <para>
727 modules are often not required for boot and can be excluded from
728 certain build configurations.
729 The following allows for the most flexibility:
730 <literallayout class='monospaced'>
731 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
732 </literallayout>
733 Where the value is derived by appending the module filename without
734 the <filename>.ko</filename> extension to the string
735 "kernel-module-".
736 </para>
737
738 <para>
739 Because the variable is
740 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
741 and not a
742 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
743 variable, the build will not fail if this module is not available
744 to include in the image.
745 </para>
746 </section>
747
748 <section id='inspecting-changes-and-commits'>
749 <title>Inspecting Changes and Commits</title>
750
751 <para>
752 A common question when working with a kernel is:
753 "What changes have been applied to this tree?"
754 Rather than using "grep" across directories to see what has
755 changed, you can use Git to inspect or search the kernel tree.
756 Using Git is an efficient way to see what has changed in the tree.
757 </para>
758
759 <section id='what-changed-in-a-kernel'>
760 <title>What Changed in a Kernel?</title>
761
762 <para>
763 Following are a few examples that show how to use Git
764 commands to examine changes.
765 These examples are by no means the only way to see changes.
766 <note>
767 In the following examples, unless you provide a commit
768 range, <filename>kernel.org</filename> history is blended
769 with Yocto Project kernel changes.
770 You can form ranges by using branch names from the
771 kernel tree as the upper and lower commit markers with
772 the Git commands.
773 You can see the branch names through the web interface
774 to the Yocto Project source repositories at
775 <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
776 </note>
777 To see a full range of the changes, use the
778 <filename>git whatchanged</filename> command and specify a
779 commit range for the branch
780 (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
781 </para>
782
783 <para>
784 Here is an example that looks at what has changed in the
785 <filename>emenlow</filename> branch of the
786 <filename>linux-yocto-3.4</filename> kernel.
787 The lower commit range is the commit associated with the
788 <filename>standard/base</filename> branch, while
789 the upper commit range is the commit associated with the
790 <filename>standard/emenlow</filename> branch.
791 <literallayout class='monospaced'>
792 $ git whatchanged origin/standard/base..origin/standard/emenlow
793 </literallayout>
794 </para>
795
796 <para>
797 To see short, one line summaries of changes use the
798 <filename>git log</filename> command:
799 <literallayout class='monospaced'>
800 $ git log --oneline origin/standard/base..origin/standard/emenlow
801 </literallayout>
802 </para>
803
804 <para>
805 Use this command to see code differences for the changes:
806 <literallayout class='monospaced'>
807 $ git diff origin/standard/base..origin/standard/emenlow
808 </literallayout>
809 </para>
810
811 <para>
812 Use this command to see the commit log messages and the
813 text differences:
814 <literallayout class='monospaced'>
815 $ git show origin/standard/base..origin/standard/emenlow
816 </literallayout>
817 </para>
818
819 <para>
820 Use this command to create individual patches for
821 each change.
822 Here is an example that that creates patch files for each
823 commit and places them in your <filename>Documents</filename>
824 directory:
825 <literallayout class='monospaced'>
826 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
827 </literallayout>
828 </para>
829 </section>
830
831 <section id='showing-a-particular-feature-or-branch-change'>
832 <title>Showing a Particular Feature or Branch Change</title>
833
834 <para>
835 Tags in the Yocto Project kernel tree divide changes for
836 significant features or branches.
837 The <filename>git show &lt;tag&gt;</filename> command shows
838 changes based on a tag.
839 Here is an example that shows <filename>systemtap</filename>
840 changes:
841 <literallayout class='monospaced'>
842 $ git show systemtap
843 </literallayout>
844 You can use the
845 <filename>git branch --contains &lt;tag&gt;</filename> command
846 to show the branches that contain a particular feature.
847 This command shows the branches that contain the
848 <filename>systemtap</filename> feature:
849 <literallayout class='monospaced'>
850 $ git branch --contains systemtap
851 </literallayout>
852 </para>
853 </section>
854 </section>
855</chapter>
856<!--
857vim: expandtab tw=80 ts=4
858-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-24 21:09:04 +0000