Re: [PATCH v11 2/2] docs: qcow2: introduce compression type feature

[Eric Blake <eblake@redhat.com>]

On 1/31/20 8:22 AM, Vladimir Sementsov-Ogievskiy wrote:
> The patch adds a new additional field to the qcow2 header: compression_type,
> which specifies compression type. If field is absent or zero, default
> compression type is set: ZLIB, which corresponds to current behavior.
> 
> New compression type (ZSTD) is to be added in further commit.
> 
> Suggested-by: Denis Plotnikov <dplotnikov@virtuozzo.com>
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
> ---
>   docs/interop/qcow2.txt | 19 ++++++++++++++++++-
>   1 file changed, 18 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/interop/qcow2.txt b/docs/interop/qcow2.txt
> index 823cc266e0..3a8d5c0c6e 100644
> --- a/docs/interop/qcow2.txt
> +++ b/docs/interop/qcow2.txt
> @@ -109,6 +109,11 @@ the next fields through header_length.
>                                   An External Data File Name header extension may
>                                   be present if this bit is set.
>   
> +                    Bit 3:      Compression type bit.  If this bit is set,
> +                                a non-default compression is used for compressed
> +                                clusters. The compression_type field must be
> +                                present and not zero.
> +

I'm still not sold on this.  What's wrong with:

            Bit 3:      Compression type bit.  If this bit is set,
                        a non-default compression may be used for
                        compressed clusters, and the compression_type
                        field must be present.

>                       Bits 3-63:  Reserved (set to 0)
>   
>            80 -  87:  compatible_features
> @@ -190,7 +195,19 @@ present*, if not altered by a specific incompatible bit.
>   to the field's offset. Also, all additional fields are not present for
>   version 2.
>   
> -        < ... No additional fields in the header currently ... >
> +              104:  compression_type
> +
> +                    Defines the compression method used for compressed clusters.
> +                    All compressed clusters in an image use the same compression
> +                    type.
> +
> +                    If the incompatible bit "Compression type" is set: the field
> +                    must be present and non-zero (which means non-zlib
> +                    compression type). Otherwise, this field must not be present
> +                    or must be zero (which means zlib).

            If the incompatible bit "Compression type" is set: the field
            must be present. Otherwise, this field must not be present
            or must be zero (which means zlib).  It is recommended but
            not required that the "Compression type" bit be clear if this
            field is present but zero.

> +
> +                    Available compression type values:
> +                        0: zlib <https://www.zlib.net/>
>   
>   
>   === Header padding ===
> 

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