[Qemu-devel] Re: [PATCH 1/2] QMP: Introduce the documentation for query-qdm

[Luiz Capitulino <lcapitulino@redhat.com>]

On Fri,  2 Jul 2010 18:27:02 -0300
Miguel Di Ciurcio Filho <miguel.filho@gmail.com> wrote:

> ---
>  qemu-monitor.hx |   68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 68 insertions(+), 0 deletions(-)
> 
> diff --git a/qemu-monitor.hx b/qemu-monitor.hx
> index 9f62b94..5348899 100644
> --- a/qemu-monitor.hx
> +++ b/qemu-monitor.hx
> @@ -2490,6 +2490,74 @@ STEXI
>  show device tree
>  @item info qdm
>  show qdev device model list
> +ETEXI
> +SQMP
> +query-qdm
> +---------
> +
> +Describe the capabilities of all devices registered with qdev.
> +
> +The returned output is a list, each element is a json-object describing a single
> +device type.

s/The returned output is a list/The returned value is a json-array

> +
> +Each json-object contains the following:
> +
> +- "name": the short name of the device (json-string)

Why short? Isn't it the name itself?

> +- "bus": the name of the bus type for the device (json-string)

Do we need a list o possible values?

> +- "alias": an alias by which the device is also known (json-string, optional)
> +- "description": a long description the device  (json-string, optional)
> +- "creatable": whether this device can be created on command line (json-boolean)
> +- "props": a list where each element is an json-object that describes a property
> +of the device. Each json-object contains the following:

Suggest using "properties" (vs. "props")

> +     - "name": the short name of the property (json-string)

Why short? Isn't it the name itself?

> +     - "info": short description of the property (json-string)

You sure it's a description of the property? It seems to describe how to
set it (related, but slightly different).

Also, most of the time it seems to be an exact copy of "type". I suggest
to make it optional and only show it when it differs from "type".

> +     - "type": the data type of the property value (json-string)

We need a list o possible values, with a small explanation of each one.
Do we need the equivalent in json too?

> +
> +Example:
> +
> +-> { "execute": "query-qdm" }
> +<- {
> +      "return": [
> +        {
> +           "name": "virtio-9p-pci",
> +           "creatable": true,
> +           "bus": "PCI",
> +           "props": [
> +             {
> +                 "name": "indirect_desc",
> +                 "type": "bit",
> +                 "info": "on/off"
> +             },
> +             {
> +                 "name": "mount_tag",
> +                 "type": "string",
> +                 "info": "string"
> +             },
> +             {
> +                 "name": "fsdev",
> +                 "type": "string",
> +                 "info": "string"
> +             }
> +           ]
> +        },
> +        {
> +           "name": "virtio-balloon-pci",
> +           "creatable": true,
> +           "bus": "PCI",
> +           "props": [
> +             {
> +               "name": "indirect_desc",
> +               "type": "bit",
> +               "info": "on/off"
> +             }
> +           ]
> +        },
> +      ....
> +    ]

Suggest a NOTE saying this the equivalent of command-line options -device ?
and -device devname,?

> +
> +EQMP
> +
> +STEXI
>  @item info roms
>  show roms
>  @end table