summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-intro.xml
blob: a2644aaa13adc91a5aaa4ca28ad3cc1e7a21146f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

<chapter id='kernel-dev-intro'>
<title>Introduction</title>

<section id='kernel-dev-overview'>
    <title>Overview</title>

    <para>
        Regardless of how you intend to make use of the Yocto Project,
        chances are you will work with the Linux kernel.
        This manual describes how to set up your build host to support
        kernel development, introduces the kernel development process,
        provides background information on the Yocto Linux kernel
        <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>,
        describes common tasks you can perform using the kernel tools,
        and shows you how to use the kernel Metadata needed to work with
        the kernel inside the Yocto Project.
   </para>

   <para>
        Each Yocto Project release has a set of Yocto Linux kernel recipes,
        whose Git repositories you can view in the Yocto
        <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
        the "Yocto Linux Kernel" heading.
        New recipes for the release track the latest Linux kernel
        upstream developments from
        <ulink url='http://www.kernel.org'></ulink> and introduce
        newly-supported platforms.
        Previous recipes in the release are refreshed and supported for at
        least one additional Yocto Project release.
        As they align, these previous releases are updated to include the
        latest from the
        <ulink url='&YOCTO_HOME_URL;/organization/long-term-support-initiative-ltsi'>Long Term Support Initiative</ulink>
        (LTSI) project.
        Also included is a Yocto Linux kernel development recipe
        (<filename>linux-yocto-dev.bb</filename>) should you want to work
        with the very latest in upstream Yocto Linux kernel development and
        kernel Metadata development.
        <note>
            For more on Yocto Linux kernels, see the
            "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>
            section.
        </note>
    </para>

    <para>
        The Yocto Project also provides a powerful set of kernel
        tools for managing Yocto Linux kernel sources and configuration data.
        You can use these tools to make a single configuration change,
        apply multiple patches, or work with your own kernel sources.
    </para>

    <para>
        In particular, the kernel tools allow you to generate configuration
        fragments that specify only what you must, and nothing more.
        Configuration fragments only need to contain the highest level
        visible <filename>CONFIG</filename> options as presented by the
        Yocto Linux kernel <filename>menuconfig</filename> system.
        Contrast this against a complete Yocto Linux kernel
        <filename>.config</filename> file, which includes all the automatically
        selected <filename>CONFIG</filename> options.
        This efficiency reduces your maintenance effort and allows you
        to further separate your configuration in ways that make sense for
        your project.
        A common split separates policy and hardware.
        For example, all your kernels might support the
        <filename>proc</filename> and <filename>sys</filename> filesystems,
        but only specific boards require sound, USB, or specific drivers.
        Specifying these configurations individually allows you to aggregate
        them together as needed, but maintains them in only one place.
        Similar logic applies to separating source changes.
    </para>

    <para>
        If you do not maintain your own kernel sources and need to make
        only minimal changes to the sources, the released recipes provide a
        vetted base upon which to layer your changes.
        Doing so allows you to benefit from the continual kernel
        integration and testing performed during development of the
        Yocto Project.
    </para>

    <para>
        If, instead, you have a very specific Linux kernel source tree
        and are unable to align with one of the official Yocto Linux kernel
        recipes, an alternative exists by which you can use the Yocto
        Project Linux kernel tools with your own kernel sources.
    </para>
</section>

