yocto-project-qs and others: Rewrite of the QS

This was a complete re-write of the YP Quick Start in an attempt
to streamline it, remove unecessary detail, and make it flow better
with the examples.  In doing so, many manuals were affected due to
section headings being renamed, information being moved, etc.  Here
is a list of the changes by manual:

Makefile - Removed two figures from TARFILE list for the
           yocto-project-qs.

           Added building-an-image.png to the ref-manual TARFILE list.

           Added using-a-pre-build-image.png to the adt-manual TARFILE
           list.

           Repositioned 'eclipse' in the adt-manual TARFILE list.

adt-manual: Fixed a cross-reference so that it goes to the new
            'Building Images' section that is within the YP QS.

            Added new section 'Example Using Pre-Build Binaries and
            QEMU' to hold the information that was formerly in YP QS.

dev-manual: Removed a cross-reference into the YP QS that promised how
            to configure the most efficent build.

            Changed a cross-reference into the YP QS from 'The Packages'
            to 'The Build System Packages'.

            Changed a cross-reference into the YP QS from 'Building an
            Image' to 'Building Images'.

            Changed a text reference from the YP QS to the adt-manual.

            Moved the bit about getting YP files by using the YP website
            from the YP QS to the dev-manual.

            Changed a cross-reference into the YP QS from 'Using Pre-Built
            Binaries and QEMU' to 'Example Using Pre-built Binaries and
            QEMU', which was moved to the adt-manual.

ref-manual: Changed a cross-reference into the YP QS from 'What You
            Need and How You Get It' to 'Setting Up to Use the Yocto Project'.

            Moved the note about if your system has oss4-dev in the
            packages area in the YP QS to the appropriate area in the
            ref-manual.

            Moved the introduction information regarding building an image
            along with the figure from YP QS to the ref-manual's section on
            building images.

toaster-manual: Changed a cross-reference into the YP QS from 'What You
                Need and How You Get It' to 'Setting Up to Use the Yocto
                Project'.

yocto-project-qs: Complete rewrite that changed many section headings and
                  removed much detail, which was placed in other manuals.

(From yocto-docs rev: da4ed8147b04963a700caa784bda709c57b4eb6e)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

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
new file mode 100644
index 0000000000..b03130d123
--- /dev/null
+++ b/documentation/adt-manual/figures/using-a-pre-built-image.png