Re: [Qemu-devel] [RFC PATCH 09/12] qapi/block-core: add BitmapMapping and BitmapEntry structs

[John Snow]

On 05/16/2018 05:37 PM, Eric Blake wrote:
>> +##
>> +# @BitmapMapping:
>> +#
>> +# List of described regions correlated to a named bitmap.
>> +#
>> +# @name: The name of the bitmap whose range is described here
>> +#
>> +# @entries: A list of zero or more @BitmapEntry elements representing
>> +#           the range(s) described by the bitmap.
> 
> Is it also worth documenting that the list will be in ascending order,
> with no overlaps (no two entries covering the same offset); and in fact
> with a gap between all entries (as otherwise those two consecutive
> entries could have been consolidated to one)?
> 

Hm. I didn't necessarily want to guarantee the order, but being more
specific about the output will assist legibility of the spec.

I'll amend the documentation and make some stronger guarantees.

>> +#
>> +# Since: 2.13
>> +#
>> +##
>> +{ 'struct': 'BitmapMapping',
>> +  'data': { 'name': 'str',
>> +            'entries': [ 'BitmapEntry' ] } }
>> +
>>   ##
>>   # @BlockdevCacheInfo:
>>   #