Skip to contentSkip to conversation

specs/qcow2: Fix documentation of the compressed cluster descriptor

PATCH Superseded Alberto Garcia 2 participants 2 messages Feb 20, 2018

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 specs/qcow2: Fix documentation of the compressed cluster descriptor

The documentation claims that the cluster descriptor contains the number of sectors used to store the compressed data, but what it actually contains is the number of sectors *minus one*.

That can be easily seen in qcow2_decompress_cluster(), that adds one to the value stored in that field:

  nb_csectors = ((cluster_offset >> s->csize_shift) & s->csize_mask) + 1;
---
 docs/interop/qcow2.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
docs/interop/qcow2.txt +2 -1
index d7fdb1fee3..b12972be82 100644
@@ -429,7 +429,8 @@ Compressed Clusters Descriptor (x = 62 - (cluster_bits - 8)):
     Bit  0 -  x:    Host cluster offset. This is usually _not_ aligned to a
                     cluster boundary!
 
-       x+1 - 61:    Compressed size of the images in sectors of 512 bytes
+       x+1 - 61:    Size of the compressed data in sectors of 512 bytes,
+                    minus one (that is, a value of n here means n+1 sectors).
 
 If a cluster is unallocated, read requests shall read the data from the backing
 file (except if bit 0 in the Standard Cluster Descriptor is set). If there is
Signature · 1 line
2.11.0
Reviewed-by on v1 1/1
#1 lore raw
Quoted 19 lines · Alberto Garcia

The documentation claims that the cluster descriptor contains the number of sectors used to store the compressed data, but what it actually contains is the number of sectors *minus one*.

That can be easily seen in qcow2_decompress_cluster(), that adds one to the value stored in that field:

   nb_csectors = ((cluster_offset >> s->csize_shift) & s->csize_mask) + 1;
---
  docs/interop/qcow2.txt | 3 ++-
  1 file changed, 2 insertions(+), 1 deletion(-)
docs/interop/qcow2.txt +0 -0
index d7fdb1fee3..b12972be82 100644

docs/interop/qcow2.txt Compressed Clusters Descriptor (x = 62 - (cluster_bits - 8)): · line 433

Quoted 6 lines
docs/interop/qcow2.txt +2 -1
@@ -429,7 +429,8 @@ Compressed Clusters Descriptor (x = 62 - (cluster_bits - 8)):
      Bit  0 -  x:    Host cluster offset. This is usually _not_ aligned to a
                      cluster boundary!
 
-       x+1 - 61:    Compressed size of the images in sectors of 512 bytes
+       x+1 - 61:    Size of the compressed data in sectors of 512 bytes,
+                    minus one (that is, a value of n here means n+1 sectors).

Another way to read this field is as the index of the sector that includes the tail of the compressed data (so a value of 0 means the data ends in sector[0], occupying 1 sector; a value of 10 means the data ends in sector[10], occupying 11 sectors...). But your wording is more compact.

Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org