path: root/documentation/kernel-dev/kernel-dev-intro.xml

<!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 introduces the kernel development process and
        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>
        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.
        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 role='writernotes'>
            Need the updated wiki stuff here
        </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
                "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
                section in the Yocto Project Quick Start for options on how
                to get a build host ready to use the Yocto Project.
                </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
-->