1 files changed, 147 insertions, 0 deletions
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
new file mode 100644
index 0000000000..297696c965
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -0,0 +1,147 @@
+<!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>
+<!--
+<para>
+    <emphasis>AR - Darrren 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 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 Long Term Support Initiative (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://developer.berlios.de/projects/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;#modifying-temporary-source-code'>Modifying Temporary 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
+-->

diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml new file mode 100644 index 0000000000..297696c965 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -0,0 +1,147 @@
	1	<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	2	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	3	[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
	4
	5	<chapter id='kernel-dev-intro'>
	6	<title>Introduction</title>
	7
	8	<!--
	9	<para>
	10	<emphasis>AR - Darrren Hart:</emphasis> See if the concepts in these
	11	three bullets are adequately covered in somewhere in this manual:
	12	<itemizedlist>
	13	<listitem><para>Do we convey that our kernel Git repositories
	14	have a clear and continuous history, similar to the way the
	15	kernel Git repositories for <filename>kernel.org</filename>
	16	do.
	17	</para></listitem>
	18	<listitem><para>Does the manual note that Yocto Project delivers
	19	a key set of supported kernel types, where
	20	each type is tailored to meet a specific use (e.g. networking,
	21	consumer, devices, and so forth).</para></listitem>
	22	<listitem><para>Do we convey that the Yocto Project uses a
	23	Git branching strategy that, from a
	24	developer's point of view, results in a linear path from the
	25	baseline kernel.org, through a select group of features and
	26	ends with their BSP-specific commits.</para></listitem>
	27	</itemizedlist>
	28	</para>
	29	-->
	30
	31	<section id='kernel-dev-overview'>
	32	<title>Overview</title>
	33
	34	<para>
	35	Regardless of how you intend to make use of the Yocto Project,
	36	chances are you will work with the Linux kernel.
	37	This manual provides background information on the Yocto Linux kernel
	38	<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
	39	describes common tasks you can perform using the kernel tools,
	40	and shows you how to use the kernel Metadata needed to work with
	41	the kernel inside the Yocto Project.
	42	</para>
	43
	44	<para>
	45	Each Yocto Project release has a set of linux-yocto recipes, whose
	46	Git repositories you can view in the Yocto
	47	<ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
	48	the "Yocto Linux Kernel" heading.
	49	New recipes for the release track the latest upstream developments
	50	and introduce newly supported platforms.
	51	Previous recipes in the release are refreshed and supported for at
	52	least one additional release.
	53	As they align, these previous releases are updated to include the
	54	latest from the Long Term Support Initiative (LTSI) project.
	55	Also included is a linux-yocto development recipe
	56	(<filename>linux-yocto-dev.bb</filename>) should you want to work
	57	with the very latest in upstream Linux kernel development and
	58	kernel Metadata development.
	59	</para>
	60
	61	<para>
	62	The Yocto Project also provides a powerful set of kernel
	63	tools for managing Linux kernel sources and configuration data.
	64	You can use these tools to make a single configuration change,
	65	apply multiple patches, or work with your own kernel sources.
	66	</para>
	67
	68	<para>
	69	In particular, the kernel tools allow you to generate configuration
	70	fragments that specify only what you must, and nothing more.
	71	Configuration fragments only need to contain the highest level
	72	visible <filename>CONFIG</filename> options as presented by the Linux
	73	kernel <filename>menuconfig</filename> system.
	74	Contrast this against a complete Linux kernel
	75	<filename>.config</filename>, which includes all the automatically
	76	selected <filename>CONFIG</filename> options.
	77	This efficiency reduces your maintenance effort and allows you
	78	to further separate your configuration in ways that make sense for
	79	your project.
	80	A common split separates policy and hardware.
	81	For example, all your kernels might support
	82	the <filename>proc</filename> and <filename>sys</filename> filesystems,
	83	but only specific boards require sound, USB, or specific drivers.
	84	Specifying these configurations individually allows you to aggregate
	85	them together as needed, but maintains them in only one place.
	86	Similar logic applies to separating source changes.
	87	</para>
	88
	89	<para>
	90	If you do not maintain your own kernel sources and need to make
	91	only minimal changes to the sources, the released recipes provide a
	92	vetted base upon which to layer your changes.
	93	Doing so allows you to benefit from the continual kernel
	94	integration and testing performed during development of the
	95	Yocto Project.
	96	</para>
	97
	98	<para>
	99	If, instead, you have a very specific Linux kernel source tree
	100	and are unable to align with one of the official linux-yocto
	101	recipes, an alternative exists by which you can use the Yocto
	102	Project Linux kernel tools with your own kernel sources.
	103	</para>
	104	</section>
	105
	106	<section id='kernel-dev-other-resources'>
	107	<title>Other Resources</title>
	108
	109	<para>
	110	The sections that follow provide instructions for completing
	111	specific Linux kernel development tasks.
	112	These instructions assume you are comfortable working with
	113	<ulink url='http://developer.berlios.de/projects/bitbake/'>BitBake</ulink>
	114	recipes and basic open-source development tools.
	115	Understanding these concepts will facilitate the process of working
	116	with the kernel recipes.
	117	If you find you need some additional background, please be sure to
	118	review and understand the following documentation:
	119	<itemizedlist>
	120	<listitem><para><ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
	121	</para></listitem>
	122	<listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-temporary-source-code'>Modifying Temporary Source Code</ulink>"
	123	section in the Yocto Project Development Manual
	124	</para></listitem>
	125	<listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section
	126	in the Yocto Project Development Manual</para></listitem>
	127	<listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel'>Modifying the Kernel</ulink>" section
	128	in the Yocto Project Development Manual.</para></listitem>
	129	</itemizedlist>
	130	</para>
	131
	132	<para>
	133	Finally, while this document focuses on the manual creation of
	134	recipes, patches, and configuration files, the Yocto Project
	135	Board Support Package (BSP) tools are available to automate
	136	this process with existing content and work well to create the
	137	initial framework and boilerplate code.
	138	For details on these tools, see the
	139	"<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
	140	section in the Yocto Project Board Support Package (BSP) Developer's
	141	Guide.
	142	</para>
	143	</section>
	144	</chapter>
	145	<!--
	146	vim: expandtab tw=80 ts=4
	147	-->