specs/qcow2: Fix documentation of the compressed cluster descriptor
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
@@ -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
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;Signed-off-by Alberto Garcia <[email protected]>--- docs/interop/qcow2.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)docs/interop/qcow2.txt +0
-0
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