Re: [Qemu-devel] [PATCH 1/2] QMP: Introduce commands doc

[Markus Armbruster <armbru@redhat.com>]

Luiz Capitulino <lcapitulino@redhat.com> writes:

> One of the most important missing feature in QMP today is its
> supported commands documentation.
>
> The plan is to make it part of self-description support, however
> self-description is a big task we have been postponing for a
> long time now and still don't know when it's going to be done.
>
> In order not to compromise QMP adoption and make users' life easier,
> this commit adds a simple text documentation which fully describes
> all QMP supported commands.
>
> This is not ideal for a number of reasons (harder to maintain,
> text-only, etc) but does improve the current situation.
>
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>  QMP/README           |    5 +-
>  QMP/qmp-commands.txt | 1033 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 1036 insertions(+), 2 deletions(-)
>  create mode 100644 QMP/qmp-commands.txt
>
> diff --git a/QMP/README b/QMP/README
> index 9334c25..35a80c7 100644
> --- a/QMP/README
> +++ b/QMP/README
> @@ -15,8 +15,9 @@ QMP is JSON[1] based and has the following features:
>  
>  For more information, please, refer to the following files:
>  
> -o qmp-spec.txt    QEMU Monitor Protocol current specification
> -o qmp-events.txt  List of available asynchronous events
> +o qmp-spec.txt      QEMU Monitor Protocol current specification
> +o qmp-commands.txt  QMP supported commands
> +o qmp-events.txt    List of available asynchronous events
>  
>  There are also two simple Python scripts available:
>  
> diff --git a/QMP/qmp-commands.txt b/QMP/qmp-commands.txt
> new file mode 100644
> index 0000000..b1b0e02
> --- /dev/null
> +++ b/QMP/qmp-commands.txt
> @@ -0,0 +1,1033 @@

I reviewed this part before, and it looks good now.

[...]
> +2. Query Commands
> +=================
> +
> +query-balloon
> +-------------
> +
> +Show balloon information.
> +
> +Make an asynchronous request for balloon info. When the request completes a
> +json-object will be returned containing the following data:
> +
> +- "actual": current balloon value in bytes (json-int)
> +- "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
> +- "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
> +- "major_page_faults": Number of major faults (json-int, optional)
> +- "minor_page_faults": Number of minor faults (json-int, optional)
> +- "free_mem":Total amount of free and unused memory in bytes (json-int,optional)

Nitpick: space after comma, please.

> +- "total_mem": Total amount of available memory in bytes (json-int, optional)
> +
> +Example:
> +
> +{
> +   "return":{
> +      "actual":1073741824,
> +      "mem_swapped_in":0,
> +      "mem_swapped_out":0,
> +      "major_page_faults":142,
> +      "minor_page_faults":239245,
> +      "free_mem":1014185984,
> +      "total_mem":1044668416
> +   }
> +}
> +
> +query-block
> +-----------
> +
> +Show the block devices.
> +
> +Each block device information is stored in a json-object and the returned value
> +is a json-array of all devices.
> +
> +Each json-object contain the following:
> +
> +- "device": device name (json-string)
> +- "type": device type (json-string)

Possible values?  "hd", "cdrom", "floppy".  Code also has "unknown", but
when it uses that, it's badly broken.

> +- "removable": true if the device is removable, false otherwise (json-bool)
> +- "locked": true if the device is locked, false otherwise (json-bool)
> +- "inserted": only present if the device is inserted, it is a json-object
> +   containing the following:
> +         - "file": device file name (json-string)
> +         - "ro": true if read-only, false otherwise (json-bool)
> +         - "drv": driver format name (json-string)

Possible values?

> +         - "backing_file": backing file name if one is used (json-string)

Suggest

            - "backing_file": backing file name (json-string, optional)

for consistency with optional members elsewhere.

