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 qemuarch kernel-image filesystem-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. + +
+
+