json-lexer: Initialize 'x' and 'y'
[qemu/mdroth.git] / qemu-monitor.hx
blobf6a94f2b8383288ef219cc4e4d6163e3f8c815d7
1 HXCOMM Use DEFHEADING() to define headings in both help text and texi
2 HXCOMM Text between STEXI and ETEXI are copied to texi version and
3 HXCOMM discarded from C version
4 HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and
5 HXCOMM does not show up in the other formats.
6 HXCOMM DEF(command, args, callback, arg_string, help) is used to construct
7 HXCOMM monitor commands
8 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
10 SQMP
11 QMP Supported Commands
12 ----------------------
14 This document describes all commands currently supported by QMP.
16 Most of the time their usage is exactly the same as in the user Monitor, this
17 means that any other document which also describe commands (the manpage,
18 QEMU's manual, etc) can and should be consulted.
20 QMP has two types of commands: regular and query commands. Regular commands
21 usually change the Virtual Machine's state someway, while query commands just
22 return information. The sections below are divided accordingly.
24 It's important to observe that all communication examples are formatted in
25 a reader-friendly way, so that they're easier to understand. However, in real
26 protocol usage, they're emitted as a single line.
28 Also, the following notation is used to denote data flow:
30 -> data issued by the Client
31 <- Server data response
33 Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
34 information on the Server command and response formats.
36 NOTE: This document is temporary and will be replaced soon.
38 1. Regular Commands
39 ===================
41 Server's responses in the examples below are always a success response, please
42 refer to the QMP specification for more details on error responses.
44 EQMP
46 STEXI
47 @table @option
48 ETEXI
51 .name = "help|?",
52 .args_type = "name:s?",
53 .params = "[cmd]",
54 .help = "show the help",
55 .mhandler.cmd = do_help_cmd,
58 STEXI
59 @item help or ? [@var{cmd}]
60 @findex help
61 Show the help for all commands or just for command @var{cmd}.
62 ETEXI
65 .name = "commit",
66 .args_type = "device:B",
67 .params = "device|all",
68 .help = "commit changes to the disk images (if -snapshot is used) or backing files",
69 .mhandler.cmd = do_commit,
72 STEXI
73 @item commit
74 @findex commit
75 Commit changes to the disk images (if -snapshot is used) or backing files.
76 ETEXI
79 .name = "q|quit",
80 .args_type = "",
81 .params = "",
82 .help = "quit the emulator",
83 .user_print = monitor_user_noop,
84 .mhandler.cmd_new = do_quit,
87 STEXI
88 @item q or quit
89 @findex quit
90 Quit the emulator.
91 ETEXI
92 SQMP
93 quit
94 ----
96 Quit the emulator.
98 Arguments: None.
100 Example:
102 -> { "execute": "quit" }
103 <- { "return": {} }
105 EQMP
108 .name = "eject",
109 .args_type = "force:-f,device:B",
110 .params = "[-f] device",
111 .help = "eject a removable medium (use -f to force it)",
112 .user_print = monitor_user_noop,
113 .mhandler.cmd_new = do_eject,
116 STEXI
117 @item eject [-f] @var{device}
118 @findex eject
119 Eject a removable medium (use -f to force it).
120 ETEXI
121 SQMP
122 eject
123 -----
125 Eject a removable medium.
127 Arguments:
129 - force: force ejection (json-bool, optional)
130 - device: device name (json-string)
132 Example:
134 -> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
135 <- { "return": {} }
137 Note: The "force" argument defaults to false.
139 EQMP
142 .name = "change",
143 .args_type = "device:B,target:F,arg:s?",
144 .params = "device filename [format]",
145 .help = "change a removable medium, optional format",
146 .user_print = monitor_user_noop,
147 .mhandler.cmd_new = do_change,
150 STEXI
151 @item change @var{device} @var{setting}
152 @findex change
154 Change the configuration of a device.
156 @table @option
157 @item change @var{diskdevice} @var{filename} [@var{format}]
158 Change the medium for a removable disk device to point to @var{filename}. eg
160 @example
161 (qemu) change ide1-cd0 /path/to/some.iso
162 @end example
164 @var{format} is optional.
166 @item change vnc @var{display},@var{options}
167 Change the configuration of the VNC server. The valid syntax for @var{display}
168 and @var{options} are described at @ref{sec_invocation}. eg
170 @example
171 (qemu) change vnc localhost:1
172 @end example
174 @item change vnc password [@var{password}]
176 Change the password associated with the VNC server. If the new password is not
177 supplied, the monitor will prompt for it to be entered. VNC passwords are only
178 significant up to 8 letters. eg
180 @example
181 (qemu) change vnc password
182 Password: ********
183 @end example
185 @end table
186 ETEXI
187 SQMP
188 change
189 ------
191 Change a removable medium or VNC configuration.
193 Arguments:
195 - "device": device name (json-string)
196 - "target": filename or item (json-string)
197 - "arg": additional argument (json-string, optional)
199 Examples:
201 1. Change a removable medium
203 -> { "execute": "change",
204 "arguments": { "device": "ide1-cd0",
205 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
206 <- { "return": {} }
208 2. Change VNC password
210 -> { "execute": "change",
211 "arguments": { "device": "vnc", "target": "password",
212 "arg": "foobar1" } }
213 <- { "return": {} }
215 EQMP
218 .name = "screendump",
219 .args_type = "filename:F",
220 .params = "filename",
221 .help = "save screen into PPM image 'filename'",
222 .user_print = monitor_user_noop,
223 .mhandler.cmd_new = do_screen_dump,
226 STEXI
227 @item screendump @var{filename}
228 @findex screendump
229 Save screen into PPM image @var{filename}.
230 ETEXI
231 SQMP
232 screendump
233 ----------
235 Save screen into PPM image.
237 Arguments:
239 - "filename": file path (json-string)
241 Example:
243 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
244 <- { "return": {} }
246 EQMP
249 .name = "logfile",
250 .args_type = "filename:F",
251 .params = "filename",
252 .help = "output logs to 'filename'",
253 .mhandler.cmd = do_logfile,
256 STEXI
257 @item logfile @var{filename}
258 @findex logfile
259 Output logs to @var{filename}.
260 ETEXI
263 .name = "log",
264 .args_type = "items:s",
265 .params = "item1[,...]",
266 .help = "activate logging of the specified items to '/tmp/qemu.log'",
267 .mhandler.cmd = do_log,
270 STEXI
271 @item log @var{item1}[,...]
272 @findex log
273 Activate logging of the specified items to @file{/tmp/qemu.log}.
274 ETEXI
277 .name = "savevm",
278 .args_type = "name:s?",
279 .params = "[tag|id]",
280 .help = "save a VM snapshot. If no tag or id are provided, a new snapshot is created",
281 .mhandler.cmd = do_savevm,
284 STEXI
285 @item savevm [@var{tag}|@var{id}]
286 @findex savevm
287 Create a snapshot of the whole virtual machine. If @var{tag} is
288 provided, it is used as human readable identifier. If there is already
289 a snapshot with the same tag or ID, it is replaced. More info at
290 @ref{vm_snapshots}.
291 ETEXI
294 .name = "loadvm",
295 .args_type = "name:s",
296 .params = "tag|id",
297 .help = "restore a VM snapshot from its tag or id",
298 .mhandler.cmd = do_loadvm,
301 STEXI
302 @item loadvm @var{tag}|@var{id}
303 @findex loadvm
304 Set the whole virtual machine to the snapshot identified by the tag
305 @var{tag} or the unique snapshot ID @var{id}.
306 ETEXI
309 .name = "delvm",
310 .args_type = "name:s",
311 .params = "tag|id",
312 .help = "delete a VM snapshot from its tag or id",
313 .mhandler.cmd = do_delvm,
316 STEXI
317 @item delvm @var{tag}|@var{id}
318 @findex delvm
319 Delete the snapshot identified by @var{tag} or @var{id}.
320 ETEXI
323 .name = "singlestep",
324 .args_type = "option:s?",
325 .params = "[on|off]",
326 .help = "run emulation in singlestep mode or switch to normal mode",
327 .mhandler.cmd = do_singlestep,
330 STEXI
331 @item singlestep [off]
332 @findex singlestep
333 Run the emulation in single step mode.
334 If called with option off, the emulation returns to normal mode.
335 ETEXI
338 .name = "stop",
339 .args_type = "",
340 .params = "",
341 .help = "stop emulation",
342 .user_print = monitor_user_noop,
343 .mhandler.cmd_new = do_stop,
346 STEXI
347 @item stop
348 @findex stop
349 Stop emulation.
350 ETEXI
351 SQMP
352 stop
353 ----
355 Stop the emulator.
357 Arguments: None.
359 Example:
361 -> { "execute": "stop" }
362 <- { "return": {} }
364 EQMP
367 .name = "c|cont",
368 .args_type = "",
369 .params = "",
370 .help = "resume emulation",
371 .user_print = monitor_user_noop,
372 .mhandler.cmd_new = do_cont,
375 STEXI
376 @item c or cont
377 @findex cont
378 Resume emulation.
379 ETEXI
380 SQMP
381 cont
382 ----
384 Resume emulation.
386 Arguments: None.
388 Example:
390 -> { "execute": "cont" }
391 <- { "return": {} }
393 EQMP
396 .name = "gdbserver",
397 .args_type = "device:s?",
398 .params = "[device]",
399 .help = "start gdbserver on given device (default 'tcp::1234'), stop with 'none'",
400 .mhandler.cmd = do_gdbserver,
403 STEXI
404 @item gdbserver [@var{port}]
405 @findex gdbserver
406 Start gdbserver session (default @var{port}=1234)
407 ETEXI
410 .name = "x",
411 .args_type = "fmt:/,addr:l",
412 .params = "/fmt addr",
413 .help = "virtual memory dump starting at 'addr'",
414 .mhandler.cmd = do_memory_dump,
417 STEXI
418 @item x/fmt @var{addr}
419 @findex x
420 Virtual memory dump starting at @var{addr}.
421 ETEXI
424 .name = "xp",
425 .args_type = "fmt:/,addr:l",
426 .params = "/fmt addr",
427 .help = "physical memory dump starting at 'addr'",
428 .mhandler.cmd = do_physical_memory_dump,
431 STEXI
432 @item xp /@var{fmt} @var{addr}
433 @findex xp
434 Physical memory dump starting at @var{addr}.
436 @var{fmt} is a format which tells the command how to format the
437 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
439 @table @var
440 @item count
441 is the number of items to be dumped.
443 @item format
444 can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
445 c (char) or i (asm instruction).
447 @item size
448 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
449 @code{h} or @code{w} can be specified with the @code{i} format to
450 respectively select 16 or 32 bit code instruction size.
452 @end table
454 Examples:
455 @itemize
456 @item
457 Dump 10 instructions at the current instruction pointer:
458 @example
459 (qemu) x/10i $eip
460 0x90107063: ret
461 0x90107064: sti
462 0x90107065: lea 0x0(%esi,1),%esi
463 0x90107069: lea 0x0(%edi,1),%edi
464 0x90107070: ret
465 0x90107071: jmp 0x90107080
466 0x90107073: nop
467 0x90107074: nop
468 0x90107075: nop
469 0x90107076: nop
470 @end example
472 @item
473 Dump 80 16 bit values at the start of the video memory.
474 @smallexample
475 (qemu) xp/80hx 0xb8000
476 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
477 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
478 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
479 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
480 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
481 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
482 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
483 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
484 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
485 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
486 @end smallexample
487 @end itemize
488 ETEXI
491 .name = "p|print",
492 .args_type = "fmt:/,val:l",
493 .params = "/fmt expr",
494 .help = "print expression value (use $reg for CPU register access)",
495 .mhandler.cmd = do_print,
498 STEXI
499 @item p or print/@var{fmt} @var{expr}
500 @findex print
502 Print expression value. Only the @var{format} part of @var{fmt} is
503 used.
504 ETEXI
507 .name = "i",
508 .args_type = "fmt:/,addr:i,index:i.",
509 .params = "/fmt addr",
510 .help = "I/O port read",
511 .mhandler.cmd = do_ioport_read,
514 STEXI
515 Read I/O port.
516 ETEXI
519 .name = "o",
520 .args_type = "fmt:/,addr:i,val:i",
521 .params = "/fmt addr value",
522 .help = "I/O port write",
523 .mhandler.cmd = do_ioport_write,
526 STEXI
527 Write to I/O port.
528 ETEXI
531 .name = "sendkey",
532 .args_type = "string:s,hold_time:i?",
533 .params = "keys [hold_ms]",
534 .help = "send keys to the VM (e.g. 'sendkey ctrl-alt-f1', default hold time=100 ms)",
535 .mhandler.cmd = do_sendkey,
538 STEXI
539 @item sendkey @var{keys}
540 @findex sendkey
542 Send @var{keys} to the emulator. @var{keys} could be the name of the
543 key or @code{#} followed by the raw value in either decimal or hexadecimal
544 format. Use @code{-} to press several keys simultaneously. Example:
545 @example
546 sendkey ctrl-alt-f1
547 @end example
549 This command is useful to send keys that your graphical user interface
550 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
551 ETEXI
554 .name = "system_reset",
555 .args_type = "",
556 .params = "",
557 .help = "reset the system",
558 .user_print = monitor_user_noop,
559 .mhandler.cmd_new = do_system_reset,
562 STEXI
563 @item system_reset
564 @findex system_reset
566 Reset the system.
567 ETEXI
568 SQMP
569 system_reset
570 ------------
572 Reset the system.
574 Arguments: None.
576 Example:
578 -> { "execute": "system_reset" }
579 <- { "return": {} }
581 EQMP
584 .name = "system_powerdown",
585 .args_type = "",
586 .params = "",
587 .help = "send system power down event",
588 .user_print = monitor_user_noop,
589 .mhandler.cmd_new = do_system_powerdown,
592 STEXI
593 @item system_powerdown
594 @findex system_powerdown
596 Power down the system (if supported).
597 ETEXI
598 SQMP
599 system_powerdown
600 ----------------
602 Send system power down event.
604 Arguments: None.
606 Example:
608 -> { "execute": "system_powerdown" }
609 <- { "return": {} }
611 EQMP
614 .name = "sum",
615 .args_type = "start:i,size:i",
616 .params = "addr size",
617 .help = "compute the checksum of a memory region",
618 .mhandler.cmd = do_sum,
621 STEXI
622 @item sum @var{addr} @var{size}
623 @findex sum
625 Compute the checksum of a memory region.
626 ETEXI
629 .name = "usb_add",
630 .args_type = "devname:s",
631 .params = "device",
632 .help = "add USB device (e.g. 'host:bus.addr' or 'host:vendor_id:product_id')",
633 .mhandler.cmd = do_usb_add,
636 STEXI
637 @item usb_add @var{devname}
638 @findex usb_add
640 Add the USB device @var{devname}. For details of available devices see
641 @ref{usb_devices}
642 ETEXI
645 .name = "usb_del",
646 .args_type = "devname:s",
647 .params = "device",
648 .help = "remove USB device 'bus.addr'",
649 .mhandler.cmd = do_usb_del,
652 STEXI
653 @item usb_del @var{devname}
654 @findex usb_del
656 Remove the USB device @var{devname} from the QEMU virtual USB
657 hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
658 command @code{info usb} to see the devices you can remove.
659 ETEXI
662 .name = "device_add",
663 .args_type = "device:O",
664 .params = "driver[,prop=value][,...]",
665 .help = "add device, like -device on the command line",
666 .user_print = monitor_user_noop,
667 .mhandler.cmd_new = do_device_add,
670 STEXI
671 @item device_add @var{config}
672 @findex device_add
674 Add device.
675 ETEXI
676 SQMP
677 device_add
678 ----------
680 Add a device.
682 Arguments:
684 - "driver": the name of the new device's driver (json-string)
685 - "bus": the device's parent bus (device tree path, json-string, optional)
686 - "id": the device's ID, must be unique (json-string)
687 - device properties
689 Example:
691 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
692 <- { "return": {} }
694 Notes:
696 (1) For detailed information about this command, please refer to the
697 'docs/qdev-device-use.txt' file.
699 (2) It's possible to list device properties by running QEMU with the
700 "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
702 EQMP
705 .name = "device_del",
706 .args_type = "id:s",
707 .params = "device",
708 .help = "remove device",
709 .user_print = monitor_user_noop,
710 .mhandler.cmd_new = do_device_del,
713 STEXI
714 @item device_del @var{id}
715 @findex device_del
717 Remove device @var{id}.
718 ETEXI
719 SQMP
720 device_del
721 ----------
723 Remove a device.
725 Arguments:
727 - "id": the device's ID (json-string)
729 Example:
731 -> { "execute": "device_del", "arguments": { "id": "net1" } }
732 <- { "return": {} }
734 EQMP
737 .name = "cpu",
738 .args_type = "index:i",
739 .params = "index",
740 .help = "set the default CPU",
741 .user_print = monitor_user_noop,
742 .mhandler.cmd_new = do_cpu_set,
745 STEXI
746 @item cpu @var{index}
747 @findex cpu
748 Set the default CPU.
749 ETEXI
750 SQMP
754 Set the default CPU.
756 Arguments:
758 - "index": the CPU's index (json-int)
760 Example:
762 -> { "execute": "cpu", "arguments": { "index": 0 } }
763 <- { "return": {} }
765 Note: CPUs' indexes are obtained with the 'query-cpus' command.
767 EQMP
770 .name = "mouse_move",
771 .args_type = "dx_str:s,dy_str:s,dz_str:s?",
772 .params = "dx dy [dz]",
773 .help = "send mouse move events",
774 .mhandler.cmd = do_mouse_move,
777 STEXI
778 @item mouse_move @var{dx} @var{dy} [@var{dz}]
779 @findex mouse_move
780 Move the active mouse to the specified coordinates @var{dx} @var{dy}
781 with optional scroll axis @var{dz}.
782 ETEXI
785 .name = "mouse_button",
786 .args_type = "button_state:i",
787 .params = "state",
788 .help = "change mouse button state (1=L, 2=M, 4=R)",
789 .mhandler.cmd = do_mouse_button,
792 STEXI
793 @item mouse_button @var{val}
794 @findex mouse_button
795 Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
796 ETEXI
799 .name = "mouse_set",
800 .args_type = "index:i",
801 .params = "index",
802 .help = "set which mouse device receives events",
803 .mhandler.cmd = do_mouse_set,
806 STEXI
807 @item mouse_set @var{index}
808 @findex mouse_set
809 Set which mouse device receives events at given @var{index}, index
810 can be obtained with
811 @example
812 info mice
813 @end example
814 ETEXI
816 #ifdef HAS_AUDIO
818 .name = "wavcapture",
819 .args_type = "path:F,freq:i?,bits:i?,nchannels:i?",
820 .params = "path [frequency [bits [channels]]]",
821 .help = "capture audio to a wave file (default frequency=44100 bits=16 channels=2)",
822 .mhandler.cmd = do_wav_capture,
824 #endif
825 STEXI
826 @item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
827 @findex wavcapture
828 Capture audio into @var{filename}. Using sample rate @var{frequency}
829 bits per sample @var{bits} and number of channels @var{channels}.
831 Defaults:
832 @itemize @minus
833 @item Sample rate = 44100 Hz - CD quality
834 @item Bits = 16
835 @item Number of channels = 2 - Stereo
836 @end itemize
837 ETEXI
839 #ifdef HAS_AUDIO
841 .name = "stopcapture",
842 .args_type = "n:i",
843 .params = "capture index",
844 .help = "stop capture",
845 .mhandler.cmd = do_stop_capture,
847 #endif
848 STEXI
849 @item stopcapture @var{index}
850 @findex stopcapture
851 Stop capture with a given @var{index}, index can be obtained with
852 @example
853 info capture
854 @end example
855 ETEXI
858 .name = "memsave",
859 .args_type = "val:l,size:i,filename:s",
860 .params = "addr size file",
861 .help = "save to disk virtual memory dump starting at 'addr' of size 'size'",
862 .user_print = monitor_user_noop,
863 .mhandler.cmd_new = do_memory_save,
866 STEXI
867 @item memsave @var{addr} @var{size} @var{file}
868 @findex memsave
869 save to disk virtual memory dump starting at @var{addr} of size @var{size}.
870 ETEXI
871 SQMP
872 memsave
873 -------
875 Save to disk virtual memory dump starting at 'val' of size 'size'.
877 Arguments:
879 - "val": the starting address (json-int)
880 - "size": the memory size, in bytes (json-int)
881 - "filename": file path (json-string)
883 Example:
885 -> { "execute": "memsave",
886 "arguments": { "val": 10,
887 "size": 100,
888 "filename": "/tmp/virtual-mem-dump" } }
889 <- { "return": {} }
891 Note: Depends on the current CPU.
893 EQMP
896 .name = "pmemsave",
897 .args_type = "val:l,size:i,filename:s",
898 .params = "addr size file",
899 .help = "save to disk physical memory dump starting at 'addr' of size 'size'",
900 .user_print = monitor_user_noop,
901 .mhandler.cmd_new = do_physical_memory_save,
904 STEXI
905 @item pmemsave @var{addr} @var{size} @var{file}
906 @findex pmemsave
907 save to disk physical memory dump starting at @var{addr} of size @var{size}.
908 ETEXI
909 SQMP
910 pmemsave
911 --------
913 Save to disk physical memory dump starting at 'val' of size 'size'.
915 Arguments:
917 - "val": the starting address (json-int)
918 - "size": the memory size, in bytes (json-int)
919 - "filename": file path (json-string)
921 Example:
923 -> { "execute": "pmemsave",
924 "arguments": { "val": 10,
925 "size": 100,
926 "filename": "/tmp/physical-mem-dump" } }
927 <- { "return": {} }
929 EQMP
932 .name = "boot_set",
933 .args_type = "bootdevice:s",
934 .params = "bootdevice",
935 .help = "define new values for the boot device list",
936 .mhandler.cmd = do_boot_set,
939 STEXI
940 @item boot_set @var{bootdevicelist}
941 @findex boot_set
943 Define new values for the boot device list. Those values will override
944 the values specified on the command line through the @code{-boot} option.
946 The values that can be specified here depend on the machine type, but are
947 the same that can be specified in the @code{-boot} command line option.
948 ETEXI
950 #if defined(TARGET_I386)
952 .name = "nmi",
953 .args_type = "cpu_index:i",
954 .params = "cpu",
955 .help = "inject an NMI on the given CPU",
956 .mhandler.cmd = do_inject_nmi,
958 #endif
959 STEXI
960 @item nmi @var{cpu}
961 @findex nmi
962 Inject an NMI on the given CPU (x86 only).
963 ETEXI
966 .name = "migrate",
967 .args_type = "detach:-d,blk:-b,inc:-i,uri:s",
968 .params = "[-d] [-b] [-i] uri",
969 .help = "migrate to URI (using -d to not wait for completion)"
970 "\n\t\t\t -b for migration without shared storage with"
971 " full copy of disk\n\t\t\t -i for migration without "
972 "shared storage with incremental copy of disk "
973 "(base image shared between src and destination)",
974 .user_print = monitor_user_noop,
975 .mhandler.cmd_new = do_migrate,
979 STEXI
980 @item migrate [-d] [-b] [-i] @var{uri}
981 @findex migrate
982 Migrate to @var{uri} (using -d to not wait for completion).
983 -b for migration with full copy of disk
984 -i for migration with incremental copy of disk (base image is shared)
985 ETEXI
986 SQMP
987 migrate
988 -------
990 Migrate to URI.
992 Arguments:
994 - "blk": block migration, full disk copy (json-bool, optional)
995 - "inc": incremental disk copy (json-bool, optional)
996 - "uri": Destination URI (json-string)
998 Example:
1000 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
1001 <- { "return": {} }
1003 Notes:
1005 (1) The 'query-migrate' command should be used to check migration's progress
1006 and final result (this information is provided by the 'status' member)
1007 (2) All boolean arguments default to false
1008 (3) The user Monitor's "detach" argument is invalid in QMP and should not
1009 be used
1011 EQMP
1014 .name = "migrate_cancel",
1015 .args_type = "",
1016 .params = "",
1017 .help = "cancel the current VM migration",
1018 .user_print = monitor_user_noop,
1019 .mhandler.cmd_new = do_migrate_cancel,
1022 STEXI
1023 @item migrate_cancel
1024 @findex migrate_cancel
1025 Cancel the current VM migration.
1026 ETEXI
1027 SQMP
1028 migrate_cancel
1029 --------------
1031 Cancel the current migration.
1033 Arguments: None.
1035 Example:
1037 -> { "execute": "migrate_cancel" }
1038 <- { "return": {} }
1040 EQMP
1043 .name = "migrate_set_speed",
1044 .args_type = "value:f",
1045 .params = "value",
1046 .help = "set maximum speed (in bytes) for migrations",
1047 .user_print = monitor_user_noop,
1048 .mhandler.cmd_new = do_migrate_set_speed,
1051 STEXI
1052 @item migrate_set_speed @var{value}
1053 @findex migrate_set_speed
1054 Set maximum speed to @var{value} (in bytes) for migrations.
1055 ETEXI
1056 SQMP
1057 migrate_set_speed
1058 -----------------
1060 Set maximum speed for migrations.
1062 Arguments:
1064 - "value": maximum speed, in bytes per second (json-number)
1066 Example:
1068 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
1069 <- { "return": {} }
1071 EQMP
1074 .name = "migrate_set_downtime",
1075 .args_type = "value:T",
1076 .params = "value",
1077 .help = "set maximum tolerated downtime (in seconds) for migrations",
1078 .user_print = monitor_user_noop,
1079 .mhandler.cmd_new = do_migrate_set_downtime,
1082 STEXI
1083 @item migrate_set_downtime @var{second}
1084 @findex migrate_set_downtime
1085 Set maximum tolerated downtime (in seconds) for migration.
1086 ETEXI
1087 SQMP
1088 migrate_set_downtime
1089 --------------------
1091 Set maximum tolerated downtime (in seconds) for migrations.
1093 Arguments:
1095 - "value": maximum downtime (json-number)
1097 Example:
1099 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
1100 <- { "return": {} }
1102 EQMP
1104 #if defined(TARGET_I386)
1106 .name = "drive_add",
1107 .args_type = "pci_addr:s,opts:s",
1108 .params = "[[<domain>:]<bus>:]<slot>\n"
1109 "[file=file][,if=type][,bus=n]\n"
1110 "[,unit=m][,media=d][index=i]\n"
1111 "[,cyls=c,heads=h,secs=s[,trans=t]]\n"
1112 "[snapshot=on|off][,cache=on|off]",
1113 .help = "add drive to PCI storage controller",
1114 .mhandler.cmd = drive_hot_add,
1116 #endif
1118 STEXI
1119 @item drive_add
1120 @findex drive_add
1121 Add drive to PCI storage controller.
1122 ETEXI
1124 #if defined(TARGET_I386)
1126 .name = "pci_add",
1127 .args_type = "pci_addr:s,type:s,opts:s?",
1128 .params = "auto|[[<domain>:]<bus>:]<slot> nic|storage [[vlan=n][,macaddr=addr][,model=type]] [file=file][,if=type][,bus=nr]...",
1129 .help = "hot-add PCI device",
1130 .mhandler.cmd = pci_device_hot_add,
1132 #endif
1134 STEXI
1135 @item pci_add
1136 @findex pci_add
1137 Hot-add PCI device.
1138 ETEXI
1140 #if defined(TARGET_I386)
1142 .name = "pci_del",
1143 .args_type = "pci_addr:s",
1144 .params = "[[<domain>:]<bus>:]<slot>",
1145 .help = "hot remove PCI device",
1146 .mhandler.cmd = do_pci_device_hot_remove,
1148 #endif
1150 STEXI
1151 @item pci_del
1152 @findex pci_del
1153 Hot remove PCI device.
1154 ETEXI
1157 .name = "host_net_add",
1158 .args_type = "device:s,opts:s?",
1159 .params = "tap|user|socket|vde|dump [options]",
1160 .help = "add host VLAN client",
1161 .mhandler.cmd = net_host_device_add,
1164 STEXI
1165 @item host_net_add
1166 @findex host_net_add
1167 Add host VLAN client.
1168 ETEXI
1171 .name = "host_net_remove",
1172 .args_type = "vlan_id:i,device:s",
1173 .params = "vlan_id name",
1174 .help = "remove host VLAN client",
1175 .mhandler.cmd = net_host_device_remove,
1178 STEXI
1179 @item host_net_remove
1180 @findex host_net_remove
1181 Remove host VLAN client.
1182 ETEXI
1185 .name = "netdev_add",
1186 .args_type = "netdev:O",
1187 .params = "[user|tap|socket],id=str[,prop=value][,...]",
1188 .help = "add host network device",
1189 .user_print = monitor_user_noop,
1190 .mhandler.cmd_new = do_netdev_add,
1193 STEXI
1194 @item netdev_add
1195 @findex netdev_add
1196 Add host network device.
1197 ETEXI
1198 SQMP
1199 netdev_add
1200 ----------
1202 Add host network device.
1204 Arguments:
1206 - "type": the device type, "tap", "user", ... (json-string)
1207 - "id": the device's ID, must be unique (json-string)
1208 - device options
1210 Example:
1212 -> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
1213 <- { "return": {} }
1215 Note: The supported device options are the same ones supported by the '-net'
1216 command-line argument, which are listed in the '-help' output or QEMU's
1217 manual
1219 EQMP
1222 .name = "netdev_del",
1223 .args_type = "id:s",
1224 .params = "id",
1225 .help = "remove host network device",
1226 .user_print = monitor_user_noop,
1227 .mhandler.cmd_new = do_netdev_del,
1230 STEXI
1231 @item netdev_del
1232 @findex netdev_del
1233 Remove host network device.
1234 ETEXI
1235 SQMP
1236 netdev_del
1237 ----------
1239 Remove host network device.
1241 Arguments:
1243 - "id": the device's ID, must be unique (json-string)
1245 Example:
1247 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
1248 <- { "return": {} }
1250 EQMP
1252 #ifdef CONFIG_SLIRP
1254 .name = "hostfwd_add",
1255 .args_type = "arg1:s,arg2:s?,arg3:s?",
1256 .params = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport",
1257 .help = "redirect TCP or UDP connections from host to guest (requires -net user)",
1258 .mhandler.cmd = net_slirp_hostfwd_add,
1260 #endif
1261 STEXI
1262 @item hostfwd_add
1263 @findex hostfwd_add
1264 Redirect TCP or UDP connections from host to guest (requires -net user).
1265 ETEXI
1267 #ifdef CONFIG_SLIRP
1269 .name = "hostfwd_remove",
1270 .args_type = "arg1:s,arg2:s?,arg3:s?",
1271 .params = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport",
1272 .help = "remove host-to-guest TCP or UDP redirection",
1273 .mhandler.cmd = net_slirp_hostfwd_remove,
1276 #endif
1277 STEXI
1278 @item hostfwd_remove
1279 @findex hostfwd_remove
1280 Remove host-to-guest TCP or UDP redirection.
1281 ETEXI
1284 .name = "balloon",
1285 .args_type = "value:M",
1286 .params = "target",
1287 .help = "request VM to change its memory allocation (in MB)",
1288 .user_print = monitor_user_noop,
1289 .mhandler.cmd_async = do_balloon,
1290 .async = 1,
1293 STEXI
1294 @item balloon @var{value}
1295 @findex balloon
1296 Request VM to change its memory allocation to @var{value} (in MB).
1297 ETEXI
1298 SQMP
1299 balloon
1300 -------
1302 Request VM to change its memory allocation (in bytes).
1304 Arguments:
1306 - "value": New memory allocation (json-int)
1308 Example:
1310 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1311 <- { "return": {} }
1313 EQMP
1316 .name = "set_link",
1317 .args_type = "name:s,up:b",
1318 .params = "name on|off",
1319 .help = "change the link status of a network adapter",
1320 .user_print = monitor_user_noop,
1321 .mhandler.cmd_new = do_set_link,
1324 STEXI
1325 @item set_link @var{name} [on|off]
1326 @findex set_link
1327 Switch link @var{name} on (i.e. up) or off (i.e. down).
1328 ETEXI
1329 SQMP
1330 set_link
1331 --------
1333 Change the link status of a network adapter.
1335 Arguments:
1337 - "name": network device name (json-string)
1338 - "up": status is up (json-bool)
1340 Example:
1342 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1343 <- { "return": {} }
1345 EQMP
1348 .name = "watchdog_action",
1349 .args_type = "action:s",
1350 .params = "[reset|shutdown|poweroff|pause|debug|none]",
1351 .help = "change watchdog action",
1352 .mhandler.cmd = do_watchdog_action,
1355 STEXI
1356 @item watchdog_action
1357 @findex watchdog_action
1358 Change watchdog action.
1359 ETEXI
1362 .name = "acl_show",
1363 .args_type = "aclname:s",
1364 .params = "aclname",
1365 .help = "list rules in the access control list",
1366 .mhandler.cmd = do_acl_show,
1369 STEXI
1370 @item acl_show @var{aclname}
1371 @findex acl_show
1372 List all the matching rules in the access control list, and the default
1373 policy. There are currently two named access control lists,
1374 @var{vnc.x509dname} and @var{vnc.username} matching on the x509 client
1375 certificate distinguished name, and SASL username respectively.
1376 ETEXI
1379 .name = "acl_policy",
1380 .args_type = "aclname:s,policy:s",
1381 .params = "aclname allow|deny",
1382 .help = "set default access control list policy",
1383 .mhandler.cmd = do_acl_policy,
1386 STEXI
1387 @item acl_policy @var{aclname} @code{allow|deny}
1388 @findex acl_policy
1389 Set the default access control list policy, used in the event that
1390 none of the explicit rules match. The default policy at startup is
1391 always @code{deny}.
1392 ETEXI
1395 .name = "acl_add",
1396 .args_type = "aclname:s,match:s,policy:s,index:i?",
1397 .params = "aclname match allow|deny [index]",
1398 .help = "add a match rule to the access control list",
1399 .mhandler.cmd = do_acl_add,
1402 STEXI
1403 @item acl_add @var{aclname} @var{match} @code{allow|deny} [@var{index}]
1404 @findex acl_add
1405 Add a match rule to the access control list, allowing or denying access.
1406 The match will normally be an exact username or x509 distinguished name,
1407 but can optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to
1408 allow all users in the @code{EXAMPLE.COM} kerberos realm. The match will
1409 normally be appended to the end of the ACL, but can be inserted
1410 earlier in the list if the optional @var{index} parameter is supplied.
1411 ETEXI
1414 .name = "acl_remove",
1415 .args_type = "aclname:s,match:s",
1416 .params = "aclname match",
1417 .help = "remove a match rule from the access control list",
1418 .mhandler.cmd = do_acl_remove,
1421 STEXI
1422 @item acl_remove @var{aclname} @var{match}
1423 @findex acl_remove
1424 Remove the specified match rule from the access control list.
1425 ETEXI
1428 .name = "acl_reset",
1429 .args_type = "aclname:s",
1430 .params = "aclname",
1431 .help = "reset the access control list",
1432 .mhandler.cmd = do_acl_reset,
1435 STEXI
1436 @item acl_reset @var{aclname}
1437 @findex acl_reset
1438 Remove all matches from the access control list, and set the default
1439 policy back to @code{deny}.
1440 ETEXI
1442 #if defined(TARGET_I386)
1445 .name = "mce",
1446 .args_type = "cpu_index:i,bank:i,status:l,mcg_status:l,addr:l,misc:l",
1447 .params = "cpu bank status mcgstatus addr misc",
1448 .help = "inject a MCE on the given CPU",
1449 .mhandler.cmd = do_inject_mce,
1452 #endif
1453 STEXI
1454 @item mce @var{cpu} @var{bank} @var{status} @var{mcgstatus} @var{addr} @var{misc}
1455 @findex mce (x86)
1456 Inject an MCE on the given CPU (x86 only).
1457 ETEXI
1460 .name = "getfd",
1461 .args_type = "fdname:s",
1462 .params = "getfd name",
1463 .help = "receive a file descriptor via SCM rights and assign it a name",
1464 .user_print = monitor_user_noop,
1465 .mhandler.cmd_new = do_getfd,
1468 STEXI
1469 @item getfd @var{fdname}
1470 @findex getfd
1471 If a file descriptor is passed alongside this command using the SCM_RIGHTS
1472 mechanism on unix sockets, it is stored using the name @var{fdname} for
1473 later use by other monitor commands.
1474 ETEXI
1475 SQMP
1476 getfd
1477 -----
1479 Receive a file descriptor via SCM rights and assign it a name.
1481 Arguments:
1483 - "fdname": file descriptor name (json-string)
1485 Example:
1487 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1488 <- { "return": {} }
1490 EQMP
1493 .name = "closefd",
1494 .args_type = "fdname:s",
1495 .params = "closefd name",
1496 .help = "close a file descriptor previously passed via SCM rights",
1497 .user_print = monitor_user_noop,
1498 .mhandler.cmd_new = do_closefd,
1501 STEXI
1502 @item closefd @var{fdname}
1503 @findex closefd
1504 Close the file descriptor previously assigned to @var{fdname} using the
1505 @code{getfd} command. This is only needed if the file descriptor was never
1506 used by another monitor command.
1507 ETEXI
1508 SQMP
1509 closefd
1510 -------
1512 Close a file descriptor previously passed via SCM rights.
1514 Arguments:
1516 - "fdname": file descriptor name (json-string)
1518 Example:
1520 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1521 <- { "return": {} }
1523 EQMP
1526 .name = "block_passwd",
1527 .args_type = "device:B,password:s",
1528 .params = "block_passwd device password",
1529 .help = "set the password of encrypted block devices",
1530 .user_print = monitor_user_noop,
1531 .mhandler.cmd_new = do_block_set_passwd,
1534 STEXI
1535 @item block_passwd @var{device} @var{password}
1536 @findex block_passwd
1537 Set the encrypted device @var{device} password to @var{password}
1538 ETEXI
1539 SQMP
1540 block_passwd
1541 ------------
1543 Set the password of encrypted block devices.
1545 Arguments:
1547 - "device": device name (json-string)
1548 - "password": password (json-string)
1550 Example:
1552 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1553 "password": "12345" } }
1554 <- { "return": {} }
1556 EQMP
1559 .name = "qmp_capabilities",
1560 .args_type = "",
1561 .params = "",
1562 .help = "enable QMP capabilities",
1563 .user_print = monitor_user_noop,
1564 .mhandler.cmd_new = do_qmp_capabilities,
1567 STEXI
1568 @item qmp_capabilities
1569 @findex qmp_capabilities
1570 Enable the specified QMP capabilities
1571 ETEXI
1572 SQMP
1573 qmp_capabilities
1574 ----------------
1576 Enable QMP capabilities.
1578 Arguments: None.
1580 Example:
1582 -> { "execute": "qmp_capabilities" }
1583 <- { "return": {} }
1585 Note: This command must be issued before issuing any other command.
1587 EQMP
1590 HXCOMM Keep the 'info' command at the end!
1591 HXCOMM This is required for the QMP documentation layout.
1593 SQMP
1595 2. Query Commands
1596 =================
1598 EQMP
1601 .name = "info",
1602 .args_type = "item:s?",
1603 .params = "[subcommand]",
1604 .help = "show various information about the system state",
1605 .user_print = monitor_user_noop,
1606 .mhandler.cmd_new = do_info,
1609 STEXI
1610 @item info @var{subcommand}
1611 @findex info
1612 Show various information about the system state.
1614 @table @option
1615 @item info version
1616 show the version of QEMU
1617 ETEXI
1618 SQMP
1619 query-version
1620 -------------
1622 Show QEMU version.
1624 Return a json-object with the following information:
1626 - "qemu": QEMU's version (json-string)
1627 - "package": package's version (json-string)
1629 Example:
1631 -> { "execute": "query-version" }
1632 <- { "return": { "qemu": "0.11.50", "package": "" } }
1634 EQMP
1636 STEXI
1637 @item info commands
1638 list QMP available commands
1639 ETEXI
1640 SQMP
1641 query-commands
1642 --------------
1644 List QMP available commands.
1646 Each command is represented by a json-object, the returned value is a json-array
1647 of all commands.
1649 Each json-object contain:
1651 - "name": command's name (json-string)
1653 Example:
1655 -> { "execute": "query-commands" }
1656 <- {
1657 "return":[
1659 "name":"query-balloon"
1662 "name":"system_powerdown"
1667 Note: This example has been shortened as the real response is too long.
1669 EQMP
1671 STEXI
1672 @item info network
1673 show the various VLANs and the associated devices
1674 ETEXI
1676 STEXI
1677 @item info chardev
1678 show the character devices
1679 ETEXI
1680 SQMP
1681 query-chardev
1682 -------------
1684 Each device is represented by a json-object. The returned value is a json-array
1685 of all devices.
1687 Each json-object contain the following:
1689 - "label": device's label (json-string)
1690 - "filename": device's file (json-string)
1692 Example:
1694 -> { "execute": "query-chardev" }
1695 <- {
1696 "return":[
1698 "label":"monitor",
1699 "filename":"stdio"
1702 "label":"serial0",
1703 "filename":"vc"
1708 EQMP
1710 STEXI
1711 @item info block
1712 show the block devices
1713 ETEXI
1714 SQMP
1715 query-block
1716 -----------
1718 Show the block devices.
1720 Each block device information is stored in a json-object and the returned value
1721 is a json-array of all devices.
1723 Each json-object contain the following:
1725 - "device": device name (json-string)
1726 - "type": device type (json-string)
1727 - Possible values: "hd", "cdrom", "floppy", "unknown"
1728 - "removable": true if the device is removable, false otherwise (json-bool)
1729 - "locked": true if the device is locked, false otherwise (json-bool)
1730 - "inserted": only present if the device is inserted, it is a json-object
1731 containing the following:
1732 - "file": device file name (json-string)
1733 - "ro": true if read-only, false otherwise (json-bool)
1734 - "drv": driver format name (json-string)
1735 - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1736 "file", "file", "ftp", "ftps", "host_cdrom",
1737 "host_device", "host_floppy", "http", "https",
1738 "nbd", "parallels", "qcow", "qcow2", "raw",
1739 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1740 - "backing_file": backing file name (json-string, optional)
1741 - "encrypted": true if encrypted, false otherwise (json-bool)
1743 Example:
1745 -> { "execute": "query-block" }
1746 <- {
1747 "return":[
1749 "device":"ide0-hd0",
1750 "locked":false,
1751 "removable":false,
1752 "inserted":{
1753 "ro":false,
1754 "drv":"qcow2",
1755 "encrypted":false,
1756 "file":"disks/test.img"
1758 "type":"hd"
1761 "device":"ide1-cd0",
1762 "locked":false,
1763 "removable":true,
1764 "type":"cdrom"
1767 "device":"floppy0",
1768 "locked":false,
1769 "removable":true,
1770 "type": "floppy"
1773 "device":"sd0",
1774 "locked":false,
1775 "removable":true,
1776 "type":"floppy"
1781 EQMP
1783 STEXI
1784 @item info blockstats
1785 show block device statistics
1786 ETEXI
1787 SQMP
1788 query-blockstats
1789 ----------------
1791 Show block device statistics.
1793 Each device statistic information is stored in a json-object and the returned
1794 value is a json-array of all devices.
1796 Each json-object contain the following:
1798 - "device": device name (json-string)
1799 - "stats": A json-object with the statistics information, it contains:
1800 - "rd_bytes": bytes read (json-int)
1801 - "wr_bytes": bytes written (json-int)
1802 - "rd_operations": read operations (json-int)
1803 - "wr_operations": write operations (json-int)
1804 - "wr_highest_offset": Highest offset of a sector written since the
1805 BlockDriverState has been opened (json-int)
1806 - "parent": Contains recursively the statistics of the underlying
1807 protocol (e.g. the host file for a qcow2 image). If there is
1808 no underlying protocol, this field is omitted
1809 (json-object, optional)
1811 Example:
1813 -> { "execute": "query-blockstats" }
1814 <- {
1815 "return":[
1817 "device":"ide0-hd0",
1818 "parent":{
1819 "stats":{
1820 "wr_highest_offset":3686448128,
1821 "wr_bytes":9786368,
1822 "wr_operations":751,
1823 "rd_bytes":122567168,
1824 "rd_operations":36772
1827 "stats":{
1828 "wr_highest_offset":2821110784,
1829 "wr_bytes":9786368,
1830 "wr_operations":692,
1831 "rd_bytes":122739200,
1832 "rd_operations":36604
1836 "device":"ide1-cd0",
1837 "stats":{
1838 "wr_highest_offset":0,
1839 "wr_bytes":0,
1840 "wr_operations":0,
1841 "rd_bytes":0,
1842 "rd_operations":0
1846 "device":"floppy0",
1847 "stats":{
1848 "wr_highest_offset":0,
1849 "wr_bytes":0,
1850 "wr_operations":0,
1851 "rd_bytes":0,
1852 "rd_operations":0
1856 "device":"sd0",
1857 "stats":{
1858 "wr_highest_offset":0,
1859 "wr_bytes":0,
1860 "wr_operations":0,
1861 "rd_bytes":0,
1862 "rd_operations":0
1868 EQMP
1870 STEXI
1871 @item info registers
1872 show the cpu registers
1873 @item info cpus
1874 show infos for each CPU
1875 ETEXI
1876 SQMP
1877 query-cpus
1878 ----------
1880 Show CPU information.
1882 Return a json-array. Each CPU is represented by a json-object, which contains:
1884 - "CPU": CPU index (json-int)
1885 - "current": true if this is the current CPU, false otherwise (json-bool)
1886 - "halted": true if the cpu is halted, false otherwise (json-bool)
1887 - Current program counter. The key's name depends on the architecture:
1888 "pc": i386/x86_64 (json-int)
1889 "nip": PPC (json-int)
1890 "pc" and "npc": sparc (json-int)
1891 "PC": mips (json-int)
1893 Example:
1895 -> { "execute": "query-cpus" }
1896 <- {
1897 "return":[
1899 "CPU":0,
1900 "current":true,
1901 "halted":false,
1902 "pc":3227107138
1905 "CPU":1,
1906 "current":false,
1907 "halted":true,
1908 "pc":7108165
1913 EQMP
1915 STEXI
1916 @item info history
1917 show the command line history
1918 @item info irq
1919 show the interrupts statistics (if available)
1920 @item info pic
1921 show i8259 (PIC) state
1922 ETEXI
1924 STEXI
1925 @item info pci
1926 show emulated PCI device info
1927 ETEXI
1928 SQMP
1929 query-pci
1930 ---------
1932 PCI buses and devices information.
1934 The returned value is a json-array of all buses. Each bus is represented by
1935 a json-object, which has a key with a json-array of all PCI devices attached
1936 to it. Each device is represented by a json-object.
1938 The bus json-object contains the following:
1940 - "bus": bus number (json-int)
1941 - "devices": a json-array of json-objects, each json-object represents a
1942 PCI device
1944 The PCI device json-object contains the following:
1946 - "bus": identical to the parent's bus number (json-int)
1947 - "slot": slot number (json-int)
1948 - "function": function number (json-int)
1949 - "class_info": a json-object containing:
1950 - "desc": device class description (json-string, optional)
1951 - "class": device class number (json-int)
1952 - "id": a json-object containing:
1953 - "device": device ID (json-int)
1954 - "vendor": vendor ID (json-int)
1955 - "irq": device's IRQ if assigned (json-int, optional)
1956 - "qdev_id": qdev id string (json-string)
1957 - "pci_bridge": It's a json-object, only present if this device is a
1958 PCI bridge, contains:
1959 - "bus": bus number (json-int)
1960 - "secondary": secondary bus number (json-int)
1961 - "subordinate": subordinate bus number (json-int)
1962 - "io_range": I/O memory range information, a json-object with the
1963 following members:
1964 - "base": base address, in bytes (json-int)
1965 - "limit": limit address, in bytes (json-int)
1966 - "memory_range": memory range information, a json-object with the
1967 following members:
1968 - "base": base address, in bytes (json-int)
1969 - "limit": limit address, in bytes (json-int)
1970 - "prefetchable_range": Prefetchable memory range information, a
1971 json-object with the following members:
1972 - "base": base address, in bytes (json-int)
1973 - "limit": limit address, in bytes (json-int)
1974 - "devices": a json-array of PCI devices if there's any attached, each
1975 each element is represented by a json-object, which contains
1976 the same members of the 'PCI device json-object' described
1977 above (optional)
1978 - "regions": a json-array of json-objects, each json-object represents a
1979 memory region of this device
1981 The memory range json-object contains the following:
1983 - "base": base memory address (json-int)
1984 - "limit": limit value (json-int)
1986 The region json-object can be an I/O region or a memory region, an I/O region
1987 json-object contains the following:
1989 - "type": "io" (json-string, fixed)
1990 - "bar": BAR number (json-int)
1991 - "address": memory address (json-int)
1992 - "size": memory size (json-int)
1994 A memory region json-object contains the following:
1996 - "type": "memory" (json-string, fixed)
1997 - "bar": BAR number (json-int)
1998 - "address": memory address (json-int)
1999 - "size": memory size (json-int)
2000 - "mem_type_64": true or false (json-bool)
2001 - "prefetch": true or false (json-bool)
2003 Example:
2005 -> { "execute": "query-pci" }
2006 <- {
2007 "return":[
2009 "bus":0,
2010 "devices":[
2012 "bus":0,
2013 "qdev_id":"",
2014 "slot":0,
2015 "class_info":{
2016 "class":1536,
2017 "desc":"Host bridge"
2019 "id":{
2020 "device":32902,
2021 "vendor":4663
2023 "function":0,
2024 "regions":[
2029 "bus":0,
2030 "qdev_id":"",
2031 "slot":1,
2032 "class_info":{
2033 "class":1537,
2034 "desc":"ISA bridge"
2036 "id":{
2037 "device":32902,
2038 "vendor":28672
2040 "function":0,
2041 "regions":[
2046 "bus":0,
2047 "qdev_id":"",
2048 "slot":1,
2049 "class_info":{
2050 "class":257,
2051 "desc":"IDE controller"
2053 "id":{
2054 "device":32902,
2055 "vendor":28688
2057 "function":1,
2058 "regions":[
2060 "bar":4,
2061 "size":16,
2062 "address":49152,
2063 "type":"io"
2068 "bus":0,
2069 "qdev_id":"",
2070 "slot":2,
2071 "class_info":{
2072 "class":768,
2073 "desc":"VGA controller"
2075 "id":{
2076 "device":4115,
2077 "vendor":184
2079 "function":0,
2080 "regions":[
2082 "prefetch":true,
2083 "mem_type_64":false,
2084 "bar":0,
2085 "size":33554432,
2086 "address":4026531840,
2087 "type":"memory"
2090 "prefetch":false,
2091 "mem_type_64":false,
2092 "bar":1,
2093 "size":4096,
2094 "address":4060086272,
2095 "type":"memory"
2098 "prefetch":false,
2099 "mem_type_64":false,
2100 "bar":6,
2101 "size":65536,
2102 "address":-1,
2103 "type":"memory"
2108 "bus":0,
2109 "qdev_id":"",
2110 "irq":11,
2111 "slot":4,
2112 "class_info":{
2113 "class":1280,
2114 "desc":"RAM controller"
2116 "id":{
2117 "device":6900,
2118 "vendor":4098
2120 "function":0,
2121 "regions":[
2123 "bar":0,
2124 "size":32,
2125 "address":49280,
2126 "type":"io"
2135 Note: This example has been shortened as the real response is too long.
2137 EQMP
2139 STEXI
2140 @item info tlb
2141 show virtual to physical memory mappings (i386 only)
2142 @item info mem
2143 show the active virtual memory mappings (i386 only)
2144 ETEXI
2146 STEXI
2147 @item info hpet
2148 show state of HPET (i386 only)
2149 ETEXI
2150 SQMP
2151 query-hpet
2152 ----------
2154 Show HPET state.
2156 Return a json-object with the following information:
2158 - "enabled": true if hpet if enabled, false otherwise (json-bool)
2160 Example:
2162 -> { "execute": "query-hpet" }
2163 <- { "return": { "enabled": true } }
2165 EQMP
2167 STEXI
2168 @item info jit
2169 show dynamic compiler info
2170 @item info kvm
2171 show KVM information
2172 @item info numa
2173 show NUMA information
2174 ETEXI
2176 STEXI
2177 @item info kvm
2178 show KVM information
2179 ETEXI
2180 SQMP
2181 query-kvm
2182 ---------
2184 Show KVM information.
2186 Return a json-object with the following information:
2188 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
2189 - "present": true if QEMU has KVM support, false otherwise (json-bool)
2191 Example:
2193 -> { "execute": "query-kvm" }
2194 <- { "return": { "enabled": true, "present": true } }
2196 EQMP
2198 STEXI
2199 @item info usb
2200 show USB devices plugged on the virtual USB hub
2201 @item info usbhost
2202 show all USB host devices
2203 @item info profile
2204 show profiling information
2205 @item info capture
2206 show information about active capturing
2207 @item info snapshots
2208 show list of VM snapshots
2209 ETEXI
2211 STEXI
2212 @item info status
2213 show the current VM status (running|paused)
2214 ETEXI
2215 SQMP
2216 query-status
2217 ------------
2219 Return a json-object with the following information:
2221 - "running": true if the VM is running, or false if it is paused (json-bool)
2222 - "singlestep": true if the VM is in single step mode,
2223 false otherwise (json-bool)
2225 Example:
2227 -> { "execute": "query-status" }
2228 <- { "return": { "running": true, "singlestep": false } }
2230 EQMP
2232 STEXI
2233 @item info pcmcia
2234 show guest PCMCIA status
2235 ETEXI
2237 STEXI
2238 @item info mice
2239 show which guest mouse is receiving events
2240 ETEXI
2241 SQMP
2242 query-mice
2243 ----------
2245 Show VM mice information.
2247 Each mouse is represented by a json-object, the returned value is a json-array
2248 of all mice.
2250 The mouse json-object contains the following:
2252 - "name": mouse's name (json-string)
2253 - "index": mouse's index (json-int)
2254 - "current": true if this mouse is receiving events, false otherwise (json-bool)
2255 - "absolute": true if the mouse generates absolute input events (json-bool)
2257 Example:
2259 -> { "execute": "query-mice" }
2260 <- {
2261 "return":[
2263 "name":"QEMU Microsoft Mouse",
2264 "index":0,
2265 "current":false,
2266 "absolute":false
2269 "name":"QEMU PS/2 Mouse",
2270 "index":1,
2271 "current":true,
2272 "absolute":true
2277 EQMP
2279 STEXI
2280 @item info vnc
2281 show the vnc server status
2282 ETEXI
2283 SQMP
2284 query-vnc
2285 ---------
2287 Show VNC server information.
2289 Return a json-object with server information. Connected clients are returned
2290 as a json-array of json-objects.
2292 The main json-object contains the following:
2294 - "enabled": true or false (json-bool)
2295 - "host": server's IP address (json-string)
2296 - "family": address family (json-string)
2297 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2298 - "service": server's port number (json-string)
2299 - "auth": authentication method (json-string)
2300 - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2301 "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2302 "vencrypt+plain", "vencrypt+tls+none",
2303 "vencrypt+tls+plain", "vencrypt+tls+sasl",
2304 "vencrypt+tls+vnc", "vencrypt+x509+none",
2305 "vencrypt+x509+plain", "vencrypt+x509+sasl",
2306 "vencrypt+x509+vnc", "vnc"
2307 - "clients": a json-array of all connected clients
2309 Clients are described by a json-object, each one contain the following:
2311 - "host": client's IP address (json-string)
2312 - "family": address family (json-string)
2313 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2314 - "service": client's port number (json-string)
2315 - "x509_dname": TLS dname (json-string, optional)
2316 - "sasl_username": SASL username (json-string, optional)
2318 Example:
2320 -> { "execute": "query-vnc" }
2321 <- {
2322 "return":{
2323 "enabled":true,
2324 "host":"0.0.0.0",
2325 "service":"50402",
2326 "auth":"vnc",
2327 "family":"ipv4",
2328 "clients":[
2330 "host":"127.0.0.1",
2331 "service":"50401",
2332 "family":"ipv4"
2338 EQMP
2340 STEXI
2341 @item info name
2342 show the current VM name
2343 ETEXI
2344 SQMP
2345 query-name
2346 ----------
2348 Show VM name.
2350 Return a json-object with the following information:
2352 - "name": VM's name (json-string, optional)
2354 Example:
2356 -> { "execute": "query-name" }
2357 <- { "return": { "name": "qemu-name" } }
2359 EQMP
2361 STEXI
2362 @item info uuid
2363 show the current VM UUID
2364 ETEXI
2365 SQMP
2366 query-uuid
2367 ----------
2369 Show VM UUID.
2371 Return a json-object with the following information:
2373 - "UUID": Universally Unique Identifier (json-string)
2375 Example:
2377 -> { "execute": "query-uuid" }
2378 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2380 EQMP
2382 STEXI
2383 @item info cpustats
2384 show CPU statistics
2385 @item info usernet
2386 show user network stack connection states
2387 ETEXI
2389 STEXI
2390 @item info migrate
2391 show migration status
2392 ETEXI
2393 SQMP
2394 query-migrate
2395 -------------
2397 Migration status.
2399 Return a json-object. If migration is active there will be another json-object
2400 with RAM migration status and if block migration is active another one with
2401 block migration status.
2403 The main json-object contains the following:
2405 - "status": migration status (json-string)
2406 - Possible values: "active", "completed", "failed", "cancelled"
2407 - "ram": only present if "status" is "active", it is a json-object with the
2408 following RAM information (in bytes):
2409 - "transferred": amount transferred (json-int)
2410 - "remaining": amount remaining (json-int)
2411 - "total": total (json-int)
2412 - "disk": only present if "status" is "active" and it is a block migration,
2413 it is a json-object with the following disk information (in bytes):
2414 - "transferred": amount transferred (json-int)
2415 - "remaining": amount remaining (json-int)
2416 - "total": total (json-int)
2418 Examples:
2420 1. Before the first migration
2422 -> { "execute": "query-migrate" }
2423 <- { "return": {} }
2425 2. Migration is done and has succeeded
2427 -> { "execute": "query-migrate" }
2428 <- { "return": { "status": "completed" } }
2430 3. Migration is done and has failed
2432 -> { "execute": "query-migrate" }
2433 <- { "return": { "status": "failed" } }
2435 4. Migration is being performed and is not a block migration:
2437 -> { "execute": "query-migrate" }
2438 <- {
2439 "return":{
2440 "status":"active",
2441 "ram":{
2442 "transferred":123,
2443 "remaining":123,
2444 "total":246
2449 5. Migration is being performed and is a block migration:
2451 -> { "execute": "query-migrate" }
2452 <- {
2453 "return":{
2454 "status":"active",
2455 "ram":{
2456 "total":1057024,
2457 "remaining":1053304,
2458 "transferred":3720
2460 "disk":{
2461 "total":20971520,
2462 "remaining":20880384,
2463 "transferred":91136
2468 EQMP
2470 STEXI
2471 @item info balloon
2472 show balloon information
2473 ETEXI
2474 SQMP
2475 query-balloon
2476 -------------
2478 Show balloon information.
2480 Make an asynchronous request for balloon info. When the request completes a
2481 json-object will be returned containing the following data:
2483 - "actual": current balloon value in bytes (json-int)
2484 - "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
2485 - "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
2486 - "major_page_faults": Number of major faults (json-int, optional)
2487 - "minor_page_faults": Number of minor faults (json-int, optional)
2488 - "free_mem": Total amount of free and unused memory in
2489 bytes (json-int, optional)
2490 - "total_mem": Total amount of available memory in bytes (json-int, optional)
2492 Example:
2494 -> { "execute": "query-balloon" }
2495 <- {
2496 "return":{
2497 "actual":1073741824,
2498 "mem_swapped_in":0,
2499 "mem_swapped_out":0,
2500 "major_page_faults":142,
2501 "minor_page_faults":239245,
2502 "free_mem":1014185984,
2503 "total_mem":1044668416
2507 EQMP
2509 STEXI
2510 @item info qtree
2511 show device tree
2512 @item info qdm
2513 show qdev device model list
2514 @item info roms
2515 show roms
2516 @end table
2517 ETEXI
2519 HXCOMM DO NOT add new commands after 'info', move your addition before it!
2521 STEXI
2522 @end table
2523 ETEXI