> +         - "encrypted": true if encrypted, false otherwise (json-bool)
> +
> +Example:
> +
> +{
> +   "return":[
> +      {
> +         "device":"ide0-hd0",
> +         "type":"hd",
> +         "removable":false,
> +         "locked":false,
> +         "inserted":{
> +            "file":"/tmp/foobar",
> +            "ro":false,
> +            "drv":"qcow2"

"encrypted" is missing here.

> +         }
> +      },
> +      {
> +         "device":"floppy0",
> +         "type":"floppy",
> +         "removable":true,
> +         "locked":false
> +      }
> +   ]
> +}
> +
> +query-blockstats
> +----------------
> +
> +Show block device statistics.
> +
> +Each device statistic information is stored in a json-object and the returned
> +value is a json-array of all devices.
> +
> +Each json-object contain the following:
> +
> +- "device": device name (json-string)
> +- "stats": A json-object with the statistics information, it contains:
> +    - "rd_bytes": bytes read (json-int)
> +    - "wr_bytes": bytes written (json-int)
> +    - "rd_operations": read operations (json-int)
> +    - "wr_operations": write operations (json-int)
> +    - "wr_highest_offset": Highest offset of a sector written since the
> +                           BlockDriverState has been opened (json-int)
> +    - "parent": Contains recursively the statistics of the underlying
> +                protocol (e.g. the host file for a qcow2 image). If there is
> +                no underlying protocol, this field is omitted
> +                (json-object, optional)
> +
> +Example:
> +
> +{
> +   "return":[
> +      {
> +         "device":"ide0-hd0",
> +         "stats":{
> +            "rd_bytes":512,
> +            "wr_bytes":0,
> +            "rd_operations":1,
> +            "wr_operations":0,
> +            "wr_highest_offset":0,
> +            "parent":{
> +               "stats":{
> +                  "rd_bytes":1024,
> +                  "wr_bytes":0,
> +                  "rd_operations":2,
> +                  "wr_operations":0,
> +                  "wr_highest_offset":0
> +               }
> +            }
> +         }
> +      },
> +      {
> +         "device":"ide1-cd0",
> +         "stats":{
> +            "rd_bytes":0,
> +            "wr_bytes":0,
> +            "rd_operations":0,
> +            "wr_operations":0,
> +            "wr_highest_offset":0
> +         }
> +      }
> +   ]
> +}
> +
> +query-chardev
> +-------------
> +
> +Each device is represented by a json-object. The returned value is a json-array
> +of all devices.
> +
> +Each json-object contain the following:
> +
> +- "label": device's label (json-string)
> +- "filename": device's file (json-string)
> +
> +Example:
> +
> +{
> +   "return":[
> +      {
> +         "label":"monitor",
> +         "filename":"stdio"
> +      },
> +      {
> +         "label":"serial0",
> +         "filename":"vc"
> +      }
> +   ]
> +}
> +
> +query-commands
> +--------------
> +
> +List QMP available commands.
> +
> +Each command is represented by a json-object, the returned value is a json-array
> +of all commands.
> +
> +Each json-object contain:
> +
> +- "name": command's name (json-string)
> +
> +Example:
> +
> +{
> +   "return":[
> +      {
> +         "name":"query-balloon"
> +      },
> +      {
> +         "name":"system_powerdown"
> +      }
> +   ]
> +}
> +
> +Note: This example has been shortened as the real response is too long.
> +
> +query-cpus
> +----------
> +
> +Show CPU information.
> +
> +Return a json-array. Each CPU is represented by a json-object, which contains:
> +
> +- "cpu": CPU index (json-int)

It's actually upper case (see example below).  I hate that.

> +- "current": true if this is the current CPU, false otherwise (json-bool)
> +- "halted": true if the cpu is halted, false otherwise (json-bool)
> +- Current program counter. The key's name depends on the architecture:
> +     "pc": i386/x86_64 (json-int)
> +     "nip": PPC (json-int)
> +     "pc" and "npc": sparc (json-int)
> +     "PC": mips (json-int)

Key name depending on arch: isn't that an extraordinarily bad idea?

