Luiz Capitulino <lcapitul...@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 <lcapitul...@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" > + } > + ] > + } > +}