1 files changed, 173 insertions, 33 deletions
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index 56cf6bc7e2..a2644aaa13 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -120,52 +120,192 @@
    <section id='getting-ready-to-develop-using-devtool'>
        <title>Getting Ready to Develop using <filename>devtool</filename></title>
-        <para role='writernotes'>
+        <para>
-            Sections as follows:
+            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 role='writernotes'>
+                <listitem><para>
-                    Source the oe-init-build-env script.
+                    <emphasis>Initialize the BitBake Environment:</emphasis>
-                    At this point, we assume the build host is set up and
+                    Before building an extensible SDK, you need to
-                    <filename>poky</filename> repository has been cloned.
+                    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 role='writernotes'>
+                <listitem><para>
-                    Be sure your <filename>local.conf</filename> file has
+                    <emphasis>Prepare Your <filename>local.conf</filename> File:</emphasis>
-                    the correct
+                    By default, the
                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
-                    variable set for the target hardware on which your
+                    variable is set to "qemux86", which is fine if you are
-                    kernel image runs.
+                    building for the QEMU emulator in 32-bit mode.
-                    Also have the
+                    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 set equal to "kernel-modules".
+                    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 role='writernotes'>
+                <listitem><para>
-                    Create a layer for later that will contain your patches
+                    <emphasis>Create a Layer for Patches:</emphasis>
-                    (if any) to the kernel.
+                    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 role='writernotes'>
+                <listitem><para>
-                    Build the extensible SDK.
+                    <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 role='writernotes'>
+                <listitem><para>
-                    Install the extensible SDK.
+                    <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 role='writernotes'>
+                <listitem><para id='setting-up-the-esdk-terminal'>
-                    Set up the terminal so that you can work with the
+                    <emphasis>Set Up a New Terminal to Work With the Extensible SDK:</emphasis>
-                    extensible SDK.
+                    You must set up a new terminal to work with the SDK.
-                    This terminal is known as the "eSDK Terminal" unlike the
+                    You cannot use the same BitBake shell used to build the
-                    terminal that is set up to run BitBake, which is known
+                    installer.</para>
-                    as the "BitBake Terminal".
+                    <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 role='writernotes'>
+                <listitem><para>
-                    Build the initial image using the extensible SDK.
+                    <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 role='writernotes'>
+        <para>
-            At this point, the user has enough stuff set up to work on the
+            At this point you have set up to start making modifications to the
-            kernel.
+            kernel by using the extensible SDK.
-            I will put a section in the "Common Tasks" area of this manual
+            For a continued example, see the
-            that finished out how to make a modification to the kernel.
+            "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
+            section.
        </para>
    </section>

diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml index 56cf6bc7e2..a2644aaa13 100644 --- a/documentation/kernel-dev/kernel-dev-intro.xml +++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -120,52 +120,192 @@
120	<section id='getting-ready-to-develop-using-devtool'>	120	<section id='getting-ready-to-develop-using-devtool'>
121	<title>Getting Ready to Develop using <filename>devtool</filename></title>	121	<title>Getting Ready to Develop using <filename>devtool</filename></title>
122		122
123	<para role='writernotes'>	123	<para>
124	Sections as follows:	124	Follow these steps to prepare to update the kernel image using
		125	<filename>devtool</filename>.
		126	Completing this procedure leaves you with a clean kernel image
		127	and ready to make modifications as described in the
		128	"<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
		129	section:
125	<orderedlist>	130	<orderedlist>
126	<listitem><para role='writernotes'>	131	<listitem><para>
127	Source the oe-init-build-env script.	132	<emphasis>Initialize the BitBake Environment:</emphasis>
128	At this point, we assume the build host is set up and	133	Before building an extensible SDK, you need to
129	<filename>poky</filename> repository has been cloned.	134	initialize the BitBake build environment by sourcing a
		135	build environment script
		136	(i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>
		137	or
		138	<ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>):
		139	<literallayout class='monospaced'>
		140	$ cd ~/poky
		141	$ source oe-init-build-env
		142	</literallayout>
		143	<note>
		144	The previous commands assume the
		145	<ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
		146	(i.e. <filename>poky</filename>) have been cloned
		147	using Git and the local repository is named
		148	"poky".
		149	</note>
