Re: [Qemu-devel] [PATCH V7 08/14] qmp: add interface query-images.

[Markus Armbruster]

Humor me: no period at end of subject, please

First pass, concentrating on interfaces, implementation mostly ignored.

Wenchao Xia <address@hidden> writes:

>   This mirror function will return all image info including
> snapshots, if specified backing image's info will also be returned.
> Now Qemu have both query-images and query-block interfaces.
>
> Signed-off-by: Wenchao Xia <address@hidden>
> ---
>  block.c          |   83 
> ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  qapi-schema.json |   34 ++++++++++++++++++++++
>  qmp-commands.hx  |   76 +++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 193 insertions(+), 0 deletions(-)
>
[...]
> diff --git a/qapi-schema.json b/qapi-schema.json
> index cd7ea25..9122bb9 100644
> --- a/qapi-schema.json
> +++ b/qapi-schema.json
> @@ -245,6 +245,22 @@
>             '*backing-filename-format': 'str', '*snapshots': ['SnapshotInfo'] 
> } }
>  
>  ##
> +# @DeviceImageInfo:
> +#
> +# Information about an image used by a QEMU block device
> +#
> +# @device: name of the block device
> +#
> +# @image: #optional info of the image used
> +#
> +# Since: 1.5
> +#
> +##
> +
> +{ 'type': 'DeviceImageInfo',
> +  'data': {'device': 'str', '*image': 'ImageInfo' } }
> +
> +##
>  # @StatusInfo:
>  #
>  # Information about VCPU run state
> @@ -789,6 +805,24 @@
>  { 'command': 'query-block', 'returns': ['BlockInfo'] }
>  
>  ##
> +# @query-images:
> +#
> +# Get a list of DeviceImageInfo for all virtual block devices.

# Get block device image information

> +#
> +# @device: #optional the name of the device to get image info from. If not
> +#          specified, all block devices will be queried
> +# @backing: #optional true to show information on backing images, false or
> +#          omitted to show just the top image of a block device

I'm not sure these flags are necessary.

> +#
> +# Returns: a list of @DeviceImageInfo describing each virtual block device
> +#
> +# Since: 1.5
> +##
> +{ 'command': 'query-images',
> +  'data': { '*device': 'str', '*backing': 'bool' },
> +  'returns': ['DeviceImageInfo'] }
> +
> +##
>  # @BlockDeviceStats:
>  #
>  # Statistics of a virtual block device or a block backing device.
> diff --git a/qmp-commands.hx b/qmp-commands.hx
> index 799adea..292d61e 100644
> --- a/qmp-commands.hx
> +++ b/qmp-commands.hx
> @@ -1743,6 +1743,82 @@ EQMP
>      },
>  
>  SQMP
> +query-images
> +-----------
> +
> +Show the block devices' images.

Show block device image information

> +
> +Each block image information is stored in a json-object and the returned 
> value
> +is a json-array of all devices' images.

Each device is represented by a json-object. The returned value is a json-array
of all devices.

> +
> +Each json-object contain the following:
> +
> +- "device": device name (json-string)
> +- "image": related image information, it is a optional json-object 
> containing the following:

- "image": image information (json-object, optional) containing:

> +         - "filename": image file name (json-string)
> +         - "format": image format (json-string)
> +         - "virtual-size": maximum capacity in bytes of the image (json-int)

            - "virtual-size": image capacity in bytes (json-int)

> +         - "dirty-flag": true if image is not cleanly closed (json-bool, 
> optional)

Long line.

What's the meaning of dirty-flag not present in object?

> +         - "actual-size": actual size on disk in bytes of the image 
> (json-int, optional)

            - "actual-size": actual on-disk image size in bytes
              (json-int, optional)

Can you explain when actual-size is present, and when not?  Same for the
other optional members.

> +         - "cluster-size": size of a cluster in bytes (json-int, optional)
> +         - "encrypted": true if the image is encrypted (json-bool, optional)
> +         - "backing_file": backing file name (json-string, optional)
> +         - "full-backing-filename": full path of the backing file 
> (json-string, optional)
> +         - "backing-filename-format": the format of the backing file 
> (json-string, optional)

Long lines.

> +         - "snapshots": the internal snapshot info, it is an optional list 
> of json-object
> +            containing the following:

            - "snapshots": internal snapshot info
              (json-array of json-object, optional)
              Each object contains:

> +             - "id": unique snapshot id (json-string)
> +             - "name": internal snapshot name (json-string)

Suggest to drop "internal"

> +             - "vm-state-size": size of the VM state in bytes (json-int)
> +             - "date-sec": UTC date of the snapshot in seconds (json-int)
> +             - "date-nsec": fractional part in nano seconds to be used with 
> date-sec(json-int)
> +             - "vm-clock-sec": VM clock relative to boot in seconds 
> (json-int)
> +             - "vm-clock-nsec": fractional part in nano seconds to be used 
> with vm-clock-sec (json-int)

Long lines.

A year has 86400 s == 8.64e13 ns, thus int64_t is good for more than
10000 years.  Why can't we simply measure in ns and dispense with the
awkward (sec, nsec) pair?

> +
> +Example:
> +
> +-> { "execute": "query-images" }
> +<- {
> +      "return":[
> +         {
> +            "device":"ide0-hd0",
> +            "image":{
> +               "filename":"disks/test0.img",
> +               "format":"qcow2",
> +               "virtual-size":1024000
> +            }
> +         },
> +         {
> +            "device":"ide0-hd1",
> +            "image":{
> +               "filename":"disks/test1.img",
> +               "format":"qcow2",
> +               "virtual-size":2048000,
> +               "snapshots":[
> +                  {
> +                     "id": "1",
> +                     "name": "snapshot1",
> +                     "vm-state-size": 0,
> +                     "date-sec": 10000200,
> +                     "date-nsec": 12,
> +                     "vm-clock-sec": 206,
> +                     "vm-clock-nsec": 30
> +                  }
> +               ]
> +            }
> +         }
> +      ]
> +   }
> +
> +EQMP
> +
> +    {
> +        .name       = "query-images",
> +        .args_type  = "device:B?, backing:-b",
> +        .mhandler.cmd_new = qmp_marshal_input_query_images,
> +    },
> +
> +SQMP
>  query-blockstats
>  ----------------