blob: aa40fc852a86d6d13bc82576c61fb4f6f77babd6 [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!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>).
Brad Bishop6e60e8b2018-02-01 10:27:11 -050034 For details on how to create and work with layers, see the
35 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
36 section in the Yocto Project Development Manual.
37 <note><title>Tip</title>
38 The Yocto Project comes with many tools that simplify
39 tasks you need to perform.
40 One such tool is the <filename>yocto-layer create</filename>
41 script, which simplifies creating a new layer.
42 See the
43 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
44 section in the Yocto Project Development Manual for more
45 information.
46 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050047 </para>
48 </section>
49
50 <section id='modifying-an-existing-recipe'>
51 <title>Modifying an Existing Recipe</title>
52
53 <para>
54 In many cases, you can customize an existing linux-yocto recipe to
55 meet the needs of your project.
56 Each release of the Yocto Project provides a few Linux
57 kernel recipes from which you can choose.
58 These are located in the
59 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
60 in <filename>meta/recipes-kernel/linux</filename>.
61 </para>
62
63 <para>
64 Modifying an existing recipe can consist of the following:
65 <itemizedlist>
66 <listitem><para>Creating the append file</para></listitem>
67 <listitem><para>Applying patches</para></listitem>
68 <listitem><para>Changing the configuration</para></listitem>
69 </itemizedlist>
70 </para>
71
72 <para>
73 Before modifying an existing recipe, be sure that you have created
74 a minimal, custom layer from which you can work.
75 See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
76 section for some general resources.
77 You can also see the
78 "<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section
79 of the Yocto Project Development Manual for a detailed
80 example.
81 </para>
82
83 <section id='creating-the-append-file'>
84 <title>Creating the Append File</title>
85
86 <para>
87 You create this file in your custom layer.
88 You also name it accordingly based on the linux-yocto recipe
89 you are using.
90 For example, if you are modifying the
Brad Bishop6e60e8b2018-02-01 10:27:11 -050091 <filename>meta/recipes-kernel/linux/linux-yocto_4.4.bb</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050092 recipe, the append file will typically be located as follows
93 within your custom layer:
94 <literallayout class='monospaced'>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050095 <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.4.bbappend
Patrick Williamsc124f4f2015-09-15 14:41:29 -050096 </literallayout>
97 The append file should initially extend the
98 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
99 search path by prepending the directory that contains your
100 files to the
101 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
102 variable as follows:
103 <literallayout class='monospaced'>
104 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
105 </literallayout>
106 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>
107 expands to "linux-yocto" in the current directory for this
108 example.
109 If you add any new files that modify the kernel recipe and you
110 have extended <filename>FILESPATH</filename> as
111 described above, you must place the files in your layer in the
112 following area:
113 <literallayout class='monospaced'>
114 <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto/
115 </literallayout>
116 <note>If you are working on a new machine Board Support Package
117 (BSP), be sure to refer to the
118 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
119 </note>
120 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500121
122 <para>
123 As an example, consider the following append file
124 used by the BSPs in <filename>meta-yocto-bsp</filename>:
125 <literallayout class='monospaced'>
126 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend
127 </literallayout>
128 The following listing shows the file.
129 Be aware that the actual commit ID strings in this
130 example listing might be different than the actual strings
131 in the file from the <filename>meta-yocto-bsp</filename>
132 layer upstream.
133 <literallayout class='monospaced'>
134 KBRANCH_genericx86 = "standard/base"
135 KBRANCH_genericx86-64 = "standard/base"
136
137 KMACHINE_genericx86 ?= "common-pc"
138 KMACHINE_genericx86-64 ?= "common-pc-64"
139 KBRANCH_edgerouter = "standard/edgerouter"
140 KBRANCH_beaglebone = "standard/beaglebone"
141 KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
142
143 SRCREV_machine_genericx86 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2"
144 SRCREV_machine_genericx86-64 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2"
145 SRCREV_machine_edgerouter ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c"
146 SRCREV_machine_beaglebone ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c"
147 SRCREV_machine_mpc8315e-rdb ?= "06c0dbdcba374ca7f92a53d69292d6bb7bc9b0f3"
148
149 COMPATIBLE_MACHINE_genericx86 = "genericx86"
150 COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
151 COMPATIBLE_MACHINE_edgerouter = "edgerouter"
152 COMPATIBLE_MACHINE_beaglebone = "beaglebone"
153 COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
154
155 LINUX_VERSION_genericx86 = "4.4.41"
156 LINUX_VERSION_genericx86-64 = "4.4.41"
157 LINUX_VERSION_edgerouter = "4.4.53"
158 LINUX_VERSION_beaglebone = "4.4.53"
159 LINUX_VERSION_mpc8315e-rdb = "4.4.53"
160 </literallayout>
161 This append file contains statements used to support
162 several BSPs that ship with the Yocto Project.
163 The file defines machines using the
164 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
165 variable and uses the
166 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
167 variable to ensure the machine name used by the OpenEmbedded
168 build system maps to the machine name used by the Linux Yocto
169 kernel.
170 The file also uses the optional
171 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
172 variable to ensure the build process uses the
173 appropriate kernel branch.
174 </para>
175
176 <para>
177 Although this particular example does not use it, the
178 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
179 variable could be used to enable features specific to
180 the kernel.
181 The append file points to specific commits in the
182 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
183 Git repository and the <filename>meta</filename> Git repository
184 branches to identify the exact kernel needed to build the
185 BSP.
186 </para>
187
188 <para>
189 One thing missing in this particular BSP, which you will
190 typically need when developing a BSP, is the kernel configuration
191 file (<filename>.config</filename>) for your BSP.
192 When developing a BSP, you probably have a kernel configuration
193 file or a set of kernel configuration files that, when taken
194 together, define the kernel configuration for your BSP.
195 You can accomplish this definition by putting the configurations
196 in a file or a set of files inside a directory located at the
197 same level as your kernel's append file and having the same
198 name as the kernel's main recipe file.
199 With all these conditions met, simply reference those files in the
200 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
201 statement in the append file.
202 </para>
203
204 <para>
205 For example, suppose you had some configuration options
206 in a file called <filename>network_configs.cfg</filename>.
207 You can place that file inside a directory named
208 <filename>linux-yocto</filename> and then add
209 a <filename>SRC_URI</filename> statement such as the
210 following to the append file.
211 When the OpenEmbedded build system builds the kernel, the
212 configuration options are picked up and applied.
213 <literallayout class='monospaced'>
214 SRC_URI += "file://network_configs.cfg"
215 </literallayout>
216 </para>
217
218 <para>
219 To group related configurations into multiple files, you
220 perform a similar procedure.
221 Here is an example that groups separate configurations
222 specifically for Ethernet and graphics into their own
223 files and adds the configurations by using a
224 <filename>SRC_URI</filename> statement like the following
225 in your append file:
226 <literallayout class='monospaced'>
227 SRC_URI += "file://myconfig.cfg \
228 file://eth.cfg \
229 file://gfx.cfg"
230 </literallayout>
231 </para>
232
233 <para>
234 Another variable you can use in your kernel recipe append
235 file is the
236 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
237 variable.
238 When you use this statement, you are extending the locations
239 used by the OpenEmbedded system to look for files and
240 patches as the recipe is processed.
241 </para>
242
243 <note>
244 <para>
245 Other methods exist to accomplish grouping and defining configuration options.
246 For example, if you are working with a local clone of the kernel repository,
247 you could checkout the kernel's <filename>meta</filename> branch, make your changes,
248 and then push the changes to the local bare clone of the kernel.
249 The result is that you directly add configuration options to the
250 <filename>meta</filename> branch for your BSP.
251 The configuration options will likely end up in that location anyway if the BSP gets
252 added to the Yocto Project.
253 </para>
254
255 <para>
256 In general, however, the Yocto Project maintainers take care of moving the
257 <filename>SRC_URI</filename>-specified
258 configuration options to the kernel's <filename>meta</filename> branch.
259 Not only is it easier for BSP developers to not have to worry about putting those
260 configurations in the branch, but having the maintainers do it allows them to apply
261 'global' knowledge about the kinds of common configuration options multiple BSPs in
262 the tree are typically using.
263 This allows for promotion of common configurations into common features.
264 </para>
265 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500266 </section>
267
268 <section id='applying-patches'>
269 <title>Applying Patches</title>
270
271 <para>
272 If you have a single patch or a small series of patches
273 that you want to apply to the Linux kernel source, you
274 can do so just as you would with any other recipe.
275 You first copy the patches to the path added to
276 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
277 in your <filename>.bbappend</filename> file as described in
278 the previous section, and then reference them in
279 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
280 statements.
281 </para>
282
283 <para>
284 For example, you can apply a three-patch series by adding the
285 following lines to your linux-yocto
286 <filename>.bbappend</filename> file in your layer:
287 <literallayout class='monospaced'>
288 SRC_URI += "file://0001-first-change.patch"
289 SRC_URI += "file://0002-second-change.patch"
290 SRC_URI += "file://0003-third-change.patch"
291 </literallayout>
292 The next time you run BitBake to build the Linux kernel,
293 BitBake detects the change in the recipe and fetches and
294 applies the patches before building the kernel.
295 </para>
296
297 <para>
298 For a detailed example showing how to patch the kernel, see the
299 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
300 section in the Yocto Project Development Manual.
301 </para>
302 </section>
303
304 <section id='changing-the-configuration'>
305 <title>Changing the Configuration</title>
306
307 <para>
308 You can make wholesale or incremental changes to the final
309 <filename>.config</filename> file used for the eventual
310 Linux kernel configuration by including a
311 <filename>defconfig</filename> file and by specifying
312 configuration fragments in the
313 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
314 to be applied to that file.
315 </para>
316
317 <para>
318 If you have a complete, working Linux kernel
319 <filename>.config</filename>
320 file you want to use for the configuration, as before, copy
321 that file to the appropriate <filename>${PN}</filename>
322 directory in your layer's
323 <filename>recipes-kernel/linux</filename> directory,
324 and rename the copied file to "defconfig".
325 Then, add the following lines to the linux-yocto
326 <filename>.bbappend</filename> file in your layer:
327 <literallayout class='monospaced'>
328 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
329 SRC_URI += "file://defconfig"
330 </literallayout>
331 The <filename>SRC_URI</filename> tells the build system how to
332 search for the file, while the
333 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
334 extends the
335 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
336 variable (search directories) to include the
337 <filename>${PN}</filename> directory you created to hold the
338 configuration changes.
339 </para>
340
341 <note>
342 The build system applies the configurations from the
343 <filename>defconfig</filename> file before applying any
344 subsequent configuration fragments.
345 The final kernel configuration is a combination of the
346 configurations in the <filename>defconfig</filename> file and
347 any configuration fragments you provide.
348 You need to realize that if you have any configuration
349 fragments, the build system applies these on top of and
350 after applying the existing <filename>defconfig</filename>
351 file configurations.
352 </note>
353
354 <para>
355 Generally speaking, the preferred approach is to determine the
356 incremental change you want to make and add that as a
357 configuration fragment.
358 For example, if you want to add support for a basic serial
359 console, create a file named <filename>8250.cfg</filename> in
360 the <filename>${PN}</filename> directory with the following
361 content (without indentation):
362 <literallayout class='monospaced'>
363 CONFIG_SERIAL_8250=y
364 CONFIG_SERIAL_8250_CONSOLE=y
365 CONFIG_SERIAL_8250_PCI=y
366 CONFIG_SERIAL_8250_NR_UARTS=4
367 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
368 CONFIG_SERIAL_CORE=y
369 CONFIG_SERIAL_CORE_CONSOLE=y
370 </literallayout>
371 Next, include this configuration fragment and extend the
372 <filename>FILESPATH</filename> variable in your
373 <filename>.bbappend</filename> file:
374 <literallayout class='monospaced'>
375 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
376 SRC_URI += "file://8250.cfg"
377 </literallayout>
378 The next time you run BitBake to build the Linux kernel, BitBake
379 detects the change in the recipe and fetches and applies the
380 new configuration before building the kernel.
381 </para>
382
383 <para>
384 For a detailed example showing how to configure the kernel,
385 see the
386 "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
387 section in the Yocto Project Development Manual.
388 </para>
389 </section>
390
391 <section id='using-an-in-tree-defconfig-file'>
392 <title>Using an "In-Tree"&nbsp;&nbsp;<filename>defconfig</filename> File</title>
393
394 <para>
395 It might be desirable to have kernel configuration fragment
396 support through a <filename>defconfig</filename> file that
397 is pulled from the kernel source tree for the configured
398 machine.
399 By default, the OpenEmbedded build system looks for
400 <filename>defconfig</filename> files in the layer used for
401 Metadata, which is "out-of-tree", and then configures them
402 using the following:
403 <literallayout class='monospaced'>
404 SRC_URI += "file://defconfig"
405 </literallayout>
406 If you do not want to maintain copies of
407 <filename>defconfig</filename> files in your layer but would
408 rather allow users to use the default configuration from the
409 kernel tree and still be able to add configuration fragments
410 to the
411 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
412 through, for example, append files, you can direct the
413 OpenEmbedded build system to use a
414 <filename>defconfig</filename> file that is "in-tree".
415 </para>
416
417 <para>
418 To specify an "in-tree" <filename>defconfig</filename> file,
419 edit the recipe that builds your kernel so that it has the
420 following command form:
421 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500422 KBUILD_DEFCONFIG_KMACHINE ?= <replaceable>defconfig_file</replaceable>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500423 </literallayout>
424 You need to append the variable with
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500425 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
426 and then supply the path to your "in-tree"
427 <filename>defconfig</filename> file.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500428 </para>
429
430 <para>
431 Aside from modifying your kernel recipe and providing your own
432 <filename>defconfig</filename> file, you need to be sure no
433 files or statements set <filename>SRC_URI</filename> to use a
434 <filename>defconfig</filename> other than your "in-tree"
435 file (e.g. a kernel's <filename>linux-</filename><replaceable>machine</replaceable><filename>.inc</filename>
436 file).
437 In other words, if the build system detects a statement
438 that identifies an "out-of-tree"
439 <filename>defconfig</filename> file, that statement
440 will override your
441 <filename>KBUILD_DEFCONFIG</filename> variable.
442 </para>
443
444 <para>
445 See the
446 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG'><filename>KBUILD_DEFCONFIG</filename></ulink>
447 variable description for more information.
448 </para>
449 </section>
450 </section>
451
452 <section id='using-an-iterative-development-process'>
453 <title>Using an Iterative Development Process</title>
454
455 <para>
456 If you do not have existing patches or configuration files,
457 you can iteratively generate them from within the BitBake build
458 environment as described within this section.
459 During an iterative workflow, running a previously completed BitBake
460 task causes BitBake to invalidate the tasks that follow the
461 completed task in the build sequence.
462 Invalidated tasks rebuild the next time you run the build using
463 BitBake.
464 </para>
465
466 <para>
467 As you read this section, be sure to substitute the name
468 of your Linux kernel recipe for the term
469 "linux-yocto".
470 </para>
471
472 <section id='tip-dirty-string'>
473 <title>"-dirty" String</title>
474
475<!--
476 <para>
477 <emphasis>AR - Darren Hart:</emphasis> This section
478 originated from the old Yocto Project Kernel Architecture
479 and Use Manual.
480 It was decided we need to put it in this section here.
481 Darren needs to figure out where we want it and what part
482 of it we want (all, revision???)
483 </para>
484-->
485
486 <para>
487 If kernel images are being built with "-dirty" on the
488 end of the version string, this simply means that
489 modifications in the source directory have not been committed.
490 <literallayout class='monospaced'>
491 $ git status
492 </literallayout>
493 </para>
494
495 <para>
496 You can use the above Git command to report modified,
497 removed, or added files.
498 You should commit those changes to the tree regardless of
499 whether they will be saved, exported, or used.
500 Once you commit the changes, you need to rebuild the kernel.
501 </para>
502
503 <para>
504 To force a pickup and commit of all such pending changes,
505 enter the following:
506 <literallayout class='monospaced'>
507 $ git add .
508 $ git commit -s -a -m "getting rid of -dirty"
509 </literallayout>
510 </para>
511
512 <para>
513 Next, rebuild the kernel.
514 </para>
515 </section>
516
517 <section id='generating-configuration-files'>
518 <title>Generating Configuration Files</title>
519
520 <para>
521 You can manipulate the <filename>.config</filename> file
522 used to build a linux-yocto recipe with the
523 <filename>menuconfig</filename> command as follows:
524 <literallayout class='monospaced'>
525 $ bitbake linux-yocto -c menuconfig
526 </literallayout>
527 This command starts the Linux kernel configuration tool,
528 which allows you to prepare a new
529 <filename>.config</filename> file for the build.
530 When you exit the tool, be sure to save your changes
531 at the prompt.
532 </para>
533
534 <para>
535 The resulting <filename>.config</filename> file is
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600536 located in the build directory,
537 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>,
538 which expands to
539 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500540 You can use the entire <filename>.config</filename> file as the
541 <filename>defconfig</filename> file as described in the
542 "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section.
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500543 For more information on the <filename>.config</filename> file,
544 see the
545 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
546 section in the Yocto Project Development Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600547 <note>
548 You can determine what a variable expands to by looking
549 at the output of the <filename>bitbake -e</filename>
550 command:
551 <literallayout class='monospaced'>
552 $ bitbake -e virtual/kernel
553 </literallayout>
554 Search the output for the variable in which you are
555 interested to see exactly how it is expanded and used.
556 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500557 </para>
558
559 <para>
560 A better method is to create a configuration fragment using the
561 differences between two configuration files: one previously
562 created and saved, and one freshly created using the
563 <filename>menuconfig</filename> tool.
564 </para>
565
566 <para>
567 To create a configuration fragment using this method, follow
568 these steps:
569 <orderedlist>
570 <listitem><para>Complete a build at least through the kernel
571 configuration task as follows:
572 <literallayout class='monospaced'>
573 $ bitbake linux-yocto -c kernel_configme -f
574 </literallayout>
575 This step ensures that you will be creating a
576 <filename>.config</filename> file from a known state.
577 Because situations exist where your build state might
578 become unknown, it is best to run the previous
579 command prior to starting up
580 <filename>menuconfig</filename>.
581 </para></listitem>
582 <listitem><para>Run the <filename>menuconfig</filename>
583 command:
584 <literallayout class='monospaced'>
585 $ bitbake linux-yocto -c menuconfig
586 </literallayout></para></listitem>
587 <listitem><para>Run the <filename>diffconfig</filename>
588 command to prepare a configuration fragment.
589 The resulting file <filename>fragment.cfg</filename>
590 will be placed in the
591 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> directory:
592 <literallayout class='monospaced'>
593 $ bitbake linux-yocto -c diffconfig
594 </literallayout></para></listitem>
595 </orderedlist>
596 </para>
597
598 <para>
599 The <filename>diffconfig</filename> command creates a file that is a
600 list of Linux kernel <filename>CONFIG_</filename> assignments.
601 See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
602 section for information on how to use the output as a
603 configuration fragment.
604 <note>
605 You can also use this method to create configuration
606 fragments for a BSP.
607 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
608 section for more information.
609 </note>
610 </para>
611
612 <para>
613 The kernel tools also provide configuration validation.
614 You can use these tools to produce warnings for when a
615 requested configuration does not appear in the final
616 <filename>.config</filename> file or when you override a
617 policy configuration in a hardware configuration fragment.
618 Here is an example with some sample output of the command
619 that runs these tools:
620 <literallayout class='monospaced'>
621 $ bitbake linux-yocto -c kernel_configcheck -f
622
623 ...
624
625 NOTE: validating kernel configuration
626 This BSP sets 3 invalid/obsolete kernel options.
627 These config options are not offered anywhere within this kernel.
628 The full list can be found in your kernel src dir at:
629 meta/cfg/standard/mybsp/invalid.cfg
630
631 This BSP sets 21 kernel options that are possibly non-hardware related.
632 The full list can be found in your kernel src dir at:
633 meta/cfg/standard/mybsp/specified_non_hdw.cfg
634
635 WARNING: There were 2 hardware options requested that do not
636 have a corresponding value present in the final ".config" file.
637 This probably means you are not getting the config you wanted.
638 The full list can be found in your kernel src dir at:
639 meta/cfg/standard/mybsp/mismatch.cfg
640 </literallayout>
641 </para>
642
643 <para>
644 The output describes the various problems that you can
645 encounter along with where to find the offending configuration
646 items.
647 You can use the information in the logs to adjust your
648 configuration files and then repeat the
649 <filename>kernel_configme</filename> and
650 <filename>kernel_configcheck</filename> commands until
651 they produce no warnings.
652 </para>
653
654 <para>
655 For more information on how to use the
656 <filename>menuconfig</filename> tool, see the
657 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
658 section in the Yocto Project Development Manual.
659 </para>
660 </section>
661
662 <section id='modifying-source-code'>
663 <title>Modifying Source Code</title>
664
665 <para>
666 You can experiment with source code changes and create a
667 simple patch without leaving the BitBake environment.
668 To get started, be sure to complete a build at
669 least through the kernel configuration task:
670 <literallayout class='monospaced'>
671 $ bitbake linux-yocto -c kernel_configme -f
672 </literallayout>
673 Taking this step ensures you have the sources prepared
674 and the configuration completed.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600675 You can find the sources in the build directory within the
676 <filename>source/</filename> directory, which is a symlink
677 (i.e. <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}/source</filename>).
678 The <filename>source/</filename> directory expands to
679 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build/source</filename>.
680 The directory pointed to by the
681 <filename>source/</filename> symlink is also known as
682 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink><filename>}</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500683 </para>
684
685 <para>
686 You can edit the sources as you would any other Linux source
687 tree.
688 However, keep in mind that you will lose changes if you
689 trigger the
690 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
691 task for the recipe.
692 You can avoid triggering this task by not using BitBake to
693 run the
694 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>cleanall</filename></ulink>,
695 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>cleansstate</filename></ulink>,
696 or forced
697 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>fetch</filename></ulink>
698 commands.
699 Also, do not modify the recipe itself while working
700 with temporary changes or BitBake might run the
701 <filename>fetch</filename> command depending on the
702 changes to the recipe.
703 </para>
704
705 <para>
706 To test your temporary changes, instruct BitBake to run the
707 <filename>compile</filename> again.
708 The <filename>-f</filename> option forces the command to run
709 even though BitBake might think it has already done so:
710 <literallayout class='monospaced'>
711 $ bitbake linux-yocto -c compile -f
712 </literallayout>
713 If the compile fails, you can update the sources and repeat
714 the <filename>compile</filename>.
715 Once compilation is successful, you can inspect and test
716 the resulting build (i.e. kernel, modules, and so forth) from
717 the following build directory:
718 <literallayout class='monospaced'>
719 ${WORKDIR}/linux-${PACKAGE_ARCH}-${LINUX_KERNEL_TYPE}-build
720 </literallayout>
721 Alternatively, you can run the <filename>deploy</filename>
722 command to place the kernel image in the
723 <filename>tmp/deploy/images</filename> directory:
724 <literallayout class='monospaced'>
725 $ bitbake linux-yocto -c deploy
726 </literallayout>
727 And, of course, you can perform the remaining installation and
728 packaging steps by issuing:
729 <literallayout class='monospaced'>
730 $ bitbake linux-yocto
731 </literallayout>
732 </para>
733
734 <para>
735 For rapid iterative development, the edit-compile-repeat loop
736 described in this section is preferable to rebuilding the
737 entire recipe because the installation and packaging tasks
738 are very time consuming.
739 </para>
740
741 <para>
742 Once you are satisfied with your source code modifications,
743 you can make them permanent by generating patches and
744 applying them to the
745 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
746 statement as described in the
747 "<link linkend='applying-patches'>Applying Patches</link>"
748 section.
749 If you are not familiar with generating patches, refer to the
750 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>"
751 section in the Yocto Project Development Manual.
752 </para>
753 </section>
754 </section>
755
756 <section id='working-with-your-own-sources'>
757 <title>Working With Your Own Sources</title>
758
759 <para>
760 If you cannot work with one of the Linux kernel
761 versions supported by existing linux-yocto recipes, you can
762 still make use of the Yocto Project Linux kernel tooling by
763 working with your own sources.
764 When you use your own sources, you will not be able to
765 leverage the existing kernel
766 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> and
767 stabilization work of the linux-yocto sources.
768 However, you will be able to manage your own Metadata in the same
769 format as the linux-yocto sources.
770 Maintaining format compatibility facilitates converging with
771 linux-yocto on a future, mutually-supported kernel version.
772 </para>
773
774 <para>
775 To help you use your own sources, the Yocto Project provides a
776 linux-yocto custom recipe
777 (<filename>linux-yocto-custom.bb</filename>) that uses
778 <filename>kernel.org</filename> sources
779 and the Yocto Project Linux kernel tools for managing
780 kernel Metadata.
781 You can find this recipe in the
782 <filename>poky</filename> Git repository of the
783 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
784 at:
785 <literallayout class="monospaced">
786 poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
787 </literallayout>
788 </para>
789
790 <para>
791 Here are some basic steps you can use to work with your own sources:
792 <orderedlist>
793 <listitem><para>Copy the <filename>linux-yocto-custom.bb</filename>
794 recipe to your layer and give it a meaningful name.
795 The name should include the version of the Linux kernel you
796 are using (e.g.
797 <filename>linux-yocto-myproject_3.19.bb</filename>,
798 where "3.19" is the base version of the Linux kernel
799 with which you would be working).</para></listitem>
800 <listitem><para>In the same directory inside your layer,
801 create a matching directory
802 to store your patches and configuration files (e.g.
803 <filename>linux-yocto-myproject</filename>).
804 </para></listitem>
805 <listitem><para>Make sure you have either a
806 <filename>defconfig</filename> file or configuration
807 fragment files.
808 When you use the <filename>linux-yocto-custom.bb</filename>
809 recipe, you must specify a configuration.
810 If you do not have a <filename>defconfig</filename> file,
811 you can run the following:
812 <literallayout class='monospaced'>
813 $ make defconfig
814 </literallayout>
815 After running the command, copy the resulting
816 <filename>.config</filename> to the
817 <filename>files</filename> directory as "defconfig" and
818 then add it to the
819 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
820 variable in the recipe.</para>
821 <para>Running the <filename>make defconfig</filename>
822 command results in the default configuration for your
823 architecture as defined by your kernel.
824 However, no guarantee exists that this configuration is
825 valid for your use case, or that your board will even boot.
826 This is particularly true for non-x86 architectures.
827 To use non-x86 <filename>defconfig</filename> files, you
828 need to be more specific and find one that matches your
829 board (i.e. for arm, you look in
830 <filename>arch/arm/configs</filename> and use the one that
831 is the best starting point for your board).
832 </para></listitem>
833 <listitem><para>Edit the following variables in your recipe
834 as appropriate for your project:
835 <itemizedlist>
836 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>:
837 The <filename>SRC_URI</filename> should specify
838 a Git repository that uses one of the supported Git
839 fetcher protocols (i.e. <filename>file</filename>,
840 <filename>git</filename>, <filename>http</filename>,
841 and so forth).
842 The <filename>SRC_URI</filename> variable should
843 also specify either a <filename>defconfig</filename>
844 file or some configuration fragment files.
845 The skeleton recipe provides an example
846 <filename>SRC_URI</filename> as a syntax reference.
847 </para></listitem>
848 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
849 The Linux kernel version you are using (e.g.
850 "3.19").</para></listitem>
851 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>:
852 The Linux kernel <filename>CONFIG_LOCALVERSION</filename>
853 that is compiled into the resulting kernel and visible
854 through the <filename>uname</filename> command.
855 </para></listitem>
856 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
857 The commit ID from which you want to build.
858 </para></listitem>
859 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
860 Treat this variable the same as you would in any other
861 recipe.
862 Increment the variable to indicate to the OpenEmbedded
863 build system that the recipe has changed.
864 </para></listitem>
865 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
866 The default <filename>PV</filename> assignment is
867 typically adequate.
868 It combines the <filename>LINUX_VERSION</filename>
869 with the Source Control Manager (SCM) revision
870 as derived from the
871 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>
872 variable.
873 The combined results are a string with
874 the following form:
875 <literallayout class='monospaced'>
876 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
877 </literallayout>
878 While lengthy, the extra verbosity in <filename>PV</filename>
879 helps ensure you are using the exact
880 sources from which you intend to build.
881 </para></listitem>
882 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
883 A list of the machines supported by your new recipe.
884 This variable in the example recipe is set
885 by default to a regular expression that matches
886 only the empty string, "(^$)".
887 This default setting triggers an explicit build
888 failure.
889 You must change it to match a list of the machines
890 that your new recipe supports.
891 For example, to support the <filename>qemux86</filename>
892 and <filename>qemux86-64</filename> machines, use
893 the following form:
894 <literallayout class='monospaced'>
895 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
896 </literallayout></para></listitem>
897 </itemizedlist></para></listitem>
898 <listitem><para>Provide further customizations to your recipe
899 as needed just as you would customize an existing
900 linux-yocto recipe.
901 See the "<link linkend='modifying-an-existing-recipe'>Modifying
902 an Existing Recipe</link>" section for information.
903 </para></listitem>
904 </orderedlist>
905 </para>
906 </section>
907
908 <section id='working-with-out-of-tree-modules'>
909 <title>Working with Out-of-Tree Modules</title>
910
911 <para>
912 This section describes steps to build out-of-tree modules on
913 your target and describes how to incorporate out-of-tree modules
914 in the build.
915 </para>
916
917 <section id='building-out-of-tree-modules-on-the-target'>
918 <title>Building Out-of-Tree Modules on the Target</title>
919
920 <para>
921 While the traditional Yocto Project development model would be
922 to include kernel modules as part of the normal build
923 process, you might find it useful to build modules on the
924 target.
925 This could be the case if your target system is capable
926 and powerful enough to handle the necessary compilation.
927 Before deciding to build on your target, however, you should
928 consider the benefits of using a proper cross-development
929 environment from your build host.
930 </para>
931
932 <para>
933 If you want to be able to build out-of-tree modules on
934 the target, there are some steps you need to take
935 on the target that is running your SDK image.
936 Briefly, the <filename>kernel-dev</filename> package
937 is installed by default on all
938 <filename>*.sdk</filename> images and the
939 <filename>kernel-devsrc</filename> package is installed
940 on many of the <filename>*.sdk</filename> images.
941 However, you need to create some scripts prior to
942 attempting to build the out-of-tree modules on the target
943 that is running that image.
944 </para>
945
946 <para>
947 Prior to attempting to build the out-of-tree modules,
948 you need to be on the target as root and you need to
949 change to the <filename>/usr/src/kernel</filename> directory.
950 Next, <filename>make</filename> the scripts:
951 <literallayout class='monospaced'>
952 # cd /usr/src/kernel
953 # make scripts
954 </literallayout>
955 Because all SDK image recipes include
956 <filename>dev-pkgs</filename>, the
957 <filename>kernel-dev</filename> packages will be installed
958 as part of the SDK image and the
959 <filename>kernel-devsrc</filename> packages will be installed
960 as part of applicable SDK images.
961 The SDK uses the scripts when building out-of-tree
962 modules.
963 Once you have switched to that directory and created the
964 scripts, you should be able to build your out-of-tree modules
965 on the target.
966 </para>
967 </section>
968
969 <section id='incorporating-out-of-tree-modules'>
970 <title>Incorporating Out-of-Tree Modules</title>
971
972 <para>
973 While it is always preferable to work with sources integrated
974 into the Linux kernel sources, if you need an external kernel
975 module, the <filename>hello-mod.bb</filename> recipe is
976 available as a template from which you can create your
977 own out-of-tree Linux kernel module recipe.
978 </para>
979
980 <para>
981 This template recipe is located in the
982 <filename>poky</filename> Git repository of the
983 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
984 at:
985 <literallayout class="monospaced">
986 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
987 </literallayout>
988 </para>
989
990 <para>
991 To get started, copy this recipe to your layer and give it a
992 meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
993 In the same directory, create a new directory named
994 <filename>files</filename> where you can store any source files,
995 patches, or other files necessary for building
996 the module that do not come with the sources.
997 Finally, update the recipe as needed for the module.
998 Typically, you will need to set the following variables:
999 <itemizedlist>
1000 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
1001 </para></listitem>
1002 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
1003 </para></listitem>
1004 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1005 </para></listitem>
1006 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1007 </para></listitem>
1008 </itemizedlist>
1009 </para>
1010
1011 <para>
1012 Depending on the build system used by the module sources,
1013 you might need to make some adjustments.
1014 For example, a typical module <filename>Makefile</filename>
1015 looks much like the one provided with the
1016 <filename>hello-mod</filename> template:
1017 <literallayout class='monospaced'>
1018 obj-m := hello.o
1019
1020 SRC := $(shell pwd)
1021
1022 all:
1023 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
1024
1025 modules_install:
1026 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
1027 ...
1028 </literallayout>
1029 </para>
1030
1031 <para>
1032 The important point to note here is the
1033 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
1034 variable.
1035 The
1036 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-module'><filename>module</filename></ulink>
1037 class sets this variable and the
1038 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
1039 variable to
1040 <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
1041 with the necessary Linux kernel build information to build
1042 modules.
1043 If your module <filename>Makefile</filename> uses a different
1044 variable, you might want to override the
1045 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink>
1046 step, or create a patch to
1047 the <filename>Makefile</filename> to work with the more typical
1048 <filename>KERNEL_SRC</filename> or
1049 <filename>KERNEL_PATH</filename> variables.
1050 </para>
1051
1052 <para>
1053 After you have prepared your recipe, you will likely want to
1054 include the module in your images.
1055 To do this, see the documentation for the following variables in
1056 the Yocto Project Reference Manual and set one of them
1057 appropriately for your machine configuration file:
1058 <itemizedlist>
1059 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
1060 </para></listitem>
1061 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
1062 </para></listitem>
1063 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
1064 </para></listitem>
1065 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
1066 </para></listitem>
1067 </itemizedlist>
1068 </para>
1069
1070 <para>
1071 Modules are often not required for boot and can be excluded from
1072 certain build configurations.
1073 The following allows for the most flexibility:
1074 <literallayout class='monospaced'>
1075 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
1076 </literallayout>
1077 The value is derived by appending the module filename without
1078 the <filename>.ko</filename> extension to the string
1079 "kernel-module-".
1080 </para>
1081
1082 <para>
1083 Because the variable is
1084 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
1085 and not a
1086 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
1087 variable, the build will not fail if this module is not
1088 available to include in the image.
1089 </para>
1090 </section>
1091 </section>
1092
1093
1094 <section id='inspecting-changes-and-commits'>
1095 <title>Inspecting Changes and Commits</title>
1096
1097 <para>
1098 A common question when working with a kernel is:
1099 "What changes have been applied to this tree?"
1100 Rather than using "grep" across directories to see what has
1101 changed, you can use Git to inspect or search the kernel tree.
1102 Using Git is an efficient way to see what has changed in the tree.
1103 </para>
1104
1105 <section id='what-changed-in-a-kernel'>
1106 <title>What Changed in a Kernel?</title>
1107
1108 <para>
1109 Following are a few examples that show how to use Git
1110 commands to examine changes.
1111 These examples are by no means the only way to see changes.
1112 <note>
1113 In the following examples, unless you provide a commit
1114 range, <filename>kernel.org</filename> history is blended
1115 with Yocto Project kernel changes.
1116 You can form ranges by using branch names from the
1117 kernel tree as the upper and lower commit markers with
1118 the Git commands.
1119 You can see the branch names through the web interface
1120 to the Yocto Project source repositories at
1121 <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
1122 </note>
1123 To see a full range of the changes, use the
1124 <filename>git whatchanged</filename> command and specify a
1125 commit range for the branch
1126 (<replaceable>commit</replaceable><filename>..</filename><replaceable>commit</replaceable>).
1127 </para>
1128
1129 <para>
1130 Here is an example that looks at what has changed in the
1131 <filename>emenlow</filename> branch of the
1132 <filename>linux-yocto-3.19</filename> kernel.
1133 The lower commit range is the commit associated with the
1134 <filename>standard/base</filename> branch, while
1135 the upper commit range is the commit associated with the
1136 <filename>standard/emenlow</filename> branch.
1137 <literallayout class='monospaced'>
1138 $ git whatchanged origin/standard/base..origin/standard/emenlow
1139 </literallayout>
1140 </para>
1141
1142 <para>
1143 To see short, one line summaries of changes use the
1144 <filename>git log</filename> command:
1145 <literallayout class='monospaced'>
1146 $ git log --oneline origin/standard/base..origin/standard/emenlow
1147 </literallayout>
1148 </para>
1149
1150 <para>
1151 Use this command to see code differences for the changes:
1152 <literallayout class='monospaced'>
1153 $ git diff origin/standard/base..origin/standard/emenlow
1154 </literallayout>
1155 </para>
1156
1157 <para>
1158 Use this command to see the commit log messages and the
1159 text differences:
1160 <literallayout class='monospaced'>
1161 $ git show origin/standard/base..origin/standard/emenlow
1162 </literallayout>
1163 </para>
1164
1165 <para>
1166 Use this command to create individual patches for
1167 each change.
1168 Here is an example that that creates patch files for each
1169 commit and places them in your <filename>Documents</filename>
1170 directory:
1171 <literallayout class='monospaced'>
1172 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
1173 </literallayout>
1174 </para>
1175 </section>
1176
1177 <section id='showing-a-particular-feature-or-branch-change'>
1178 <title>Showing a Particular Feature or Branch Change</title>
1179
1180 <para>
1181 Tags in the Yocto Project kernel tree divide changes for
1182 significant features or branches.
1183 The <filename>git show</filename>&nbsp;<replaceable>tag</replaceable>
1184 command shows changes based on a tag.
1185 Here is an example that shows <filename>systemtap</filename>
1186 changes:
1187 <literallayout class='monospaced'>
1188 $ git show systemtap
1189 </literallayout>
1190 You can use the
1191 <filename>git branch --contains</filename>&nbsp;<replaceable>tag</replaceable>
1192 command to show the branches that contain a particular feature.
1193 This command shows the branches that contain the
1194 <filename>systemtap</filename> feature:
1195 <literallayout class='monospaced'>
1196 $ git branch --contains systemtap
1197 </literallayout>
1198 </para>
1199 </section>
1200 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001201
1202 <section id='adding-recipe-space-kernel-features'>
1203 <title>Adding Recipe-Space Kernel Features</title>
1204
1205 <para>
1206 You can add kernel features in the
1207 <link linkend='recipe-space-metadata'>recipe-space</link> by
1208 using the
1209 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
1210 variable and by specifying the feature's <filename>.scc</filename>
1211 file path in the
1212 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1213 statement.
1214 When you add features using this method, the OpenEmbedded build
1215 system checks to be sure the features are present.
1216 If the features are not present, the build stops.
1217 Kernel features are the last elements processed for configuring
1218 and patching the kernel.
1219 Therefore, adding features in this manner is a way
1220 to enforce specific features are present and enabled
1221 without needing to do a full audit of any other layer's additions
1222 to the <filename>SRC_URI</filename> statement.
1223 </para>
1224
1225 <para>
1226 You add a kernel feature by providing the feature as part of the
1227 <filename>KERNEL_FEATURES</filename> variable and by providing the
1228 path to the feature's <filename>.scc</filename> file, which is
1229 relative to the root of the kernel Metadata.
1230 The OpenEmbedded build system searches all forms of kernel
1231 Metadata on the <filename>SRC_URI</filename> statement regardless
1232 of whether the Metadata is in the "kernel-cache", system kernel
1233 Metadata, or a recipe-space Metadata.
1234 See the
1235 "<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>"
1236 section for additional information.
1237 </para>
1238
1239 <para>
1240 When you specify the feature's <filename>.scc</filename> file
1241 on the <filename>SRC_URI</filename> statement, the OpenEmbedded
1242 build system adds the directory of that
1243 <filename>.scc</filename> file along with all its subdirectories
1244 to the kernel feature search path.
1245 Because subdirectories are searched, you can reference a single
1246 <filename>.scc</filename> file in the
1247 <filename>SRC_URI</filename> statement to reference multiple kernel
1248 features.
1249 </para>
1250
1251 <para>
1252 Consider the following example that adds the "test.scc" feature
1253 to the build.
1254 <orderedlist>
1255 <listitem><para>
1256 Create a <filename>.scc</filename> file and locate it
1257 just as you would any other patch file,
1258 <filename>.cfg</filename> file, or fetcher item
1259 you specify in the <filename>SRC_URI</filename>
1260 statement.
1261 <note><title>Notes</title>
1262 <itemizedlist>
1263 <listitem><para>
1264 You must add the directory of the
1265 <filename>.scc</filename> file to the fetcher's
1266 search path in the same manner as you would
1267 add a <filename>.patch</filename> file.
1268 </para></listitem>
1269 <listitem><para>
1270 You can create additional
1271 <filename>.scc</filename> files beneath the
1272 directory that contains the file you are
1273 adding.
1274 All subdirectories are searched during the
1275 build as potential feature directories.
1276 </para></listitem>
1277 </itemizedlist>
1278 </note>
1279 Continuing with the example, suppose the "test.scc"
1280 feature you are adding has a
1281 <filename>test.scc</filename> file in the following
1282 directory:
1283 <literallayout class='monospaced'>
1284 <replaceable>my_recipe</replaceable>
1285 |
1286 +-linux-yocto
1287 |
1288 +-test.cfg
1289 +-test.scc
1290 </literallayout>
1291 In this example, the <filename>linux-yocto</filename>
1292 directory has both the feature
1293 <filename>test.scc</filename> file and a similarly
1294 named configuration fragment file
1295 <filename>test.cfg</filename>.
1296 </para></listitem>
1297 <listitem><para>
1298 Add the <filename>.scc</filename> file to the
1299 recipe's <filename>SRC_URI</filename> statement:
1300 <literallayout class='monospaced'>
1301 SRC_URI_append = " file://test.scc"
1302 </literallayout>
1303 The leading space before the path is important as the
1304 path is appended to the existing path.
1305 </para></listitem>
1306 <listitem><para>
1307 Specify the feature as a kernel feature:
1308 <literallayout class='monospaced'>
1309 KERNEL_FEATURES_append = " test.scc"
1310 </literallayout>
1311 The OpenEmbedded build system processes the kernel feature
1312 when it builds the kernel.
1313 <note>
1314 If other features are contained below "test.scc",
1315 then their directories are relative to the directory
1316 containing the <filename>test.scc</filename> file.
1317 </note>
1318 </para></listitem>
1319 </orderedlist>
1320 </para>
1321 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001322</chapter>
1323<!--
1324vim: expandtab tw=80 ts=4
1325-->