diff options
Diffstat (limited to 'documentation/adt-manual')
| -rw-r--r-- | documentation/adt-manual/adt-prepare.xml | 264 | ||||
| -rw-r--r-- | documentation/adt-manual/figures/using-a-pre-built-image.png | bin | 0 -> 12733 bytes |
2 files changed, 261 insertions, 3 deletions
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 @@ <para> 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 - "<ulink url='&YOCTO_DOCS_QS_URL;#test-run'>A Quick Test Run</ulink>" section of - the Yocto Project Quick Start. + For an example of how to build these images, see the + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-buiding-images'>Buiding Images</ulink>" + section of the Yocto Project Quick Start. + For an example of downloading pre-build versions, see the + "<link linkend='using-pre-built'>Example Using Pre-Built Binaries and QEMU</link>" + section. </para> <para> @@ -720,6 +723,261 @@ variable in the Yocto Project Reference Manual's variable glossary. </para> </section> + + <section id='using-pre-built'> + <title>Example Using Pre-Built Binaries and QEMU</title> + + <para> + 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. + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/> + </imageobject> + <caption> + <para>Using a Pre-Built Image</para> + </caption> + </mediaobject> + + <para> + For this scenario, you need to do several things: + </para> + + <itemizedlist> + <listitem><para>Install the appropriate stand-alone toolchain tarball.</para></listitem> + <listitem><para>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.).</para></listitem> + <listitem><para>Download the filesystem image for your target machine's architecture. + </para></listitem> + <listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator. + </para></listitem> + </itemizedlist> + + <section id='installing-the-toolchain'> + <title>Installing the Toolchain</title> + + <para> + You can download a tarball installer, which includes the + pre-built toolchain, the <filename>runqemu</filename> + script, and support files from the appropriate directory under + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. + Toolchains are available for 32-bit and 64-bit x86 development + systems from the <filename>i686</filename> and + <filename>x86_64</filename> directories, respectively. + The toolchains the Yocto Project provides are based off the + <filename>core-image-sato</filename> image and contain + libraries appropriate for developing against that image. + Each type of development system supports five or more target + architectures. + </para> + + <para> + 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. + </para> + + <literallayout class='monospaced'> + poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh + + Where: + <replaceable>host_system</replaceable> is a string representing your development system: + + i686 or x86_64. + + <replaceable>image_type</replaceable> 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 + + <replaceable>arch</replaceable> is a string representing the tuned target architecture: + + i586, x86_64, powerpc, mips, armv7a or armv5te + + <replaceable>release_version</replaceable> is a string representing the release number of the + Yocto Project: + + &DISTRO;, &DISTRO;+snapshot + </literallayout> + + <para> + 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 <filename>core-image-sato</filename>: + <literallayout class='monospaced'> + poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + </literallayout> + </para> + + <para> + Toolchains are self-contained and by default are installed into + <filename>/opt/poky</filename>. + However, when you run the toolchain installer, you can choose an + installation directory. + </para> + + <para> + 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. + </para> + + <para> + The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>. + <note> + 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. + </note> + </para> + + <para> + <literallayout class='monospaced'> + $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + </literallayout> + </para> + + <para> + For more information on how to install tarballs, see the + "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and + "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" sections in the Yocto Project Application Developer's Guide. + </para> + </section> + + <section id='downloading-the-pre-built-linux-kernel'> + <title>Downloading the Pre-Built Linux Kernel</title> + + <para> + You can download the pre-built Linux kernel suitable for running in the QEMU emulator from + <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>. + Be sure to use the kernel that matches the architecture you want to simulate. + Download areas exist for the five supported machine architectures: + <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>, + <filename>qemux86</filename>, and <filename>qemux86-64</filename>. + </para> + + <para> + Most kernel files have one of the following forms: + <literallayout class='monospaced'> + *zImage-qemu<replaceable>arch</replaceable>.bin + vmlinux-qemu<replaceable>arch</replaceable>.bin + + Where: + <replaceable>arch</replaceable> is a string representing the target architecture: + x86, x86-64, ppc, mips, or arm. + </literallayout> + </para> + + <para> + You can learn more about downloading a Yocto Project kernel in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" + bulleted item in the Yocto Project Development Manual. + </para> + </section> + + <section id='downloading-the-filesystem'> + <title>Downloading the Filesystem</title> + + <para> + You can also download the filesystem image suitable for your target architecture from + <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>. + Again, be sure to use the filesystem that matches the architecture you want + to simulate. + </para> + + <para> + The filesystem image has two tarball forms: <filename>ext3</filename> and + <filename>tar</filename>. + You must use the <filename>ext3</filename> form when booting an image using the + QEMU emulator. + The <filename>tar</filename> form can be flattened out in your host development system + and used for build purposes with the Yocto Project. + <literallayout class='monospaced'> + core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.ext3 + core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.tar.bz2 + + Where: + <replaceable>profile</replaceable> 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 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" + chapter in the Yocto Project Reference Manual. + + <replaceable>arch</replaceable> is a string representing the target architecture: + x86, x86-64, ppc, mips, or arm. + </literallayout> + </para> + </section> + + <section id='setting-up-the-environment-and-starting-the-qemu-emulator'> + <title>Setting Up the Environment and Starting the QEMU Emulator</title> + + <para> + Before you start the QEMU emulator, you need to set up the emulation environment. + The following command form sets up the emulation environment. + <literallayout class='monospaced'> + $ source &YOCTO_ADTPATH_DIR;/environment-setup-<replaceable>arch</replaceable>-poky-linux-<replaceable>if</replaceable> + + Where: + <replaceable>arch</replaceable> is a string representing the target architecture: + i586, x86_64, ppc603e, mips, or armv5te. + + <replaceable>if</replaceable> is a string representing an embedded application binary interface. + Not all setup scripts include this string. + </literallayout> + </para> + + <para> + Finally, this command form invokes the QEMU emulator + <literallayout class='monospaced'> + $ runqemu <replaceable>qemuarch</replaceable> <replaceable>kernel-image</replaceable> <replaceable>filesystem-image</replaceable> + + Where: + <replaceable>qemuarch</replaceable> is a string representing the target architecture: qemux86, qemux86-64, + qemuppc, qemumips, or qemuarm. + + <replaceable>kernel-image</replaceable> is the architecture-specific kernel image. + + <replaceable>filesystem-image</replaceable> is the .ext3 filesystem image. + + </literallayout> + </para> + + <para> + Continuing with the example, the following two commands setup the emulation + environment and launch QEMU. + This example assumes the root filesystem (<filename>.ext3</filename> 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. + <literallayout class='monospaced'> + $ cd $HOME + $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux + $ runqemu qemux86 bzImage-qemux86.bin \ + core-image-sato-qemux86.ext3 + </literallayout> + </para> + + <para> + 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. + <note>Booting the PPC image results in QEMU launching in the same shell in + command-line mode.</note> + </para> + </section> +</section> + </chapter> <!-- vim: expandtab tw=80 ts=4 diff --git a/documentation/adt-manual/figures/using-a-pre-built-image.png b/documentation/adt-manual/figures/using-a-pre-built-image.png Binary files differnew file mode 100644 index 0000000000..b03130d123 --- /dev/null +++ b/documentation/adt-manual/figures/using-a-pre-built-image.png |