130	</para></listitem>	150	</para></listitem>
131	<listitem><para role='writernotes'>	151	<listitem><para>
132	Be sure your <filename>local.conf</filename> file has	152	<emphasis>Prepare Your <filename>local.conf</filename> File:</emphasis>
133	the correct	153	By default, the
134	<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>	154	<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
135	variable set for the target hardware on which your	155	variable is set to "qemux86", which is fine if you are
136	kernel image runs.	156	building for the QEMU emulator in 32-bit mode.
137	Also have the	157	However, if you are not, you need to set the
		158	<filename>MACHINE</filename> variable appropriately in
		159	your <filename>local.conf</filename> file found in the
		160	<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
		161	(i.e. <filename>~/poky/build</filename> in this example).
		162	</para>
		163
		164	<para>Also, since you are preparing to work on the kernel
		165	image, you need to set the
138	<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>	166	<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
139	variable set equal to "kernel-modules".	167	variable to include kernel modules.</para>
		168
		169	<para>This example uses the default "qemux86" for the
		170	<filename>MACHINE</filename> variable but needs to
		171	add the "kernel-modules":
		172	<literallayout class='monospaced'>
		173	MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
		174	</literallayout>
140	</para></listitem>	175	</para></listitem>
141	<listitem><para role='writernotes'>	176	<listitem><para>
142	Create a layer for later that will contain your patches	177	<emphasis>Create a Layer for Patches:</emphasis>
143	(if any) to the kernel.	178	You need to create a layer to hold patches created
		179	for the kernel image.
		180	You can use the <filename>yocto-layer</filename> command
		181	as follows:
		182	<literallayout class='monospaced'>
		183	$ cd ~/poky
		184	$ yocto-layer create my-kernel -o ../meta-my-kernel
		185	Please enter the layer priority you'd like to use for the layer: [default: 6]
		186	Would you like to have an example recipe created? (y/n) [default: n]
		187	Would you like to have an example bbappend file created? (y/n) [default: n]
		188
		189	New layer created in ../meta-my-kernel.
		190
		191	Don't forget to add it to your BBLAYERS (for details see ../meta-my-kernel/README).
		192	</literallayout>
		193	</para></listitem>
		194	<listitem><para>
		195	<emphasis>Inform the BitBake Build Environment About Your Layer:</emphasis>
		196	As directed when you created your layer, you need to add
		197	the layer to the
		198	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
		199	variable in the <filename>bblayers.conf</filename> file
		200	as follows:
		201	<literallayout class='monospaced'>
		202	$ cd ~/poky/build
		203	$ bitbake-layers add-layer ../../meta-my-kernel
		204	</literallayout>
144	</para></listitem>	205	</para></listitem>
145	<listitem><para role='writernotes'>	206	<listitem><para>
146	Build the extensible SDK.	207	<emphasis>Build the Extensible SDK:</emphasis>
		208	Use BitBake to build the extensible SDK specifically for
		209	the Minnowboard:
		210	<literallayout class='monospaced'>
		211	$ bitbake core-image-minimal -c populate_sdk_ext
		212	</literallayout>
		213	Once the build finishes, you can find the SDK installer
		214	file (i.e. <filename>*.sh</filename> file) in the
		215	following directory:
		216	<literallayout class='monospaced'>
		217	~/poky/build/tmp/deploy/sdk
		218	</literallayout>
		219	For this example, the installer file is named
		220	<filename>poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh</filename>
