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
STEXI
@item help or ? [@var{cmd}]
+@findex help
Show the help for all commands or just for command @var{cmd}.
ETEXI
STEXI
@item commit
+@findex commit
Commit changes to the disk images (if -snapshot is used) or backing files.
-ETEXI
-
- {
- .name = "info",
- .args_type = "item:s?",
- .params = "[subcommand]",
- .help = "show various information about the system state",
- .user_print = monitor_user_noop,
- .mhandler.cmd_new = do_info,
- },
-
-STEXI
-@item info @var{subcommand}
-Show various information about the system state.
-
-@table @option
-@item info version
-show the version of QEMU
-@item info network
-show the various VLANs and the associated devices
-@item info chardev
-show the character devices
-@item info block
-show the block devices
-@item info block
-show block device statistics
-@item info registers
-show the cpu registers
-@item info cpus
-show infos for each CPU
-@item info history
-show the command line history
-@item info irq
-show the interrupts statistics (if available)
-@item info pic
-show i8259 (PIC) state
-@item info pci
-show emulated PCI device info
-@item info tlb
-show virtual to physical memory mappings (i386 only)
-@item info mem
-show the active virtual memory mappings (i386 only)
-@item info hpet
-show state of HPET (i386 only)
-@item info kvm
-show KVM information
-@item info usb
-show USB devices plugged on the virtual USB hub
-@item info usbhost
-show all USB host devices
-@item info profile
-show profiling information
-@item info capture
-show information about active capturing
-@item info snapshots
-show list of VM snapshots
-@item info status
-show the current VM status (running|paused)
-@item info pcmcia
-show guest PCMCIA status
-@item info mice
-show which guest mouse is receiving events
-@item info vnc
-show the vnc server status
-@item info name
-show the current VM name
-@item info uuid
-show the current VM UUID
-@item info cpustats
-show CPU statistics
-@item info usernet
-show user network stack connection states
-@item info migrate
-show migration status
-@item info balloon
-show balloon information
-@item info qtree
-show device tree
-@end table
ETEXI
{
STEXI
@item q or quit
+@findex quit
Quit the emulator.
ETEXI
+SQMP
+quit
+----
+
+Quit the emulator.
+
+Arguments: None.
+
+Example:
+
+-> { "execute": "quit" }
+<- { "return": {} }
+
+EQMP
{
.name = "eject",
- .args_type = "force:-f,filename:B",
+ .args_type = "force:-f,device:B",
.params = "[-f] device",
.help = "eject a removable medium (use -f to force it)",
- .mhandler.cmd = do_eject,
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_eject,
},
STEXI
@item eject [-f] @var{device}
+@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",
.args_type = "device:B,target:F,arg:s?",
.params = "device filename [format]",
.help = "change a removable medium, optional format",
- .mhandler.cmd = do_change,
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_change,
},
STEXI
@item change @var{device} @var{setting}
+@findex change
Change the configuration of a device.
@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",
.args_type = "filename:F",
.params = "filename",
.help = "save screen into PPM image 'filename'",
- .mhandler.cmd = do_screen_dump,
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_screen_dump,
},
STEXI
@item screendump @var{filename}
+@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",
STEXI
@item logfile @var{filename}
+@findex logfile
Output logs to @var{filename}.
ETEXI
STEXI
@item log @var{item1}[,...]
+@findex log
Activate logging of the specified items to @file{/tmp/qemu.log}.
ETEXI
STEXI
@item savevm [@var{tag}|@var{id}]
+@findex savevm
Create a snapshot of the whole virtual machine. If @var{tag} is
provided, it is used as human readable identifier. If there is already
a snapshot with the same tag or ID, it is replaced. More info at
STEXI
@item loadvm @var{tag}|@var{id}
+@findex loadvm
Set the whole virtual machine to the snapshot identified by the tag
@var{tag} or the unique snapshot ID @var{id}.
ETEXI
STEXI
@item delvm @var{tag}|@var{id}
+@findex delvm
Delete the snapshot identified by @var{tag} or @var{id}.
ETEXI
STEXI
@item singlestep [off]
+@findex singlestep
Run the emulation in single step mode.
If called with option off, the emulation returns to normal mode.
ETEXI
STEXI
@item stop
+@findex stop
Stop emulation.
ETEXI
+SQMP
+stop
+----
+
+Stop the emulator.
+
+Arguments: None.
+
+Example:
+
+-> { "execute": "stop" }
+<- { "return": {} }
+
+EQMP
{
.name = "c|cont",
STEXI
@item c or cont
+@findex cont
Resume emulation.
ETEXI
+SQMP
+cont
+----
+
+Resume emulation.
+
+Arguments: None.
+
+Example:
+
+-> { "execute": "cont" }
+<- { "return": {} }
+
+EQMP
{
.name = "gdbserver",
STEXI
@item gdbserver [@var{port}]
+@findex gdbserver
Start gdbserver session (default @var{port}=1234)
ETEXI
STEXI
@item x/fmt @var{addr}
+@findex x
Virtual memory dump starting at @var{addr}.
ETEXI
STEXI
@item xp /@var{fmt} @var{addr}
+@findex xp
Physical memory dump starting at @var{addr}.
@var{fmt} is a format which tells the command how to format the
STEXI
@item p or print/@var{fmt} @var{expr}
+@findex print
Print expression value. Only the @var{format} part of @var{fmt} is
used.
STEXI
@item sendkey @var{keys}
+@findex sendkey
Send @var{keys} to the emulator. @var{keys} could be the name of the
key or @code{#} followed by the raw value in either decimal or hexadecimal
STEXI
@item system_reset
+@findex system_reset
Reset the system.
ETEXI
+SQMP
+system_reset
+------------
+
+Reset the system.
+
+Arguments: None.
+
+Example:
+
+-> { "execute": "system_reset" }
+<- { "return": {} }
+
+EQMP
{
.name = "system_powerdown",
STEXI
@item system_powerdown
+@findex system_powerdown
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",
STEXI
@item sum @var{addr} @var{size}
+@findex sum
Compute the checksum of a memory region.
ETEXI
STEXI
@item usb_add @var{devname}
+@findex usb_add
Add the USB device @var{devname}. For details of available devices see
@ref{usb_devices}
STEXI
@item usb_del @var{devname}
+@findex usb_del
Remove the USB device @var{devname} from the QEMU virtual USB
hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
{
.name = "device_add",
- .args_type = "config:s",
- .params = "device",
+ .args_type = "device:O",
+ .params = "driver[,prop=value][,...]",
.help = "add device, like -device on the command line",
- .mhandler.cmd = do_device_add,
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_device_add,
},
STEXI
@item device_add @var{config}
+@findex device_add
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",
.args_type = "id:s",
.params = "device",
.help = "remove device",
- .mhandler.cmd = do_device_del,
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_device_del,
},
STEXI
@item device_del @var{id}
+@findex device_del
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",
.args_type = "index:i",
.params = "index",
.help = "set the default CPU",
- .mhandler.cmd = do_cpu_set,
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_cpu_set,
},
STEXI
+@item cpu @var{index}
+@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",
STEXI
@item mouse_move @var{dx} @var{dy} [@var{dz}]
+@findex mouse_move
Move the active mouse to the specified coordinates @var{dx} @var{dy}
with optional scroll axis @var{dz}.
ETEXI
STEXI
@item mouse_button @var{val}
+@findex mouse_button
Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
ETEXI
STEXI
@item mouse_set @var{index}
+@findex mouse_set
Set which mouse device receives events at given @var{index}, index
can be obtained with
@example
#endif
STEXI
@item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
+@findex wavcapture
Capture audio into @var{filename}. Using sample rate @var{frequency}
bits per sample @var{bits} and number of channels @var{channels}.
#endif
STEXI
@item stopcapture @var{index}
+@findex stopcapture
Stop capture with a given @var{index}, index can be obtained with
@example
info capture
STEXI
@item memsave @var{addr} @var{size} @var{file}
+@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",
STEXI
@item pmemsave @var{addr} @var{size} @var{file}
+@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",
STEXI
@item boot_set @var{bootdevicelist}
+@findex boot_set
Define new values for the boot device list. Those values will override
the values specified on the command line through the @code{-boot} option.
#endif
STEXI
@item nmi @var{cpu}
+@findex nmi
Inject an NMI on the given CPU (x86 only).
ETEXI
{
.name = "migrate",
- .args_type = "detach:-d,uri:s",
- .params = "[-d] uri",
- .help = "migrate to URI (using -d to not wait for completion)",
- .user_print = monitor_user_noop,
- .mhandler.cmd_new = do_migrate,
+ .args_type = "detach:-d,blk:-b,inc:-i,uri:s",
+ .params = "[-d] [-b] [-i] uri",
+ .help = "migrate to URI (using -d to not wait for completion)"
+ "\n\t\t\t -b for migration without shared storage with"
+ " full copy of disk\n\t\t\t -i for migration without "
+ "shared storage with incremental copy of disk "
+ "(base image shared between src and destination)",
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_migrate,
},
+
STEXI
-@item migrate [-d] @var{uri}
+@item migrate [-d] [-b] [-i] @var{uri}
+@findex migrate
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",
STEXI
@item migrate_cancel
+@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",
- .args_type = "value:s",
+ .args_type = "value:f",
.params = "value",
.help = "set maximum speed (in bytes) for migrations",
.user_print = monitor_user_noop,
STEXI
@item migrate_set_speed @var{value}
+@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",
- .args_type = "value:s",
+ .args_type = "value:T",
.params = "value",
.help = "set maximum tolerated downtime (in seconds) for migrations",
- .mhandler.cmd = do_migrate_set_downtime,
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_migrate_set_downtime,
},
STEXI
@item migrate_set_downtime @var{second}
+@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)
{
STEXI
@item drive_add
+@findex drive_add
Add drive to PCI storage controller.
ETEXI
STEXI
@item pci_add
+@findex pci_add
Hot-add PCI device.
ETEXI
STEXI
@item pci_del
+@findex pci_del
Hot remove PCI device.
ETEXI
STEXI
@item host_net_add
+@findex host_net_add
Add host VLAN client.
ETEXI
STEXI
@item host_net_remove
+@findex host_net_remove
Remove host VLAN client.
ETEXI
+ {
+ .name = "netdev_add",
+ .args_type = "netdev:O",
+ .params = "[user|tap|socket],id=str[,prop=value][,...]",
+ .help = "add host network device",
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_netdev_add,
+ },
+
+STEXI
+@item netdev_add
+@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",
+ .args_type = "id:s",
+ .params = "id",
+ .help = "remove host network device",
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_netdev_del,
+ },
+
+STEXI
+@item netdev_del
+@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
{
.name = "hostfwd_add",
.help = "redirect TCP or UDP connections from host to guest (requires -net user)",
.mhandler.cmd = net_slirp_hostfwd_add,
},
+#endif
+STEXI
+@item hostfwd_add
+@findex hostfwd_add
+Redirect TCP or UDP connections from host to guest (requires -net user).
+ETEXI
+#ifdef CONFIG_SLIRP
{
.name = "hostfwd_remove",
.args_type = "arg1:s,arg2:s?,arg3:s?",
#endif
STEXI
-@item host_net_redir
-Redirect TCP or UDP connections from host to guest (requires -net user).
+@item hostfwd_remove
+@findex hostfwd_remove
+Remove host-to-guest TCP or UDP redirection.
ETEXI
{
.name = "balloon",
- .args_type = "value:i",
+ .args_type = "value:M",
.params = "target",
- .help = "request VM to change it's memory allocation (in MB)",
+ .help = "request VM to change its memory allocation (in MB)",
.user_print = monitor_user_noop,
- .mhandler.cmd_new = do_balloon,
+ .mhandler.cmd_async = do_balloon,
+ .flags = MONITOR_CMD_ASYNC,
},
STEXI
@item balloon @var{value}
+@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",
- .args_type = "name:s,up_or_down:s",
- .params = "name up|down",
+ .args_type = "name:s,up:b",
+ .params = "name on|off",
.help = "change the link status of a network adapter",
- .mhandler.cmd = do_set_link,
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_set_link,
},
STEXI
-@item set_link @var{name} [up|down]
-Set link @var{name} up or down.
+@item set_link @var{name} [on|off]
+@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",
STEXI
@item watchdog_action
+@findex watchdog_action
Change watchdog action.
ETEXI
STEXI
@item acl_show @var{aclname}
+@findex acl_show
List all the matching rules in the access control list, and the default
policy. There are currently two named access control lists,
@var{vnc.x509dname} and @var{vnc.username} matching on the x509 client
STEXI
@item acl_policy @var{aclname} @code{allow|deny}
+@findex acl_policy
Set the default access control list policy, used in the event that
none of the explicit rules match. The default policy at startup is
always @code{deny}.
},
STEXI
-@item acl_allow @var{aclname} @var{match} @code{allow|deny} [@var{index}]
+@item acl_add @var{aclname} @var{match} @code{allow|deny} [@var{index}]
+@findex acl_add
Add a match rule to the access control list, allowing or denying access.
The match will normally be an exact username or x509 distinguished name,
but can optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to
STEXI
@item acl_remove @var{aclname} @var{match}
+@findex acl_remove
Remove the specified match rule from the access control list.
ETEXI
},
STEXI
-@item acl_remove @var{aclname} @var{match}
+@item acl_reset @var{aclname}
+@findex acl_reset
Remove all matches from the access control list, and set the default
policy back to @code{deny}.
ETEXI
#endif
STEXI
@item mce @var{cpu} @var{bank} @var{status} @var{mcgstatus} @var{addr} @var{misc}
+@findex mce (x86)
Inject an MCE on the given CPU (x86 only).
ETEXI
.args_type = "fdname:s",
.params = "getfd name",
.help = "receive a file descriptor via SCM rights and assign it a name",
- .mhandler.cmd = do_getfd,
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_getfd,
},
STEXI
@item getfd @var{fdname}
+@findex getfd
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",
.args_type = "fdname:s",
.params = "closefd name",
.help = "close a file descriptor previously passed via SCM rights",
- .mhandler.cmd = do_closefd,
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_closefd,
},
STEXI
@item closefd @var{fdname}
+@findex closefd
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",
+ .args_type = "device:B,password:s",
+ .params = "block_passwd device password",
+ .help = "set the password of encrypted block devices",
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_block_set_passwd,
+ },
+
+STEXI
+@item block_passwd @var{device} @var{password}
+@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",
+ .args_type = "",
+ .params = "",
+ .help = "enable QMP capabilities",
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_qmp_capabilities,
+ },
+
+STEXI
+@item qmp_capabilities
+@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?",
+ .params = "[subcommand]",
+ .help = "show various information about the system state",
+ .user_print = monitor_user_noop,
+ .mhandler.cmd_new = do_info,
+ },
+
+STEXI
+@item info @var{subcommand}
+@findex info
+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 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
+show all USB host devices
+@item info profile
+show profiling information
+@item info capture
+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
+show qdev device model list
+@item info roms
+show roms
+@end table
+ETEXI
+
+HXCOMM DO NOT add new commands after 'info', move your addition before it!
STEXI
@end table
projects / qemu.git / blobdiff