> +
> +Example:
> +
> +{
> +   "return":[
> +      {
> +         "CPU":0,
> +         "current":true,
> +         "halted":false,
> +         "pc":3227107138
> +      },
> +      {
> +         "CPU":1,
> +         "current":false,
> +         "halted":true,
> +         "pc":7108165
> +      }
> +   ]
> +}
> +
> +query-hpet
> +----------
> +
> +Show HPET state.
> +
> +Return a json-object with the following information:
> +
> +- "enabled": true if hpet if enabled, false otherwise (json-bool)
> +
> +Example:
> +
> +{ "return": { "enabled": true } }
> +
> +query-kvm
> +---------
> +
> +Show KVM information.
> +
> +Return a json-object with the following information:
> +
> +- "enabled": true if KVM support is enabled, false otherwise (json-bool)
> +- "present": true if QEMU has KVM support, false otherwise (json-bool)
> +
> +Example:
> +
> +{ "return": { "enabled": true, "present": true } }
> +
> +query-mice
> +----------
> +
> +Show VM mice information.
> +
> +Each mouse is represented by a json-object, the returned value is a json-array
> +of all mice.
> +
> +The mouse json-object contains the following:
> +
> +- "name": mouse's name (json-string)
> +- "index": mouse's index (json-int)
> +- "current": true if this mouse is receiving events, false otherwise (json-bool)
> +- "absolute": true if the mouse generates absolute input events (json-bool)
> +
> +Example:
> +
> +{
> +   "return":[
> +      {
> +         "name":"QEMU Microsoft Mouse",
> +         "index":0,
> +         "current":false,
> +         "absolute":false
> +      },
> +      {
> +         "name":"QEMU PS/2 Mouse",
> +         "index":1,
> +         "current":true,
> +         "absolute":true
> +      }
> +   ]
> +}
> +
> +query-migrate
> +-------------
> +
> +Migration status.
> +
> +Return a json-object. If migration is active there will be another json-object
> +with RAM migration status and if block migration is active another one with
> +block migration status.
> +
> +The main json-object contains the following:
> +
> +- "status": migration status (json-string)

Possible values?  "active", "completed", "failed", "cancelled".  Note
there's no value for "never attempted"; see below.

> +- "ram": only present if "status" is "active", it is a json-object with the
> +  following RAM information (in bytes):
> +         - "transferred": amount transferred (json-int)
> +         - "remaining": amount remaining (json-int)
> +         - "total": total (json-int)
> +- "disk": only present if "status" is "active" and it is a block migration,
> +  it is a json-object with the following disk information (in bytes):
> +         - "transferred": amount transferred (json-int)
> +         - "remaining": amount remaining (json-int)
> +         - "total": total (json-int)

Before the first migration, we actually reply with

{"return": {}}

which contradicts the doc.