<section id='preparing-the-build-host-to-work-on-the-kernel'>
    <title>Preparing the Build Host to Work on the Kernel</title>

    <para>
        Before you can do any kernel development, you need to be
        sure your build host is set up to use the Yocto Project.
        For information on how to get set up, see the
        "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up to Use the Yocto Project</ulink>"
        section in the Yocto Project Development Manual.
        Part of preparing the system is creating a local Git
        repository of the
        <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
        (<filename>poky</filename>) on your system.
        Follow the steps in the
        "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
        section in the Yocto Project Development Manual to set up your
        Source Directory.
    </para>

    <para>
        Kernel development is best accomplished using
        <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
        and not through traditional kernel workflow methods.
        The remainder of this section provides information for both scenarios.
    </para>

    <section id='getting-ready-to-develop-using-devtool'>
        <title>Getting Ready to Develop using <filename>devtool</filename></title>

        <para>
            Follow these steps to prepare to update the kernel image using
            <filename>devtool</filename>.
            Completing this procedure leaves you with a clean kernel image
            and ready to make modifications as described in the
            "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
            section:
            <orderedlist>
                <listitem><para>
                    <emphasis>Initialize the BitBake Environment:</emphasis>
                    Before building an extensible SDK, you need to
                    initialize the BitBake build environment by sourcing a
                    build environment script
                    (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>
                    or
                    <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>):
                    <literallayout class='monospaced'>
     $ cd ~/poky
     $ source oe-init-build-env
                    </literallayout>
                    <note>
                        The previous commands assume the
                        <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
                        (i.e. <filename>poky</filename>) have been cloned
                        using Git and the local repository is named
                        "poky".
                    </note>
                    </para></listitem>
                <listitem><para>
                    <emphasis>Prepare Your <filename>local.conf</filename> File:</emphasis>
                    By default, the
                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
                    variable is set to "qemux86", which is fine if you are
                    building for the QEMU emulator in 32-bit mode.
                    However, if you are not, you need to set the
                    <filename>MACHINE</filename> variable appropriately in
                    your <filename>local.conf</filename> file found in the
                    <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
                    (i.e. <filename>~/poky/build</filename> in this example).
                    </para>

                    <para>Also, since you are preparing to work on the kernel
                    image, you need to set the
                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
                    variable to include kernel modules.</para>

                    <para>This example uses the default "qemux86" for the
                    <filename>MACHINE</filename> variable but needs to
                    add the "kernel-modules":
                    <literallayout class='monospaced'>
     MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
                    </literallayout>
                    </para></listitem>
                <listitem><para>
                    <emphasis>Create a Layer for Patches:</emphasis>
                    You need to create a layer to hold patches created
                    for the kernel image.
                    You can use the <filename>yocto-layer</filename> command
                    as follows:
                    <literallayout class='monospaced'>
     $ cd ~/poky
     $ yocto-layer create my-kernel -o ../meta-my-kernel
      Please enter the layer priority you'd like to use for the layer: [default: 6]
      Would you like to have an example recipe created? (y/n) [default: n]
      Would you like to have an example bbappend file created? (y/n) [default: n]

      New layer created in ../meta-my-kernel.

      Don't forget to add it to your BBLAYERS (for details see ../meta-my-kernel/README).
                    </literallayout>
                    </para></listitem>
                <listitem><para>
                    <emphasis>Inform the BitBake Build Environment About Your Layer:</emphasis>
                    As directed when you created your layer, you need to add
                    the layer to the
                    <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
                    variable in the <filename>bblayers.conf</filename> file
                    as follows:
                    <literallayout class='monospaced'>
     $ cd ~/poky/build
     $ bitbake-layers add-layer ../../meta-my-kernel
                    </literallayout>
                    </para></listitem>
                <listitem><para>
                    <emphasis>Build the Extensible SDK:</emphasis>
                    Use BitBake to build the extensible SDK specifically for
                    the Minnowboard:
                    <literallayout class='monospaced'>
     $ bitbake core-image-minimal -c populate_sdk_ext
                    </literallayout>
                    Once the build finishes, you can find the SDK installer
                    file (i.e. <filename>*.sh</filename> file) in the
                    following directory:
                    <literallayout class='monospaced'>
     ~/poky/build/tmp/deploy/sdk
                    </literallayout>
                    For this example, the installer file is named
                    <filename>poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh</filename>
                    </para></listitem>
                <listitem><para>
                    <emphasis>Install the Extensible SDK:</emphasis>
                    Use the following command to install the SDK.
                    For this example, install the SDK in the default
                    <filename>~/poky_sdk</filename> directory:
                    <literallayout class='monospaced'>
     $ cd ~/poky/build/tmp/deploy/sdk
     $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh
     Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
     ============================================================================
     Enter target directory for SDK (default: ~/poky_sdk):
     You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
     Extracting SDK......................................done
     Setting it up...
     Extracting buildtools...
     Preparing build system...
     Parsing recipes: 100% |#################################################################| Time: 0:00:52
     Initializing tasks: 100% |############## ###############################################| Time: 0:00:04
     Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00
     Parsing recipes: 100% |#################################################################| Time: 0:00:33
     Initializing tasks: 100% |##############################################################| Time: 0:00:00
     done
     SDK has been successfully set up and is ready to be used.
     Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
      $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux
                    </literallayout>
                    </para></listitem>
                <listitem><para id='setting-up-the-esdk-terminal'>
                    <emphasis>Set Up a New Terminal to Work With the Extensible SDK:</emphasis>
                    You must set up a new terminal to work with the SDK.
                    You cannot use the same BitBake shell used to build the
                    installer.</para>

                    <para>After opening a new shell, run the SDK environment
                    setup script as directed by the output from installing
                    the SDK:
                    <literallayout class='monospaced'>
     $ source ~/poky_sdk/environment-setup-i586-poky-linux
     "SDK environment now set up; additionally you may now run devtool to perform development tasks.
     Run devtool --help for further details.
                    </literallayout>
                    <note>
                        If you get a warning about attempting to use the
                        extensible SDK in an environment set up to run
                        BitBake, you did not use a new shell.
                    </note>
                    </para></listitem>
                <listitem><para>
                    <emphasis>Build the Clean Image:</emphasis>
                    The final step in preparing to work on the kernel is to
                    build an initial image using <filename>devtool</filename>
                    in the new terminal you just set up and initialized for
                    SDK work:
                    <literallayout class='monospaced'>
     $ devtool build-image
     Parsing recipes: 100% |##########################################| Time: 0:00:05
     Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors.
     WARNING: No packages to add, building image core-image-minimal unmodified
     Loading cache: 100% |############################################| Time: 0:00:00
     Loaded 1299 entries from dependency cache.
     NOTE: Resolving any missing task queue dependencies
     Initializing tasks: 100% |#######################################| Time: 0:00:07
     Checking sstate mirror object availability: 100% |###############| Time: 0:00:00
     NOTE: Executing SetScene Tasks
     NOTE: Executing RunQueue Tasks
     NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded.
     NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86
                    </literallayout>
                    If you were building for actual hardware and not for
                    emulation, you could flash the image to a USB stick
                    on <filename>/dev/sdd</filename> and boot your device.
                    Use a command similar to the following command to flash
                    the image:
                    <literallayout class='monospaced'>
     $ sudo dd if=tmp/deploy/images/<replaceable>architecture</replaceable>/core-image-minimal-<replaceable>architecture</replaceable>.wic of=/dev/sdd bs=1MB
     $ sync
                    </literallayout>
                    </para></listitem>
            </orderedlist>
        </para>

        <para>
            At this point you have set up to start making modifications to the
            kernel by using the extensible SDK.
            For a continued example, see the
            "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
            section.
        </para>
    </section>

    <section id='getting-ready-for-traditional-kernel-development'>
        <title>Getting Ready for Traditional Kernel Development</title>

        <para>
            For traditional kernel development using the Yocto
            Project, you need to establish local copies of the
            kernel source.
            You can find Git repositories of supported Yocto Project
            kernels organized under "Yocto Linux Kernel" in the Yocto
            Project Source Repositories at
            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
        </para>

        <para>
            This setup can involve creating a bare clone of the
            Yocto Project kernel and then copying that cloned
            repository.
            You can create the bare clone and the copy of the bare
            clone anywhere you like.
            For simplicity, it is recommended that you create these
            structures outside of the
            <ulink url='&YOCTO_DOCS_REF_URL;source-directory'>Source Directory</ulink>,
            which is usually named <filename>poky</filename>.
        </para>

        <para>
            The following steps show how to create a bare clone of the
            <filename>linux-yocto-4.4</filename> kernel and then
            create a copy of that clone:
            <note>
                When you have a local Yocto Project kernel Git
                repository, you can reference that repository rather than
                the upstream Git repository as part of the
                <filename>clone</filename> command.
                Doing so can speed up the process.
            </note>
            <orderedlist>
                <listitem><para>
                    <emphasis>Create the Bare Clone:</emphasis>
                    In the following example, the bare clone is named
                    <filename>linux-yocto-4.4.git</filename>:
                    <literallayout class='monospaced'>
     $ git clone &dash;&dash;bare git://git.yoctoproject.org/linux-yocto-4.4 linux-yocto-4.4.git
     Cloning into bare repository 'linux-yocto-4.4.git'...
     remote: Counting objects: 4543903, done.
     remote: Compressing objects: 100% (695618/695618), done.
     remote: Total 4543903 (delta 3818435), reused 4541724 (delta 3816256)
     Receiving objects: 100% (4543903/4543903), 801.08 MiB | 6.55 MiB/s, done.
     Resolving deltas: 100% (3818435/3818435), done.
     Checking connectivity... done.
                    </literallayout>
                    </para></listitem>
                <listitem><para>
                    <emphasis>Create the Copy of the Bare Clone:</emphasis>
                    In the following command, the copy of the bare clone
                    is named <filename>my-linux-yocto-4.4-work</filename>:
                    <literallayout class='monospaced'>
     $ git clone linux-yocto-4.4.git my-linux-yocto-4.4-work
     Cloning into 'my-linux-yocto-4.4-work'...
     done.
     Checking out files: 100% (52221/52221), done.
                    </literallayout>
                    </para></listitem>
                <listitem><para>
                    <emphasis>Cloning the <filename>meta-yocto-kernel-extras</filename> Repository:</emphasis>
                    The <filename>meta-yocto-kernel-extras</filename> Git
                    repository contains Metadata needed only if you are
                    modifying and building the kernel image.
                    In particular, it contains the kernel BitBake append
                    (<filename>.bbappend</filename>) files that you edit to
                    point to your locally modified kernel source files and
                    to build the kernel image.
                    Pointing to these local files is much more efficient
                    than requiring a download of the kernel's source files
                    from upstream each time you make changes to the kernel.
                    </para>

                    <para>You can find the
                    <filename>meta-yocto-kernel-extras</filename> Git
                    Repository in the "Yocto Metadata Layers" area of the
                    Yocto Project Source Repositories at
                    <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
                    It is good practice to create this Git repository
                    inside the Source Directory.</para>

                    <para>Following is an example that creates the
                    <filename>meta-yocto-kernel-extras</filename> Git
                    repository inside the Source Directory, which is named
                    <filename>poky</filename>, in this case:
                    <literallayout class='monospaced'>
     $ cd ~/poky
     $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
     Cloning into 'meta-yocto-kernel-extras'...
     remote: Counting objects: 727, done.
     remote: Compressing objects: 100% (452/452), done.
     remote: Total 727 (delta 260), reused 719 (delta 252)
     Receiving objects: 100% (727/727), 536.36 KiB | 0 bytes/s, done.
     Resolving deltas: 100% (260/260), done.
     Checking connectivity... done.
                    </literallayout>
                    </para></listitem>
            </orderedlist>
        </para>
    </section>
