poky/documentation/kernel-dev/kernel-dev-intro.xml - openbmc/openbmc - Gitiles

 <!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; ] >
 <!--SPDX-License-Identifier: CC-BY-2.0-UK-->

 <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,
         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_BRIEF_URL;'>Yocto Project Quick Build</ulink>
                 document.
                 </para></listitem>
             <listitem><para>
                 <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</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>
 </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_DEV_URL;#dev-manual-start'>Setting Up the Development Host to Use the Yocto Project</ulink>"
                 section in the Yocto Project Development Tasks Manual 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 <filename>menuconfig</filename>.
                 </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>

 </chapter>
 <!--
 vim: expandtab tw=80 ts=4
 -->
	<!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; ] >
	<!--SPDX-License-Identifier: CC-BY-2.0-UK-->

	<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,
	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_BRIEF_URL;'>Yocto Project Quick Build</ulink>
	document.
	</para></listitem>
	<listitem><para>
	<ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</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>
	</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_DEV_URL;#dev-manual-start'>Setting Up the Development Host to Use the Yocto Project</ulink>"
	section in the Yocto Project Development Tasks Manual 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 <filename>menuconfig</filename>.
	</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>

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