From 2c7d367d3153dc231a57111c98ed717e16bd5ca3 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Thu, 27 Nov 2014 10:42:10 +0000
Subject: [PATCH 1/1] Add section "Notes on disk format" to the manual.

---
 virt-bmap.pod | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/virt-bmap.pod b/virt-bmap.pod
index 14f56ac..9e66147 100644
--- a/virt-bmap.pod
+++ b/virt-bmap.pod
@@ -85,6 +85,19 @@ file
 
 The following column(s) identify the file or object.
 
+=head2 Notes on disk format
+
+The virt-bmap tool does I<not> auto-detect the disk format: you have
+to specify the correct format.
+
+Although in theory you can use any disk format, we found that block
+map detection works much more reliably if the disk is in C<raw>
+format.  With other formats it appears that structures within the
+format (like the qcow2 header) can confuse disk format detection,
+resulting in files appearing to be read which are probably not being
+accessed.  Therefore it is recommended that you first convert disks to
+raw using a tool such as L<qemu-img(1)>.
+
 =head2 bmaplogger: nbdkit plugin to observe file accesses
 
 The second tool is an L<nbdkit(1)> plugin called C<bmaplogger>.  Use
@@ -104,8 +117,7 @@ observe the files accessed by a virtual machine when booting:
 
 Set the format of the input disk image.  The default is C<raw>.
 
-Note this is I<not> auto-detected, you I<have to> specify the
-correct format.
+See L</Notes on disk format> above.
 
 =item B<--help>
 
@@ -159,6 +171,7 @@ Send the log output to a file.
 L<nbdkit(1)>,
 L<nbdkit-plugin(1)>,
 L<guestfs(3)>,
+L<qemu-img(1)>,
 L<http://libguestfs.org/>,
 L<http://www.redhat.com/mailman/listinfo/virt-tools-list>
 
-- 
1.8.3.1