From a8e9faac4053afe57352eba62da5e9693952e260 Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <srifenbark@gmail.com>
Date: Tue, 3 Jan 2017 14:15:31 -0800
Subject: [PATCH] dev-manual: Added section on bmap-tool to flash images

Fixes [YOCTO #10621]

bmaptool is integrated into the OpenEmbedded build system but is
not documented.  I added a new section describing how to flash an
image to media using the tool.  Also, updated a small section in the
Wic part of the manual that used "dd" to flash an example.  I added
a bmaptool counterpart here and referenced the reader back to the
main new section.

(From yocto-docs rev: 83a9a3aa5f20c7f389306eea9213eabea997aba1)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 .../dev-manual/dev-manual-common-tasks.xml    | 29 +++++-
 documentation/dev-manual/dev-manual-start.xml | 93 +++++++++++++++++++
 2 files changed, 118 insertions(+), 4 deletions(-)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index b2a2e32c5d..95289c990f 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4823,10 +4823,14 @@
                     </para>
 
                     <para>
-                        Continuing with the example, you can now directly
-                        <filename>dd</filename> the image to a USB stick, or
-                        whatever media for which you built your image,
-                        and boot the resulting media:
+                        Continuing with the example, you can now write the
+                        image to a USB stick, or whatever media for which
+                        you built your image, and boot the resulting media.
+                    </para>
+
+                    <para>
+                        The following example uses <filename>dd</filename>
+                        to write the image to a USB stick:
                         <literallayout class='monospaced'>
      $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb
      [sudo] password for trz:
@@ -4836,6 +4840,23 @@
      [trz at empanada ~]$ sudo eject /dev/sdb
                         </literallayout>
                     </para>
+
+                    <para>
+                        This next example uses the
+                        <filename>bmap-tool</filename>.
+                        For this example, it is assumed you have write
+                        access:
+                        <literallayout class='monospaced'>
+     $ oe-run-native bmap-tool copy /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks /dev/sdb
+                        </literallayout>
+                        <note>
+                            For more information on how to use the
+                            <filename>bmap-tool</filename> to flash a device
+                            with an image, see the
+                            "<link linkend='flashing-images-using-bmap-tool'>Flashing Images Using <filename>bmap-tool</filename></link>"
+                            section.
+                        </note>
+                    </para>
                 </section>
 
                 <section id='using-a-modified-kickstart-file'>
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index b59f54b085..bcee11ba22 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -328,6 +328,99 @@
     </para>
 </section>
 
+<section id='flashing-images-using-bmap-tool'>
+    <title>Flashing Images Using <filename>bmap-tool</filename></title>
+
+    <para>
+        An easy way to flash an image to a bootable device is to use
+        <filename>bmap-tool</filename>, which is integrated into the
+        OpenEmbedded build system.
+    </para>
+
+    <para>
+        Following, is an example that shows how to flash a Wic image.
+        <note>
+            You can use <filename>bmap-tool</filename> to flash any
+            type of image.
+        </note>
+        Use these steps to flash an image using
+        <filename>bmap-tool</filename>:
+        <orderedlist>
+            <listitem><para>
+                Add the following to your <filename>local.conf</filename>
+                file:
+                <literallayout class='monospaced'>
+     IMAGE_FSTYPES += "WIC WIC.BMAP"
+                </literallayout>
+                </para></listitem>
+            <listitem><para>
+                Either have your image ready (pre-built) or take the step
+                build the image:
+                <literallayout class='monospaced'>
+     $ bitbake <replaceable>image</replaceable>
+                </literallayout>
+                </para></listitem>
+            <listitem><para>
+                Flash the image to the media by using the
+                <filename>bmap-tool</filename> depending on your particular
+                setup:
+                <itemizedlist>
+                    <listitem><para>
+                        If you have write access, use this command form:
+                        <literallayout class='monospaced'>
+     $ oe-run-native bmap-tool copy ./tmp/deploy/images/qemux86-64/core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable>
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        If you do not have write access, use the following
+                        commands:
+                        <literallayout class='monospaced'>
+     $ sudo bash
+     $ PATH=tmp/sysroots/x86_64-linux/usr/bin/ bmaptool copy ./tmp/deploy/images/qemux86-64/core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable>
+                        </literallayout>
+                        <note>
+                            If you are using Ubuntu 16.10 or Debian,
+                            you can install
+                            <filename>bmaptool</filename> using the
+                            following command and then use the tool
+                            without specifying
+                            <filename>PATH</filename> even from the
+                            root account:
+                            <literallayout class='monospaced'>
+     $ sudo apt-get install bmap-tool
+                            </literallayout>
+                        </note>
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+        </orderedlist>
+    </para>
+
+    <para>
+        For help on the <filename>bmaptool</filename> command, use
+        <filename>bmaptool --help</filename>:
+        <literallayout class='monospaced'>
+     $ bmaptool --help
+     usage: bmaptool [-h] [--version] [-q] [-d] {create,copy} ...
+
+     Create block map (bmap) and copy files using bmap. The documentation can be
+     found here: source.tizen.org/documentation/reference/bmaptool
+
+     optional arguments:
+       -h, --help     show this help message and exit
+       --version      show program's version number and exit
+       -q, --quiet    be quiet
+       -d, --debug    print debugging information
+
+     subcommands:
+       {create,copy}
+         create       generate bmap for an image file (which should be a sparse
+                      file)
+         copy         write an image to a block device using bmap
+        </literallayout>
+    </para>
+</section>
+
 <section id='using-pre-built-binaries-and-qemu'>
     <title>Using Pre-Built Binaries and QEMU</title>