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: 98ebe9acccceea2b833c1372a3e664befd1b6aef)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 95289c990f4cf45474b43a2dd12115b5b31275e6..811c23e8106936b00fb0abb5a842fc0edba6667e 100644 (file)
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4824,36 +4824,23 @@
 
                     <para>
                         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:
+                        image to a USB stick, or whatever media for which you
+                        built your image, and boot the resulting media.
+                        You can write the image by using
+                        <filename>bmaptool</filename> or
+                        <filename>dd</filename>:
                         <literallayout class='monospaced'>
-     $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb
-     [sudo] password for trz:
-     182274+0 records in
-     182274+0 records out
-     93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s
-     [trz at empanada ~]$ sudo eject /dev/sdb
+     $ oe-run-native bmaptool copy /var/tmp/wic/build/mkefidisk-201310230946-sda.direct /dev/sd<replaceable>X</replaceable>
                         </literallayout>
-                    </para>
-
-                    <para>
-                        This next example uses the
-                        <filename>bmap-tool</filename>.
-                        For this example, it is assumed you have write
-                        access:
+                        or
                         <literallayout class='monospaced'>
-     $ oe-run-native bmap-tool copy /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks /dev/sdb
+     $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sd<replaceable>X</replaceable>
                         </literallayout>
                         <note>
                             For more information on how to use the
-                            <filename>bmap-tool</filename> to flash a device
+                            <filename>bmaptool</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>"
+                            "<link linkend='flashing-images-using-bmaptool'>Flashing Images Using <filename>bmaptool</filename></link>"
                             section.
                         </note>
                     </para>

diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index bcee11ba220c16b45a16628b4859a66555d2b3f5..fd7e03f1aad0ce9dba90a93bf790fcd2e167a140 100644 (file)
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -328,29 +328,39 @@
     </para>
 </section>
 
-<section id='flashing-images-using-bmap-tool'>
-    <title>Flashing Images Using <filename>bmap-tool</filename></title>
+<section id='flashing-images-using-bmaptool'>
+    <title>Flashing Images Using <filename>bmaptool</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
+        <filename>bmaptool</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
+            You can use <filename>bmaptool</filename> to flash any
             type of image.
         </note>
         Use these steps to flash an image using
-        <filename>bmap-tool</filename>:
+        <filename>bmaptool</filename>:
+        <note>
+            Unless you are able to install the
+            <filename>bmap-tools</filename> package as mentioned in the note
+            in the second bullet of step 3 further down, you will need to build
+            <filename>bmaptool</filename> before using it.
+            Build the tool using the following command:
+            <literallayout class='monospaced'>
+     $ bitbake bmap-tools-native
+            </literallayout>
+        </note>
         <orderedlist>
             <listitem><para>
                 Add the following to your <filename>local.conf</filename>
                 file:
                 <literallayout class='monospaced'>
-     IMAGE_FSTYPES += "WIC WIC.BMAP"
+     IMAGE_FSTYPES += "wic wic.bmap"
                 </literallayout>
                 </para></listitem>
             <listitem><para>
@@ -361,33 +371,35 @@
                 </literallayout>
                 </para></listitem>
             <listitem><para>
-                Flash the image to the media by using the
-                <filename>bmap-tool</filename> depending on your particular
+                Flash the image to the media by using
+                <filename>bmaptool</filename> depending on your particular
                 setup:
                 <itemizedlist>
                     <listitem><para>
-                        If you have write access, use this command form:
+                        If you have write access to the media,
+                        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>
+     $ oe-run-native bmaptool 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
+                        If you do not have write access to
+                        the media, 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
+                            If you are using Ubuntu or Debian distributions,
+                            you can install the
+                            <filename>bmap-tools</filename> package 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
+     $ sudo apt-get install bmap-tools
                             </literallayout>
                         </note>
                         </para></listitem>
@@ -397,26 +409,11 @@
     </para>
 
     <para>
-        For help on the <filename>bmaptool</filename> command, use
-        <filename>bmaptool --help</filename>:
+        For help on the <filename>bmaptool</filename> command, use either of
+        the following commands:
         <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
+     $ oe-run-native bmaptool --help
         </literallayout>
     </para>
 </section>