Re: [Qemu-devel] [PATCH V11 11/17] qmp: add ImageInfo in BlockDeviceInfo used by query-block

[Luiz Capitulino <lcapitulino@redhat.com>]

On Wed, 10 Apr 2013 18:17:04 +0200
Markus Armbruster <armbru@redhat.com> wrote:

> Stefan Hajnoczi <stefanha@gmail.com> writes:
> 
> > On Tue, Apr 02, 2013 at 07:47:24PM +0800, Wenchao Xia wrote:
> >> diff --git a/qmp-commands.hx b/qmp-commands.hx
> >> index 6b20684..b856be7 100644
> >> --- a/qmp-commands.hx
> >> +++ b/qmp-commands.hx
> >> @@ -1703,6 +1703,47 @@ Each json-object contain the following:
> >>           - "iops": limit total I/O operations per second (json-int)
> >>           - "iops_rd": limit read operations per second (json-int)
> >>           - "iops_wr": limit write operations per second (json-int)
> >> +         - "image": the detail of the image, it is a json-object containing
> >> +            the following:
> >> +             - "filename": image file name (json-string)
> >> +             - "format": image format (json-string)
> >> +             - "virtual-size": image capacity in bytes (json-int)
> >> +             - "dirty-flag": true if image is not cleanly closed, not present
> >> +                             means clean (json-bool, optional)
> >> +             - "actual-size": actual size on disk in bytes of the image, not
> >> +                              present when image does not support thin
> >> +                              provision (json-int, optional)
> >> + - "cluster-size": size of a cluster in bytes, not present if image
> >> + format does not support it (json-int, optional)
> >> +             - "encrypted": true if the image is encrypted, not present means
> >> +                            false or the image format does not support
> >> +                            encryption (json-bool, optional)
> >> + - "backing_file": backing file name, not present means no backing
> >> +                               file is used or the image format does not
> >> +                               support backing file chain
> >> +                               (json-string, optional)
> >> +             - "full-backing-filename": full path of the backing file, not
> >> + present if it equals backing_file or no
> >> +                                        backing file is used
> >> +                                        (json-string, optional)
> >> +             - "backing-filename-format": the format of the backing file, not
> >> +                                          present means unknown or no backing
> >> +                                          file (json-string, optional)
> >> + - "snapshots": the internal snapshot info, it is an optional list
> >> +                of json-object containing the following:
> >> +                 - "id": unique snapshot id (json-string)
> >> +                 - "name": snapshot name (json-string)
> >> +                 - "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 nanoseconds 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 nanoseconds to be used
> >> +                                    with vm-clock-sec (json-int)
> >> +             - "backing-image": the detail of the backing image, it is an
> >> +                                optional json-object only present when a
> >> +                                backing image present for this image
> >
> > Please don't duplicate the ImageInfo documentation from
> > qapi-schema.json.
> 
> No, this is actually how it still needs to be done.
> 
> qmp-commands.hx predates qapi-schema.json.  We still generate
> QMP/qmp-commands.txt from qmp-commands.hx, not from qapi-schema.json.

Unfortunately, yes. However, as there are just a few commands missing
to be converted to the qapi, we could start generating the docs from
qapi-schema.json and avoid the duplication.

There's a problem though. qapi-schema.json is not tied to the QMP protocol
as qmp-commands.hx is, so I'm not sure it's a good place for the examples,
as the examples _are_ QMP specific. On the other hand, I don't know where
should the examples go.

Ideas?

> > I'm not sure how the documentation gets generated but we need to avoid
> > this, otherwise it will quickly get out of sync.
> 
> If I remember correctly, Luiz wants to get rid of qmp-commands.hx.  But
> we're not there, yet.

Right. We'll be able to do that when we finish to convert all commands
to the qapi. It's unfortunate that we (or maybe me) lost all speed at
the end of the race.