> +
> +Examples:
> +
> +1. Migration is "completed":
> +
> +{ "return": { "status": "completed" } }
> +
> +2. Migration is "active" and it is not a block migration:
> +
> +{
> +   "return":{
> +      "status":"active",
> +      "ram":{
> +         "transferred":123,
> +         "remaining":123,
> +         "total":246
> +      }
> +   }
> +}
> +
> +3. Migration is "active" and it is a block migration:
> +
> +{
> +   "return":{
> +      "status":"active",
> +      "ram":{
> +         "total":1057024,
> +         "remaining":1053304,
> +         "transferred":3720
> +      },
> +      "disk":{
> +         "total":20971520,
> +         "remaining":20880384,
> +         "transferred":91136
> +      }
> +   }
> +}
> +
> +query-name
> +----------
> +
> +Show VM name.
> +
> +Return a json-object with the following information:
> +
> +- "name": VM's name (json-string, optional)
> +
> +Example:
> +
> +{ "return": { "name": "qemu-name" } }
> +
> +query-pci
> +---------
> +
> +PCI buses and devices information.
> +
> +The returned value is a json-array of all buses. Each bus is represented by
> +a json-object, which has a key with a json-array of all PCI devices attached
> +to it. Each device is represented by a json-object.
> +
> +The bus json-object contains the following:
> +
> +- "bus": bus number (json-int)
> +- "devices": a json-array of json-objects, each json-object represents a
> +             PCI device
> +
> +The PCI device json-object contains the following:
> +
> +- "bus": identical to the parent's bus number (json-int)
> +- "slot": slot number (json-int)
> +- "function": function number (json-int)
> +- "class_info": a json-object containing:
> +     - "desc": device class description (json-string, optional)
> +     - "class": device class number (json-int)
> +- "id": a json-object containing:
> +     - "device": device ID (json-int)
> +     - "vendor": vendor ID (json-int)
> +- "irq": device's IRQ if assigned (json-int, optional)
> +- "qdev_id": qdev id string (json-string)
> +- "pci_bridge": It's a json-object, only present if this device is a
> +                PCI bridge, contains:
> +     - "bus": bus number (json-int)
> +     - "secondary": secondary bus number (json-int)
> +     - "subordinate": subordinate bus number (json-int)
> +     - "io_range": a json-object with memory range information (json-int)
> +     - "memory_range": a json-object with memory range information (json-int)
> +     - "prefetchable_range": a json-object with memory range
> +                             information (json-int)
> +     - "devices": a json-array of PCI devices if there's any attached (optional)
> +- "regions": a json-array of json-objects, each json-object represents a
> +             memory region of this device
> +
> +The memory range json-object contains the following:
> +
> +- "base": base memory address (json-int)
> +- "limit": limit value (json-int)
> +
> +The region json-object can be an I/O region or a memory region, an I/O region
> +json-object contains the following:
> +
> +- "type": "io" (json-string, fixed)
> +- "bar": BAR number (json-int)
> +- "address": memory address (json-int)
> +- "size": memory size (json-int)
> +
> +A memory region json-object contains the following:
> +
> +- "type": "memory" (json-string, fixed)
> +- "bar": BAR number (json-int)
> +- "address": memory address (json-int)
> +- "size": memory size (json-int)
> +- "mem_type_64": true or false (json-bool)
> +- "prefetch": true or false (json-bool)
> +
> +Example:
> +
> +{
> +   "return":[
> +      {
> +         "bus":0,
> +         "devices":[
> +            {
> +               "bus":0,
> +               "qdev_id":"",
> +               "slot":0,
> +               "class_info":{
> +                  "class":1536,
> +                  "desc":"Host bridge"
> +               },
> +               "id":{
> +                  "device":32902,
> +                  "vendor":4663
> +               },
> +               "function":0,
> +               "regions":[
> +
> +               ]

Suggest to simply write

                  "regions":[]


> +            },
> +            {
> +               "bus":0,
> +               "qdev_id":"",
> +               "slot":1,
> +               "class_info":{
> +                  "class":1537,
> +                  "desc":"ISA bridge"
> +               },
> +               "id":{
> +                  "device":32902,
> +                  "vendor":28672
> +               },
> +               "function":0,
> +               "regions":[
> +
> +               ]
> +            },
> +            {
> +               "bus":0,
> +               "qdev_id":"",
> +               "slot":1,
> +               "class_info":{
> +                  "class":257,
> +                  "desc":"IDE controller"
> +               },
> +               "id":{
> +                  "device":32902,
> +                  "vendor":28688
> +               },
> +               "function":1,
> +               "regions":[
> +                  {
> +                     "bar":4,
> +                     "size":16,
> +                     "address":49152,
> +                     "type":"io"
> +                  }
> +               ]
> +            },
> +            {
> +               "bus":0,
> +               "qdev_id":"",
> +               "slot":2,
> +               "class_info":{
> +                  "class":768,
> +                  "desc":"VGA controller"
> +               },
> +               "id":{
> +                  "device":4115,
> +                  "vendor":184
> +               },
> +               "function":0,
> +               "regions":[
> +                  {
> +                     "prefetch":true,
> +                     "mem_type_64":false,
> +                     "bar":0,
> +                     "size":33554432,
> +                     "address":4026531840,
> +                     "type":"memory"
> +                  },
> +                  {
> +                     "prefetch":false,
> +                     "mem_type_64":false,
> +                     "bar":1,
> +                     "size":4096,
> +                     "address":4060086272,
> +                     "type":"memory"
> +                  },
> +                  {
> +                     "prefetch":false,
> +                     "mem_type_64":false,
> +                     "bar":6,
> +                     "size":65536,
> +                     "address":-1,
> +                     "type":"memory"
> +                  }
> +               ]
> +            },
> +            {
> +               "bus":0,
> +               "qdev_id":"",
> +               "irq":11,
> +               "slot":4,
> +               "class_info":{
> +                  "class":1280,
> +                  "desc":"RAM controller"
> +               },
> +               "id":{
> +                  "device":6900,
> +                  "vendor":4098
> +               },
> +               "function":0,
> +               "regions":[
> +                  {
> +                     "bar":0,
> +                     "size":32,
> +                     "address":49280,
> +                     "type":"io"
> +                  }
> +               ]
> +            }
> +         ]
> +      }
> +   ]
> +}
> +
> +Note: This example has been shortened as the real response is too long.

