[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH 1/2] QMP: Introduce commands doc
From: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] [PATCH 1/2] QMP: Introduce commands doc |
Date: |
Wed, 12 May 2010 18:48:38 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/23.1 (gnu/linux) |
Luiz Capitulino <address@hidden> 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 <address@hidden>
> ---
> 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"
> + }
> + ]
> + }
> +}
- [Qemu-devel] [PATCH v2 0/2]: QMP: Commands doc, Luiz Capitulino, 2010/05/05
- Re: [Qemu-devel] [PATCH 1/2] QMP: Introduce commands doc, Avi Kivity, 2010/05/13
- Re: [Qemu-devel] [PATCH 1/2] QMP: Introduce commands doc, Luiz Capitulino, 2010/05/13
- Re: [Qemu-devel] [PATCH 1/2] QMP: Introduce commands doc, Daniel P. Berrange, 2010/05/13
- Re: [Qemu-devel] [PATCH 1/2] QMP: Introduce commands doc, Avi Kivity, 2010/05/13
- Re: [Qemu-devel] [PATCH 1/2] QMP: Introduce commands doc, Luiz Capitulino, 2010/05/13
- Re: [Qemu-devel] [PATCH 1/2] QMP: Introduce commands doc, Markus Armbruster, 2010/05/14