diff --git a/documentation/Makefile b/documentation/Makefile
index 71420ac2bb..9197a40a78 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -147,7 +147,6 @@ ifeq ($(DOC),yocto-project-qs)
XSLTOPTS = --xinclude
ALLPREQ = html eclipse tarball
TARFILES = yocto-project-qs.html qs-style.css figures/yocto-environment.png \
- figures/building-an-image.png figures/using-a-pre-built-image.png \
figures/yocto-project-transp.png \
eclipse
MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
@@ -263,7 +262,7 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
figures/images.png figures/sdk.png figures/source-fetching.png \
figures/patching.png figures/configuration-compile-autoreconf.png \
figures/analysis-for-package-splitting.png figures/image-generation.png \
- figures/sdk-generation.png
+ figures/sdk-generation.png figures/building-an-image.png
MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
FIGURES = figures
STYLESHEET = $(DOC)/*.css
@@ -274,7 +273,8 @@ ifeq ($(DOC),adt-manual)
XSLTOPTS = --xinclude
ALLPREQ = html eclipse tarball
TARFILES = adt-manual.html adt-style.css figures/adt-title.png \
- eclipse
+ figures/using-a-pre-built-image.png \
+ eclipse
MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
FIGURES = figures
STYLESHEET = $(DOC)/*.css
diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
index 814adbd615..01f569f805 100644
--- a/documentation/adt-manual/adt-prepare.xml
+++ b/documentation/adt-manual/adt-prepare.xml
@@ -465,9 +465,12 @@
To get the kernel and filesystem images, you either have to build them or download
pre-built versions.
- You can find examples for both these situations in the
- "A Quick Test Run" section of
- the Yocto Project Quick Start.
+ For an example of how to build these images, see the
+ "Buiding Images"
+ section of the Yocto Project Quick Start.
+ For an example of downloading pre-build versions, see the
+ "Example Using Pre-Built Binaries and QEMU"
+ section.
@@ -720,6 +723,261 @@
variable in the Yocto Project Reference Manual's variable glossary.
+
+
+ Example Using Pre-Built Binaries and QEMU
+
+
+ If hardware, libraries and services are stable, you can get started by using a pre-built binary
+ of the filesystem image, kernel, and toolchain and run it using the QEMU emulator.
+ This scenario is useful for developing application software.
+
+
+
+
+
+
+
+ Using a Pre-Built Image
+
+
+
+
+ For this scenario, you need to do several things:
+
+
+
+ Install the appropriate stand-alone toolchain tarball.
+ Download the pre-built image that will boot with QEMU.
+ You need to be sure to get the QEMU image that matches your target machine’s
+ architecture (e.g. x86, ARM, etc.).
+ Download the filesystem image for your target machine's architecture.
+
+ Set up the environment to emulate the hardware and then start the QEMU emulator.
+
+
+
+
+ Installing the Toolchain
+
+
+ You can download a tarball installer, which includes the
+ pre-built toolchain, the runqemu
+ script, and support files from the appropriate directory under
+ .
+ Toolchains are available for 32-bit and 64-bit x86 development
+ systems from the i686 and
+ x86_64 directories, respectively.
+ The toolchains the Yocto Project provides are based off the
+ core-image-sato image and contain
+ libraries appropriate for developing against that image.
+ Each type of development system supports five or more target
+ architectures.
+
+
+
+ The names of the tarball installer scripts are such that a
+ string representing the host system appears first in the
+ filename and then is immediately followed by a string
+ representing the target architecture.
+
+
+
+ poky-glibc-host_system-image_type-arch-toolchain-release_version.sh
+
+ Where:
+ host_system is a string representing your development system:
+
+ i686 or x86_64.
+
+ image_type is a string representing the image you wish to
+ develop a Software Development Toolkit (SDK) for use against.
+ The Yocto Project builds toolchain installers using the
+ following BitBake command:
+
+ bitbake core-image-sato -c populate_sdk
+
+ arch is a string representing the tuned target architecture:
+
+ i586, x86_64, powerpc, mips, armv7a or armv5te
+
+ release_version is a string representing the release number of the
+ Yocto Project:
+
+ &DISTRO;, &DISTRO;+snapshot
+
+
+
+ For example, the following toolchain installer is for a 64-bit
+ development host system and a i586-tuned target architecture
+ based off the SDK for core-image-sato:
+
+ poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+
+
+
+
+ Toolchains are self-contained and by default are installed into
+ /opt/poky.
+ However, when you run the toolchain installer, you can choose an
+ installation directory.
+
+
+
+ The following command shows how to run the installer given a toolchain tarball
+ for a 64-bit x86 development host system and a 32-bit x86 target architecture.
+ You must change the permissions on the toolchain
+ installer script so that it is executable.
+
+
+
+ The example assumes the toolchain installer is located in ~/Downloads/.
+
+ If you do not have write permissions for the directory into which you are installing
+ the toolchain, the toolchain installer notifies you and exits.
+ Be sure you have write permissions in the directory and run the installer again.
+
+
+
+
+
+ $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+
+
+
+
+ For more information on how to install tarballs, see the
+ "Using a Cross-Toolchain Tarball" and
+ "Using BitBake and the Build Directory" sections in the Yocto Project Application Developer's Guide.
+
+
+
+
+ Downloading the Pre-Built Linux Kernel
+
+
+ You can download the pre-built Linux kernel suitable for running in the QEMU emulator from
+ .
+ Be sure to use the kernel that matches the architecture you want to simulate.
+ Download areas exist for the five supported machine architectures:
+ qemuarm, qemumips, qemuppc,
+ qemux86, and qemux86-64.
+
+
+
+ Most kernel files have one of the following forms:
+
+ *zImage-qemuarch.bin
+ vmlinux-qemuarch.bin
+
+ Where:
+ arch is a string representing the target architecture:
+ x86, x86-64, ppc, mips, or arm.
+
+
+
+
+ You can learn more about downloading a Yocto Project kernel in the
+ "Yocto Project Kernel"
+ bulleted item in the Yocto Project Development Manual.
+
+
+
+
+ Downloading the Filesystem
+
+
+ You can also download the filesystem image suitable for your target architecture from
+ .
+ Again, be sure to use the filesystem that matches the architecture you want
+ to simulate.
+
+
+
+ The filesystem image has two tarball forms: ext3 and
+ tar.
+ You must use the ext3 form when booting an image using the
+ QEMU emulator.
+ The tar form can be flattened out in your host development system
+ and used for build purposes with the Yocto Project.
+
+ core-image-profile-qemuarch.ext3
+ core-image-profile-qemuarch.tar.bz2
+
+ Where:
+ profile is the filesystem image's profile:
+ lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato,
+ sato-dev, or sato-sdk. For information on these types of image
+ profiles, see the "Images"
+ chapter in the Yocto Project Reference Manual.
+
+ arch is a string representing the target architecture:
+ x86, x86-64, ppc, mips, or arm.
+
+
+
+
+
+ Setting Up the Environment and Starting the QEMU Emulator
+
+
+ Before you start the QEMU emulator, you need to set up the emulation environment.
+ The following command form sets up the emulation environment.
+
+ $ source &YOCTO_ADTPATH_DIR;/environment-setup-arch-poky-linux-if
+
+ Where:
+ arch is a string representing the target architecture:
+ i586, x86_64, ppc603e, mips, or armv5te.
+
+ if is a string representing an embedded application binary interface.
+ Not all setup scripts include this string.
+
+
+
+
+ Finally, this command form invokes the QEMU emulator
+
+ $ runqemu qemuarchkernel-imagefilesystem-image
+
+ Where:
+ qemuarch is a string representing the target architecture: qemux86, qemux86-64,
+ qemuppc, qemumips, or qemuarm.
+
+ kernel-image is the architecture-specific kernel image.
+
+ filesystem-image is the .ext3 filesystem image.
+
+
+
+
+
+ Continuing with the example, the following two commands setup the emulation
+ environment and launch QEMU.
+ This example assumes the root filesystem (.ext3 file) and
+ the pre-built kernel image file both reside in your home directory.
+ The kernel and filesystem are for a 32-bit target architecture.
+
+ $ cd $HOME
+ $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux
+ $ runqemu qemux86 bzImage-qemux86.bin \
+ core-image-sato-qemux86.ext3
+
+
+
+
+ The environment in which QEMU launches varies depending on the filesystem image and on the
+ target architecture.
+ For example, if you source the environment for the ARM target
+ architecture and then boot the minimal QEMU image, the emulator comes up in a new
+ shell in command-line mode.
+ However, if you boot the SDK image, QEMU comes up with a GUI.
+ Booting the PPC image results in QEMU launching in the same shell in
+ command-line mode.
+
+
+
+