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