</section>

<section id='kernel-modification-workflow'>
    <title>Kernel Modification Workflow</title>

    <para>
        Kernel modification involves changing the Yocto Project kernel,
        which could involve changing configuration options as well as adding
        new kernel recipes.
        Configuration changes can be added in the form of configuration
        fragments, while recipe modification comes through the kernel's
        <filename>recipes-kernel</filename> area in a kernel layer you create.
    </para>

    <para>
        This section presents a high-level overview of the Yocto Project
        kernel modification workflow.
        You can find additional information here:
        <itemizedlist>
            <listitem><para>
                The
                "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
                section.
                </para></listitem>
            <listitem><para>
                The
                "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
                section in the Yocto Project Development Manual.
                </para></listitem>
        </itemizedlist>
        This illustration and the following list summarizes the kernel
        modification general workflow.
        <imagedata fileref="figures/kernel-dev-flow.png"
            width="9in" depth="5in" align="center" scalefit="1" />
    </para>

    <para>
        <orderedlist>
            <listitem><para>
                <emphasis>Set up Your Host Development System to Support
                Development Using the Yocto Project</emphasis>:
                See the
                "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
                section and be sure you have everything set up to use the
                Yocto Project, including a local Git repository of the
                <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
                (<filename>poky</filename>).
                </para></listitem>
            <listitem><para>
                <emphasis>Establish the Temporary Kernel Source Files</emphasis>:
                Temporary kernel source files are kept in the
                <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
                created by the OpenEmbedded build system when you run BitBake.
                If you have never built the kernel in which you are
                interested, you need to run an initial build to
                establish local kernel source files.</para>

                <para>If you are building an image for the first time, you
                need to get the build environment ready by sourcing an
                environment setup script
                (i.e. <filename>oe-init-build-env</filename> or
                <filename>oe-init-build-env-memres</filename>).
                You also need to be sure two key configuration files
                (<filename>local.conf</filename> and
                <filename>bblayers.conf</filename>) are configured
                appropriately.</para>

                <para>The entire process for building an image is overviewed
                in the
                "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
                section of the Yocto Project Quick Start.
                You might want to reference this information.
                You can find more information on BitBake in the
                <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
                </para>

                <para>The build process supports several types of images to
                satisfy different needs.
                See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
                chapter in the Yocto Project Reference Manual for information
                on supported images.
                </para></listitem>
            <listitem><para>
                <emphasis>Make Changes to the Kernel Source Code if
                applicable</emphasis>:
                Modifying the kernel does not always mean directly
                changing source files.
                However, if you have to do this, you make the changes to the
                files in the Build Directory.
                </para></listitem>
            <listitem><para>
                <emphasis>Make Kernel Configuration Changes if
                Applicable</emphasis>:
                If your situation calls for changing the kernel's
                configuration, you can use
                <link linkend='generating-configuration-files'><filename>menuconfig</filename></link>,
                which allows you to interactively develop and test the
                configuration changes you are making to the kernel.
                Saving changes you make with <filename>menuconfig</filename>
                updates the kernel's <filename>.config</filename> file.
                <note><title>Warning</title>
                    Try to resist the temptation to directly edit an
                    existing <filename>.config</filename> file, which is
                    found in the Build Directory among the source code
                    used for the build (e.g. see the workflow illustration
                    in the
                    "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
                    section).
                    Doing so, can produce unexpected results when the
                    OpenEmbedded build system regenerates the configuration
                    file.
                </note>
                Once you are satisfied with the configuration
                changes made using <filename>menuconfig</filename>
                and you have saved them, you can directly compare the
                resulting <filename>.config</filename> file against an
                existing original and gather those changes into a
                <ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>configuration fragment file</ulink>
                to be referenced from within the kernel's
                <filename>.bbappend</filename> file.</para>

                <para>Additionally, if you are working in a BSP layer
                and need to modify the BSP's kernel's configuration,
                you can use the
                <ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'><filename>yocto-kernel</filename></ulink>
                script as well as <filename>menuconfig</filename>.
                The <filename>yocto-kernel</filename> script lets
                you interactively set up kernel configurations.
                </para></listitem>
            <listitem><para>
                <emphasis>Rebuild the Kernel Image With Your Changes</emphasis>:
                Rebuilding the kernel image applies your changes.
                </para></listitem>
        </orderedlist>
    </para>
