ref-manual, mega-manual: Updates to "Image Generation"

Fixes [YOCTO #2808]

Updated the figure and placed it in the folders area for both
the ref-manual and mega-manual.  I had to add the
DEPLOY_DIR_IMAGE variable and create a new machine-specific
directory below deploy.  The text had to be adjusted to reflect
this change as well.

Also, created a new variable entry for DEPLOY_DIR_IMAGE for
the glossary of the ref-manual.

(From yocto-docs rev: 50a68810f854b32fa5dba477eafa8fd1eebbd7a4)

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

3 files changed, 49 insertions, 16 deletions

diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index f3f0db2..0947340 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -1079,13 +1079,16 @@
         <para>
             Images are written out to the
             <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-            inside the <filename>deploy/images</filename> folder as shown
-            in the figure.
+            inside the <filename>deploy/images/&lt;machine&gt;/</filename>
+            folder as shown in the figure.
             This folder contains any files expected to be loaded on the
             target device.
             The
             <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
-            variable points to the <filename>deploy</filename> directory.
+            variable points to the <filename>deploy</filename> directory,
+            while the
+            <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
+            variable points to the machine-specific directory.
             <itemizedlist>
                 <listitem><para><filename>&lt;kernel-image&gt;</filename>:
                     A kernel binary file.
@@ -1094,8 +1097,9 @@
                     kernel image file.
                     Depending on that variable, the file could begin with
                     a variety of naming strings.
-                    The <filename>deploy/images</filename> directory can
-                    contain multiple image files.</para></listitem>
+                    The <filename>deploy/images/&lt;machine&gt;</filename>
+                    directory can contain multiple image files for the
+                    machine.</para></listitem>
                 <listitem><para><filename>&lt;root-filesystem-image&gt;</filename>:
                     Root filesystems for the target device (e.g.
                     <filename>*.ext3</filename> or <filename>*.bz2</filename>
@@ -1103,25 +1107,27 @@
                     The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
                     variable setting determines the root filesystem image
                     type.
-                    The <filename>deploy/images</filename> directory can
-                    contain multiple root filesystems.</para></listitem>
+                    The <filename>deploy/images/&lt;machine&gt;</filename>
+                    directory can contain multiple root filesystems for the
+                    machine.</para></listitem>
                 <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
                     Tarballs that contain all the modules built for the kernel.
                     Kernel module tarballs exist for legacy purposes and
                     can be suppressed by setting the
                     <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
                     variable to "0".
-                    The <filename>deploy/images</filename> directory can
-                    contain multiple kernel module tarballs.
-                    </para></listitem>
+                    The <filename>deploy/images/&lt;machine&gt;</filename>
+                    directory can contain multiple kernel module tarballs
+                    for the machine.</para></listitem>
                 <listitem><para><filename>&lt;bootloaders&gt;</filename>:
                     Bootloaders supporting the image, if applicable to the
                     target machine.
-                    The <filename>deploy/images</filename> directory can
-                    contain multiple bootloaders.
-                    </para></listitem>
+                    The <filename>deploy/images/&lt;machine&gt;</filename>
+                    directory can contain multiple bootloaders for the
+                    machine.</para></listitem>
                 <listitem><para><filename>&lt;symlinks&gt;</filename>:
-                    The <filename>deploy/images</filename> folder contains
+                    The <filename>deploy/images/&lt;machine&gt;</filename>
+                    folder contains
                     a symbolic link that points to the most recently built file
                     for each machine.
                     These links might be useful for external scripts that
diff --git a/documentation/ref-manual/figures/images.png b/documentation/ref-manual/figures/images.png
index f81905d..d99eac1 100644
--- a/documentation/ref-manual/figures/images.png
+++ b/documentation/ref-manual/figures/images.png
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 51f4966..9e2be22 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1059,8 +1059,8 @@ Core layer for images cannot be removed
         <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
             <glossdef>
                 <para>
-                    Points to the area that the OpenEmbedded build system uses
-                    to place images, packages, SDKs and other output
+                    Points to the general area that the OpenEmbedded build
+                    system uses to place images, packages, SDKs and other output
                     files that are ready to be used outside of the build system.
                     By default, this directory resides within the
                     <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
@@ -1081,6 +1081,33 @@ Core layer for images cannot be removed
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
+            <glossdef>
+                <para>
+                    Points to the area that the OpenEmbedded build system uses
+                    to place images and other associated output files that are
+                    ready to be deployed onto the target machine.
+                    The directory is machine-specific as it contains the
+                    <filename>${MACHINE}</filename> name.
+                    By default, this directory resides within the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                    as <filename>tmp/deploy/images/${MACHINE}/</filename>.
+                </para>
+
+                <para>
+                    For more information on the structure of the Build
+                    Directory, see
+                    "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
+                    section.
+                    For more detail on the contents of the
+                    <filename>deploy</filename> directory, see the
+                    "<link linkend='images-dev-environment'>Images</link>" and
+                    "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
+                    sections.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
             <glossdef>
                 <para>The package description used by package managers.