diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml | 393 |
1 files changed, 256 insertions, 137 deletions
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml index 263e50098..dba45495f 100644 --- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml +++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml @@ -5,144 +5,263 @@ <chapter id='kernel-dev-intro'> <title>Introduction</title> -<!-- -<para> - <emphasis>AR - Darren Hart:</emphasis> See if the concepts in these - three bullets are adequately covered in somewhere in this manual: - <itemizedlist> - <listitem><para>Do we convey that our kernel Git repositories - have a clear and continuous history, similar to the way the - kernel Git repositories for <filename>kernel.org</filename> - do. - </para></listitem> - <listitem><para>Does the manual note that Yocto Project delivers - a key set of supported kernel types, where - each type is tailored to meet a specific use (e.g. networking, - consumer, devices, and so forth).</para></listitem> - <listitem><para>Do we convey that the Yocto Project uses a - Git branching strategy that, from a - developer's point of view, results in a linear path from the - baseline kernel.org, through a select group of features and - ends with their BSP-specific commits.</para></listitem> - </itemizedlist> -</para> ---> +<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, + shows you how to use the kernel Metadata needed to work with + the kernel inside the Yocto Project, and provides insight into how + the Yocto Project team develops and maintains Yocto Linux kernel + Git repositories and Metadata. + </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 Long Term Support Initiative (LTSI) project. + You can learn more about Yocto Linux kernels and LTSI in the + "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>" + section. + </para> + + <para> + 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> + + <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 Application Development and + the Extensible Software Development Kit (eSDK) manual. + </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 Tasks 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> + +<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. + The illustration and accompanying list provide general information + and references for further information. + <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>Set Up Your Host Development System for Kernel Development:</emphasis> + It is recommended that you use <filename>devtool</filename> + and an extensible SDK for kernel development. + Alternatively, you can use traditional kernel development + methods with the Yocto Project. + Either way, there are steps you need to take to get the + development environment ready.</para> + + <para>Using <filename>devtool</filename> and the eSDK requires + that you have a clean build of the image and that you are + set up with the appropriate eSDK. + For more information, see the + "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" + section.</para> + + <para>Using traditional kernel development requires that you + have the kernel source available in an isolated local Git + repository. + For more information, see the + "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" + section. + </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 eSDK's Build Directory if you are using + <filename>devtool</filename>. + For more information, see the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + section.</para> + + <para>If you are using traditional kernel development, you + edit the source files in the kernel's local Git repository. + For more information, see the + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + section. + </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='using-menuconfig'><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. + 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 + <link linkend='creating-config-fragments'>configuration fragment file</link> + 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. + Depending on your target hardware, you can verify your changes + on actual hardware or perhaps QEMU. + </para></listitem> + </orderedlist> + The remainder of this developer's guide covers common tasks typically + used during kernel development, advanced Metadata usage, and Yocto Linux + kernel maintenance concepts. + </para> +</section> - <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 provides background information on the Yocto Linux kernel - <ulink url='&YOCTO_DOCS_DEV_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 linux-yocto 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 upstream developments - and introduce newly-supported platforms. - Previous recipes in the release are refreshed and supported for at - least one additional 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 linux-yocto development recipe - (<filename>linux-yocto-dev.bb</filename>) should you want to work - with the very latest in upstream Linux kernel development and - kernel Metadata development. - </para> - - <para> - The Yocto Project also provides a powerful set of kernel - tools for managing 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 Linux - kernel <filename>menuconfig</filename> system. - Contrast this against a complete Linux kernel - <filename>.config</filename>, 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 linux-yocto - recipes, an alternative exists by which you can use the Yocto - Project Linux kernel tools with your own kernel sources. - </para> - </section> - - <section id='kernel-dev-other-resources'> - <title>Other Resources</title> - - <para> - The sections that follow provide 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>The "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-modifying-source-code'>Modifying Source Code</ulink>" - section in the Yocto Project Development Manual - </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 "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel'>Modifying the Kernel</ulink>" section - in the Yocto Project Development Manual.</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 |
