diff options
| -rw-r--r-- | Makefile | 5 | ||||
| -rw-r--r-- | QMP/README | 5 | ||||
| -rwxr-xr-x | configure | 4 | ||||
| -rw-r--r-- | hxtool | 44 | ||||
| -rw-r--r-- | qemu-monitor.hx | 1322 |
5 files changed, 1376 insertions, 4 deletions
@@ -29,7 +29,7 @@ $(call set-vpath, $(SRC_PATH):$(SRC_PATH)/hw) LIBS+=-lz $(LIBS_TOOLS) ifdef BUILD_DOCS -DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 +DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 QMP/qmp-commands.txt else DOCS= endif @@ -263,6 +263,9 @@ qemu-options.texi: $(SRC_PATH)/qemu-options.hx qemu-monitor.texi: $(SRC_PATH)/qemu-monitor.hx $(call quiet-command,sh $(SRC_PATH)/hxtool -t < $< > $@," GEN $@") +QMP/qmp-commands.txt: $(SRC_PATH)/qemu-monitor.hx + $(call quiet-command,sh $(SRC_PATH)/hxtool -q < $< > $@," GEN $@") + qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx $(call quiet-command,sh $(SRC_PATH)/hxtool -t < $< > $@," GEN $@") diff --git a/QMP/README b/QMP/README index 9334c2551..35a80c73e 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: @@ -2817,3 +2817,7 @@ ln -s $source_path/Makefile.user $d/Makefile if test "$static" = "no" -a "$user_pie" = "yes" ; then echo "QEMU_CFLAGS+=-fpie" > $d/config.mak fi + +if test "$docs" = "yes" ; then + mkdir -p QMP +fi @@ -7,7 +7,7 @@ hxtoh() case $str in HXCOMM*) ;; - STEXI*|ETEXI*) flag=$(($flag^1)) + STEXI*|ETEXI*|SQMP*|EQMP*) flag=$(($flag^1)) ;; *) test $flag -eq 1 && printf "%s\n" "$str" @@ -38,6 +38,12 @@ hxtotexi() fi flag=0 ;; + SQMP*|EQMP*) + if test $flag -eq 1 ; then + echo "line $line: syntax error: expected ETEXI, found $str" >&2 + exit 1 + fi + ;; DEFHEADING*) echo "$(expr "$str" : "DEFHEADING(\(.*\))")" ;; @@ -49,9 +55,45 @@ hxtotexi() done } +hxtoqmp() +{ + IFS= + flag=0 + while read -r str; do + case "$str" in + HXCOMM*) + ;; + SQMP*) + if test $flag -eq 1 ; then + echo "line $line: syntax error: expected EQMP, found $str" >&2 + exit 1 + fi + flag=1 + ;; + EQMP*) + if test $flag -ne 1 ; then + echo "line $line: syntax error: expected SQMP, found $str" >&2 + exit 1 + fi + flag=0 + ;; + STEXI*|ETEXI*) + if test $flag -eq 1 ; then + echo "line $line: syntax error: expected EQMP, found $str" >&2 + exit 1 + fi + ;; + *) + test $flag -eq 1 && echo "$str" + ;; + esac + done +} + case "$1" in "-h") hxtoh ;; "-t") hxtotexi ;; +"-q") hxtoqmp ;; *) exit 1 ;; esac diff --git a/qemu-monitor.hx b/qemu-monitor.hx index b8c765b7b..f6a94f2b8 100644 --- a/qemu-monitor.hx +++ b/qemu-monitor.hx @@ -1,10 +1,48 @@ HXCOMM Use DEFHEADING() to define headings in both help text and texi HXCOMM Text between STEXI and ETEXI are copied to texi version and HXCOMM discarded from C version +HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and +HXCOMM does not show up in the other formats. HXCOMM DEF(command, args, callback, arg_string, help) is used to construct HXCOMM monitor commands HXCOMM HXCOMM can be used for comments, discarded from both texi and C +SQMP + QMP Supported Commands + ---------------------- + +This document describes all commands currently supported by QMP. + +Most of the time their usage is exactly the same as in the user Monitor, this +means that any other document which also describe commands (the manpage, +QEMU's manual, etc) can and should be consulted. + +QMP has two types of commands: regular and query commands. Regular commands +usually change the Virtual Machine's state someway, while query commands just +return information. The sections below are divided accordingly. + +It's important to observe that all communication examples are formatted in +a reader-friendly way, so that they're easier to understand. However, in real +protocol usage, they're emitted as a single line. + +Also, the following notation is used to denote data flow: + +-> data issued by the Client +<- Server data response + +Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed +information on the Server command and response formats. + +NOTE: This document is temporary and will be replaced soon. + +1. Regular Commands +=================== + +Server's responses in the examples below are always a success response, please +refer to the QMP specification for more details on error responses. + +EQMP + STEXI @table @option ETEXI @@ -51,6 +89,20 @@ STEXI @findex quit Quit the emulator. ETEXI +SQMP +quit +---- + +Quit the emulator. + +Arguments: None. + +Example: + +-> { "execute": "quit" } +<- { "return": {} } + +EQMP { .name = "eject", @@ -66,6 +118,25 @@ STEXI @findex eject Eject a removable medium (use -f to force it). ETEXI +SQMP +eject +----- + +Eject a removable medium. + +Arguments: + +- force: force ejection (json-bool, optional) +- device: device name (json-string) + +Example: + +-> { "execute": "eject", "arguments": { "device": "ide1-cd0" } } +<- { "return": {} } + +Note: The "force" argument defaults to false. + +EQMP { .name = "change", @@ -113,6 +184,35 @@ Password: ******** @end table ETEXI +SQMP +change +------ + +Change a removable medium or VNC configuration. + +Arguments: + +- "device": device name (json-string) +- "target": filename or item (json-string) +- "arg": additional argument (json-string, optional) + +Examples: + +1. Change a removable medium + +-> { "execute": "change", + "arguments": { "device": "ide1-cd0", + "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } } +<- { "return": {} } + +2. Change VNC password + +-> { "execute": "change", + "arguments": { "device": "vnc", "target": "password", + "arg": "foobar1" } } +<- { "return": {} } + +EQMP { .name = "screendump", @@ -128,6 +228,22 @@ STEXI @findex screendump Save screen into PPM image @var{filename}. ETEXI +SQMP +screendump +---------- + +Save screen into PPM image. + +Arguments: + +- "filename": file path (json-string) + +Example: + +-> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } } +<- { "return": {} } + +EQMP { .name = "logfile", @@ -232,6 +348,20 @@ STEXI @findex stop Stop emulation. ETEXI +SQMP +stop +---- + +Stop the emulator. + +Arguments: None. + +Example: + +-> { "execute": "stop" } +<- { "return": {} } + +EQMP { .name = "c|cont", @@ -247,6 +377,20 @@ STEXI @findex cont Resume emulation. ETEXI +SQMP +cont +---- + +Resume emulation. + +Arguments: None. + +Example: + +-> { "execute": "cont" } +<- { "return": {} } + +EQMP { .name = "gdbserver", @@ -421,6 +565,20 @@ STEXI Reset the system. ETEXI +SQMP +system_reset +------------ + +Reset the system. + +Arguments: None. + +Example: + +-> { "execute": "system_reset" } +<- { "return": {} } + +EQMP { .name = "system_powerdown", @@ -437,6 +595,20 @@ STEXI Power down the system (if supported). ETEXI +SQMP +system_powerdown +---------------- + +Send system power down event. + +Arguments: None. + +Example: + +-> { "execute": "system_powerdown" } +<- { "return": {} } + +EQMP { .name = "sum", @@ -501,6 +673,33 @@ STEXI Add device. ETEXI +SQMP +device_add +---------- + +Add a device. + +Arguments: + +- "driver": the name of the new device's driver (json-string) +- "bus": the device's parent bus (device tree path, json-string, optional) +- "id": the device's ID, must be unique (json-string) +- device properties + +Example: + +-> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } } +<- { "return": {} } + +Notes: + +(1) For detailed information about this command, please refer to the + 'docs/qdev-device-use.txt' file. + +(2) It's possible to list device properties by running QEMU with the + "-device DEVICE,\?" command-line argument, where DEVICE is the device's name + +EQMP { .name = "device_del", @@ -517,6 +716,22 @@ STEXI Remove device @var{id}. ETEXI +SQMP +device_del +---------- + +Remove a device. + +Arguments: + +- "id": the device's ID (json-string) + +Example: + +-> { "execute": "device_del", "arguments": { "id": "net1" } } +<- { "return": {} } + +EQMP { .name = "cpu", @@ -532,6 +747,24 @@ STEXI @findex cpu Set the default CPU. ETEXI +SQMP +cpu +--- + +Set the default CPU. + +Arguments: + +- "index": the CPU's index (json-int) + +Example: + +-> { "execute": "cpu", "arguments": { "index": 0 } } +<- { "return": {} } + +Note: CPUs' indexes are obtained with the 'query-cpus' command. + +EQMP { .name = "mouse_move", @@ -635,6 +868,29 @@ STEXI @findex memsave save to disk virtual memory dump starting at @var{addr} of size @var{size}. ETEXI +SQMP +memsave +------- + +Save to disk virtual memory dump starting at 'val' of size 'size'. + +Arguments: + +- "val": the starting address (json-int) +- "size": the memory size, in bytes (json-int) +- "filename": file path (json-string) + +Example: + +-> { "execute": "memsave", + "arguments": { "val": 10, + "size": 100, + "filename": "/tmp/virtual-mem-dump" } } +<- { "return": {} } + +Note: Depends on the current CPU. + +EQMP { .name = "pmemsave", @@ -650,6 +906,27 @@ STEXI @findex pmemsave save to disk physical memory dump starting at @var{addr} of size @var{size}. ETEXI +SQMP +pmemsave +-------- + +Save to disk physical memory dump starting at 'val' of size 'size'. + +Arguments: + +- "val": the starting address (json-int) +- "size": the memory size, in bytes (json-int) +- "filename": file path (json-string) + +Example: + +-> { "execute": "pmemsave", + "arguments": { "val": 10, + "size": 100, + "filename": "/tmp/physical-mem-dump" } } +<- { "return": {} } + +EQMP { .name = "boot_set", @@ -706,6 +983,32 @@ Migrate to @var{uri} (using -d to not wait for completion). -b for migration with full copy of disk -i for migration with incremental copy of disk (base image is shared) ETEXI +SQMP +migrate +------- + +Migrate to URI. + +Arguments: + +- "blk": block migration, full disk copy (json-bool, optional) +- "inc": incremental disk copy (json-bool, optional) +- "uri": Destination URI (json-string) + +Example: + +-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } +<- { "return": {} } + +Notes: + +(1) The 'query-migrate' command should be used to check migration's progress + and final result (this information is provided by the 'status' member) +(2) All boolean arguments default to false +(3) The user Monitor's "detach" argument is invalid in QMP and should not + be used + +EQMP { .name = "migrate_cancel", @@ -721,6 +1024,20 @@ STEXI @findex migrate_cancel Cancel the current VM migration. ETEXI +SQMP +migrate_cancel +-------------- + +Cancel the current migration. + +Arguments: None. + +Example: + +-> { "execute": "migrate_cancel" } +<- { "return": {} } + +EQMP { .name = "migrate_set_speed", @@ -736,6 +1053,22 @@ STEXI @findex migrate_set_speed Set maximum speed to @var{value} (in bytes) for migrations. ETEXI +SQMP +migrate_set_speed +----------------- + +Set maximum speed for migrations. + +Arguments: + +- "value": maximum speed, in bytes per second (json-number) + +Example: + +-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } } +<- { "return": {} } + +EQMP { .name = "migrate_set_downtime", @@ -751,6 +1084,22 @@ STEXI @findex migrate_set_downtime Set maximum tolerated downtime (in seconds) for migration. ETEXI +SQMP +migrate_set_downtime +-------------------- + +Set maximum tolerated downtime (in seconds) for migrations. + +Arguments: + +- "value": maximum downtime (json-number) + +Example: + +-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } } +<- { "return": {} } + +EQMP #if defined(TARGET_I386) { @@ -846,6 +1195,28 @@ STEXI @findex netdev_add Add host network device. ETEXI +SQMP +netdev_add +---------- + +Add host network device. + +Arguments: + +- "type": the device type, "tap", "user", ... (json-string) +- "id": the device's ID, must be unique (json-string) +- device options + +Example: + +-> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } } +<- { "return": {} } + +Note: The supported device options are the same ones supported by the '-net' + command-line argument, which are listed in the '-help' output or QEMU's + manual + +EQMP { .name = "netdev_del", @@ -861,6 +1232,22 @@ STEXI @findex netdev_del Remove host network device. ETEXI +SQMP +netdev_del +---------- + +Remove host network device. + +Arguments: + +- "id": the device's ID, must be unique (json-string) + +Example: + +-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } +<- { "return": {} } + +EQMP #ifdef CONFIG_SLIRP { @@ -908,6 +1295,22 @@ STEXI @findex balloon Request VM to change its memory allocation to @var{value} (in MB). ETEXI +SQMP +balloon +------- + +Request VM to change its memory allocation (in bytes). + +Arguments: + +- "value": New memory allocation (json-int) + +Example: + +-> { "execute": "balloon", "arguments": { "value": 536870912 } } +<- { "return": {} } + +EQMP { .name = "set_link", @@ -923,6 +1326,23 @@ STEXI @findex set_link Switch link @var{name} on (i.e. up) or off (i.e. down). ETEXI +SQMP +set_link +-------- + +Change the link status of a network adapter. + +Arguments: + +- "name": network device name (json-string) +- "up": status is up (json-bool) + +Example: + +-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } } +<- { "return": {} } + +EQMP { .name = "watchdog_action", @@ -1052,6 +1472,22 @@ If a file descriptor is passed alongside this command using the SCM_RIGHTS mechanism on unix sockets, it is stored using the name @var{fdname} for later use by other monitor commands. ETEXI +SQMP +getfd +----- + +Receive a file descriptor via SCM rights and assign it a name. + +Arguments: + +- "fdname": file descriptor name (json-string) + +Example: + +-> { "execute": "getfd", "arguments": { "fdname": "fd1" } } +<- { "return": {} } + +EQMP { .name = "closefd", @@ -1069,6 +1505,22 @@ Close the file descriptor previously assigned to @var{fdname} using the @code{getfd} command. This is only needed if the file descriptor was never used by another monitor command. ETEXI +SQMP +closefd +------- + +Close a file descriptor previously passed via SCM rights. + +Arguments: + +- "fdname": file descriptor name (json-string) + +Example: + +-> { "execute": "closefd", "arguments": { "fdname": "fd1" } } +<- { "return": {} } + +EQMP { .name = "block_passwd", @@ -1084,6 +1536,24 @@ STEXI @findex block_passwd Set the encrypted device @var{device} password to @var{password} ETEXI +SQMP +block_passwd +------------ + +Set the password of encrypted block devices. + +Arguments: + +- "device": device name (json-string) +- "password": password (json-string) + +Example: + +-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0", + "password": "12345" } } +<- { "return": {} } + +EQMP { .name = "qmp_capabilities", @@ -1099,11 +1569,34 @@ STEXI @findex qmp_capabilities Enable the specified QMP capabilities ETEXI +SQMP +qmp_capabilities +---------------- + +Enable QMP capabilities. + +Arguments: None. + +Example: + +-> { "execute": "qmp_capabilities" } +<- { "return": {} } + +Note: This command must be issued before issuing any other command. + +EQMP HXCOMM Keep the 'info' command at the end! HXCOMM This is required for the QMP documentation layout. +SQMP + +2. Query Commands +================= + +EQMP + { .name = "info", .args_type = "item:s?", @@ -1121,40 +1614,588 @@ Show various information about the system state. @table @option @item info version show the version of QEMU +ETEXI +SQMP +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: + +-> { "execute": "query-version" } +<- { "return": { "qemu": "0.11.50", "package": "" } } + +EQMP + +STEXI @item info commands list QMP available commands +ETEXI +SQMP +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: + +-> { "execute": "query-commands" } +<- { + "return":[ + { + "name":"query-balloon" + }, + { + "name":"system_powerdown" + } + ] + } + +Note: This example has been shortened as the real response is too long. + +EQMP + +STEXI @item info network show the various VLANs and the associated devices +ETEXI + +STEXI @item info chardev show the character devices +ETEXI +SQMP +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: + +-> { "execute": "query-chardev" } +<- { + "return":[ + { + "label":"monitor", + "filename":"stdio" + }, + { + "label":"serial0", + "filename":"vc" + } + ] + } + +EQMP + +STEXI @item info block show the block devices +ETEXI +SQMP +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", "unknown" +- "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: "blkdebug", "bochs", "cloop", "cow", "dmg", + "file", "file", "ftp", "ftps", "host_cdrom", + "host_device", "host_floppy", "http", "https", + "nbd", "parallels", "qcow", "qcow2", "raw", + "tftp", "vdi", "vmdk", "vpc", "vvfat" + - "backing_file": backing file name (json-string, optional) + - "encrypted": true if encrypted, false otherwise (json-bool) + +Example: + +-> { "execute": "query-block" } +<- { + "return":[ + { + "device":"ide0-hd0", + "locked":false, + "removable":false, + "inserted":{ + "ro":false, + "drv":"qcow2", + "encrypted":false, + "file":"disks/test.img" + }, + "type":"hd" + }, + { + "device":"ide1-cd0", + "locked":false, + "removable":true, + "type":"cdrom" + }, + { + "device":"floppy0", + "locked":false, + "removable":true, + "type": "floppy" + }, + { + "device":"sd0", + "locked":false, + "removable":true, + "type":"floppy" + } + ] + } + +EQMP + +STEXI @item info blockstats show block device statistics +ETEXI +SQMP +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: + +-> { "execute": "query-blockstats" } +<- { + "return":[ + { + "device":"ide0-hd0", + "parent":{ + "stats":{ + "wr_highest_offset":3686448128, + "wr_bytes":9786368, + "wr_operations":751, + "rd_bytes":122567168, + "rd_operations":36772 + } + }, + "stats":{ + "wr_highest_offset":2821110784, + "wr_bytes":9786368, + "wr_operations":692, + "rd_bytes":122739200, + "rd_operations":36604 + } + }, + { + "device":"ide1-cd0", + "stats":{ + "wr_highest_offset":0, + "wr_bytes":0, + "wr_operations":0, + "rd_bytes":0, + "rd_operations":0 + } + }, + { + "device":"floppy0", + "stats":{ + "wr_highest_offset":0, + "wr_bytes":0, + "wr_operations":0, + "rd_bytes":0, + "rd_operations":0 + } + }, + { + "device":"sd0", + "stats":{ + "wr_highest_offset":0, + "wr_bytes":0, + "wr_operations":0, + "rd_bytes":0, + "rd_operations":0 + } + } + ] + } + +EQMP + +STEXI @item info registers show the cpu registers @item info cpus show infos for each CPU +ETEXI +SQMP +query-cpus +---------- + +Show CPU information. + +Return a json-array. Each CPU is represented by a json-object, which contains: + +- "CPU": CPU index (json-int) +- "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) + +Example: + +-> { "execute": "query-cpus" } +<- { + "return":[ + { + "CPU":0, + "current":true, + "halted":false, + "pc":3227107138 + }, + { + "CPU":1, + "current":false, + "halted":true, + "pc":7108165 + } + ] + } + +EQMP + +STEXI @item info history show the command line history @item info irq show the interrupts statistics (if available) @item info pic show i8259 (PIC) state +ETEXI + +STEXI @item info pci show emulated PCI device info +ETEXI +SQMP +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": I/O memory range information, a json-object with the + following members: + - "base": base address, in bytes (json-int) + - "limit": limit address, in bytes (json-int) + - "memory_range": memory range information, a json-object with the + following members: + - "base": base address, in bytes (json-int) + - "limit": limit address, in bytes (json-int) + - "prefetchable_range": Prefetchable memory range information, a + json-object with the following members: + - "base": base address, in bytes (json-int) + - "limit": limit address, in bytes (json-int) + - "devices": a json-array of PCI devices if there's any attached, each + each element is represented by a json-object, which contains + the same members of the 'PCI device json-object' described + above (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: + +-> { "execute": "query-pci" } +<- { + "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":[ + + ] + }, + { + "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. + +EQMP + +STEXI @item info tlb show virtual to physical memory mappings (i386 only) @item info mem show the active virtual memory mappings (i386 only) +ETEXI + +STEXI @item info hpet show state of HPET (i386 only) +ETEXI +SQMP +query-hpet +---------- + +Show HPET state. + +Return a json-object with the following information: + +- "enabled": true if hpet if enabled, false otherwise (json-bool) + +Example: + +-> { "execute": "query-hpet" } +<- { "return": { "enabled": true } } + +EQMP + +STEXI @item info jit show dynamic compiler info @item info kvm show KVM information @item info numa show NUMA information +ETEXI + +STEXI +@item info kvm +show KVM information +ETEXI +SQMP +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: + +-> { "execute": "query-kvm" } +<- { "return": { "enabled": true, "present": true } } + +EQMP + +STEXI @item info usb show USB devices plugged on the virtual USB hub @item info usbhost @@ -1165,26 +2206,307 @@ show profiling information show information about active capturing @item info snapshots show list of VM snapshots +ETEXI + +STEXI @item info status show the current VM status (running|paused) +ETEXI +SQMP +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: + +-> { "execute": "query-status" } +<- { "return": { "running": true, "singlestep": false } } + +EQMP + +STEXI @item info pcmcia show guest PCMCIA status +ETEXI + +STEXI @item info mice show which guest mouse is receiving events +ETEXI +SQMP +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: + +-> { "execute": "query-mice" } +<- { + "return":[ + { + "name":"QEMU Microsoft Mouse", + "index":0, + "current":false, + "absolute":false + }, + { + "name":"QEMU PS/2 Mouse", + "index":1, + "current":true, + "absolute":true + } + ] + } + +EQMP + +STEXI @item info vnc show the vnc server status +ETEXI +SQMP +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) +- "family": address family (json-string) + - Possible values: "ipv4", "ipv6", "unix", "unknown" +- "service": server's port number (json-string) +- "auth": authentication method (json-string) + - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight", + "tls", "ultra", "unknown", "vencrypt", "vencrypt", + "vencrypt+plain", "vencrypt+tls+none", + "vencrypt+tls+plain", "vencrypt+tls+sasl", + "vencrypt+tls+vnc", "vencrypt+x509+none", + "vencrypt+x509+plain", "vencrypt+x509+sasl", + "vencrypt+x509+vnc", "vnc" +- "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) + - Possible values: "ipv4", "ipv6", "unix", "unknown" +- "service": client's port number (json-string) +- "x509_dname": TLS dname (json-string, optional) +- "sasl_username": SASL username (json-string, optional) + +Example: + +-> { "execute": "query-vnc" } +<- { + "return":{ + "enabled":true, + "host":"0.0.0.0", + "service":"50402", + "auth":"vnc", + "family":"ipv4", + "clients":[ + { + "host":"127.0.0.1", + "service":"50401", + "family":"ipv4" + } + ] + } + } + +EQMP + +STEXI @item info name show the current VM name +ETEXI +SQMP +query-name +---------- + +Show VM name. + +Return a json-object with the following information: + +- "name": VM's name (json-string, optional) + +Example: + +-> { "execute": "query-name" } +<- { "return": { "name": "qemu-name" } } + +EQMP + +STEXI @item info uuid show the current VM UUID +ETEXI +SQMP +query-uuid +---------- + +Show VM UUID. + +Return a json-object with the following information: + +- "UUID": Universally Unique Identifier (json-string) + +Example: + +-> { "execute": "query-uuid" } +<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } + +EQMP + +STEXI @item info cpustats show CPU statistics @item info usernet show user network stack connection states +ETEXI + +STEXI @item info migrate show migration status +ETEXI +SQMP +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" +- "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) + +Examples: + +1. Before the first migration + +-> { "execute": "query-migrate" } +<- { "return": {} } + +2. Migration is done and has succeeded + +-> { "execute": "query-migrate" } +<- { "return": { "status": "completed" } } + +3. Migration is done and has failed + +-> { "execute": "query-migrate" } +<- { "return": { "status": "failed" } } + +4. Migration is being performed and is not a block migration: + +-> { "execute": "query-migrate" } +<- { + "return":{ + "status":"active", + "ram":{ + "transferred":123, + "remaining":123, + "total":246 + } + } + } + +5. Migration is being performed and is a block migration: + +-> { "execute": "query-migrate" } +<- { + "return":{ + "status":"active", + "ram":{ + "total":1057024, + "remaining":1053304, + "transferred":3720 + }, + "disk":{ + "total":20971520, + "remaining":20880384, + "transferred":91136 + } + } + } + +EQMP + +STEXI @item info balloon show balloon information +ETEXI +SQMP +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) +- "total_mem": Total amount of available memory in bytes (json-int, optional) + +Example: + +-> { "execute": "query-balloon" } +<- { + "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 + } + } + +EQMP + +STEXI @item info qtree show device tree @item info qdm |