[Qemu-devel] [PATCH] specs/qcow2: Fix documentation of the compressed cluster descriptor

[Qemu-devel] [PATCH] specs/qcow2: Fix documentation of the compressed cluster descriptor

[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 <berto@igalia.com>
---
 docs/interop/qcow2.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/interop/qcow2.txt b/docs/interop/qcow2.txt
index d7fdb1fee3..b12972be82 100644
--- a/docs/interop/qcow2.txt
+++ b/docs/interop/qcow2.txt
@@ -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
-- 
2.11.0

Re: [Qemu-devel] [PATCH] specs/qcow2: Fix documentation of the compressed cluster descriptor

[Eric Blake]

On 02/20/2018 08:15 AM, Alberto Garcia wrote:
> 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 <berto@igalia.com>
> ---
>   docs/interop/qcow2.txt | 3 ++-
>   1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/interop/qcow2.txt b/docs/interop/qcow2.txt
> index d7fdb1fee3..b12972be82 100644
> --- a/docs/interop/qcow2.txt
> +++ b/docs/interop/qcow2.txt
> @@ -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.

Reviewed-by: Eric Blake <eblake@redhat.com>

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