</section>

<section id='kernel-dev-other-resources'>
    <title>Other Resources</title>

    <para>
        The remainder of this manual provides instructions for completing
        specific Linux kernel development tasks.
        These instructions assume you are comfortable working with
        <ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink>
        recipes and basic open-source development tools.
        Understanding these concepts will facilitate the process of working
        with the kernel recipes.
        If you find you need some additional background, please be sure to
        review and understand the following documentation:
        <itemizedlist>
            <listitem><para>
                <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
                </para></listitem>
            <listitem><para>
                <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
                as described in the Yocto Project Software Development Kit
                (SDK) Developer's Guide.
                </para></listitem>
            <listitem><para>
                The
                "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section
                in the Yocto Project Development Manual
                </para></listitem>
            <listitem><para>
                The
                "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
                section.
                </para></listitem>
        </itemizedlist>
    </para>

    <para>
        Finally, while this document focuses on the manual creation of
        recipes, patches, and configuration files, the Yocto Project
        Board Support Package (BSP) tools are available to automate
        this process with existing content and work well to create the
        initial framework and boilerplate code.
        For details on these tools, see the
        "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
        section in the Yocto Project Board Support Package (BSP) Developer's
        Guide.
    </para>
</section>

</chapter>
<!--
vim: expandtab tw=80 ts=4
-->