rcu: fix comment with s/rcu_gp_lock/rcu_registry_lock/
[qemu/ar7.git] / qmp-commands.hx
blobba630b1e7f22d4c339b4d7055dfa7b73a627ccba
1 HXCOMM QMP dispatch table and documentation
2 HXCOMM Text between SQMP and EQMP is copied to the QMP documentation file and
3 HXCOMM does not show up in the other formats.
5 SQMP
6 QMP Supported Commands
7 ----------------------
9 This document describes all commands currently supported by QMP.
11 Most of the time their usage is exactly the same as in the user Monitor, this
12 means that any other document which also describe commands (the manpage,
13 QEMU's manual, etc) can and should be consulted.
15 QMP has two types of commands: regular and query commands. Regular commands
16 usually change the Virtual Machine's state someway, while query commands just
17 return information. The sections below are divided accordingly.
19 It's important to observe that all communication examples are formatted in
20 a reader-friendly way, so that they're easier to understand. However, in real
21 protocol usage, they're emitted as a single line.
23 Also, the following notation is used to denote data flow:
25 -> data issued by the Client
26 <- Server data response
28 Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
29 information on the Server command and response formats.
31 NOTE: This document is temporary and will be replaced soon.
33 1. Stability Considerations
34 ===========================
36 The current QMP command set (described in this file) may be useful for a
37 number of use cases, however it's limited and several commands have bad
38 defined semantics, specially with regard to command completion.
40 These problems are going to be solved incrementally in the next QEMU releases
41 and we're going to establish a deprecation policy for badly defined commands.
43 If you're planning to adopt QMP, please observe the following:
45 1. The deprecation policy will take effect and be documented soon, please
46 check the documentation of each used command as soon as a new release of
47 QEMU is available
49 2. DO NOT rely on anything which is not explicit documented
51 3. Errors, in special, are not documented. Applications should NOT check
52 for specific errors classes or data (it's strongly recommended to only
53 check for the "error" key)
55 2. Regular Commands
56 ===================
58 Server's responses in the examples below are always a success response, please
59 refer to the QMP specification for more details on error responses.
61 EQMP
64 .name = "quit",
65 .args_type = "",
66 .mhandler.cmd_new = qmp_marshal_input_quit,
69 SQMP
70 quit
71 ----
73 Quit the emulator.
75 Arguments: None.
77 Example:
79 -> { "execute": "quit" }
80 <- { "return": {} }
82 EQMP
85 .name = "eject",
86 .args_type = "force:-f,device:B",
87 .mhandler.cmd_new = qmp_marshal_input_eject,
90 SQMP
91 eject
92 -----
94 Eject a removable medium.
96 Arguments:
98 - force: force ejection (json-bool, optional)
99 - device: device name (json-string)
101 Example:
103 -> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
104 <- { "return": {} }
106 Note: The "force" argument defaults to false.
108 EQMP
111 .name = "change",
112 .args_type = "device:B,target:F,arg:s?",
113 .mhandler.cmd_new = qmp_marshal_input_change,
116 SQMP
117 change
118 ------
120 Change a removable medium or VNC configuration.
122 Arguments:
124 - "device": device name (json-string)
125 - "target": filename or item (json-string)
126 - "arg": additional argument (json-string, optional)
128 Examples:
130 1. Change a removable medium
132 -> { "execute": "change",
133 "arguments": { "device": "ide1-cd0",
134 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
135 <- { "return": {} }
137 2. Change VNC password
139 -> { "execute": "change",
140 "arguments": { "device": "vnc", "target": "password",
141 "arg": "foobar1" } }
142 <- { "return": {} }
144 EQMP
147 .name = "screendump",
148 .args_type = "filename:F",
149 .mhandler.cmd_new = qmp_marshal_input_screendump,
152 SQMP
153 screendump
154 ----------
156 Save screen into PPM image.
158 Arguments:
160 - "filename": file path (json-string)
162 Example:
164 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
165 <- { "return": {} }
167 EQMP
170 .name = "stop",
171 .args_type = "",
172 .mhandler.cmd_new = qmp_marshal_input_stop,
175 SQMP
176 stop
177 ----
179 Stop the emulator.
181 Arguments: None.
183 Example:
185 -> { "execute": "stop" }
186 <- { "return": {} }
188 EQMP
191 .name = "cont",
192 .args_type = "",
193 .mhandler.cmd_new = qmp_marshal_input_cont,
196 SQMP
197 cont
198 ----
200 Resume emulation.
202 Arguments: None.
204 Example:
206 -> { "execute": "cont" }
207 <- { "return": {} }
209 EQMP
212 .name = "system_wakeup",
213 .args_type = "",
214 .mhandler.cmd_new = qmp_marshal_input_system_wakeup,
217 SQMP
218 system_wakeup
219 -------------
221 Wakeup guest from suspend.
223 Arguments: None.
225 Example:
227 -> { "execute": "system_wakeup" }
228 <- { "return": {} }
230 EQMP
233 .name = "system_reset",
234 .args_type = "",
235 .mhandler.cmd_new = qmp_marshal_input_system_reset,
238 SQMP
239 system_reset
240 ------------
242 Reset the system.
244 Arguments: None.
246 Example:
248 -> { "execute": "system_reset" }
249 <- { "return": {} }
251 EQMP
254 .name = "system_powerdown",
255 .args_type = "",
256 .mhandler.cmd_new = qmp_marshal_input_system_powerdown,
259 SQMP
260 system_powerdown
261 ----------------
263 Send system power down event.
265 Arguments: None.
267 Example:
269 -> { "execute": "system_powerdown" }
270 <- { "return": {} }
272 EQMP
275 .name = "device_add",
276 .args_type = "device:O",
277 .params = "driver[,prop=value][,...]",
278 .help = "add device, like -device on the command line",
279 .mhandler.cmd_new = qmp_device_add,
282 SQMP
283 device_add
284 ----------
286 Add a device.
288 Arguments:
290 - "driver": the name of the new device's driver (json-string)
291 - "bus": the device's parent bus (device tree path, json-string, optional)
292 - "id": the device's ID, must be unique (json-string)
293 - device properties
295 Example:
297 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
298 <- { "return": {} }
300 Notes:
302 (1) For detailed information about this command, please refer to the
303 'docs/qdev-device-use.txt' file.
305 (2) It's possible to list device properties by running QEMU with the
306 "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
308 EQMP
311 .name = "device_del",
312 .args_type = "id:s",
313 .mhandler.cmd_new = qmp_marshal_input_device_del,
316 SQMP
317 device_del
318 ----------
320 Remove a device.
322 Arguments:
324 - "id": the device's ID (json-string)
326 Example:
328 -> { "execute": "device_del", "arguments": { "id": "net1" } }
329 <- { "return": {} }
331 EQMP
334 .name = "send-key",
335 .args_type = "keys:q,hold-time:i?",
336 .mhandler.cmd_new = qmp_marshal_input_send_key,
339 SQMP
340 send-key
341 ----------
343 Send keys to VM.
345 Arguments:
347 keys array:
348 - "key": key sequence (a json-array of key union values,
349 union can be number or qcode enum)
351 - hold-time: time to delay key up events, milliseconds. Defaults to 100
352 (json-int, optional)
354 Example:
356 -> { "execute": "send-key",
357 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
358 { "type": "qcode", "data": "alt" },
359 { "type": "qcode", "data": "delete" } ] } }
360 <- { "return": {} }
362 EQMP
365 .name = "cpu",
366 .args_type = "index:i",
367 .mhandler.cmd_new = qmp_marshal_input_cpu,
370 SQMP
374 Set the default CPU.
376 Arguments:
378 - "index": the CPU's index (json-int)
380 Example:
382 -> { "execute": "cpu", "arguments": { "index": 0 } }
383 <- { "return": {} }
385 Note: CPUs' indexes are obtained with the 'query-cpus' command.
387 EQMP
390 .name = "cpu-add",
391 .args_type = "id:i",
392 .mhandler.cmd_new = qmp_marshal_input_cpu_add,
395 SQMP
396 cpu-add
397 -------
399 Adds virtual cpu
401 Arguments:
403 - "id": cpu id (json-int)
405 Example:
407 -> { "execute": "cpu-add", "arguments": { "id": 2 } }
408 <- { "return": {} }
410 EQMP
413 .name = "memsave",
414 .args_type = "val:l,size:i,filename:s,cpu:i?",
415 .mhandler.cmd_new = qmp_marshal_input_memsave,
418 SQMP
419 memsave
420 -------
422 Save to disk virtual memory dump starting at 'val' of size 'size'.
424 Arguments:
426 - "val": the starting address (json-int)
427 - "size": the memory size, in bytes (json-int)
428 - "filename": file path (json-string)
429 - "cpu": virtual CPU index (json-int, optional)
431 Example:
433 -> { "execute": "memsave",
434 "arguments": { "val": 10,
435 "size": 100,
436 "filename": "/tmp/virtual-mem-dump" } }
437 <- { "return": {} }
439 EQMP
442 .name = "pmemsave",
443 .args_type = "val:l,size:i,filename:s",
444 .mhandler.cmd_new = qmp_marshal_input_pmemsave,
447 SQMP
448 pmemsave
449 --------
451 Save to disk physical memory dump starting at 'val' of size 'size'.
453 Arguments:
455 - "val": the starting address (json-int)
456 - "size": the memory size, in bytes (json-int)
457 - "filename": file path (json-string)
459 Example:
461 -> { "execute": "pmemsave",
462 "arguments": { "val": 10,
463 "size": 100,
464 "filename": "/tmp/physical-mem-dump" } }
465 <- { "return": {} }
467 EQMP
470 .name = "inject-nmi",
471 .args_type = "",
472 .mhandler.cmd_new = qmp_marshal_input_inject_nmi,
475 SQMP
476 inject-nmi
477 ----------
479 Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64).
481 Arguments: None.
483 Example:
485 -> { "execute": "inject-nmi" }
486 <- { "return": {} }
488 Note: inject-nmi fails when the guest doesn't support injecting.
490 EQMP
493 .name = "ringbuf-write",
494 .args_type = "device:s,data:s,format:s?",
495 .mhandler.cmd_new = qmp_marshal_input_ringbuf_write,
498 SQMP
499 ringbuf-write
500 -------------
502 Write to a ring buffer character device.
504 Arguments:
506 - "device": ring buffer character device name (json-string)
507 - "data": data to write (json-string)
508 - "format": data format (json-string, optional)
509 - Possible values: "utf8" (default), "base64"
510 Bug: invalid base64 is currently not rejected.
511 Whitespace *is* invalid.
513 Example:
515 -> { "execute": "ringbuf-write",
516 "arguments": { "device": "foo",
517 "data": "abcdefgh",
518 "format": "utf8" } }
519 <- { "return": {} }
521 EQMP
524 .name = "ringbuf-read",
525 .args_type = "device:s,size:i,format:s?",
526 .mhandler.cmd_new = qmp_marshal_input_ringbuf_read,
529 SQMP
530 ringbuf-read
531 -------------
533 Read from a ring buffer character device.
535 Arguments:
537 - "device": ring buffer character device name (json-string)
538 - "size": how many bytes to read at most (json-int)
539 - Number of data bytes, not number of characters in encoded data
540 - "format": data format (json-string, optional)
541 - Possible values: "utf8" (default), "base64"
542 - Naturally, format "utf8" works only when the ring buffer
543 contains valid UTF-8 text. Invalid UTF-8 sequences get
544 replaced. Bug: replacement doesn't work. Bug: can screw
545 up on encountering NUL characters, after the ring buffer
546 lost data, and when reading stops because the size limit
547 is reached.
549 Example:
551 -> { "execute": "ringbuf-read",
552 "arguments": { "device": "foo",
553 "size": 1000,
554 "format": "utf8" } }
555 <- {"return": "abcdefgh"}
557 EQMP
560 .name = "xen-save-devices-state",
561 .args_type = "filename:F",
562 .mhandler.cmd_new = qmp_marshal_input_xen_save_devices_state,
565 SQMP
566 xen-save-devices-state
567 -------
569 Save the state of all devices to file. The RAM and the block devices
570 of the VM are not saved by this command.
572 Arguments:
574 - "filename": the file to save the state of the devices to as binary
575 data. See xen-save-devices-state.txt for a description of the binary
576 format.
578 Example:
580 -> { "execute": "xen-save-devices-state",
581 "arguments": { "filename": "/tmp/save" } }
582 <- { "return": {} }
584 EQMP
587 .name = "xen-set-global-dirty-log",
588 .args_type = "enable:b",
589 .mhandler.cmd_new = qmp_marshal_input_xen_set_global_dirty_log,
592 SQMP
593 xen-set-global-dirty-log
594 -------
596 Enable or disable the global dirty log mode.
598 Arguments:
600 - "enable": Enable it or disable it.
602 Example:
604 -> { "execute": "xen-set-global-dirty-log",
605 "arguments": { "enable": true } }
606 <- { "return": {} }
608 EQMP
611 .name = "migrate",
612 .args_type = "detach:-d,blk:-b,inc:-i,uri:s",
613 .mhandler.cmd_new = qmp_marshal_input_migrate,
616 SQMP
617 migrate
618 -------
620 Migrate to URI.
622 Arguments:
624 - "blk": block migration, full disk copy (json-bool, optional)
625 - "inc": incremental disk copy (json-bool, optional)
626 - "uri": Destination URI (json-string)
628 Example:
630 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
631 <- { "return": {} }
633 Notes:
635 (1) The 'query-migrate' command should be used to check migration's progress
636 and final result (this information is provided by the 'status' member)
637 (2) All boolean arguments default to false
638 (3) The user Monitor's "detach" argument is invalid in QMP and should not
639 be used
641 EQMP
644 .name = "migrate_cancel",
645 .args_type = "",
646 .mhandler.cmd_new = qmp_marshal_input_migrate_cancel,
649 SQMP
650 migrate_cancel
651 --------------
653 Cancel the current migration.
655 Arguments: None.
657 Example:
659 -> { "execute": "migrate_cancel" }
660 <- { "return": {} }
662 EQMP
665 .name = "migrate-incoming",
666 .args_type = "uri:s",
667 .mhandler.cmd_new = qmp_marshal_input_migrate_incoming,
670 SQMP
671 migrate-incoming
672 ----------------
674 Continue an incoming migration
676 Arguments:
678 - "uri": Source/listening URI (json-string)
680 Example:
682 -> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } }
683 <- { "return": {} }
685 Notes:
687 (1) QEMU must be started with -incoming defer to allow migrate-incoming to
688 be used
689 (2) The uri format is the same as for -incoming
691 EQMP
693 .name = "migrate-set-cache-size",
694 .args_type = "value:o",
695 .mhandler.cmd_new = qmp_marshal_input_migrate_set_cache_size,
698 SQMP
699 migrate-set-cache-size
700 ----------------------
702 Set cache size to be used by XBZRLE migration, the cache size will be rounded
703 down to the nearest power of 2
705 Arguments:
707 - "value": cache size in bytes (json-int)
709 Example:
711 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
712 <- { "return": {} }
714 EQMP
716 .name = "query-migrate-cache-size",
717 .args_type = "",
718 .mhandler.cmd_new = qmp_marshal_input_query_migrate_cache_size,
721 SQMP
722 query-migrate-cache-size
723 ------------------------
725 Show cache size to be used by XBZRLE migration
727 returns a json-object with the following information:
728 - "size" : json-int
730 Example:
732 -> { "execute": "query-migrate-cache-size" }
733 <- { "return": 67108864 }
735 EQMP
738 .name = "migrate_set_speed",
739 .args_type = "value:o",
740 .mhandler.cmd_new = qmp_marshal_input_migrate_set_speed,
743 SQMP
744 migrate_set_speed
745 -----------------
747 Set maximum speed for migrations.
749 Arguments:
751 - "value": maximum speed, in bytes per second (json-int)
753 Example:
755 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
756 <- { "return": {} }
758 EQMP
761 .name = "migrate_set_downtime",
762 .args_type = "value:T",
763 .mhandler.cmd_new = qmp_marshal_input_migrate_set_downtime,
766 SQMP
767 migrate_set_downtime
768 --------------------
770 Set maximum tolerated downtime (in seconds) for migrations.
772 Arguments:
774 - "value": maximum downtime (json-number)
776 Example:
778 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
779 <- { "return": {} }
781 EQMP
784 .name = "client_migrate_info",
785 .args_type = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
786 .params = "protocol hostname port tls-port cert-subject",
787 .help = "set migration information for remote display",
788 .mhandler.cmd_new = qmp_marshal_input_client_migrate_info,
791 SQMP
792 client_migrate_info
793 -------------------
795 Set migration information for remote display. This makes the server
796 ask the client to automatically reconnect using the new parameters
797 once migration finished successfully. Only implemented for SPICE.
799 Arguments:
801 - "protocol": must be "spice" (json-string)
802 - "hostname": migration target hostname (json-string)
803 - "port": spice tcp port for plaintext channels (json-int, optional)
804 - "tls-port": spice tcp port for tls-secured channels (json-int, optional)
805 - "cert-subject": server certificate subject (json-string, optional)
807 Example:
809 -> { "execute": "client_migrate_info",
810 "arguments": { "protocol": "spice",
811 "hostname": "virt42.lab.kraxel.org",
812 "port": 1234 } }
813 <- { "return": {} }
815 EQMP
818 .name = "dump-guest-memory",
819 .args_type = "paging:b,protocol:s,begin:i?,end:i?,format:s?",
820 .params = "-p protocol [begin] [length] [format]",
821 .help = "dump guest memory to file",
822 .mhandler.cmd_new = qmp_marshal_input_dump_guest_memory,
825 SQMP
826 dump
829 Dump guest memory to file. The file can be processed with crash or gdb.
831 Arguments:
833 - "paging": do paging to get guest's memory mapping (json-bool)
834 - "protocol": destination file(started with "file:") or destination file
835 descriptor (started with "fd:") (json-string)
836 - "begin": the starting physical address. It's optional, and should be specified
837 with length together (json-int)
838 - "length": the memory size, in bytes. It's optional, and should be specified
839 with begin together (json-int)
840 - "format": the format of guest memory dump. It's optional, and can be
841 elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will
842 conflict with paging and filter, ie. begin and length (json-string)
844 Example:
846 -> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
847 <- { "return": {} }
849 Notes:
851 (1) All boolean arguments default to false
853 EQMP
856 .name = "query-dump-guest-memory-capability",
857 .args_type = "",
858 .mhandler.cmd_new = qmp_marshal_input_query_dump_guest_memory_capability,
861 SQMP
862 query-dump-guest-memory-capability
863 ----------
865 Show available formats for 'dump-guest-memory'
867 Example:
869 -> { "execute": "query-dump-guest-memory-capability" }
870 <- { "return": { "formats":
871 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
873 EQMP
876 .name = "netdev_add",
877 .args_type = "netdev:O",
878 .mhandler.cmd_new = qmp_netdev_add,
881 SQMP
882 netdev_add
883 ----------
885 Add host network device.
887 Arguments:
889 - "type": the device type, "tap", "user", ... (json-string)
890 - "id": the device's ID, must be unique (json-string)
891 - device options
893 Example:
895 -> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
896 <- { "return": {} }
898 Note: The supported device options are the same ones supported by the '-netdev'
899 command-line argument, which are listed in the '-help' output or QEMU's
900 manual
902 EQMP
905 .name = "netdev_del",
906 .args_type = "id:s",
907 .mhandler.cmd_new = qmp_marshal_input_netdev_del,
910 SQMP
911 netdev_del
912 ----------
914 Remove host network device.
916 Arguments:
918 - "id": the device's ID, must be unique (json-string)
920 Example:
922 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
923 <- { "return": {} }
926 EQMP
929 .name = "object-add",
930 .args_type = "qom-type:s,id:s,props:q?",
931 .mhandler.cmd_new = qmp_object_add,
934 SQMP
935 object-add
936 ----------
938 Create QOM object.
940 Arguments:
942 - "qom-type": the object's QOM type, i.e. the class name (json-string)
943 - "id": the object's ID, must be unique (json-string)
944 - "props": a dictionary of object property values (optional, json-dict)
946 Example:
948 -> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1",
949 "props": { "filename": "/dev/hwrng" } } }
950 <- { "return": {} }
952 EQMP
955 .name = "object-del",
956 .args_type = "id:s",
957 .mhandler.cmd_new = qmp_marshal_input_object_del,
960 SQMP
961 object-del
962 ----------
964 Remove QOM object.
966 Arguments:
968 - "id": the object's ID (json-string)
970 Example:
972 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
973 <- { "return": {} }
976 EQMP
980 .name = "block_resize",
981 .args_type = "device:s?,node-name:s?,size:o",
982 .mhandler.cmd_new = qmp_marshal_input_block_resize,
985 SQMP
986 block_resize
987 ------------
989 Resize a block image while a guest is running.
991 Arguments:
993 - "device": the device's ID, must be unique (json-string)
994 - "node-name": the node name in the block driver state graph (json-string)
995 - "size": new size
997 Example:
999 -> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
1000 <- { "return": {} }
1002 EQMP
1005 .name = "block-stream",
1006 .args_type = "device:B,base:s?,speed:o?,backing-file:s?,on-error:s?",
1007 .mhandler.cmd_new = qmp_marshal_input_block_stream,
1010 SQMP
1011 block-stream
1012 ------------
1014 Copy data from a backing file into a block device.
1016 Arguments:
1018 - "device": The device's ID, must be unique (json-string)
1019 - "base": The file name of the backing image above which copying starts
1020 (json-string, optional)
1021 - "backing-file": The backing file string to write into the active layer. This
1022 filename is not validated.
1024 If a pathname string is such that it cannot be resolved by
1025 QEMU, that means that subsequent QMP or HMP commands must use
1026 node-names for the image in question, as filename lookup
1027 methods will fail.
1029 If not specified, QEMU will automatically determine the
1030 backing file string to use, or error out if there is no
1031 obvious choice. Care should be taken when specifying the
1032 string, to specify a valid filename or protocol.
1033 (json-string, optional) (Since 2.1)
1034 - "speed": the maximum speed, in bytes per second (json-int, optional)
1035 - "on-error": the action to take on an error (default 'report'). 'stop' and
1036 'enospc' can only be used if the block device supports io-status.
1037 (json-string, optional) (Since 2.1)
1039 Example:
1041 -> { "execute": "block-stream", "arguments": { "device": "virtio0",
1042 "base": "/tmp/master.qcow2" } }
1043 <- { "return": {} }
1045 EQMP
1048 .name = "block-commit",
1049 .args_type = "device:B,base:s?,top:s?,backing-file:s?,speed:o?",
1050 .mhandler.cmd_new = qmp_marshal_input_block_commit,
1053 SQMP
1054 block-commit
1055 ------------
1057 Live commit of data from overlay image nodes into backing nodes - i.e., writes
1058 data between 'top' and 'base' into 'base'.
1060 Arguments:
1062 - "device": The device's ID, must be unique (json-string)
1063 - "base": The file name of the backing image to write data into.
1064 If not specified, this is the deepest backing image
1065 (json-string, optional)
1066 - "top": The file name of the backing image within the image chain,
1067 which contains the topmost data to be committed down. If
1068 not specified, this is the active layer. (json-string, optional)
1070 - backing-file: The backing file string to write into the overlay
1071 image of 'top'. If 'top' is the active layer,
1072 specifying a backing file string is an error. This
1073 filename is not validated.
1075 If a pathname string is such that it cannot be
1076 resolved by QEMU, that means that subsequent QMP or
1077 HMP commands must use node-names for the image in
1078 question, as filename lookup methods will fail.
1080 If not specified, QEMU will automatically determine
1081 the backing file string to use, or error out if
1082 there is no obvious choice. Care should be taken
1083 when specifying the string, to specify a valid
1084 filename or protocol.
1085 (json-string, optional) (Since 2.1)
1087 If top == base, that is an error.
1088 If top == active, the job will not be completed by itself,
1089 user needs to complete the job with the block-job-complete
1090 command after getting the ready event. (Since 2.0)
1092 If the base image is smaller than top, then the base image
1093 will be resized to be the same size as top. If top is
1094 smaller than the base image, the base will not be
1095 truncated. If you want the base image size to match the
1096 size of the smaller top, you can safely truncate it
1097 yourself once the commit operation successfully completes.
1098 (json-string)
1099 - "speed": the maximum speed, in bytes per second (json-int, optional)
1102 Example:
1104 -> { "execute": "block-commit", "arguments": { "device": "virtio0",
1105 "top": "/tmp/snap1.qcow2" } }
1106 <- { "return": {} }
1108 EQMP
1111 .name = "drive-backup",
1112 .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
1113 "bitmap:s?,on-source-error:s?,on-target-error:s?",
1114 .mhandler.cmd_new = qmp_marshal_input_drive_backup,
1117 SQMP
1118 drive-backup
1119 ------------
1121 Start a point-in-time copy of a block device to a new destination. The
1122 status of ongoing drive-backup operations can be checked with
1123 query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
1124 The operation can be stopped before it has completed using the
1125 block-job-cancel command.
1127 Arguments:
1129 - "device": the name of the device which should be copied.
1130 (json-string)
1131 - "target": the target of the new image. If the file exists, or if it is a
1132 device, the existing file/device will be used as the new
1133 destination. If it does not exist, a new file will be created.
1134 (json-string)
1135 - "format": the format of the new destination, default is to probe if 'mode' is
1136 'existing', else the format of the source
1137 (json-string, optional)
1138 - "sync": what parts of the disk image should be copied to the destination;
1139 possibilities include "full" for all the disk, "top" for only the sectors
1140 allocated in the topmost image, "incremental" for only the dirty sectors in
1141 the bitmap, or "none" to only replicate new I/O (MirrorSyncMode).
1142 - "bitmap": dirty bitmap name for sync==incremental. Must be present if sync
1143 is "incremental", must NOT be present otherwise.
1144 - "mode": whether and how QEMU should create a new image
1145 (NewImageMode, optional, default 'absolute-paths')
1146 - "speed": the maximum speed, in bytes per second (json-int, optional)
1147 - "on-source-error": the action to take on an error on the source, default
1148 'report'. 'stop' and 'enospc' can only be used
1149 if the block device supports io-status.
1150 (BlockdevOnError, optional)
1151 - "on-target-error": the action to take on an error on the target, default
1152 'report' (no limitations, since this applies to
1153 a different block device than device).
1154 (BlockdevOnError, optional)
1156 Example:
1157 -> { "execute": "drive-backup", "arguments": { "device": "drive0",
1158 "sync": "full",
1159 "target": "backup.img" } }
1160 <- { "return": {} }
1162 EQMP
1165 .name = "blockdev-backup",
1166 .args_type = "sync:s,device:B,target:B,speed:i?,"
1167 "on-source-error:s?,on-target-error:s?",
1168 .mhandler.cmd_new = qmp_marshal_input_blockdev_backup,
1171 SQMP
1172 blockdev-backup
1173 ---------------
1175 The device version of drive-backup: this command takes an existing named device
1176 as backup target.
1178 Arguments:
1180 - "device": the name of the device which should be copied.
1181 (json-string)
1182 - "target": the name of the backup target device. (json-string)
1183 - "sync": what parts of the disk image should be copied to the destination;
1184 possibilities include "full" for all the disk, "top" for only the
1185 sectors allocated in the topmost image, or "none" to only replicate
1186 new I/O (MirrorSyncMode).
1187 - "speed": the maximum speed, in bytes per second (json-int, optional)
1188 - "on-source-error": the action to take on an error on the source, default
1189 'report'. 'stop' and 'enospc' can only be used
1190 if the block device supports io-status.
1191 (BlockdevOnError, optional)
1192 - "on-target-error": the action to take on an error on the target, default
1193 'report' (no limitations, since this applies to
1194 a different block device than device).
1195 (BlockdevOnError, optional)
1197 Example:
1198 -> { "execute": "blockdev-backup", "arguments": { "device": "src-id",
1199 "sync": "full",
1200 "target": "tgt-id" } }
1201 <- { "return": {} }
1203 EQMP
1206 .name = "block-job-set-speed",
1207 .args_type = "device:B,speed:o",
1208 .mhandler.cmd_new = qmp_marshal_input_block_job_set_speed,
1212 .name = "block-job-cancel",
1213 .args_type = "device:B,force:b?",
1214 .mhandler.cmd_new = qmp_marshal_input_block_job_cancel,
1217 .name = "block-job-pause",
1218 .args_type = "device:B",
1219 .mhandler.cmd_new = qmp_marshal_input_block_job_pause,
1222 .name = "block-job-resume",
1223 .args_type = "device:B",
1224 .mhandler.cmd_new = qmp_marshal_input_block_job_resume,
1227 .name = "block-job-complete",
1228 .args_type = "device:B",
1229 .mhandler.cmd_new = qmp_marshal_input_block_job_complete,
1232 .name = "transaction",
1233 .args_type = "actions:q",
1234 .mhandler.cmd_new = qmp_marshal_input_transaction,
1237 SQMP
1238 transaction
1239 -----------
1241 Atomically operate on one or more block devices. The only supported operations
1242 for now are drive-backup, internal and external snapshotting. A list of
1243 dictionaries is accepted, that contains the actions to be performed.
1244 If there is any failure performing any of the operations, all operations
1245 for the group are abandoned.
1247 For external snapshots, the dictionary contains the device, the file to use for
1248 the new snapshot, and the format. The default format, if not specified, is
1249 qcow2.
1251 Each new snapshot defaults to being created by QEMU (wiping any
1252 contents if the file already exists), but it is also possible to reuse
1253 an externally-created file. In the latter case, you should ensure that
1254 the new image file has the same contents as the current one; QEMU cannot
1255 perform any meaningful check. Typically this is achieved by using the
1256 current image file as the backing file for the new image.
1258 On failure, the original disks pre-snapshot attempt will be used.
1260 For internal snapshots, the dictionary contains the device and the snapshot's
1261 name. If an internal snapshot matching name already exists, the request will
1262 be rejected. Only some image formats support it, for example, qcow2, rbd,
1263 and sheepdog.
1265 On failure, qemu will try delete the newly created internal snapshot in the
1266 transaction. When an I/O error occurs during deletion, the user needs to fix
1267 it later with qemu-img or other command.
1269 Arguments:
1271 actions array:
1272 - "type": the operation to perform. The only supported
1273 value is "blockdev-snapshot-sync". (json-string)
1274 - "data": a dictionary. The contents depend on the value
1275 of "type". When "type" is "blockdev-snapshot-sync":
1276 - "device": device name to snapshot (json-string)
1277 - "node-name": graph node name to snapshot (json-string)
1278 - "snapshot-file": name of new image file (json-string)
1279 - "snapshot-node-name": graph node name of the new snapshot (json-string)
1280 - "format": format of new image (json-string, optional)
1281 - "mode": whether and how QEMU should create the snapshot file
1282 (NewImageMode, optional, default "absolute-paths")
1283 When "type" is "blockdev-snapshot-internal-sync":
1284 - "device": device name to snapshot (json-string)
1285 - "name": name of the new snapshot (json-string)
1287 Example:
1289 -> { "execute": "transaction",
1290 "arguments": { "actions": [
1291 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
1292 "snapshot-file": "/some/place/my-image",
1293 "format": "qcow2" } },
1294 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
1295 "snapshot-file": "/some/place/my-image2",
1296 "snapshot-node-name": "node3432",
1297 "mode": "existing",
1298 "format": "qcow2" } },
1299 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
1300 "snapshot-file": "/some/place/my-image2",
1301 "mode": "existing",
1302 "format": "qcow2" } },
1303 { "type": "blockdev-snapshot-internal-sync", "data" : {
1304 "device": "ide-hd2",
1305 "name": "snapshot0" } } ] } }
1306 <- { "return": {} }
1308 EQMP
1311 .name = "block-dirty-bitmap-add",
1312 .args_type = "node:B,name:s,granularity:i?",
1313 .mhandler.cmd_new = qmp_marshal_input_block_dirty_bitmap_add,
1316 SQMP
1318 block-dirty-bitmap-add
1319 ----------------------
1320 Since 2.4
1322 Create a dirty bitmap with a name on the device, and start tracking the writes.
1324 Arguments:
1326 - "node": device/node on which to create dirty bitmap (json-string)
1327 - "name": name of the new dirty bitmap (json-string)
1328 - "granularity": granularity to track writes with (int, optional)
1330 Example:
1332 -> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0",
1333 "name": "bitmap0" } }
1334 <- { "return": {} }
1336 EQMP
1339 .name = "block-dirty-bitmap-remove",
1340 .args_type = "node:B,name:s",
1341 .mhandler.cmd_new = qmp_marshal_input_block_dirty_bitmap_remove,
1344 SQMP
1346 block-dirty-bitmap-remove
1347 -------------------------
1348 Since 2.4
1350 Stop write tracking and remove the dirty bitmap that was created with
1351 block-dirty-bitmap-add.
1353 Arguments:
1355 - "node": device/node on which to remove dirty bitmap (json-string)
1356 - "name": name of the dirty bitmap to remove (json-string)
1358 Example:
1360 -> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0",
1361 "name": "bitmap0" } }
1362 <- { "return": {} }
1364 EQMP
1367 .name = "block-dirty-bitmap-clear",
1368 .args_type = "node:B,name:s",
1369 .mhandler.cmd_new = qmp_marshal_input_block_dirty_bitmap_clear,
1372 SQMP
1374 block-dirty-bitmap-clear
1375 ------------------------
1376 Since 2.4
1378 Reset the dirty bitmap associated with a node so that an incremental backup
1379 from this point in time forward will only backup clusters modified after this
1380 clear operation.
1382 Arguments:
1384 - "node": device/node on which to remove dirty bitmap (json-string)
1385 - "name": name of the dirty bitmap to remove (json-string)
1387 Example:
1389 -> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0",
1390 "name": "bitmap0" } }
1391 <- { "return": {} }
1393 EQMP
1396 .name = "blockdev-snapshot-sync",
1397 .args_type = "device:s?,node-name:s?,snapshot-file:s,snapshot-node-name:s?,format:s?,mode:s?",
1398 .mhandler.cmd_new = qmp_marshal_input_blockdev_snapshot_sync,
1401 SQMP
1402 blockdev-snapshot-sync
1403 ----------------------
1405 Synchronous snapshot of a block device. snapshot-file specifies the
1406 target of the new image. If the file exists, or if it is a device, the
1407 snapshot will be created in the existing file/device. If does not
1408 exist, a new file will be created. format specifies the format of the
1409 snapshot image, default is qcow2.
1411 Arguments:
1413 - "device": device name to snapshot (json-string)
1414 - "node-name": graph node name to snapshot (json-string)
1415 - "snapshot-file": name of new image file (json-string)
1416 - "snapshot-node-name": graph node name of the new snapshot (json-string)
1417 - "mode": whether and how QEMU should create the snapshot file
1418 (NewImageMode, optional, default "absolute-paths")
1419 - "format": format of new image (json-string, optional)
1421 Example:
1423 -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
1424 "snapshot-file":
1425 "/some/place/my-image",
1426 "format": "qcow2" } }
1427 <- { "return": {} }
1429 EQMP
1432 .name = "blockdev-snapshot-internal-sync",
1433 .args_type = "device:B,name:s",
1434 .mhandler.cmd_new = qmp_marshal_input_blockdev_snapshot_internal_sync,
1437 SQMP
1438 blockdev-snapshot-internal-sync
1439 -------------------------------
1441 Synchronously take an internal snapshot of a block device when the format of
1442 image used supports it. If the name is an empty string, or a snapshot with
1443 name already exists, the operation will fail.
1445 Arguments:
1447 - "device": device name to snapshot (json-string)
1448 - "name": name of the new snapshot (json-string)
1450 Example:
1452 -> { "execute": "blockdev-snapshot-internal-sync",
1453 "arguments": { "device": "ide-hd0",
1454 "name": "snapshot0" }
1456 <- { "return": {} }
1458 EQMP
1461 .name = "blockdev-snapshot-delete-internal-sync",
1462 .args_type = "device:B,id:s?,name:s?",
1463 .mhandler.cmd_new =
1464 qmp_marshal_input_blockdev_snapshot_delete_internal_sync,
1467 SQMP
1468 blockdev-snapshot-delete-internal-sync
1469 --------------------------------------
1471 Synchronously delete an internal snapshot of a block device when the format of
1472 image used supports it. The snapshot is identified by name or id or both. One
1473 of name or id is required. If the snapshot is not found, the operation will
1474 fail.
1476 Arguments:
1478 - "device": device name (json-string)
1479 - "id": ID of the snapshot (json-string, optional)
1480 - "name": name of the snapshot (json-string, optional)
1482 Example:
1484 -> { "execute": "blockdev-snapshot-delete-internal-sync",
1485 "arguments": { "device": "ide-hd0",
1486 "name": "snapshot0" }
1488 <- { "return": {
1489 "id": "1",
1490 "name": "snapshot0",
1491 "vm-state-size": 0,
1492 "date-sec": 1000012,
1493 "date-nsec": 10,
1494 "vm-clock-sec": 100,
1495 "vm-clock-nsec": 20
1499 EQMP
1502 .name = "drive-mirror",
1503 .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
1504 "node-name:s?,replaces:s?,"
1505 "on-source-error:s?,on-target-error:s?,"
1506 "unmap:b?,"
1507 "granularity:i?,buf-size:i?",
1508 .mhandler.cmd_new = qmp_marshal_input_drive_mirror,
1511 SQMP
1512 drive-mirror
1513 ------------
1515 Start mirroring a block device's writes to a new destination. target
1516 specifies the target of the new image. If the file exists, or if it is
1517 a device, it will be used as the new destination for writes. If it does not
1518 exist, a new file will be created. format specifies the format of the
1519 mirror image, default is to probe if mode='existing', else the format
1520 of the source.
1522 Arguments:
1524 - "device": device name to operate on (json-string)
1525 - "target": name of new image file (json-string)
1526 - "format": format of new image (json-string, optional)
1527 - "node-name": the name of the new block driver state in the node graph
1528 (json-string, optional)
1529 - "replaces": the block driver node name to replace when finished
1530 (json-string, optional)
1531 - "mode": how an image file should be created into the target
1532 file/device (NewImageMode, optional, default 'absolute-paths')
1533 - "speed": maximum speed of the streaming job, in bytes per second
1534 (json-int)
1535 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1536 - "buf_size": maximum amount of data in flight from source to target, in bytes
1537 (json-int, default 10M)
1538 - "sync": what parts of the disk image should be copied to the destination;
1539 possibilities include "full" for all the disk, "top" for only the sectors
1540 allocated in the topmost image, or "none" to only replicate new I/O
1541 (MirrorSyncMode).
1542 - "on-source-error": the action to take on an error on the source
1543 (BlockdevOnError, default 'report')
1544 - "on-target-error": the action to take on an error on the target
1545 (BlockdevOnError, default 'report')
1546 - "unmap": whether the target sectors should be discarded where source has only
1547 zeroes. (json-bool, optional, default true)
1549 The default value of the granularity is the image cluster size clamped
1550 between 4096 and 65536, if the image format defines one. If the format
1551 does not define a cluster size, the default value of the granularity
1552 is 65536.
1555 Example:
1557 -> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
1558 "target": "/some/place/my-image",
1559 "sync": "full",
1560 "format": "qcow2" } }
1561 <- { "return": {} }
1563 EQMP
1566 .name = "change-backing-file",
1567 .args_type = "device:s,image-node-name:s,backing-file:s",
1568 .mhandler.cmd_new = qmp_marshal_input_change_backing_file,
1571 SQMP
1572 change-backing-file
1573 -------------------
1574 Since: 2.1
1576 Change the backing file in the image file metadata. This does not cause
1577 QEMU to reopen the image file to reparse the backing filename (it may,
1578 however, perform a reopen to change permissions from r/o -> r/w -> r/o,
1579 if needed). The new backing file string is written into the image file
1580 metadata, and the QEMU internal strings are updated.
1582 Arguments:
1584 - "image-node-name": The name of the block driver state node of the
1585 image to modify. The "device" is argument is used to
1586 verify "image-node-name" is in the chain described by
1587 "device".
1588 (json-string, optional)
1590 - "device": The name of the device.
1591 (json-string)
1593 - "backing-file": The string to write as the backing file. This string is
1594 not validated, so care should be taken when specifying
1595 the string or the image chain may not be able to be
1596 reopened again.
1597 (json-string)
1599 Returns: Nothing on success
1600 If "device" does not exist or cannot be determined, DeviceNotFound
1602 EQMP
1605 .name = "balloon",
1606 .args_type = "value:M",
1607 .mhandler.cmd_new = qmp_marshal_input_balloon,
1610 SQMP
1611 balloon
1612 -------
1614 Request VM to change its memory allocation (in bytes).
1616 Arguments:
1618 - "value": New memory allocation (json-int)
1620 Example:
1622 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1623 <- { "return": {} }
1625 EQMP
1628 .name = "set_link",
1629 .args_type = "name:s,up:b",
1630 .mhandler.cmd_new = qmp_marshal_input_set_link,
1633 SQMP
1634 set_link
1635 --------
1637 Change the link status of a network adapter.
1639 Arguments:
1641 - "name": network device name (json-string)
1642 - "up": status is up (json-bool)
1644 Example:
1646 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1647 <- { "return": {} }
1649 EQMP
1652 .name = "getfd",
1653 .args_type = "fdname:s",
1654 .params = "getfd name",
1655 .help = "receive a file descriptor via SCM rights and assign it a name",
1656 .mhandler.cmd_new = qmp_marshal_input_getfd,
1659 SQMP
1660 getfd
1661 -----
1663 Receive a file descriptor via SCM rights and assign it a name.
1665 Arguments:
1667 - "fdname": file descriptor name (json-string)
1669 Example:
1671 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1672 <- { "return": {} }
1674 Notes:
1676 (1) If the name specified by the "fdname" argument already exists,
1677 the file descriptor assigned to it will be closed and replaced
1678 by the received file descriptor.
1679 (2) The 'closefd' command can be used to explicitly close the file
1680 descriptor when it is no longer needed.
1682 EQMP
1685 .name = "closefd",
1686 .args_type = "fdname:s",
1687 .params = "closefd name",
1688 .help = "close a file descriptor previously passed via SCM rights",
1689 .mhandler.cmd_new = qmp_marshal_input_closefd,
1692 SQMP
1693 closefd
1694 -------
1696 Close a file descriptor previously passed via SCM rights.
1698 Arguments:
1700 - "fdname": file descriptor name (json-string)
1702 Example:
1704 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1705 <- { "return": {} }
1707 EQMP
1710 .name = "add-fd",
1711 .args_type = "fdset-id:i?,opaque:s?",
1712 .params = "add-fd fdset-id opaque",
1713 .help = "Add a file descriptor, that was passed via SCM rights, to an fd set",
1714 .mhandler.cmd_new = qmp_marshal_input_add_fd,
1717 SQMP
1718 add-fd
1719 -------
1721 Add a file descriptor, that was passed via SCM rights, to an fd set.
1723 Arguments:
1725 - "fdset-id": The ID of the fd set to add the file descriptor to.
1726 (json-int, optional)
1727 - "opaque": A free-form string that can be used to describe the fd.
1728 (json-string, optional)
1730 Return a json-object with the following information:
1732 - "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1733 - "fd": The file descriptor that was received via SCM rights and added to the
1734 fd set. (json-int)
1736 Example:
1738 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1739 <- { "return": { "fdset-id": 1, "fd": 3 } }
1741 Notes:
1743 (1) The list of fd sets is shared by all monitor connections.
1744 (2) If "fdset-id" is not specified, a new fd set will be created.
1746 EQMP
1749 .name = "remove-fd",
1750 .args_type = "fdset-id:i,fd:i?",
1751 .params = "remove-fd fdset-id fd",
1752 .help = "Remove a file descriptor from an fd set",
1753 .mhandler.cmd_new = qmp_marshal_input_remove_fd,
1756 SQMP
1757 remove-fd
1758 ---------
1760 Remove a file descriptor from an fd set.
1762 Arguments:
1764 - "fdset-id": The ID of the fd set that the file descriptor belongs to.
1765 (json-int)
1766 - "fd": The file descriptor that is to be removed. (json-int, optional)
1768 Example:
1770 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1771 <- { "return": {} }
1773 Notes:
1775 (1) The list of fd sets is shared by all monitor connections.
1776 (2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1777 removed.
1779 EQMP
1782 .name = "query-fdsets",
1783 .args_type = "",
1784 .help = "Return information describing all fd sets",
1785 .mhandler.cmd_new = qmp_marshal_input_query_fdsets,
1788 SQMP
1789 query-fdsets
1790 -------------
1792 Return information describing all fd sets.
1794 Arguments: None
1796 Example:
1798 -> { "execute": "query-fdsets" }
1799 <- { "return": [
1801 "fds": [
1803 "fd": 30,
1804 "opaque": "rdonly:/path/to/file"
1807 "fd": 24,
1808 "opaque": "rdwr:/path/to/file"
1811 "fdset-id": 1
1814 "fds": [
1816 "fd": 28
1819 "fd": 29
1822 "fdset-id": 0
1827 Note: The list of fd sets is shared by all monitor connections.
1829 EQMP
1832 .name = "block_passwd",
1833 .args_type = "device:s?,node-name:s?,password:s",
1834 .mhandler.cmd_new = qmp_marshal_input_block_passwd,
1837 SQMP
1838 block_passwd
1839 ------------
1841 Set the password of encrypted block devices.
1843 Arguments:
1845 - "device": device name (json-string)
1846 - "node-name": name in the block driver state graph (json-string)
1847 - "password": password (json-string)
1849 Example:
1851 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1852 "password": "12345" } }
1853 <- { "return": {} }
1855 EQMP
1858 .name = "block_set_io_throttle",
1859 .args_type = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l,bps_max:l?,bps_rd_max:l?,bps_wr_max:l?,iops_max:l?,iops_rd_max:l?,iops_wr_max:l?,iops_size:l?,group:s?",
1860 .mhandler.cmd_new = qmp_marshal_input_block_set_io_throttle,
1863 SQMP
1864 block_set_io_throttle
1865 ------------
1867 Change I/O throttle limits for a block drive.
1869 Arguments:
1871 - "device": device name (json-string)
1872 - "bps": total throughput limit in bytes per second (json-int)
1873 - "bps_rd": read throughput limit in bytes per second (json-int)
1874 - "bps_wr": write throughput limit in bytes per second (json-int)
1875 - "iops": total I/O operations per second (json-int)
1876 - "iops_rd": read I/O operations per second (json-int)
1877 - "iops_wr": write I/O operations per second (json-int)
1878 - "bps_max": total max in bytes (json-int)
1879 - "bps_rd_max": read max in bytes (json-int)
1880 - "bps_wr_max": write max in bytes (json-int)
1881 - "iops_max": total I/O operations max (json-int)
1882 - "iops_rd_max": read I/O operations max (json-int)
1883 - "iops_wr_max": write I/O operations max (json-int)
1884 - "iops_size": I/O size in bytes when limiting (json-int)
1885 - "group": throttle group name (json-string)
1887 Example:
1889 -> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
1890 "bps": 1000000,
1891 "bps_rd": 0,
1892 "bps_wr": 0,
1893 "iops": 0,
1894 "iops_rd": 0,
1895 "iops_wr": 0,
1896 "bps_max": 8000000,
1897 "bps_rd_max": 0,
1898 "bps_wr_max": 0,
1899 "iops_max": 0,
1900 "iops_rd_max": 0,
1901 "iops_wr_max": 0,
1902 "iops_size": 0 } }
1903 <- { "return": {} }
1905 EQMP
1908 .name = "set_password",
1909 .args_type = "protocol:s,password:s,connected:s?",
1910 .mhandler.cmd_new = qmp_marshal_input_set_password,
1913 SQMP
1914 set_password
1915 ------------
1917 Set the password for vnc/spice protocols.
1919 Arguments:
1921 - "protocol": protocol name (json-string)
1922 - "password": password (json-string)
1923 - "connected": [ keep | disconnect | fail ] (json-string, optional)
1925 Example:
1927 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
1928 "password": "secret" } }
1929 <- { "return": {} }
1931 EQMP
1934 .name = "expire_password",
1935 .args_type = "protocol:s,time:s",
1936 .mhandler.cmd_new = qmp_marshal_input_expire_password,
1939 SQMP
1940 expire_password
1941 ---------------
1943 Set the password expire time for vnc/spice protocols.
1945 Arguments:
1947 - "protocol": protocol name (json-string)
1948 - "time": [ now | never | +secs | secs ] (json-string)
1950 Example:
1952 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
1953 "time": "+60" } }
1954 <- { "return": {} }
1956 EQMP
1959 .name = "add_client",
1960 .args_type = "protocol:s,fdname:s,skipauth:b?,tls:b?",
1961 .mhandler.cmd_new = qmp_marshal_input_add_client,
1964 SQMP
1965 add_client
1966 ----------
1968 Add a graphics client
1970 Arguments:
1972 - "protocol": protocol name (json-string)
1973 - "fdname": file descriptor name (json-string)
1974 - "skipauth": whether to skip authentication (json-bool, optional)
1975 - "tls": whether to perform TLS (json-bool, optional)
1977 Example:
1979 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
1980 "fdname": "myclient" } }
1981 <- { "return": {} }
1983 EQMP
1985 .name = "qmp_capabilities",
1986 .args_type = "",
1987 .params = "",
1988 .help = "enable QMP capabilities",
1989 .mhandler.cmd_new = qmp_capabilities,
1992 SQMP
1993 qmp_capabilities
1994 ----------------
1996 Enable QMP capabilities.
1998 Arguments: None.
2000 Example:
2002 -> { "execute": "qmp_capabilities" }
2003 <- { "return": {} }
2005 Note: This command must be issued before issuing any other command.
2007 EQMP
2010 .name = "human-monitor-command",
2011 .args_type = "command-line:s,cpu-index:i?",
2012 .mhandler.cmd_new = qmp_marshal_input_human_monitor_command,
2015 SQMP
2016 human-monitor-command
2017 ---------------------
2019 Execute a Human Monitor command.
2021 Arguments:
2023 - command-line: the command name and its arguments, just like the
2024 Human Monitor's shell (json-string)
2025 - cpu-index: select the CPU number to be used by commands which access CPU
2026 data, like 'info registers'. The Monitor selects CPU 0 if this
2027 argument is not provided (json-int, optional)
2029 Example:
2031 -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
2032 <- { "return": "kvm support: enabled\r\n" }
2034 Notes:
2036 (1) The Human Monitor is NOT an stable interface, this means that command
2037 names, arguments and responses can change or be removed at ANY time.
2038 Applications that rely on long term stability guarantees should NOT
2039 use this command
2041 (2) Limitations:
2043 o This command is stateless, this means that commands that depend
2044 on state information (such as getfd) might not work
2046 o Commands that prompt the user for data (eg. 'cont' when the block
2047 device is encrypted) don't currently work
2049 3. Query Commands
2050 =================
2052 HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
2053 HXCOMM this! We will possibly move query commands definitions inside those
2054 HXCOMM sections, just like regular commands.
2056 EQMP
2058 SQMP
2059 query-version
2060 -------------
2062 Show QEMU version.
2064 Return a json-object with the following information:
2066 - "qemu": A json-object containing three integer values:
2067 - "major": QEMU's major version (json-int)
2068 - "minor": QEMU's minor version (json-int)
2069 - "micro": QEMU's micro version (json-int)
2070 - "package": package's version (json-string)
2072 Example:
2074 -> { "execute": "query-version" }
2075 <- {
2076 "return":{
2077 "qemu":{
2078 "major":0,
2079 "minor":11,
2080 "micro":5
2082 "package":""
2086 EQMP
2089 .name = "query-version",
2090 .args_type = "",
2091 .mhandler.cmd_new = qmp_marshal_input_query_version,
2094 SQMP
2095 query-commands
2096 --------------
2098 List QMP available commands.
2100 Each command is represented by a json-object, the returned value is a json-array
2101 of all commands.
2103 Each json-object contain:
2105 - "name": command's name (json-string)
2107 Example:
2109 -> { "execute": "query-commands" }
2110 <- {
2111 "return":[
2113 "name":"query-balloon"
2116 "name":"system_powerdown"
2121 Note: This example has been shortened as the real response is too long.
2123 EQMP
2126 .name = "query-commands",
2127 .args_type = "",
2128 .mhandler.cmd_new = qmp_marshal_input_query_commands,
2131 SQMP
2132 query-events
2133 --------------
2135 List QMP available events.
2137 Each event is represented by a json-object, the returned value is a json-array
2138 of all events.
2140 Each json-object contains:
2142 - "name": event's name (json-string)
2144 Example:
2146 -> { "execute": "query-events" }
2147 <- {
2148 "return":[
2150 "name":"SHUTDOWN"
2153 "name":"RESET"
2158 Note: This example has been shortened as the real response is too long.
2160 EQMP
2163 .name = "query-events",
2164 .args_type = "",
2165 .mhandler.cmd_new = qmp_marshal_input_query_events,
2168 SQMP
2169 query-chardev
2170 -------------
2172 Each device is represented by a json-object. The returned value is a json-array
2173 of all devices.
2175 Each json-object contain the following:
2177 - "label": device's label (json-string)
2178 - "filename": device's file (json-string)
2179 - "frontend-open": open/closed state of the frontend device attached to this
2180 backend (json-bool)
2182 Example:
2184 -> { "execute": "query-chardev" }
2185 <- {
2186 "return": [
2188 "label": "charchannel0",
2189 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
2190 "frontend-open": false
2193 "label": "charmonitor",
2194 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
2195 "frontend-open": true
2198 "label": "charserial0",
2199 "filename": "pty:/dev/pts/2",
2200 "frontend-open": true
2205 EQMP
2208 .name = "query-chardev",
2209 .args_type = "",
2210 .mhandler.cmd_new = qmp_marshal_input_query_chardev,
2213 SQMP
2214 query-chardev-backends
2215 -------------
2217 List available character device backends.
2219 Each backend is represented by a json-object, the returned value is a json-array
2220 of all backends.
2222 Each json-object contains:
2224 - "name": backend name (json-string)
2226 Example:
2228 -> { "execute": "query-chardev-backends" }
2229 <- {
2230 "return":[
2232 "name":"udp"
2235 "name":"tcp"
2238 "name":"unix"
2241 "name":"spiceport"
2246 EQMP
2249 .name = "query-chardev-backends",
2250 .args_type = "",
2251 .mhandler.cmd_new = qmp_marshal_input_query_chardev_backends,
2254 SQMP
2255 query-block
2256 -----------
2258 Show the block devices.
2260 Each block device information is stored in a json-object and the returned value
2261 is a json-array of all devices.
2263 Each json-object contain the following:
2265 - "device": device name (json-string)
2266 - "type": device type (json-string)
2267 - deprecated, retained for backward compatibility
2268 - Possible values: "unknown"
2269 - "removable": true if the device is removable, false otherwise (json-bool)
2270 - "locked": true if the device is locked, false otherwise (json-bool)
2271 - "tray_open": only present if removable, true if the device has a tray,
2272 and it is open (json-bool)
2273 - "inserted": only present if the device is inserted, it is a json-object
2274 containing the following:
2275 - "file": device file name (json-string)
2276 - "ro": true if read-only, false otherwise (json-bool)
2277 - "drv": driver format name (json-string)
2278 - Possible values: "blkdebug", "bochs", "cloop", "dmg",
2279 "file", "file", "ftp", "ftps", "host_cdrom",
2280 "host_device", "http", "https",
2281 "nbd", "parallels", "qcow", "qcow2", "raw",
2282 "tftp", "vdi", "vmdk", "vpc", "vvfat"
2283 - "backing_file": backing file name (json-string, optional)
2284 - "backing_file_depth": number of files in the backing file chain (json-int)
2285 - "encrypted": true if encrypted, false otherwise (json-bool)
2286 - "bps": limit total bytes per second (json-int)
2287 - "bps_rd": limit read bytes per second (json-int)
2288 - "bps_wr": limit write bytes per second (json-int)
2289 - "iops": limit total I/O operations per second (json-int)
2290 - "iops_rd": limit read operations per second (json-int)
2291 - "iops_wr": limit write operations per second (json-int)
2292 - "bps_max": total max in bytes (json-int)
2293 - "bps_rd_max": read max in bytes (json-int)
2294 - "bps_wr_max": write max in bytes (json-int)
2295 - "iops_max": total I/O operations max (json-int)
2296 - "iops_rd_max": read I/O operations max (json-int)
2297 - "iops_wr_max": write I/O operations max (json-int)
2298 - "iops_size": I/O size when limiting by iops (json-int)
2299 - "detect_zeroes": detect and optimize zero writing (json-string)
2300 - Possible values: "off", "on", "unmap"
2301 - "write_threshold": write offset threshold in bytes, a event will be
2302 emitted if crossed. Zero if disabled (json-int)
2303 - "image": the detail of the image, it is a json-object containing
2304 the following:
2305 - "filename": image file name (json-string)
2306 - "format": image format (json-string)
2307 - "virtual-size": image capacity in bytes (json-int)
2308 - "dirty-flag": true if image is not cleanly closed, not present
2309 means clean (json-bool, optional)
2310 - "actual-size": actual size on disk in bytes of the image, not
2311 present when image does not support thin
2312 provision (json-int, optional)
2313 - "cluster-size": size of a cluster in bytes, not present if image
2314 format does not support it (json-int, optional)
2315 - "encrypted": true if the image is encrypted, not present means
2316 false or the image format does not support
2317 encryption (json-bool, optional)
2318 - "backing_file": backing file name, not present means no backing
2319 file is used or the image format does not
2320 support backing file chain
2321 (json-string, optional)
2322 - "full-backing-filename": full path of the backing file, not
2323 present if it equals backing_file or no
2324 backing file is used
2325 (json-string, optional)
2326 - "backing-filename-format": the format of the backing file, not
2327 present means unknown or no backing
2328 file (json-string, optional)
2329 - "snapshots": the internal snapshot info, it is an optional list
2330 of json-object containing the following:
2331 - "id": unique snapshot id (json-string)
2332 - "name": snapshot name (json-string)
2333 - "vm-state-size": size of the VM state in bytes (json-int)
2334 - "date-sec": UTC date of the snapshot in seconds (json-int)
2335 - "date-nsec": fractional part in nanoseconds to be used with
2336 date-sec (json-int)
2337 - "vm-clock-sec": VM clock relative to boot in seconds
2338 (json-int)
2339 - "vm-clock-nsec": fractional part in nanoseconds to be used
2340 with vm-clock-sec (json-int)
2341 - "backing-image": the detail of the backing image, it is an
2342 optional json-object only present when a
2343 backing image present for this image
2345 - "io-status": I/O operation status, only present if the device supports it
2346 and the VM is configured to stop on errors. It's always reset
2347 to "ok" when the "cont" command is issued (json_string, optional)
2348 - Possible values: "ok", "failed", "nospace"
2350 Example:
2352 -> { "execute": "query-block" }
2353 <- {
2354 "return":[
2356 "io-status": "ok",
2357 "device":"ide0-hd0",
2358 "locked":false,
2359 "removable":false,
2360 "inserted":{
2361 "ro":false,
2362 "drv":"qcow2",
2363 "encrypted":false,
2364 "file":"disks/test.qcow2",
2365 "backing_file_depth":1,
2366 "bps":1000000,
2367 "bps_rd":0,
2368 "bps_wr":0,
2369 "iops":1000000,
2370 "iops_rd":0,
2371 "iops_wr":0,
2372 "bps_max": 8000000,
2373 "bps_rd_max": 0,
2374 "bps_wr_max": 0,
2375 "iops_max": 0,
2376 "iops_rd_max": 0,
2377 "iops_wr_max": 0,
2378 "iops_size": 0,
2379 "detect_zeroes": "on",
2380 "write_threshold": 0,
2381 "image":{
2382 "filename":"disks/test.qcow2",
2383 "format":"qcow2",
2384 "virtual-size":2048000,
2385 "backing_file":"base.qcow2",
2386 "full-backing-filename":"disks/base.qcow2",
2387 "backing-filename-format":"qcow2",
2388 "snapshots":[
2390 "id": "1",
2391 "name": "snapshot1",
2392 "vm-state-size": 0,
2393 "date-sec": 10000200,
2394 "date-nsec": 12,
2395 "vm-clock-sec": 206,
2396 "vm-clock-nsec": 30
2399 "backing-image":{
2400 "filename":"disks/base.qcow2",
2401 "format":"qcow2",
2402 "virtual-size":2048000
2406 "type":"unknown"
2409 "io-status": "ok",
2410 "device":"ide1-cd0",
2411 "locked":false,
2412 "removable":true,
2413 "type":"unknown"
2416 "device":"floppy0",
2417 "locked":false,
2418 "removable":true,
2419 "type":"unknown"
2422 "device":"sd0",
2423 "locked":false,
2424 "removable":true,
2425 "type":"unknown"
2430 EQMP
2433 .name = "query-block",
2434 .args_type = "",
2435 .mhandler.cmd_new = qmp_marshal_input_query_block,
2438 SQMP
2439 query-blockstats
2440 ----------------
2442 Show block device statistics.
2444 Each device statistic information is stored in a json-object and the returned
2445 value is a json-array of all devices.
2447 Each json-object contain the following:
2449 - "device": device name (json-string)
2450 - "stats": A json-object with the statistics information, it contains:
2451 - "rd_bytes": bytes read (json-int)
2452 - "wr_bytes": bytes written (json-int)
2453 - "rd_operations": read operations (json-int)
2454 - "wr_operations": write operations (json-int)
2455 - "flush_operations": cache flush operations (json-int)
2456 - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
2457 - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
2458 - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
2459 - "wr_highest_offset": Highest offset of a sector written since the
2460 BlockDriverState has been opened (json-int)
2461 - "rd_merged": number of read requests that have been merged into
2462 another request (json-int)
2463 - "wr_merged": number of write requests that have been merged into
2464 another request (json-int)
2465 - "parent": Contains recursively the statistics of the underlying
2466 protocol (e.g. the host file for a qcow2 image). If there is
2467 no underlying protocol, this field is omitted
2468 (json-object, optional)
2470 Example:
2472 -> { "execute": "query-blockstats" }
2473 <- {
2474 "return":[
2476 "device":"ide0-hd0",
2477 "parent":{
2478 "stats":{
2479 "wr_highest_offset":3686448128,
2480 "wr_bytes":9786368,
2481 "wr_operations":751,
2482 "rd_bytes":122567168,
2483 "rd_operations":36772
2484 "wr_total_times_ns":313253456
2485 "rd_total_times_ns":3465673657
2486 "flush_total_times_ns":49653
2487 "flush_operations":61,
2488 "rd_merged":0,
2489 "wr_merged":0
2492 "stats":{
2493 "wr_highest_offset":2821110784,
2494 "wr_bytes":9786368,
2495 "wr_operations":692,
2496 "rd_bytes":122739200,
2497 "rd_operations":36604
2498 "flush_operations":51,
2499 "wr_total_times_ns":313253456
2500 "rd_total_times_ns":3465673657
2501 "flush_total_times_ns":49653,
2502 "rd_merged":0,
2503 "wr_merged":0
2507 "device":"ide1-cd0",
2508 "stats":{
2509 "wr_highest_offset":0,
2510 "wr_bytes":0,
2511 "wr_operations":0,
2512 "rd_bytes":0,
2513 "rd_operations":0
2514 "flush_operations":0,
2515 "wr_total_times_ns":0
2516 "rd_total_times_ns":0
2517 "flush_total_times_ns":0,
2518 "rd_merged":0,
2519 "wr_merged":0
2523 "device":"floppy0",
2524 "stats":{
2525 "wr_highest_offset":0,
2526 "wr_bytes":0,
2527 "wr_operations":0,
2528 "rd_bytes":0,
2529 "rd_operations":0
2530 "flush_operations":0,
2531 "wr_total_times_ns":0
2532 "rd_total_times_ns":0
2533 "flush_total_times_ns":0,
2534 "rd_merged":0,
2535 "wr_merged":0
2539 "device":"sd0",
2540 "stats":{
2541 "wr_highest_offset":0,
2542 "wr_bytes":0,
2543 "wr_operations":0,
2544 "rd_bytes":0,
2545 "rd_operations":0
2546 "flush_operations":0,
2547 "wr_total_times_ns":0
2548 "rd_total_times_ns":0
2549 "flush_total_times_ns":0,
2550 "rd_merged":0,
2551 "wr_merged":0
2557 EQMP
2560 .name = "query-blockstats",
2561 .args_type = "query-nodes:b?",
2562 .mhandler.cmd_new = qmp_marshal_input_query_blockstats,
2565 SQMP
2566 query-cpus
2567 ----------
2569 Show CPU information.
2571 Return a json-array. Each CPU is represented by a json-object, which contains:
2573 - "CPU": CPU index (json-int)
2574 - "current": true if this is the current CPU, false otherwise (json-bool)
2575 - "halted": true if the cpu is halted, false otherwise (json-bool)
2576 - "qom_path": path to the CPU object in the QOM tree (json-str)
2577 - Current program counter. The key's name depends on the architecture:
2578 "pc": i386/x86_64 (json-int)
2579 "nip": PPC (json-int)
2580 "pc" and "npc": sparc (json-int)
2581 "PC": mips (json-int)
2582 - "thread_id": ID of the underlying host thread (json-int)
2584 Example:
2586 -> { "execute": "query-cpus" }
2587 <- {
2588 "return":[
2590 "CPU":0,
2591 "current":true,
2592 "halted":false,
2593 "qom_path":"/machine/unattached/device[0]",
2594 "pc":3227107138,
2595 "thread_id":3134
2598 "CPU":1,
2599 "current":false,
2600 "halted":true,
2601 "qom_path":"/machine/unattached/device[2]",
2602 "pc":7108165,
2603 "thread_id":3135
2608 EQMP
2611 .name = "query-cpus",
2612 .args_type = "",
2613 .mhandler.cmd_new = qmp_marshal_input_query_cpus,
2616 SQMP
2617 query-iothreads
2618 ---------------
2620 Returns a list of information about each iothread.
2622 Note this list excludes the QEMU main loop thread, which is not declared
2623 using the -object iothread command-line option. It is always the main thread
2624 of the process.
2626 Return a json-array. Each iothread is represented by a json-object, which contains:
2628 - "id": name of iothread (json-str)
2629 - "thread-id": ID of the underlying host thread (json-int)
2631 Example:
2633 -> { "execute": "query-iothreads" }
2634 <- {
2635 "return":[
2637 "id":"iothread0",
2638 "thread-id":3134
2641 "id":"iothread1",
2642 "thread-id":3135
2647 EQMP
2650 .name = "query-iothreads",
2651 .args_type = "",
2652 .mhandler.cmd_new = qmp_marshal_input_query_iothreads,
2655 SQMP
2656 query-pci
2657 ---------
2659 PCI buses and devices information.
2661 The returned value is a json-array of all buses. Each bus is represented by
2662 a json-object, which has a key with a json-array of all PCI devices attached
2663 to it. Each device is represented by a json-object.
2665 The bus json-object contains the following:
2667 - "bus": bus number (json-int)
2668 - "devices": a json-array of json-objects, each json-object represents a
2669 PCI device
2671 The PCI device json-object contains the following:
2673 - "bus": identical to the parent's bus number (json-int)
2674 - "slot": slot number (json-int)
2675 - "function": function number (json-int)
2676 - "class_info": a json-object containing:
2677 - "desc": device class description (json-string, optional)
2678 - "class": device class number (json-int)
2679 - "id": a json-object containing:
2680 - "device": device ID (json-int)
2681 - "vendor": vendor ID (json-int)
2682 - "irq": device's IRQ if assigned (json-int, optional)
2683 - "qdev_id": qdev id string (json-string)
2684 - "pci_bridge": It's a json-object, only present if this device is a
2685 PCI bridge, contains:
2686 - "bus": bus number (json-int)
2687 - "secondary": secondary bus number (json-int)
2688 - "subordinate": subordinate bus number (json-int)
2689 - "io_range": I/O memory range information, a json-object with the
2690 following members:
2691 - "base": base address, in bytes (json-int)
2692 - "limit": limit address, in bytes (json-int)
2693 - "memory_range": memory range information, a json-object with the
2694 following members:
2695 - "base": base address, in bytes (json-int)
2696 - "limit": limit address, in bytes (json-int)
2697 - "prefetchable_range": Prefetchable memory range information, a
2698 json-object with the following members:
2699 - "base": base address, in bytes (json-int)
2700 - "limit": limit address, in bytes (json-int)
2701 - "devices": a json-array of PCI devices if there's any attached, each
2702 each element is represented by a json-object, which contains
2703 the same members of the 'PCI device json-object' described
2704 above (optional)
2705 - "regions": a json-array of json-objects, each json-object represents a
2706 memory region of this device
2708 The memory range json-object contains the following:
2710 - "base": base memory address (json-int)
2711 - "limit": limit value (json-int)
2713 The region json-object can be an I/O region or a memory region, an I/O region
2714 json-object contains the following:
2716 - "type": "io" (json-string, fixed)
2717 - "bar": BAR number (json-int)
2718 - "address": memory address (json-int)
2719 - "size": memory size (json-int)
2721 A memory region json-object contains the following:
2723 - "type": "memory" (json-string, fixed)
2724 - "bar": BAR number (json-int)
2725 - "address": memory address (json-int)
2726 - "size": memory size (json-int)
2727 - "mem_type_64": true or false (json-bool)
2728 - "prefetch": true or false (json-bool)
2730 Example:
2732 -> { "execute": "query-pci" }
2733 <- {
2734 "return":[
2736 "bus":0,
2737 "devices":[
2739 "bus":0,
2740 "qdev_id":"",
2741 "slot":0,
2742 "class_info":{
2743 "class":1536,
2744 "desc":"Host bridge"
2746 "id":{
2747 "device":32902,
2748 "vendor":4663
2750 "function":0,
2751 "regions":[
2756 "bus":0,
2757 "qdev_id":"",
2758 "slot":1,
2759 "class_info":{
2760 "class":1537,
2761 "desc":"ISA bridge"
2763 "id":{
2764 "device":32902,
2765 "vendor":28672
2767 "function":0,
2768 "regions":[
2773 "bus":0,
2774 "qdev_id":"",
2775 "slot":1,
2776 "class_info":{
2777 "class":257,
2778 "desc":"IDE controller"
2780 "id":{
2781 "device":32902,
2782 "vendor":28688
2784 "function":1,
2785 "regions":[
2787 "bar":4,
2788 "size":16,
2789 "address":49152,
2790 "type":"io"
2795 "bus":0,
2796 "qdev_id":"",
2797 "slot":2,
2798 "class_info":{
2799 "class":768,
2800 "desc":"VGA controller"
2802 "id":{
2803 "device":4115,
2804 "vendor":184
2806 "function":0,
2807 "regions":[
2809 "prefetch":true,
2810 "mem_type_64":false,
2811 "bar":0,
2812 "size":33554432,
2813 "address":4026531840,
2814 "type":"memory"
2817 "prefetch":false,
2818 "mem_type_64":false,
2819 "bar":1,
2820 "size":4096,
2821 "address":4060086272,
2822 "type":"memory"
2825 "prefetch":false,
2826 "mem_type_64":false,
2827 "bar":6,
2828 "size":65536,
2829 "address":-1,
2830 "type":"memory"
2835 "bus":0,
2836 "qdev_id":"",
2837 "irq":11,
2838 "slot":4,
2839 "class_info":{
2840 "class":1280,
2841 "desc":"RAM controller"
2843 "id":{
2844 "device":6900,
2845 "vendor":4098
2847 "function":0,
2848 "regions":[
2850 "bar":0,
2851 "size":32,
2852 "address":49280,
2853 "type":"io"
2862 Note: This example has been shortened as the real response is too long.
2864 EQMP
2867 .name = "query-pci",
2868 .args_type = "",
2869 .mhandler.cmd_new = qmp_marshal_input_query_pci,
2872 SQMP
2873 query-kvm
2874 ---------
2876 Show KVM information.
2878 Return a json-object with the following information:
2880 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
2881 - "present": true if QEMU has KVM support, false otherwise (json-bool)
2883 Example:
2885 -> { "execute": "query-kvm" }
2886 <- { "return": { "enabled": true, "present": true } }
2888 EQMP
2891 .name = "query-kvm",
2892 .args_type = "",
2893 .mhandler.cmd_new = qmp_marshal_input_query_kvm,
2896 SQMP
2897 query-status
2898 ------------
2900 Return a json-object with the following information:
2902 - "running": true if the VM is running, or false if it is paused (json-bool)
2903 - "singlestep": true if the VM is in single step mode,
2904 false otherwise (json-bool)
2905 - "status": one of the following values (json-string)
2906 "debug" - QEMU is running on a debugger
2907 "inmigrate" - guest is paused waiting for an incoming migration
2908 "internal-error" - An internal error that prevents further guest
2909 execution has occurred
2910 "io-error" - the last IOP has failed and the device is configured
2911 to pause on I/O errors
2912 "paused" - guest has been paused via the 'stop' command
2913 "postmigrate" - guest is paused following a successful 'migrate'
2914 "prelaunch" - QEMU was started with -S and guest has not started
2915 "finish-migrate" - guest is paused to finish the migration process
2916 "restore-vm" - guest is paused to restore VM state
2917 "running" - guest is actively running
2918 "save-vm" - guest is paused to save the VM state
2919 "shutdown" - guest is shut down (and -no-shutdown is in use)
2920 "watchdog" - the watchdog action is configured to pause and
2921 has been triggered
2923 Example:
2925 -> { "execute": "query-status" }
2926 <- { "return": { "running": true, "singlestep": false, "status": "running" } }
2928 EQMP
2931 .name = "query-status",
2932 .args_type = "",
2933 .mhandler.cmd_new = qmp_marshal_input_query_status,
2936 SQMP
2937 query-mice
2938 ----------
2940 Show VM mice information.
2942 Each mouse is represented by a json-object, the returned value is a json-array
2943 of all mice.
2945 The mouse json-object contains the following:
2947 - "name": mouse's name (json-string)
2948 - "index": mouse's index (json-int)
2949 - "current": true if this mouse is receiving events, false otherwise (json-bool)
2950 - "absolute": true if the mouse generates absolute input events (json-bool)
2952 Example:
2954 -> { "execute": "query-mice" }
2955 <- {
2956 "return":[
2958 "name":"QEMU Microsoft Mouse",
2959 "index":0,
2960 "current":false,
2961 "absolute":false
2964 "name":"QEMU PS/2 Mouse",
2965 "index":1,
2966 "current":true,
2967 "absolute":true
2972 EQMP
2975 .name = "query-mice",
2976 .args_type = "",
2977 .mhandler.cmd_new = qmp_marshal_input_query_mice,
2980 SQMP
2981 query-vnc
2982 ---------
2984 Show VNC server information.
2986 Return a json-object with server information. Connected clients are returned
2987 as a json-array of json-objects.
2989 The main json-object contains the following:
2991 - "enabled": true or false (json-bool)
2992 - "host": server's IP address (json-string)
2993 - "family": address family (json-string)
2994 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2995 - "service": server's port number (json-string)
2996 - "auth": authentication method (json-string)
2997 - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2998 "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2999 "vencrypt+plain", "vencrypt+tls+none",
3000 "vencrypt+tls+plain", "vencrypt+tls+sasl",
3001 "vencrypt+tls+vnc", "vencrypt+x509+none",
3002 "vencrypt+x509+plain", "vencrypt+x509+sasl",
3003 "vencrypt+x509+vnc", "vnc"
3004 - "clients": a json-array of all connected clients
3006 Clients are described by a json-object, each one contain the following:
3008 - "host": client's IP address (json-string)
3009 - "family": address family (json-string)
3010 - Possible values: "ipv4", "ipv6", "unix", "unknown"
3011 - "service": client's port number (json-string)
3012 - "x509_dname": TLS dname (json-string, optional)
3013 - "sasl_username": SASL username (json-string, optional)
3015 Example:
3017 -> { "execute": "query-vnc" }
3018 <- {
3019 "return":{
3020 "enabled":true,
3021 "host":"0.0.0.0",
3022 "service":"50402",
3023 "auth":"vnc",
3024 "family":"ipv4",
3025 "clients":[
3027 "host":"127.0.0.1",
3028 "service":"50401",
3029 "family":"ipv4"
3035 EQMP
3038 .name = "query-vnc",
3039 .args_type = "",
3040 .mhandler.cmd_new = qmp_marshal_input_query_vnc,
3043 .name = "query-vnc-servers",
3044 .args_type = "",
3045 .mhandler.cmd_new = qmp_marshal_input_query_vnc_servers,
3048 SQMP
3049 query-spice
3050 -----------
3052 Show SPICE server information.
3054 Return a json-object with server information. Connected clients are returned
3055 as a json-array of json-objects.
3057 The main json-object contains the following:
3059 - "enabled": true or false (json-bool)
3060 - "host": server's IP address (json-string)
3061 - "port": server's port number (json-int, optional)
3062 - "tls-port": server's port number (json-int, optional)
3063 - "auth": authentication method (json-string)
3064 - Possible values: "none", "spice"
3065 - "channels": a json-array of all active channels clients
3067 Channels are described by a json-object, each one contain the following:
3069 - "host": client's IP address (json-string)
3070 - "family": address family (json-string)
3071 - Possible values: "ipv4", "ipv6", "unix", "unknown"
3072 - "port": client's port number (json-string)
3073 - "connection-id": spice connection id. All channels with the same id
3074 belong to the same spice session (json-int)
3075 - "channel-type": channel type. "1" is the main control channel, filter for
3076 this one if you want track spice sessions only (json-int)
3077 - "channel-id": channel id. Usually "0", might be different needed when
3078 multiple channels of the same type exist, such as multiple
3079 display channels in a multihead setup (json-int)
3080 - "tls": whether the channel is encrypted (json-bool)
3082 Example:
3084 -> { "execute": "query-spice" }
3085 <- {
3086 "return": {
3087 "enabled": true,
3088 "auth": "spice",
3089 "port": 5920,
3090 "tls-port": 5921,
3091 "host": "0.0.0.0",
3092 "channels": [
3094 "port": "54924",
3095 "family": "ipv4",
3096 "channel-type": 1,
3097 "connection-id": 1804289383,
3098 "host": "127.0.0.1",
3099 "channel-id": 0,
3100 "tls": true
3103 "port": "36710",
3104 "family": "ipv4",
3105 "channel-type": 4,
3106 "connection-id": 1804289383,
3107 "host": "127.0.0.1",
3108 "channel-id": 0,
3109 "tls": false
3111 [ ... more channels follow ... ]
3116 EQMP
3118 #if defined(CONFIG_SPICE)
3120 .name = "query-spice",
3121 .args_type = "",
3122 .mhandler.cmd_new = qmp_marshal_input_query_spice,
3124 #endif
3126 SQMP
3127 query-name
3128 ----------
3130 Show VM name.
3132 Return a json-object with the following information:
3134 - "name": VM's name (json-string, optional)
3136 Example:
3138 -> { "execute": "query-name" }
3139 <- { "return": { "name": "qemu-name" } }
3141 EQMP
3144 .name = "query-name",
3145 .args_type = "",
3146 .mhandler.cmd_new = qmp_marshal_input_query_name,
3149 SQMP
3150 query-uuid
3151 ----------
3153 Show VM UUID.
3155 Return a json-object with the following information:
3157 - "UUID": Universally Unique Identifier (json-string)
3159 Example:
3161 -> { "execute": "query-uuid" }
3162 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
3164 EQMP
3167 .name = "query-uuid",
3168 .args_type = "",
3169 .mhandler.cmd_new = qmp_marshal_input_query_uuid,
3172 SQMP
3173 query-command-line-options
3174 --------------------------
3176 Show command line option schema.
3178 Return a json-array of command line option schema for all options (or for
3179 the given option), returning an error if the given option doesn't exist.
3181 Each array entry contains the following:
3183 - "option": option name (json-string)
3184 - "parameters": a json-array describes all parameters of the option:
3185 - "name": parameter name (json-string)
3186 - "type": parameter type (one of 'string', 'boolean', 'number',
3187 or 'size')
3188 - "help": human readable description of the parameter
3189 (json-string, optional)
3190 - "default": default value string for the parameter
3191 (json-string, optional)
3193 Example:
3195 -> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } }
3196 <- { "return": [
3198 "parameters": [
3200 "name": "romfile",
3201 "type": "string"
3204 "name": "bootindex",
3205 "type": "number"
3208 "option": "option-rom"
3213 EQMP
3216 .name = "query-command-line-options",
3217 .args_type = "option:s?",
3218 .mhandler.cmd_new = qmp_marshal_input_query_command_line_options,
3221 SQMP
3222 query-migrate
3223 -------------
3225 Migration status.
3227 Return a json-object. If migration is active there will be another json-object
3228 with RAM migration status and if block migration is active another one with
3229 block migration status.
3231 The main json-object contains the following:
3233 - "status": migration status (json-string)
3234 - Possible values: "setup", "active", "completed", "failed", "cancelled"
3235 - "total-time": total amount of ms since migration started. If
3236 migration has ended, it returns the total migration
3237 time (json-int)
3238 - "setup-time" amount of setup time in milliseconds _before_ the
3239 iterations begin but _after_ the QMP command is issued.
3240 This is designed to provide an accounting of any activities
3241 (such as RDMA pinning) which may be expensive, but do not
3242 actually occur during the iterative migration rounds
3243 themselves. (json-int)
3244 - "downtime": only present when migration has finished correctly
3245 total amount in ms for downtime that happened (json-int)
3246 - "expected-downtime": only present while migration is active
3247 total amount in ms for downtime that was calculated on
3248 the last bitmap round (json-int)
3249 - "ram": only present if "status" is "active", it is a json-object with the
3250 following RAM information:
3251 - "transferred": amount transferred in bytes (json-int)
3252 - "remaining": amount remaining to transfer in bytes (json-int)
3253 - "total": total amount of memory in bytes (json-int)
3254 - "duplicate": number of pages filled entirely with the same
3255 byte (json-int)
3256 These are sent over the wire much more efficiently.
3257 - "skipped": number of skipped zero pages (json-int)
3258 - "normal" : number of whole pages transferred. I.e. they
3259 were not sent as duplicate or xbzrle pages (json-int)
3260 - "normal-bytes" : number of bytes transferred in whole
3261 pages. This is just normal pages times size of one page,
3262 but this way upper levels don't need to care about page
3263 size (json-int)
3264 - "dirty-sync-count": times that dirty ram was synchronized (json-int)
3265 - "disk": only present if "status" is "active" and it is a block migration,
3266 it is a json-object with the following disk information:
3267 - "transferred": amount transferred in bytes (json-int)
3268 - "remaining": amount remaining to transfer in bytes json-int)
3269 - "total": total disk size in bytes (json-int)
3270 - "xbzrle-cache": only present if XBZRLE is active.
3271 It is a json-object with the following XBZRLE information:
3272 - "cache-size": XBZRLE cache size in bytes
3273 - "bytes": number of bytes transferred for XBZRLE compressed pages
3274 - "pages": number of XBZRLE compressed pages
3275 - "cache-miss": number of XBRZRLE page cache misses
3276 - "cache-miss-rate": rate of XBRZRLE page cache misses
3277 - "overflow": number of times XBZRLE overflows. This means
3278 that the XBZRLE encoding was bigger than just sent the
3279 whole page, and then we sent the whole page instead (as as
3280 normal page).
3282 Examples:
3284 1. Before the first migration
3286 -> { "execute": "query-migrate" }
3287 <- { "return": {} }
3289 2. Migration is done and has succeeded
3291 -> { "execute": "query-migrate" }
3292 <- { "return": {
3293 "status": "completed",
3294 "ram":{
3295 "transferred":123,
3296 "remaining":123,
3297 "total":246,
3298 "total-time":12345,
3299 "setup-time":12345,
3300 "downtime":12345,
3301 "duplicate":123,
3302 "normal":123,
3303 "normal-bytes":123456,
3304 "dirty-sync-count":15
3309 3. Migration is done and has failed
3311 -> { "execute": "query-migrate" }
3312 <- { "return": { "status": "failed" } }
3314 4. Migration is being performed and is not a block migration:
3316 -> { "execute": "query-migrate" }
3317 <- {
3318 "return":{
3319 "status":"active",
3320 "ram":{
3321 "transferred":123,
3322 "remaining":123,
3323 "total":246,
3324 "total-time":12345,
3325 "setup-time":12345,
3326 "expected-downtime":12345,
3327 "duplicate":123,
3328 "normal":123,
3329 "normal-bytes":123456,
3330 "dirty-sync-count":15
3335 5. Migration is being performed and is a block migration:
3337 -> { "execute": "query-migrate" }
3338 <- {
3339 "return":{
3340 "status":"active",
3341 "ram":{
3342 "total":1057024,
3343 "remaining":1053304,
3344 "transferred":3720,
3345 "total-time":12345,
3346 "setup-time":12345,
3347 "expected-downtime":12345,
3348 "duplicate":123,
3349 "normal":123,
3350 "normal-bytes":123456,
3351 "dirty-sync-count":15
3353 "disk":{
3354 "total":20971520,
3355 "remaining":20880384,
3356 "transferred":91136
3361 6. Migration is being performed and XBZRLE is active:
3363 -> { "execute": "query-migrate" }
3364 <- {
3365 "return":{
3366 "status":"active",
3367 "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
3368 "ram":{
3369 "total":1057024,
3370 "remaining":1053304,
3371 "transferred":3720,
3372 "total-time":12345,
3373 "setup-time":12345,
3374 "expected-downtime":12345,
3375 "duplicate":10,
3376 "normal":3333,
3377 "normal-bytes":3412992,
3378 "dirty-sync-count":15
3380 "xbzrle-cache":{
3381 "cache-size":67108864,
3382 "bytes":20971520,
3383 "pages":2444343,
3384 "cache-miss":2244,
3385 "cache-miss-rate":0.123,
3386 "overflow":34434
3391 EQMP
3394 .name = "query-migrate",
3395 .args_type = "",
3396 .mhandler.cmd_new = qmp_marshal_input_query_migrate,
3399 SQMP
3400 migrate-set-capabilities
3401 ------------------------
3403 Enable/Disable migration capabilities
3405 - "xbzrle": XBZRLE support
3406 - "rdma-pin-all": pin all pages when using RDMA during migration
3407 - "auto-converge": throttle down guest to help convergence of migration
3408 - "zero-blocks": compress zero blocks during block migration
3409 - "events": generate events for each migration state change
3411 Arguments:
3413 Example:
3415 -> { "execute": "migrate-set-capabilities" , "arguments":
3416 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
3418 EQMP
3421 .name = "migrate-set-capabilities",
3422 .args_type = "capabilities:q",
3423 .params = "capability:s,state:b",
3424 .mhandler.cmd_new = qmp_marshal_input_migrate_set_capabilities,
3426 SQMP
3427 query-migrate-capabilities
3428 --------------------------
3430 Query current migration capabilities
3432 - "capabilities": migration capabilities state
3433 - "xbzrle" : XBZRLE state (json-bool)
3434 - "rdma-pin-all" : RDMA Pin Page state (json-bool)
3435 - "auto-converge" : Auto Converge state (json-bool)
3436 - "zero-blocks" : Zero Blocks state (json-bool)
3438 Arguments:
3440 Example:
3442 -> { "execute": "query-migrate-capabilities" }
3443 <- { "return": [ { "state": false, "capability": "xbzrle" } ] }
3445 EQMP
3448 .name = "query-migrate-capabilities",
3449 .args_type = "",
3450 .mhandler.cmd_new = qmp_marshal_input_query_migrate_capabilities,
3453 SQMP
3454 migrate-set-parameters
3455 ----------------------
3457 Set migration parameters
3459 - "compress-level": set compression level during migration (json-int)
3460 - "compress-threads": set compression thread count for migration (json-int)
3461 - "decompress-threads": set decompression thread count for migration (json-int)
3463 Arguments:
3465 Example:
3467 -> { "execute": "migrate-set-parameters" , "arguments":
3468 { "compress-level": 1 } }
3470 EQMP
3473 .name = "migrate-set-parameters",
3474 .args_type =
3475 "compress-level:i?,compress-threads:i?,decompress-threads:i?",
3476 .mhandler.cmd_new = qmp_marshal_input_migrate_set_parameters,
3478 SQMP
3479 query-migrate-parameters
3480 ------------------------
3482 Query current migration parameters
3484 - "parameters": migration parameters value
3485 - "compress-level" : compression level value (json-int)
3486 - "compress-threads" : compression thread count value (json-int)
3487 - "decompress-threads" : decompression thread count value (json-int)
3489 Arguments:
3491 Example:
3493 -> { "execute": "query-migrate-parameters" }
3494 <- {
3495 "return": {
3496 "decompress-threads", 2,
3497 "compress-threads", 8,
3498 "compress-level", 1
3502 EQMP
3505 .name = "query-migrate-parameters",
3506 .args_type = "",
3507 .mhandler.cmd_new = qmp_marshal_input_query_migrate_parameters,
3510 SQMP
3511 query-balloon
3512 -------------
3514 Show balloon information.
3516 Make an asynchronous request for balloon info. When the request completes a
3517 json-object will be returned containing the following data:
3519 - "actual": current balloon value in bytes (json-int)
3521 Example:
3523 -> { "execute": "query-balloon" }
3524 <- {
3525 "return":{
3526 "actual":1073741824,
3530 EQMP
3533 .name = "query-balloon",
3534 .args_type = "",
3535 .mhandler.cmd_new = qmp_marshal_input_query_balloon,
3539 .name = "query-block-jobs",
3540 .args_type = "",
3541 .mhandler.cmd_new = qmp_marshal_input_query_block_jobs,
3545 .name = "qom-list",
3546 .args_type = "path:s",
3547 .mhandler.cmd_new = qmp_marshal_input_qom_list,
3551 .name = "qom-set",
3552 .args_type = "path:s,property:s,value:q",
3553 .mhandler.cmd_new = qmp_qom_set,
3557 .name = "qom-get",
3558 .args_type = "path:s,property:s",
3559 .mhandler.cmd_new = qmp_qom_get,
3563 .name = "nbd-server-start",
3564 .args_type = "addr:q",
3565 .mhandler.cmd_new = qmp_marshal_input_nbd_server_start,
3568 .name = "nbd-server-add",
3569 .args_type = "device:B,writable:b?",
3570 .mhandler.cmd_new = qmp_marshal_input_nbd_server_add,
3573 .name = "nbd-server-stop",
3574 .args_type = "",
3575 .mhandler.cmd_new = qmp_marshal_input_nbd_server_stop,
3579 .name = "change-vnc-password",
3580 .args_type = "password:s",
3581 .mhandler.cmd_new = qmp_marshal_input_change_vnc_password,
3584 .name = "qom-list-types",
3585 .args_type = "implements:s?,abstract:b?",
3586 .mhandler.cmd_new = qmp_marshal_input_qom_list_types,
3590 .name = "device-list-properties",
3591 .args_type = "typename:s",
3592 .mhandler.cmd_new = qmp_marshal_input_device_list_properties,
3596 .name = "query-machines",
3597 .args_type = "",
3598 .mhandler.cmd_new = qmp_marshal_input_query_machines,
3602 .name = "query-cpu-definitions",
3603 .args_type = "",
3604 .mhandler.cmd_new = qmp_marshal_input_query_cpu_definitions,
3608 .name = "query-target",
3609 .args_type = "",
3610 .mhandler.cmd_new = qmp_marshal_input_query_target,
3614 .name = "query-tpm",
3615 .args_type = "",
3616 .mhandler.cmd_new = qmp_marshal_input_query_tpm,
3619 SQMP
3620 query-tpm
3621 ---------
3623 Return information about the TPM device.
3625 Arguments: None
3627 Example:
3629 -> { "execute": "query-tpm" }
3630 <- { "return":
3632 { "model": "tpm-tis",
3633 "options":
3634 { "type": "passthrough",
3635 "data":
3636 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
3637 "path": "/dev/tpm0"
3640 "id": "tpm0"
3645 EQMP
3648 .name = "query-tpm-models",
3649 .args_type = "",
3650 .mhandler.cmd_new = qmp_marshal_input_query_tpm_models,
3653 SQMP
3654 query-tpm-models
3655 ----------------
3657 Return a list of supported TPM models.
3659 Arguments: None
3661 Example:
3663 -> { "execute": "query-tpm-models" }
3664 <- { "return": [ "tpm-tis" ] }
3666 EQMP
3669 .name = "query-tpm-types",
3670 .args_type = "",
3671 .mhandler.cmd_new = qmp_marshal_input_query_tpm_types,
3674 SQMP
3675 query-tpm-types
3676 ---------------
3678 Return a list of supported TPM types.
3680 Arguments: None
3682 Example:
3684 -> { "execute": "query-tpm-types" }
3685 <- { "return": [ "passthrough" ] }
3687 EQMP
3690 .name = "chardev-add",
3691 .args_type = "id:s,backend:q",
3692 .mhandler.cmd_new = qmp_marshal_input_chardev_add,
3695 SQMP
3696 chardev-add
3697 ----------------
3699 Add a chardev.
3701 Arguments:
3703 - "id": the chardev's ID, must be unique (json-string)
3704 - "backend": chardev backend type + parameters
3706 Examples:
3708 -> { "execute" : "chardev-add",
3709 "arguments" : { "id" : "foo",
3710 "backend" : { "type" : "null", "data" : {} } } }
3711 <- { "return": {} }
3713 -> { "execute" : "chardev-add",
3714 "arguments" : { "id" : "bar",
3715 "backend" : { "type" : "file",
3716 "data" : { "out" : "/tmp/bar.log" } } } }
3717 <- { "return": {} }
3719 -> { "execute" : "chardev-add",
3720 "arguments" : { "id" : "baz",
3721 "backend" : { "type" : "pty", "data" : {} } } }
3722 <- { "return": { "pty" : "/dev/pty/42" } }
3724 EQMP
3727 .name = "chardev-remove",
3728 .args_type = "id:s",
3729 .mhandler.cmd_new = qmp_marshal_input_chardev_remove,
3733 SQMP
3734 chardev-remove
3735 --------------
3737 Remove a chardev.
3739 Arguments:
3741 - "id": the chardev's ID, must exist and not be in use (json-string)
3743 Example:
3745 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
3746 <- { "return": {} }
3748 EQMP
3750 .name = "query-rx-filter",
3751 .args_type = "name:s?",
3752 .mhandler.cmd_new = qmp_marshal_input_query_rx_filter,
3755 SQMP
3756 query-rx-filter
3757 ---------------
3759 Show rx-filter information.
3761 Returns a json-array of rx-filter information for all NICs (or for the
3762 given NIC), returning an error if the given NIC doesn't exist, or
3763 given NIC doesn't support rx-filter querying, or given net client
3764 isn't a NIC.
3766 The query will clear the event notification flag of each NIC, then qemu
3767 will start to emit event to QMP monitor.
3769 Each array entry contains the following:
3771 - "name": net client name (json-string)
3772 - "promiscuous": promiscuous mode is enabled (json-bool)
3773 - "multicast": multicast receive state (one of 'normal', 'none', 'all')
3774 - "unicast": unicast receive state (one of 'normal', 'none', 'all')
3775 - "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0)
3776 - "broadcast-allowed": allow to receive broadcast (json-bool)
3777 - "multicast-overflow": multicast table is overflowed (json-bool)
3778 - "unicast-overflow": unicast table is overflowed (json-bool)
3779 - "main-mac": main macaddr string (json-string)
3780 - "vlan-table": a json-array of active vlan id
3781 - "unicast-table": a json-array of unicast macaddr string
3782 - "multicast-table": a json-array of multicast macaddr string
3784 Example:
3786 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
3787 <- { "return": [
3789 "promiscuous": true,
3790 "name": "vnet0",
3791 "main-mac": "52:54:00:12:34:56",
3792 "unicast": "normal",
3793 "vlan": "normal",
3794 "vlan-table": [
3798 "unicast-table": [
3800 "multicast": "normal",
3801 "multicast-overflow": false,
3802 "unicast-overflow": false,
3803 "multicast-table": [
3804 "01:00:5e:00:00:01",
3805 "33:33:00:00:00:01",
3806 "33:33:ff:12:34:56"
3808 "broadcast-allowed": false
3813 EQMP
3816 .name = "blockdev-add",
3817 .args_type = "options:q",
3818 .mhandler.cmd_new = qmp_marshal_input_blockdev_add,
3821 SQMP
3822 blockdev-add
3823 ------------
3825 Add a block device.
3827 This command is still a work in progress. It doesn't support all
3828 block drivers, it lacks a matching blockdev-del, and more. Stay away
3829 from it unless you want to help with its development.
3831 Arguments:
3833 - "options": block driver options
3835 Example (1):
3837 -> { "execute": "blockdev-add",
3838 "arguments": { "options" : { "driver": "qcow2",
3839 "file": { "driver": "file",
3840 "filename": "test.qcow2" } } } }
3841 <- { "return": {} }
3843 Example (2):
3845 -> { "execute": "blockdev-add",
3846 "arguments": {
3847 "options": {
3848 "driver": "qcow2",
3849 "id": "my_disk",
3850 "discard": "unmap",
3851 "cache": {
3852 "direct": true,
3853 "writeback": true
3855 "file": {
3856 "driver": "file",
3857 "filename": "/tmp/test.qcow2"
3859 "backing": {
3860 "driver": "raw",
3861 "file": {
3862 "driver": "file",
3863 "filename": "/dev/fdset/4"
3870 <- { "return": {} }
3872 EQMP
3875 .name = "query-named-block-nodes",
3876 .args_type = "",
3877 .mhandler.cmd_new = qmp_marshal_input_query_named_block_nodes,
3880 SQMP
3881 @query-named-block-nodes
3882 ------------------------
3884 Return a list of BlockDeviceInfo for all the named block driver nodes
3886 Example:
3888 -> { "execute": "query-named-block-nodes" }
3889 <- { "return": [ { "ro":false,
3890 "drv":"qcow2",
3891 "encrypted":false,
3892 "file":"disks/test.qcow2",
3893 "node-name": "my-node",
3894 "backing_file_depth":1,
3895 "bps":1000000,
3896 "bps_rd":0,
3897 "bps_wr":0,
3898 "iops":1000000,
3899 "iops_rd":0,
3900 "iops_wr":0,
3901 "bps_max": 8000000,
3902 "bps_rd_max": 0,
3903 "bps_wr_max": 0,
3904 "iops_max": 0,
3905 "iops_rd_max": 0,
3906 "iops_wr_max": 0,
3907 "iops_size": 0,
3908 "write_threshold": 0,
3909 "image":{
3910 "filename":"disks/test.qcow2",
3911 "format":"qcow2",
3912 "virtual-size":2048000,
3913 "backing_file":"base.qcow2",
3914 "full-backing-filename":"disks/base.qcow2",
3915 "backing-filename-format":"qcow2",
3916 "snapshots":[
3918 "id": "1",
3919 "name": "snapshot1",
3920 "vm-state-size": 0,
3921 "date-sec": 10000200,
3922 "date-nsec": 12,
3923 "vm-clock-sec": 206,
3924 "vm-clock-nsec": 30
3927 "backing-image":{
3928 "filename":"disks/base.qcow2",
3929 "format":"qcow2",
3930 "virtual-size":2048000
3932 } } ] }
3934 EQMP
3937 .name = "query-memdev",
3938 .args_type = "",
3939 .mhandler.cmd_new = qmp_marshal_input_query_memdev,
3942 SQMP
3943 query-memdev
3944 ------------
3946 Show memory devices information.
3949 Example (1):
3951 -> { "execute": "query-memdev" }
3952 <- { "return": [
3954 "size": 536870912,
3955 "merge": false,
3956 "dump": true,
3957 "prealloc": false,
3958 "host-nodes": [0, 1],
3959 "policy": "bind"
3962 "size": 536870912,
3963 "merge": false,
3964 "dump": true,
3965 "prealloc": true,
3966 "host-nodes": [2, 3],
3967 "policy": "preferred"
3972 EQMP
3975 .name = "query-memory-devices",
3976 .args_type = "",
3977 .mhandler.cmd_new = qmp_marshal_input_query_memory_devices,
3980 SQMP
3981 @query-memory-devices
3982 --------------------
3984 Return a list of memory devices.
3986 Example:
3987 -> { "execute": "query-memory-devices" }
3988 <- { "return": [ { "data":
3989 { "addr": 5368709120,
3990 "hotpluggable": true,
3991 "hotplugged": true,
3992 "id": "d1",
3993 "memdev": "/objects/memX",
3994 "node": 0,
3995 "size": 1073741824,
3996 "slot": 0},
3997 "type": "dimm"
3998 } ] }
3999 EQMP
4002 .name = "query-acpi-ospm-status",
4003 .args_type = "",
4004 .mhandler.cmd_new = qmp_marshal_input_query_acpi_ospm_status,
4007 SQMP
4008 @query-acpi-ospm-status
4009 --------------------
4011 Return list of ACPIOSTInfo for devices that support status reporting
4012 via ACPI _OST method.
4014 Example:
4015 -> { "execute": "query-acpi-ospm-status" }
4016 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
4017 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
4018 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
4019 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
4021 EQMP
4023 #if defined TARGET_I386
4025 .name = "rtc-reset-reinjection",
4026 .args_type = "",
4027 .mhandler.cmd_new = qmp_marshal_input_rtc_reset_reinjection,
4029 #endif
4031 SQMP
4032 rtc-reset-reinjection
4033 ---------------------
4035 Reset the RTC interrupt reinjection backlog.
4037 Arguments: None.
4039 Example:
4041 -> { "execute": "rtc-reset-reinjection" }
4042 <- { "return": {} }
4043 EQMP
4046 .name = "trace-event-get-state",
4047 .args_type = "name:s",
4048 .mhandler.cmd_new = qmp_marshal_input_trace_event_get_state,
4051 SQMP
4052 trace-event-get-state
4053 ---------------------
4055 Query the state of events.
4057 Example:
4059 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
4060 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
4061 EQMP
4064 .name = "trace-event-set-state",
4065 .args_type = "name:s,enable:b,ignore-unavailable:b?",
4066 .mhandler.cmd_new = qmp_marshal_input_trace_event_set_state,
4069 SQMP
4070 trace-event-set-state
4071 ---------------------
4073 Set the state of events.
4075 Example:
4077 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
4078 <- { "return": {} }
4079 EQMP
4082 .name = "x-input-send-event",
4083 .args_type = "console:i?,events:q",
4084 .mhandler.cmd_new = qmp_marshal_input_x_input_send_event,
4087 SQMP
4088 @x-input-send-event
4089 -----------------
4091 Send input event to guest.
4093 Arguments:
4095 - "console": console index. (json-int, optional)
4096 - "events": list of input events.
4098 The consoles are visible in the qom tree, under
4099 /backend/console[$index]. They have a device link and head property, so
4100 it is possible to map which console belongs to which device and display.
4102 Note: this command is experimental, and not a stable API.
4104 Example (1):
4106 Press left mouse button.
4108 -> { "execute": "x-input-send-event",
4109 "arguments": { "console": 0,
4110 "events": [ { "type": "btn",
4111 "data" : { "down": true, "button": "Left" } } ] } }
4112 <- { "return": {} }
4114 -> { "execute": "x-input-send-event",
4115 "arguments": { "console": 0,
4116 "events": [ { "type": "btn",
4117 "data" : { "down": false, "button": "Left" } } ] } }
4118 <- { "return": {} }
4120 Example (2):
4122 Press ctrl-alt-del.
4124 -> { "execute": "x-input-send-event",
4125 "arguments": { "console": 0, "events": [
4126 { "type": "key", "data" : { "down": true,
4127 "key": {"type": "qcode", "data": "ctrl" } } },
4128 { "type": "key", "data" : { "down": true,
4129 "key": {"type": "qcode", "data": "alt" } } },
4130 { "type": "key", "data" : { "down": true,
4131 "key": {"type": "qcode", "data": "delete" } } } ] } }
4132 <- { "return": {} }
4134 Example (3):
4136 Move mouse pointer to absolute coordinates (20000, 400).
4138 -> { "execute": "x-input-send-event" ,
4139 "arguments": { "console": 0, "events": [
4140 { "type": "abs", "data" : { "axis": "X", "value" : 20000 } },
4141 { "type": "abs", "data" : { "axis": "Y", "value" : 400 } } ] } }
4142 <- { "return": {} }
4144 EQMP
4147 .name = "block-set-write-threshold",
4148 .args_type = "node-name:s,write-threshold:l",
4149 .mhandler.cmd_new = qmp_marshal_input_block_set_write_threshold,
4152 SQMP
4153 block-set-write-threshold
4154 ------------
4156 Change the write threshold for a block drive. The threshold is an offset,
4157 thus must be non-negative. Default is no write threshold.
4158 Setting the threshold to zero disables it.
4160 Arguments:
4162 - "node-name": the node name in the block driver state graph (json-string)
4163 - "write-threshold": the write threshold in bytes (json-int)
4165 Example:
4167 -> { "execute": "block-set-write-threshold",
4168 "arguments": { "node-name": "mydev",
4169 "write-threshold": 17179869184 } }
4170 <- { "return": {} }
4172 EQMP
4175 .name = "query-rocker",
4176 .args_type = "name:s",
4177 .mhandler.cmd_new = qmp_marshal_input_query_rocker,
4180 SQMP
4181 Show rocker switch
4182 ------------------
4184 Arguments:
4186 - "name": switch name
4188 Example:
4190 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
4191 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
4193 EQMP
4196 .name = "query-rocker-ports",
4197 .args_type = "name:s",
4198 .mhandler.cmd_new = qmp_marshal_input_query_rocker_ports,
4201 SQMP
4202 Show rocker switch ports
4203 ------------------------
4205 Arguments:
4207 - "name": switch name
4209 Example:
4211 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
4212 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
4213 "autoneg": "off", "link-up": true, "speed": 10000},
4214 {"duplex": "full", "enabled": true, "name": "sw1.2",
4215 "autoneg": "off", "link-up": true, "speed": 10000}
4218 EQMP
4221 .name = "query-rocker-of-dpa-flows",
4222 .args_type = "name:s,tbl-id:i?",
4223 .mhandler.cmd_new = qmp_marshal_input_query_rocker_of_dpa_flows,
4226 SQMP
4227 Show rocker switch OF-DPA flow tables
4228 -------------------------------------
4230 Arguments:
4232 - "name": switch name
4233 - "tbl-id": (optional) flow table ID
4235 Example:
4237 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
4238 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
4239 "hits": 138,
4240 "cookie": 0,
4241 "action": {"goto-tbl": 10},
4242 "mask": {"in-pport": 4294901760}
4244 {...more...},
4247 EQMP
4250 .name = "query-rocker-of-dpa-groups",
4251 .args_type = "name:s,type:i?",
4252 .mhandler.cmd_new = qmp_marshal_input_query_rocker_of_dpa_groups,
4255 SQMP
4256 Show rocker OF-DPA group tables
4257 -------------------------------
4259 Arguments:
4261 - "name": switch name
4262 - "type": (optional) group type
4264 Example:
4266 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
4267 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
4268 "pop-vlan": 1, "id": 251723778},
4269 {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
4270 "pop-vlan": 1, "id": 251723776},
4271 {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
4272 "pop-vlan": 1, "id": 251658241},
4273 {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
4274 "pop-vlan": 1, "id": 251658240}