147	</para></listitem>	221	</para></listitem>
148	<listitem><para role='writernotes'>	222	<listitem><para>
149	Install the extensible SDK.	223	<emphasis>Install the Extensible SDK:</emphasis>
		224	Use the following command to install the SDK.
		225	For this example, install the SDK in the default
		226	<filename>~/poky_sdk</filename> directory:
		227	<literallayout class='monospaced'>
		228	$ cd ~/poky/build/tmp/deploy/sdk
		229	$ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh
		230	Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
		231	============================================================================
		232	Enter target directory for SDK (default: ~/poky_sdk):
		233	You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
		234	Extracting SDK......................................done
		235	Setting it up...
		236	Extracting buildtools...
		237	Preparing build system...
		238	Parsing recipes: 100% \|#################################################################\| Time: 0:00:52
		239	Initializing tasks: 100% \|############## ###############################################\| Time: 0:00:04
		240	Checking sstate mirror object availability: 100% \|######################################\| Time: 0:00:00
		241	Parsing recipes: 100% \|#################################################################\| Time: 0:00:33
		242	Initializing tasks: 100% \|##############################################################\| Time: 0:00:00
		243	done
		244	SDK has been successfully set up and is ready to be used.
		245	Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
		246	$ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux
		247	</literallayout>
150	</para></listitem>	248	</para></listitem>
151	<listitem><para role='writernotes'>	249	<listitem><para id='setting-up-the-esdk-terminal'>
152	Set up the terminal so that you can work with the	250	<emphasis>Set Up a New Terminal to Work With the Extensible SDK:</emphasis>
153	extensible SDK.	251	You must set up a new terminal to work with the SDK.
154	This terminal is known as the "eSDK Terminal" unlike the	252	You cannot use the same BitBake shell used to build the
155	terminal that is set up to run BitBake, which is known	253	installer.</para>
156	as the "BitBake Terminal".	254
		255	<para>After opening a new shell, run the SDK environment
		256	setup script as directed by the output from installing
		257	the SDK:
		258	<literallayout class='monospaced'>
		259	$ source ~/poky_sdk/environment-setup-i586-poky-linux
		260	"SDK environment now set up; additionally you may now run devtool to perform development tasks.
		261	Run devtool --help for further details.
		262	</literallayout>
		263	<note>
		264	If you get a warning about attempting to use the
		265	extensible SDK in an environment set up to run
		266	BitBake, you did not use a new shell.
		267	</note>
157	</para></listitem>	268	</para></listitem>
158	<listitem><para role='writernotes'>	269	<listitem><para>
159	Build the initial image using the extensible SDK.	270	<emphasis>Build the Clean Image:</emphasis>
		271	The final step in preparing to work on the kernel is to
		272	build an initial image using <filename>devtool</filename>
		273	in the new terminal you just set up and initialized for
		274	SDK work:
		275	<literallayout class='monospaced'>
		276	$ devtool build-image
		277	Parsing recipes: 100% \|##########################################\| Time: 0:00:05
		278	Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors.
		279	WARNING: No packages to add, building image core-image-minimal unmodified
		280	Loading cache: 100% \|############################################\| Time: 0:00:00
		281	Loaded 1299 entries from dependency cache.
		282	NOTE: Resolving any missing task queue dependencies
		283	Initializing tasks: 100% \|#######################################\| Time: 0:00:07
		284	Checking sstate mirror object availability: 100% \|###############\| Time: 0:00:00
		285	NOTE: Executing SetScene Tasks
		286	NOTE: Executing RunQueue Tasks
		287	NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded.
		288	NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86
		289	</literallayout>
		290	If you were building for actual hardware and not for
		291	emulation, you could flash the image to a USB stick
		292	on <filename>/dev/sdd</filename> and boot your device.
		293	Use a command similar to the following command to flash
		294	the image:
		295	<literallayout class='monospaced'>
		296	$ sudo dd if=tmp/deploy/images/<replaceable>architecture</replaceable>/core-image-minimal-<replaceable>architecture</replaceable>.wic of=/dev/sdd bs=1MB
		297	$ sync
		298	</literallayout>
160	</para></listitem>	299	</para></listitem>
161	</orderedlist>	300	</orderedlist>
162	</para>	301	</para>
163		302
164	<para role='writernotes'>	303	<para>
165	At this point, the user has enough stuff set up to work on the	304	At this point you have set up to start making modifications to the
166	kernel.	305	kernel by using the extensible SDK.
167	I will put a section in the "Common Tasks" area of this manual	306	For a continued example, see the
168	that finished out how to make a modification to the kernel.	307	"<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
		308	section.
169	</para>	309	</para>
170	</section>	310	</section>
171		311