Actually, I get a shorter response for my minimal guest: just slots
0..3.  Suggest to omit slot 4 and this note.

> +
> +query-status
> +------------
> +
> +Return a json-object with the following information:
> +
> +- "running": true if the VM is running, or false if it is paused (json-bool)
> +- "singlestep": true if the VM is in single step mode,
> +                false otherwise (json-bool)
> +
> +Example:
> +
> +{ "return": { "running": true, "singlestep": false } }
> +
> +query-uuid
> +----------
> +
> +Show VM UUID.
> +
> +Return a json-object with the following information:
> +
> +- "UUID": Universally Unique Identifier (json-string)
> +
> +Example:
> +
> +{ "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
> +
> +query-version
> +-------------
> +
> +Show QEMU version.
> +
> +Return a json-object with the following information:
> +
> +- "qemu": QEMU's version (json-string)
> +- "package": package's version (json-string)
> +
> +Example:
> +
> +{ "return": { "qemu": "0.11.50", "package": "" } }
> +
> +query-vnc
> +---------
> +
> +Show VNC server information.
> +
> +Return a json-object with server information. Connected clients are returned
> +as a json-array of json-objects.
> +
> +The main json-object contains the following:
> +
> +- "enabled": true or false (json-bool)
> +- "host": server's IP address (json-string)

Wouldn't hurt to mention it can be a wildcard address.  The example
below shows the IPv4 wildcard address "0.0.0.0".

> +- "family": address family (json-string, "ipv4" or "ipv6")

inet_strfamily() can also return "unix" and "unknown".

By the way, we use PF_INET6, PF_INET and PF_UNIX there.  To be
pedantically correct, we should use AF_INET6, AF_INET and AF_LOCAL.

> +- "service": server's port number (json-string)

Why isn't this json-int?

> +- "auth": authentication method (json-string)

Possible values?  They come from vnc_auth_name().

> +- "clients": a json-array of all connected clients
> +
> +Clients are described by a json-object, each one contain the following:
> +
> +- "host": client's IP address (json-string)
> +- "family": address family (json-string, "ipv4" or "ipv6")

Same as above.

> +- "service": client's port number (json-string)

Same as above.

> +- "x509_dname": TLS dname (json-string, optional)
> +- "sasl_username": SASL username (json-string, optional)
> +
> +Example:
> +
> +{
> +   "return":{
> +      "enabled":true,
> +      "host":"0.0.0.0",
> +      "service":"50402",
> +      "auth":"vnc",
> +      "family":"ipv4",
> +      "clients":[
> +         {
> +            "host":"127.0.0.1",
> +            "service":"50401",
> +            "family":"ipv4"
> +         }
> +      ]
> +   }
> +}