docs: Define refcount_bits value

The 'refcount_bits' term used in the description of refcount block entry is
not defined in the specification. The definition is added in the
'refcount_order' section where refcount_bits was used as 'width in bits'.

Signed-off-by: Maria Kustova <maria.k@catit.be>
---
 docs/specs/qcow2.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

On 05/23/2014 07:41 AM, Maria Kustova wrote:
> The 'refcount_bits' term used in the description of refcount block entry is
> not defined in the specification. The definition is added in the
> 'refcount_order' section where refcount_bits was used as 'width in bits'.
> 
> Signed-off-by: Maria Kustova <maria.k@catit.be>
> ---
>  docs/specs/qcow2.txt | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)

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

> 
> diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt
> index f19536a..3f713a6 100644
> --- a/docs/specs/qcow2.txt
> +++ b/docs/specs/qcow2.txt
> @@ -107,8 +107,9 @@ in the description of a field.
>  
>           96 -  99:  refcount_order
>                      Describes the width of a reference count block entry (width
> -                    in bits = 1 << refcount_order). For version 2 images, the
> -                    order is always assumed to be 4 (i.e. the width is 16 bits).
> +                    in bits: refcount_bits = 1 << refcount_order). For version 2
> +                    images, the order is always assumed to be 4
> +                    (i.e. refcount_bits = 16).
>  
>          100 - 103:  header_length
>                      Length of the header structure in bytes. For version 2
>

On 05/23/2014 07:41 AM, Maria Kustova wrote:

>           96 -  99:  refcount_order
>                      Describes the width of a reference count block entry (width
> -                    in bits = 1 << refcount_order). For version 2 images, the
> -                    order is always assumed to be 4 (i.e. the width is 16 bits).
> +                    in bits: refcount_bits = 1 << refcount_order). For version 2
> +                    images, the order is always assumed to be 4
> +                    (i.e. refcount_bits = 16).

In light of all the recent CVE fixes (and possibly a separate patch if
any code is broken), I wonder if we need more work to ensure that
refcount_order is capped to a worthwhile maximum rather than causing
undefined behavior.  That is, a refcount_order of 0x10004 should be an
error, and not a synonym of refcount_order of 4, since '1 << 0x10004' is
undefined.

Furthermore, this raises some questions in my mind. Later on, we document:

    refcount_block_entries = (cluster_size / sizeof(uint16_t))

which implies a hard cap of refcount_bits=16 as the maximum, which in
turn implies a hard cap of refcount_order of 4 as the maximum.  Or is it
possible to specify a larger refcount_order, in which case
refcount_block_entries is dynamically sized to uint32_t, and in which
case the rest of the docs need to be fixed to accommodate that?

Also,

Refcount block entry (x = refcount_bits - 1):

    Bit  0 -  x:    Reference count of the cluster. If refcount_bits
implies a
                    sub-byte width, note that bit 0 means the least
significant
                    bit in this context.

but nothing is said about bits x+1 - 15 (which only exist when
refcount_order < 4, but which presumably must be all 0 bits for the file
to be valid).

On Fri, May 23, 2014 at 07:56:16AM -0600, Eric Blake wrote:
> On 05/23/2014 07:41 AM, Maria Kustova wrote:
> 
> >           96 -  99:  refcount_order
> >                      Describes the width of a reference count block entry (width
> > -                    in bits = 1 << refcount_order). For version 2 images, the
> > -                    order is always assumed to be 4 (i.e. the width is 16 bits).
> > +                    in bits: refcount_bits = 1 << refcount_order). For version 2
> > +                    images, the order is always assumed to be 4
> > +                    (i.e. refcount_bits = 16).
> 
> In light of all the recent CVE fixes (and possibly a separate patch if
> any code is broken), I wonder if we need more work to ensure that
> refcount_order is capped to a worthwhile maximum rather than causing
> undefined behavior.  That is, a refcount_order of 0x10004 should be an
> error, and not a synonym of refcount_order of 4, since '1 << 0x10004' is
> undefined.
> 
> Furthermore, this raises some questions in my mind. Later on, we document:
> 
>     refcount_block_entries = (cluster_size / sizeof(uint16_t))
> 
> which implies a hard cap of refcount_bits=16 as the maximum, which in
> turn implies a hard cap of refcount_order of 4 as the maximum.  Or is it
> possible to specify a larger refcount_order, in which case
> refcount_block_entries is dynamically sized to uint32_t, and in which
> case the rest of the docs need to be fixed to accommodate that?
> 
> Also,
> 
> Refcount block entry (x = refcount_bits - 1):
> 
>     Bit  0 -  x:    Reference count of the cluster. If refcount_bits
> implies a
>                     sub-byte width, note that bit 0 means the least
> significant
>                     bit in this context.
> 
> but nothing is said about bits x+1 - 15 (which only exist when
> refcount_order < 4, but which presumably must be all 0 bits for the file
> to be valid).

Only refcount_order = 4 is supported by QEMU at the moment.

I agree the spec could be made a bit clearer though.  Maybe Kevin wants
to send a patch to explain the details of refcount entry sizing.

Stefan

On Fri, May 23, 2014 at 05:41:29PM +0400, Maria Kustova wrote:
> The 'refcount_bits' term used in the description of refcount block entry is
> not defined in the specification. The definition is added in the
> 'refcount_order' section where refcount_bits was used as 'width in bits'.
> 
> Signed-off-by: Maria Kustova <maria.k@catit.be>
> ---
>  docs/specs/qcow2.txt | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)

Thanks, applied to my block tree:
https://github.com/stefanha/qemu/commits/block

Stefan