Re: [Qemu-devel] [PATCH v2] QMP: Introduce the documentation for query-qdm

[Markus Armbruster <armbru@redhat.com>]

[cc: kraxel]

I didn't get around to review v1.  Sorry.

Miguel Di Ciurcio Filho <miguel.filho@gmail.com> writes:

> Changelog from v1
> -----------------
> - renamed "props" to "properties"
> - updated the examples
> - reworded the explanations of "name" and "description"
> - split "type" into a json-object, adding "qmp" and "qdev"
> - list all possible values for "bus"
> - list all possible values for "qdev" on "type"
> - list all possible values for "qmp" on "type"
> ---
>  qemu-monitor.hx |   88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 88 insertions(+), 0 deletions(-)
>
> diff --git a/qemu-monitor.hx b/qemu-monitor.hx
> index 2af3de6..0055d0a 100644
> --- a/qemu-monitor.hx
> +++ b/qemu-monitor.hx
> @@ -2490,6 +2490,94 @@ 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 json-array, each element is a json-object describing
> +a single device type.
> +
> +Each json-object contains the following:
> +
> +- "name": name of the device (json-string)
> +- "bus": the name of the bus type for the device (json-string)
> +    - Possible values: PCI, SCSI, I2C, ISA, SSI, USB, virtio-serial-bus, System

Missing: IDE (hw/ide/qdev.c) and s390-virtio (hw/s390-virtio-bus.c).

> +- "alias": an alias by which the device is also known (json-string, optional)
> +- "description": description of the device  (json-string, optional)
> +- "creatable": whether this device can be created on command line (json-boolean)

"on the command line" is misleading; it applies to monitor (human & QMP)
as well.

"by the user"?

> +- "properties": a list where each element is an json-object that describes a
> +  property of the device. Each json-object contains the following:
> +     - "name": the name of the property (json-string)
> +     - "type": a json-object that contains the following:
> +        - "qdev": the internal name of the type of the property (json-string)
> +            - Possible values: uint8, uint16, uint32, uint64, int32, macaddr,
> +              drive, chr, string, netdev, bit, taddr
> +        - "qmp": the json equivalent type of the internal type (json-string)
> +            - Possible values: integer, string, boolean

Fairly close to JSON Schema, but there are differences.

Do we need "qdev"?  Is exposing it wise?  Smells a bit too much of
internal detail for comfort...

Could we use "type" just like JSON Schema?  Drop "qdev" or move it out
of "type", then make "type" what its member "qmp" is now.

Note: qdev property documentation overlaps with QMP command
self-documentation, because qdev properties are also arguments of
command device_add.  We may wish to revisit this when we do
self-documentation.

[...]

Note: query-qdm isn't just a straight port of info qdm to QMP.  It
additionally documents properties.  It's like info qdm + device_add D,?
for all D.  I'm fine with that.