[Qemu-devel] [PATCH] docs: clarify that qcow2 file size is not always a cluster multiple

[Stefan Hajnoczi <stefanha@redhat.com>]

Normally one would expect that qcow2 image file lengths are multiples of
the cluster size.  This is not true in all cases and the spec should
document this so implementers remember to accept such files.

$ qemu-img create -f qcow2 foo.qcow2 2G
Formatting 'foo.qcow2', fmt=qcow2 size=2147483648 encryption=off cluster_size=65536 lazy_refcounts=off
$ ls -l foo.qcow2
-rw-r--r-- 1 stefanha stefanha 197120 May 22 11:40 foo.qcow2
$ bc -q
3 * (64 * 1024) + 512
197120

The extra sector are the 4 L1 table entries that a 2 GB disk with 64 KB
cluster size needs.  The rest of the L1 table is omitted from the file
but allocation will continue at the next cluster boundary.

Reported-by: Maria Kustova <maxa@catit.be>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/specs/qcow2.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt
index f19536a..a46ee57 100644
--- a/docs/specs/qcow2.txt
+++ b/docs/specs/qcow2.txt
@@ -4,6 +4,10 @@ A qcow2 image file is organized in units of constant size, which are called
 (host) clusters. A cluster is the unit in which all allocations are done,
 both for actual guest data and for image metadata.
 
+If the end of the image file is not on a cluster boundary, the missing data is
+treated as zeroes.  This layout can occur when an L1 table or refcount table is
+the last thing in the file and not all entries in the table are used.
+
 Likewise, the virtual disk as seen by the guest is divided into (guest)
 clusters of the same size.
 
-- 
1.9.0