block: Remove unused BlockDeviceMapEntry
cover block: Remove unused BlockDeviceMapEntry
Hi,
Markus has revived a rather old patch to remove an unused QAPI structure:
https://lists.nongnu.org/archive/html/qemu-block/2020-10/msg01902.html
He quoted a response of mine to the original patch, where I noted that removing this structure is OK because it is superseded by another structure (MapEntry), but that other structure’s documentation is worse. So we should merge some of BlockDeviceMapEntry’s documentation into MapEntry before removing it.
This series combines said merge with Markus’s patch to drop BlockDeviceMapEntry.
Markus Armbruster (1):
block: Remove unused BlockDeviceMapEntry
Max Reitz (1):
qapi/block-core: Improve MapEntry documentation
qapi/block-core.json | 47 ++++++++++++-------------------------------- 1 file changed, 13 insertions(+), 34 deletions(-)
Signature · 1 line
2.28.0
PATCH 1/2 qapi/block-core: Improve MapEntry documentation
MapEntry and BlockDeviceMapEntry are kind of the same thing, and the latter is not used, so we want to remove it. However, the documentation it provides for some fields is better than that of MapEntry, so steal some of it for the latter.
(And adjust them a bit in the process, because I feel like we can make them even clearer.)
--- qapi/block-core.json | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-)
qapi/block-core.json +13 -5
@@ -244,17 +244,25 @@ # # Mapping information from a virtual block range to a host file range # -# @start: the start byte of the mapped virtual range +# @start: virtual (guest) offset of the first byte described by this +# entry # # @length: the number of bytes of the mapped virtual range # -# @data: whether the mapped range has data +# @data: reading the image will actually read data from a file (in +# particular, if @offset is present this means that the sectors +# are not simply preallocated, but contain actual data in raw +# format) # -# @zero: whether the virtual blocks are zeroed +# @zero: whether the virtual blocks read as zeroes # -# @depth: the depth of the mapping +# @depth: number of layers (0 = top image, 1 = top image's backing +# file, ..., n - 1 = bottom image (where n is the number of +# images in the chain)) before reaching one for which the +# range is allocated # -# @offset: the offset in file that the virtual sectors are mapped to +# @offset: if present, the image file stores the data for this range +# in raw format at the given (host) offset # # @filename: filename that is referred to by @offset #
Signature · 1 line
2.28.0
Re: [PATCH 1/2] qapi/block-core: Improve MapEntry documentation
Quoted 38 lines · Max Reitz
MapEntry and BlockDeviceMapEntry are kind of the same thing, and the latter is not used, so we want to remove it. However, the documentation it provides for some fields is better than that of MapEntry, so steal some of it for the latter.
(And adjust them a bit in the process, because I feel like we can make them even clearer.)
Signed-off-by Max Reitz <[email protected]>--- qapi/block-core.json | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-)qapi/block-core.json +8
-4@@ -244,17 +244,25 @@ # # Mapping information from a virtual block range to a host file range # -# @start: the start byte of the mapped virtual range +# @start: virtual (guest) offset of the first byte described by this +# entry # # @length: the number of bytes of the mapped virtual range # -# @data: whether the mapped range has data +# @data: reading the image will actually read data from a file (in +# particular, if @offset is present this means that the sectors +# are not simply preallocated, but contain actual data in raw +# format) # -# @zero: whether the virtual blocks are zeroed +# @zero: whether the virtual blocks read as zeroes # -# @depth: the depth of the mapping +# @depth: number of layers (0 = top image, 1 = top image's backing
qapi/block-core.json line 268
Quoted 10 lines
qapi/block-core.json +5
-1+# file, ..., n - 1 = bottom image (where n is the number of +# images in the chain)) before reaching one for which the +# range is allocated # -# @offset: the offset in file that the virtual sectors are mapped to +# @offset: if present, the image file stores the data for this range +# in raw format at the given (host) offset # # @filename: filename that is referred to by @offset #
I can't vouch for the comment's accuracy without reading a lot of code, but I can say that the comment is clearly much clearer, so:
PATCH 2/2 block: Remove unused BlockDeviceMapEntry
In reply to Max ReitzFrom: Markus Armbruster <[email protected]>
BlockDeviceMapEntry has never been used. It was added in commit facd6e2 "so that it is published through the introspection mechanism." What exactly introspecting types that aren't used for anything could accomplish isn't clear. What "introspection mechanism" to use is also nebulous. To the best of my knowledge, there has never been one that covered this type. Certainly not query-qmp-schema, which includes only types that are actually used in QMP.
Not being able to introspect BlockDeviceMapEntry hasn't bothered anyone enough to complain in almost four years. Get rid of it.
--- qapi/block-core.json | 29 ----------------------------- 1 file changed, 29 deletions(-)
qapi/block-core.json +0 -29
@@ -426,35 +426,6 @@ ## { 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] } -## -# @BlockDeviceMapEntry: -# -# Entry in the metadata map of the device (returned by "qemu-img map") -# -# @start: Offset in the image of the first byte described by this entry -# (in bytes) -# -# @length: Length of the range described by this entry (in bytes) -# -# @depth: Number of layers (0 = top image, 1 = top image's backing file, etc.) -# before reaching one for which the range is allocated. The value is -# in the range 0 to the depth of the image chain - 1. -# -# @zero: the sectors in this range read as zeros -# -# @data: reading the image will actually read data from a file (in particular, -# if @offset is present this means that the sectors are not simply -# preallocated, but contain actual data in raw format) -# -# @offset: if present, the image file stores the data for this range in -# raw format at the given offset. -# -# Since: 1.7 -## -{ 'struct': 'BlockDeviceMapEntry', - 'data': { 'start': 'int', 'length': 'int', 'depth': 'int', 'zero': 'bool', - 'data': 'bool', '*offset': 'int' } } - ## # @DirtyBitmapStatus: #
Signature · 1 line
2.28.0
Markus Armbruster
AppliedQuoted 7 lines · Max Reitz
Hi,
Markus has revived a rather old patch to remove an unused QAPI structure:
https://lists.nongnu.org/archive/html/qemu-block/2020-10/msg01902.html
Quoted 8 lines
He quoted a response of mine to the original patch, where I noted that removing this structure is OK because it is superseded by another structure (MapEntry), but that other structure’s documentation is worse. So we should merge some of BlockDeviceMapEntry’s documentation into MapEntry before removing it.
This series combines said merge with Markus’s patch to drop BlockDeviceMapEntry.
Queued, thanks!