trace: Add trace-events file for declaring trace events
[qemu/stefanha.git] / qemu-monitor.hx
blob5c1da3398e0678c572af9ff0f2215e0ec3fd218b
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. Stability Considerations
39 ===========================
41 The current QMP command set (described in this file) may be useful for a
42 number of use cases, however it's limited and several commands have bad
43 defined semantics, specially with regard to command completion.
45 These problems are going to be solved incrementally in the next QEMU releases
46 and we're going to establish a deprecation policy for badly defined commands.
48 If you're planning to adopt QMP, please observe the following:
50 1. The deprecation policy will take efect and be documented soon, please
51 check the documentation of each used command as soon as a new release of
52 QEMU is available
54 2. DO NOT rely on anything which is not explicit documented
56 3. Errors, in special, are not documented. Applications should NOT check
57 for specific errors classes or data (it's strongly recommended to only
58 check for the "error" key)
60 2. Regular Commands
61 ===================
63 Server's responses in the examples below are always a success response, please
64 refer to the QMP specification for more details on error responses.
66 EQMP
68 STEXI
69 @table @option
70 ETEXI
73 .name = "help|?",
74 .args_type = "name:s?",
75 .params = "[cmd]",
76 .help = "show the help",
77 .mhandler.cmd = do_help_cmd,
80 STEXI
81 @item help or ? [@var{cmd}]
82 @findex help
83 Show the help for all commands or just for command @var{cmd}.
84 ETEXI
87 .name = "commit",
88 .args_type = "device:B",
89 .params = "device|all",
90 .help = "commit changes to the disk images (if -snapshot is used) or backing files",
91 .mhandler.cmd = do_commit,
94 STEXI
95 @item commit
96 @findex commit
97 Commit changes to the disk images (if -snapshot is used) or backing files.
98 ETEXI
101 .name = "q|quit",
102 .args_type = "",
103 .params = "",
104 .help = "quit the emulator",
105 .user_print = monitor_user_noop,
106 .mhandler.cmd_new = do_quit,
109 STEXI
110 @item q or quit
111 @findex quit
112 Quit the emulator.
113 ETEXI
114 SQMP
115 quit
116 ----
118 Quit the emulator.
120 Arguments: None.
122 Example:
124 -> { "execute": "quit" }
125 <- { "return": {} }
127 EQMP
130 .name = "eject",
131 .args_type = "force:-f,device:B",
132 .params = "[-f] device",
133 .help = "eject a removable medium (use -f to force it)",
134 .user_print = monitor_user_noop,
135 .mhandler.cmd_new = do_eject,
138 STEXI
139 @item eject [-f] @var{device}
140 @findex eject
141 Eject a removable medium (use -f to force it).
142 ETEXI
143 SQMP
144 eject
145 -----
147 Eject a removable medium.
149 Arguments:
151 - force: force ejection (json-bool, optional)
152 - device: device name (json-string)
154 Example:
156 -> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
157 <- { "return": {} }
159 Note: The "force" argument defaults to false.
161 EQMP
164 .name = "change",
165 .args_type = "device:B,target:F,arg:s?",
166 .params = "device filename [format]",
167 .help = "change a removable medium, optional format",
168 .user_print = monitor_user_noop,
169 .mhandler.cmd_new = do_change,
172 STEXI
173 @item change @var{device} @var{setting}
174 @findex change
176 Change the configuration of a device.
178 @table @option
179 @item change @var{diskdevice} @var{filename} [@var{format}]
180 Change the medium for a removable disk device to point to @var{filename}. eg
182 @example
183 (qemu) change ide1-cd0 /path/to/some.iso
184 @end example
186 @var{format} is optional.
188 @item change vnc @var{display},@var{options}
189 Change the configuration of the VNC server. The valid syntax for @var{display}
190 and @var{options} are described at @ref{sec_invocation}. eg
192 @example
193 (qemu) change vnc localhost:1
194 @end example
196 @item change vnc password [@var{password}]
198 Change the password associated with the VNC server. If the new password is not
199 supplied, the monitor will prompt for it to be entered. VNC passwords are only
200 significant up to 8 letters. eg
202 @example
203 (qemu) change vnc password
204 Password: ********
205 @end example
207 @end table
208 ETEXI
209 SQMP
210 change
211 ------
213 Change a removable medium or VNC configuration.
215 Arguments:
217 - "device": device name (json-string)
218 - "target": filename or item (json-string)
219 - "arg": additional argument (json-string, optional)
221 Examples:
223 1. Change a removable medium
225 -> { "execute": "change",
226 "arguments": { "device": "ide1-cd0",
227 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
228 <- { "return": {} }
230 2. Change VNC password
232 -> { "execute": "change",
233 "arguments": { "device": "vnc", "target": "password",
234 "arg": "foobar1" } }
235 <- { "return": {} }
237 EQMP
240 .name = "screendump",
241 .args_type = "filename:F",
242 .params = "filename",
243 .help = "save screen into PPM image 'filename'",
244 .user_print = monitor_user_noop,
245 .mhandler.cmd_new = do_screen_dump,
248 STEXI
249 @item screendump @var{filename}
250 @findex screendump
251 Save screen into PPM image @var{filename}.
252 ETEXI
253 SQMP
254 screendump
255 ----------
257 Save screen into PPM image.
259 Arguments:
261 - "filename": file path (json-string)
263 Example:
265 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
266 <- { "return": {} }
268 EQMP
271 .name = "logfile",
272 .args_type = "filename:F",
273 .params = "filename",
274 .help = "output logs to 'filename'",
275 .mhandler.cmd = do_logfile,
278 STEXI
279 @item logfile @var{filename}
280 @findex logfile
281 Output logs to @var{filename}.
282 ETEXI
285 .name = "log",
286 .args_type = "items:s",
287 .params = "item1[,...]",
288 .help = "activate logging of the specified items to '/tmp/qemu.log'",
289 .mhandler.cmd = do_log,
292 STEXI
293 @item log @var{item1}[,...]
294 @findex log
295 Activate logging of the specified items to @file{/tmp/qemu.log}.
296 ETEXI
299 .name = "savevm",
300 .args_type = "name:s?",
301 .params = "[tag|id]",
302 .help = "save a VM snapshot. If no tag or id are provided, a new snapshot is created",
303 .mhandler.cmd = do_savevm,
306 STEXI
307 @item savevm [@var{tag}|@var{id}]
308 @findex savevm
309 Create a snapshot of the whole virtual machine. If @var{tag} is
310 provided, it is used as human readable identifier. If there is already
311 a snapshot with the same tag or ID, it is replaced. More info at
312 @ref{vm_snapshots}.
313 ETEXI
316 .name = "loadvm",
317 .args_type = "name:s",
318 .params = "tag|id",
319 .help = "restore a VM snapshot from its tag or id",
320 .mhandler.cmd = do_loadvm,
323 STEXI
324 @item loadvm @var{tag}|@var{id}
325 @findex loadvm
326 Set the whole virtual machine to the snapshot identified by the tag
327 @var{tag} or the unique snapshot ID @var{id}.
328 ETEXI
331 .name = "delvm",
332 .args_type = "name:s",
333 .params = "tag|id",
334 .help = "delete a VM snapshot from its tag or id",
335 .mhandler.cmd = do_delvm,
338 STEXI
339 @item delvm @var{tag}|@var{id}
340 @findex delvm
341 Delete the snapshot identified by @var{tag} or @var{id}.
342 ETEXI
345 .name = "singlestep",
346 .args_type = "option:s?",
347 .params = "[on|off]",
348 .help = "run emulation in singlestep mode or switch to normal mode",
349 .mhandler.cmd = do_singlestep,
352 STEXI
353 @item singlestep [off]
354 @findex singlestep
355 Run the emulation in single step mode.
356 If called with option off, the emulation returns to normal mode.
357 ETEXI
360 .name = "stop",
361 .args_type = "",
362 .params = "",
363 .help = "stop emulation",
364 .user_print = monitor_user_noop,
365 .mhandler.cmd_new = do_stop,
368 STEXI
369 @item stop
370 @findex stop
371 Stop emulation.
372 ETEXI
373 SQMP
374 stop
375 ----
377 Stop the emulator.
379 Arguments: None.
381 Example:
383 -> { "execute": "stop" }
384 <- { "return": {} }
386 EQMP
389 .name = "c|cont",
390 .args_type = "",
391 .params = "",
392 .help = "resume emulation",
393 .user_print = monitor_user_noop,
394 .mhandler.cmd_new = do_cont,
397 STEXI
398 @item c or cont
399 @findex cont
400 Resume emulation.
401 ETEXI
402 SQMP
403 cont
404 ----
406 Resume emulation.
408 Arguments: None.
410 Example:
412 -> { "execute": "cont" }
413 <- { "return": {} }
415 EQMP
418 .name = "gdbserver",
419 .args_type = "device:s?",
420 .params = "[device]",
421 .help = "start gdbserver on given device (default 'tcp::1234'), stop with 'none'",
422 .mhandler.cmd = do_gdbserver,
425 STEXI
426 @item gdbserver [@var{port}]
427 @findex gdbserver
428 Start gdbserver session (default @var{port}=1234)
429 ETEXI
432 .name = "x",
433 .args_type = "fmt:/,addr:l",
434 .params = "/fmt addr",
435 .help = "virtual memory dump starting at 'addr'",
436 .mhandler.cmd = do_memory_dump,
439 STEXI
440 @item x/fmt @var{addr}
441 @findex x
442 Virtual memory dump starting at @var{addr}.
443 ETEXI
446 .name = "xp",
447 .args_type = "fmt:/,addr:l",
448 .params = "/fmt addr",
449 .help = "physical memory dump starting at 'addr'",
450 .mhandler.cmd = do_physical_memory_dump,
453 STEXI
454 @item xp /@var{fmt} @var{addr}
455 @findex xp
456 Physical memory dump starting at @var{addr}.
458 @var{fmt} is a format which tells the command how to format the
459 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
461 @table @var
462 @item count
463 is the number of items to be dumped.
465 @item format
466 can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
467 c (char) or i (asm instruction).
469 @item size
470 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
471 @code{h} or @code{w} can be specified with the @code{i} format to
472 respectively select 16 or 32 bit code instruction size.
474 @end table
476 Examples:
477 @itemize
478 @item
479 Dump 10 instructions at the current instruction pointer:
480 @example
481 (qemu) x/10i $eip
482 0x90107063: ret
483 0x90107064: sti
484 0x90107065: lea 0x0(%esi,1),%esi
485 0x90107069: lea 0x0(%edi,1),%edi
486 0x90107070: ret
487 0x90107071: jmp 0x90107080
488 0x90107073: nop
489 0x90107074: nop
490 0x90107075: nop
491 0x90107076: nop
492 @end example
494 @item
495 Dump 80 16 bit values at the start of the video memory.
496 @smallexample
497 (qemu) xp/80hx 0xb8000
498 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
499 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
500 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
501 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
502 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
503 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
504 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
505 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
506 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
507 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
508 @end smallexample
509 @end itemize
510 ETEXI
513 .name = "p|print",
514 .args_type = "fmt:/,val:l",
515 .params = "/fmt expr",
516 .help = "print expression value (use $reg for CPU register access)",
517 .mhandler.cmd = do_print,
520 STEXI
521 @item p or print/@var{fmt} @var{expr}
522 @findex print
524 Print expression value. Only the @var{format} part of @var{fmt} is
525 used.
526 ETEXI
529 .name = "i",
530 .args_type = "fmt:/,addr:i,index:i.",
531 .params = "/fmt addr",
532 .help = "I/O port read",
533 .mhandler.cmd = do_ioport_read,
536 STEXI
537 Read I/O port.
538 ETEXI
541 .name = "o",
542 .args_type = "fmt:/,addr:i,val:i",
543 .params = "/fmt addr value",
544 .help = "I/O port write",
545 .mhandler.cmd = do_ioport_write,
548 STEXI
549 Write to I/O port.
550 ETEXI
553 .name = "sendkey",
554 .args_type = "string:s,hold_time:i?",
555 .params = "keys [hold_ms]",
556 .help = "send keys to the VM (e.g. 'sendkey ctrl-alt-f1', default hold time=100 ms)",
557 .mhandler.cmd = do_sendkey,
560 STEXI
561 @item sendkey @var{keys}
562 @findex sendkey
564 Send @var{keys} to the emulator. @var{keys} could be the name of the
565 key or @code{#} followed by the raw value in either decimal or hexadecimal
566 format. Use @code{-} to press several keys simultaneously. Example:
567 @example
568 sendkey ctrl-alt-f1
569 @end example
571 This command is useful to send keys that your graphical user interface
572 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
573 ETEXI
576 .name = "system_reset",
577 .args_type = "",
578 .params = "",
579 .help = "reset the system",
580 .user_print = monitor_user_noop,
581 .mhandler.cmd_new = do_system_reset,
584 STEXI
585 @item system_reset
586 @findex system_reset
588 Reset the system.
589 ETEXI
590 SQMP
591 system_reset
592 ------------
594 Reset the system.
596 Arguments: None.
598 Example:
600 -> { "execute": "system_reset" }
601 <- { "return": {} }
603 EQMP
606 .name = "system_powerdown",
607 .args_type = "",
608 .params = "",
609 .help = "send system power down event",
610 .user_print = monitor_user_noop,
611 .mhandler.cmd_new = do_system_powerdown,
614 STEXI
615 @item system_powerdown
616 @findex system_powerdown
618 Power down the system (if supported).
619 ETEXI
620 SQMP
621 system_powerdown
622 ----------------
624 Send system power down event.
626 Arguments: None.
628 Example:
630 -> { "execute": "system_powerdown" }
631 <- { "return": {} }
633 EQMP
636 .name = "sum",
637 .args_type = "start:i,size:i",
638 .params = "addr size",
639 .help = "compute the checksum of a memory region",
640 .mhandler.cmd = do_sum,
643 STEXI
644 @item sum @var{addr} @var{size}
645 @findex sum
647 Compute the checksum of a memory region.
648 ETEXI
651 .name = "usb_add",
652 .args_type = "devname:s",
653 .params = "device",
654 .help = "add USB device (e.g. 'host:bus.addr' or 'host:vendor_id:product_id')",
655 .mhandler.cmd = do_usb_add,
658 STEXI
659 @item usb_add @var{devname}
660 @findex usb_add
662 Add the USB device @var{devname}. For details of available devices see
663 @ref{usb_devices}
664 ETEXI
667 .name = "usb_del",
668 .args_type = "devname:s",
669 .params = "device",
670 .help = "remove USB device 'bus.addr'",
671 .mhandler.cmd = do_usb_del,
674 STEXI
675 @item usb_del @var{devname}
676 @findex usb_del
678 Remove the USB device @var{devname} from the QEMU virtual USB
679 hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
680 command @code{info usb} to see the devices you can remove.
681 ETEXI
684 .name = "device_add",
685 .args_type = "device:O",
686 .params = "driver[,prop=value][,...]",
687 .help = "add device, like -device on the command line",
688 .user_print = monitor_user_noop,
689 .mhandler.cmd_new = do_device_add,
692 STEXI
693 @item device_add @var{config}
694 @findex device_add
696 Add device.
697 ETEXI
698 SQMP
699 device_add
700 ----------
702 Add a device.
704 Arguments:
706 - "driver": the name of the new device's driver (json-string)
707 - "bus": the device's parent bus (device tree path, json-string, optional)
708 - "id": the device's ID, must be unique (json-string)
709 - device properties
711 Example:
713 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
714 <- { "return": {} }
716 Notes:
718 (1) For detailed information about this command, please refer to the
719 'docs/qdev-device-use.txt' file.
721 (2) It's possible to list device properties by running QEMU with the
722 "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
724 EQMP
727 .name = "device_del",
728 .args_type = "id:s",
729 .params = "device",
730 .help = "remove device",
731 .user_print = monitor_user_noop,
732 .mhandler.cmd_new = do_device_del,
735 STEXI
736 @item device_del @var{id}
737 @findex device_del
739 Remove device @var{id}.
740 ETEXI
741 SQMP
742 device_del
743 ----------
745 Remove a device.
747 Arguments:
749 - "id": the device's ID (json-string)
751 Example:
753 -> { "execute": "device_del", "arguments": { "id": "net1" } }
754 <- { "return": {} }
756 EQMP
759 .name = "cpu",
760 .args_type = "index:i",
761 .params = "index",
762 .help = "set the default CPU",
763 .user_print = monitor_user_noop,
764 .mhandler.cmd_new = do_cpu_set,
767 STEXI
768 @item cpu @var{index}
769 @findex cpu
770 Set the default CPU.
771 ETEXI
772 SQMP
776 Set the default CPU.
778 Arguments:
780 - "index": the CPU's index (json-int)
782 Example:
784 -> { "execute": "cpu", "arguments": { "index": 0 } }
785 <- { "return": {} }
787 Note: CPUs' indexes are obtained with the 'query-cpus' command.
789 EQMP
792 .name = "mouse_move",
793 .args_type = "dx_str:s,dy_str:s,dz_str:s?",
794 .params = "dx dy [dz]",
795 .help = "send mouse move events",
796 .mhandler.cmd = do_mouse_move,
799 STEXI
800 @item mouse_move @var{dx} @var{dy} [@var{dz}]
801 @findex mouse_move
802 Move the active mouse to the specified coordinates @var{dx} @var{dy}
803 with optional scroll axis @var{dz}.
804 ETEXI
807 .name = "mouse_button",
808 .args_type = "button_state:i",
809 .params = "state",
810 .help = "change mouse button state (1=L, 2=M, 4=R)",
811 .mhandler.cmd = do_mouse_button,
814 STEXI
815 @item mouse_button @var{val}
816 @findex mouse_button
817 Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
818 ETEXI
821 .name = "mouse_set",
822 .args_type = "index:i",
823 .params = "index",
824 .help = "set which mouse device receives events",
825 .mhandler.cmd = do_mouse_set,
828 STEXI
829 @item mouse_set @var{index}
830 @findex mouse_set
831 Set which mouse device receives events at given @var{index}, index
832 can be obtained with
833 @example
834 info mice
835 @end example
836 ETEXI
838 #ifdef HAS_AUDIO
840 .name = "wavcapture",
841 .args_type = "path:F,freq:i?,bits:i?,nchannels:i?",
842 .params = "path [frequency [bits [channels]]]",
843 .help = "capture audio to a wave file (default frequency=44100 bits=16 channels=2)",
844 .mhandler.cmd = do_wav_capture,
846 #endif
847 STEXI
848 @item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
849 @findex wavcapture
850 Capture audio into @var{filename}. Using sample rate @var{frequency}
851 bits per sample @var{bits} and number of channels @var{channels}.
853 Defaults:
854 @itemize @minus
855 @item Sample rate = 44100 Hz - CD quality
856 @item Bits = 16
857 @item Number of channels = 2 - Stereo
858 @end itemize
859 ETEXI
861 #ifdef HAS_AUDIO
863 .name = "stopcapture",
864 .args_type = "n:i",
865 .params = "capture index",
866 .help = "stop capture",
867 .mhandler.cmd = do_stop_capture,
869 #endif
870 STEXI
871 @item stopcapture @var{index}
872 @findex stopcapture
873 Stop capture with a given @var{index}, index can be obtained with
874 @example
875 info capture
876 @end example
877 ETEXI
880 .name = "memsave",
881 .args_type = "val:l,size:i,filename:s",
882 .params = "addr size file",
883 .help = "save to disk virtual memory dump starting at 'addr' of size 'size'",
884 .user_print = monitor_user_noop,
885 .mhandler.cmd_new = do_memory_save,
888 STEXI
889 @item memsave @var{addr} @var{size} @var{file}
890 @findex memsave
891 save to disk virtual memory dump starting at @var{addr} of size @var{size}.
892 ETEXI
893 SQMP
894 memsave
895 -------
897 Save to disk virtual memory dump starting at 'val' of size 'size'.
899 Arguments:
901 - "val": the starting address (json-int)
902 - "size": the memory size, in bytes (json-int)
903 - "filename": file path (json-string)
905 Example:
907 -> { "execute": "memsave",
908 "arguments": { "val": 10,
909 "size": 100,
910 "filename": "/tmp/virtual-mem-dump" } }
911 <- { "return": {} }
913 Note: Depends on the current CPU.
915 EQMP
918 .name = "pmemsave",
919 .args_type = "val:l,size:i,filename:s",
920 .params = "addr size file",
921 .help = "save to disk physical memory dump starting at 'addr' of size 'size'",
922 .user_print = monitor_user_noop,
923 .mhandler.cmd_new = do_physical_memory_save,
926 STEXI
927 @item pmemsave @var{addr} @var{size} @var{file}
928 @findex pmemsave
929 save to disk physical memory dump starting at @var{addr} of size @var{size}.
930 ETEXI
931 SQMP
932 pmemsave
933 --------
935 Save to disk physical memory dump starting at 'val' of size 'size'.
937 Arguments:
939 - "val": the starting address (json-int)
940 - "size": the memory size, in bytes (json-int)
941 - "filename": file path (json-string)
943 Example:
945 -> { "execute": "pmemsave",
946 "arguments": { "val": 10,
947 "size": 100,
948 "filename": "/tmp/physical-mem-dump" } }
949 <- { "return": {} }
951 EQMP
954 .name = "boot_set",
955 .args_type = "bootdevice:s",
956 .params = "bootdevice",
957 .help = "define new values for the boot device list",
958 .mhandler.cmd = do_boot_set,
961 STEXI
962 @item boot_set @var{bootdevicelist}
963 @findex boot_set
965 Define new values for the boot device list. Those values will override
966 the values specified on the command line through the @code{-boot} option.
968 The values that can be specified here depend on the machine type, but are
969 the same that can be specified in the @code{-boot} command line option.
970 ETEXI
972 #if defined(TARGET_I386)
974 .name = "nmi",
975 .args_type = "cpu_index:i",
976 .params = "cpu",
977 .help = "inject an NMI on the given CPU",
978 .mhandler.cmd = do_inject_nmi,
980 #endif
981 STEXI
982 @item nmi @var{cpu}
983 @findex nmi
984 Inject an NMI on the given CPU (x86 only).
985 ETEXI
988 .name = "migrate",
989 .args_type = "detach:-d,blk:-b,inc:-i,uri:s",
990 .params = "[-d] [-b] [-i] uri",
991 .help = "migrate to URI (using -d to not wait for completion)"
992 "\n\t\t\t -b for migration without shared storage with"
993 " full copy of disk\n\t\t\t -i for migration without "
994 "shared storage with incremental copy of disk "
995 "(base image shared between src and destination)",
996 .user_print = monitor_user_noop,
997 .mhandler.cmd_new = do_migrate,
1001 STEXI
1002 @item migrate [-d] [-b] [-i] @var{uri}
1003 @findex migrate
1004 Migrate to @var{uri} (using -d to not wait for completion).
1005 -b for migration with full copy of disk
1006 -i for migration with incremental copy of disk (base image is shared)
1007 ETEXI
1008 SQMP
1009 migrate
1010 -------
1012 Migrate to URI.
1014 Arguments:
1016 - "blk": block migration, full disk copy (json-bool, optional)
1017 - "inc": incremental disk copy (json-bool, optional)
1018 - "uri": Destination URI (json-string)
1020 Example:
1022 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
1023 <- { "return": {} }
1025 Notes:
1027 (1) The 'query-migrate' command should be used to check migration's progress
1028 and final result (this information is provided by the 'status' member)
1029 (2) All boolean arguments default to false
1030 (3) The user Monitor's "detach" argument is invalid in QMP and should not
1031 be used
1033 EQMP
1036 .name = "migrate_cancel",
1037 .args_type = "",
1038 .params = "",
1039 .help = "cancel the current VM migration",
1040 .user_print = monitor_user_noop,
1041 .mhandler.cmd_new = do_migrate_cancel,
1044 STEXI
1045 @item migrate_cancel
1046 @findex migrate_cancel
1047 Cancel the current VM migration.
1048 ETEXI
1049 SQMP
1050 migrate_cancel
1051 --------------
1053 Cancel the current migration.
1055 Arguments: None.
1057 Example:
1059 -> { "execute": "migrate_cancel" }
1060 <- { "return": {} }
1062 EQMP
1065 .name = "migrate_set_speed",
1066 .args_type = "value:f",
1067 .params = "value",
1068 .help = "set maximum speed (in bytes) for migrations",
1069 .user_print = monitor_user_noop,
1070 .mhandler.cmd_new = do_migrate_set_speed,
1073 STEXI
1074 @item migrate_set_speed @var{value}
1075 @findex migrate_set_speed
1076 Set maximum speed to @var{value} (in bytes) for migrations.
1077 ETEXI
1078 SQMP
1079 migrate_set_speed
1080 -----------------
1082 Set maximum speed for migrations.
1084 Arguments:
1086 - "value": maximum speed, in bytes per second (json-number)
1088 Example:
1090 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
1091 <- { "return": {} }
1093 EQMP
1096 .name = "migrate_set_downtime",
1097 .args_type = "value:T",
1098 .params = "value",
1099 .help = "set maximum tolerated downtime (in seconds) for migrations",
1100 .user_print = monitor_user_noop,
1101 .mhandler.cmd_new = do_migrate_set_downtime,
1104 STEXI
1105 @item migrate_set_downtime @var{second}
1106 @findex migrate_set_downtime
1107 Set maximum tolerated downtime (in seconds) for migration.
1108 ETEXI
1109 SQMP
1110 migrate_set_downtime
1111 --------------------
1113 Set maximum tolerated downtime (in seconds) for migrations.
1115 Arguments:
1117 - "value": maximum downtime (json-number)
1119 Example:
1121 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
1122 <- { "return": {} }
1124 EQMP
1126 #if defined(TARGET_I386)
1128 .name = "drive_add",
1129 .args_type = "pci_addr:s,opts:s",
1130 .params = "[[<domain>:]<bus>:]<slot>\n"
1131 "[file=file][,if=type][,bus=n]\n"
1132 "[,unit=m][,media=d][index=i]\n"
1133 "[,cyls=c,heads=h,secs=s[,trans=t]]\n"
1134 "[snapshot=on|off][,cache=on|off]",
1135 .help = "add drive to PCI storage controller",
1136 .mhandler.cmd = drive_hot_add,
1138 #endif
1140 STEXI
1141 @item drive_add
1142 @findex drive_add
1143 Add drive to PCI storage controller.
1144 ETEXI
1146 #if defined(TARGET_I386)
1148 .name = "pci_add",
1149 .args_type = "pci_addr:s,type:s,opts:s?",
1150 .params = "auto|[[<domain>:]<bus>:]<slot> nic|storage [[vlan=n][,macaddr=addr][,model=type]] [file=file][,if=type][,bus=nr]...",
1151 .help = "hot-add PCI device",
1152 .mhandler.cmd = pci_device_hot_add,
1154 #endif
1156 STEXI
1157 @item pci_add
1158 @findex pci_add
1159 Hot-add PCI device.
1160 ETEXI
1162 #if defined(TARGET_I386)
1164 .name = "pci_del",
1165 .args_type = "pci_addr:s",
1166 .params = "[[<domain>:]<bus>:]<slot>",
1167 .help = "hot remove PCI device",
1168 .mhandler.cmd = do_pci_device_hot_remove,
1170 #endif
1172 STEXI
1173 @item pci_del
1174 @findex pci_del
1175 Hot remove PCI device.
1176 ETEXI
1179 .name = "host_net_add",
1180 .args_type = "device:s,opts:s?",
1181 .params = "tap|user|socket|vde|dump [options]",
1182 .help = "add host VLAN client",
1183 .mhandler.cmd = net_host_device_add,
1186 STEXI
1187 @item host_net_add
1188 @findex host_net_add
1189 Add host VLAN client.
1190 ETEXI
1193 .name = "host_net_remove",
1194 .args_type = "vlan_id:i,device:s",
1195 .params = "vlan_id name",
1196 .help = "remove host VLAN client",
1197 .mhandler.cmd = net_host_device_remove,
1200 STEXI
1201 @item host_net_remove
1202 @findex host_net_remove
1203 Remove host VLAN client.
1204 ETEXI
1207 .name = "netdev_add",
1208 .args_type = "netdev:O",
1209 .params = "[user|tap|socket],id=str[,prop=value][,...]",
1210 .help = "add host network device",
1211 .user_print = monitor_user_noop,
1212 .mhandler.cmd_new = do_netdev_add,
1215 STEXI
1216 @item netdev_add
1217 @findex netdev_add
1218 Add host network device.
1219 ETEXI
1220 SQMP
1221 netdev_add
1222 ----------
1224 Add host network device.
1226 Arguments:
1228 - "type": the device type, "tap", "user", ... (json-string)
1229 - "id": the device's ID, must be unique (json-string)
1230 - device options
1232 Example:
1234 -> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
1235 <- { "return": {} }
1237 Note: The supported device options are the same ones supported by the '-net'
1238 command-line argument, which are listed in the '-help' output or QEMU's
1239 manual
1241 EQMP
1244 .name = "netdev_del",
1245 .args_type = "id:s",
1246 .params = "id",
1247 .help = "remove host network device",
1248 .user_print = monitor_user_noop,
1249 .mhandler.cmd_new = do_netdev_del,
1252 STEXI
1253 @item netdev_del
1254 @findex netdev_del
1255 Remove host network device.
1256 ETEXI
1257 SQMP
1258 netdev_del
1259 ----------
1261 Remove host network device.
1263 Arguments:
1265 - "id": the device's ID, must be unique (json-string)
1267 Example:
1269 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
1270 <- { "return": {} }
1272 EQMP
1274 #ifdef CONFIG_SLIRP
1276 .name = "hostfwd_add",
1277 .args_type = "arg1:s,arg2:s?,arg3:s?",
1278 .params = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport",
1279 .help = "redirect TCP or UDP connections from host to guest (requires -net user)",
1280 .mhandler.cmd = net_slirp_hostfwd_add,
1282 #endif
1283 STEXI
1284 @item hostfwd_add
1285 @findex hostfwd_add
1286 Redirect TCP or UDP connections from host to guest (requires -net user).
1287 ETEXI
1289 #ifdef CONFIG_SLIRP
1291 .name = "hostfwd_remove",
1292 .args_type = "arg1:s,arg2:s?,arg3:s?",
1293 .params = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport",
1294 .help = "remove host-to-guest TCP or UDP redirection",
1295 .mhandler.cmd = net_slirp_hostfwd_remove,
1298 #endif
1299 STEXI
1300 @item hostfwd_remove
1301 @findex hostfwd_remove
1302 Remove host-to-guest TCP or UDP redirection.
1303 ETEXI
1306 .name = "balloon",
1307 .args_type = "value:M",
1308 .params = "target",
1309 .help = "request VM to change its memory allocation (in MB)",
1310 .user_print = monitor_user_noop,
1311 .mhandler.cmd_async = do_balloon,
1312 .flags = MONITOR_CMD_ASYNC,
1315 STEXI
1316 @item balloon @var{value}
1317 @findex balloon
1318 Request VM to change its memory allocation to @var{value} (in MB).
1319 ETEXI
1320 SQMP
1321 balloon
1322 -------
1324 Request VM to change its memory allocation (in bytes).
1326 Arguments:
1328 - "value": New memory allocation (json-int)
1330 Example:
1332 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1333 <- { "return": {} }
1335 EQMP
1338 .name = "set_link",
1339 .args_type = "name:s,up:b",
1340 .params = "name on|off",
1341 .help = "change the link status of a network adapter",
1342 .user_print = monitor_user_noop,
1343 .mhandler.cmd_new = do_set_link,
1346 STEXI
1347 @item set_link @var{name} [on|off]
1348 @findex set_link
1349 Switch link @var{name} on (i.e. up) or off (i.e. down).
1350 ETEXI
1351 SQMP
1352 set_link
1353 --------
1355 Change the link status of a network adapter.
1357 Arguments:
1359 - "name": network device name (json-string)
1360 - "up": status is up (json-bool)
1362 Example:
1364 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1365 <- { "return": {} }
1367 EQMP
1370 .name = "watchdog_action",
1371 .args_type = "action:s",
1372 .params = "[reset|shutdown|poweroff|pause|debug|none]",
1373 .help = "change watchdog action",
1374 .mhandler.cmd = do_watchdog_action,
1377 STEXI
1378 @item watchdog_action
1379 @findex watchdog_action
1380 Change watchdog action.
1381 ETEXI
1384 .name = "acl_show",
1385 .args_type = "aclname:s",
1386 .params = "aclname",
1387 .help = "list rules in the access control list",
1388 .mhandler.cmd = do_acl_show,
1391 STEXI
1392 @item acl_show @var{aclname}
1393 @findex acl_show
1394 List all the matching rules in the access control list, and the default
1395 policy. There are currently two named access control lists,
1396 @var{vnc.x509dname} and @var{vnc.username} matching on the x509 client
1397 certificate distinguished name, and SASL username respectively.
1398 ETEXI
1401 .name = "acl_policy",
1402 .args_type = "aclname:s,policy:s",
1403 .params = "aclname allow|deny",
1404 .help = "set default access control list policy",
1405 .mhandler.cmd = do_acl_policy,
1408 STEXI
1409 @item acl_policy @var{aclname} @code{allow|deny}
1410 @findex acl_policy
1411 Set the default access control list policy, used in the event that
1412 none of the explicit rules match. The default policy at startup is
1413 always @code{deny}.
1414 ETEXI
1417 .name = "acl_add",
1418 .args_type = "aclname:s,match:s,policy:s,index:i?",
1419 .params = "aclname match allow|deny [index]",
1420 .help = "add a match rule to the access control list",
1421 .mhandler.cmd = do_acl_add,
1424 STEXI
1425 @item acl_add @var{aclname} @var{match} @code{allow|deny} [@var{index}]
1426 @findex acl_add
1427 Add a match rule to the access control list, allowing or denying access.
1428 The match will normally be an exact username or x509 distinguished name,
1429 but can optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to
1430 allow all users in the @code{EXAMPLE.COM} kerberos realm. The match will
1431 normally be appended to the end of the ACL, but can be inserted
1432 earlier in the list if the optional @var{index} parameter is supplied.
1433 ETEXI
1436 .name = "acl_remove",
1437 .args_type = "aclname:s,match:s",
1438 .params = "aclname match",
1439 .help = "remove a match rule from the access control list",
1440 .mhandler.cmd = do_acl_remove,
1443 STEXI
1444 @item acl_remove @var{aclname} @var{match}
1445 @findex acl_remove
1446 Remove the specified match rule from the access control list.
1447 ETEXI
1450 .name = "acl_reset",
1451 .args_type = "aclname:s",
1452 .params = "aclname",
1453 .help = "reset the access control list",
1454 .mhandler.cmd = do_acl_reset,
1457 STEXI
1458 @item acl_reset @var{aclname}
1459 @findex acl_reset
1460 Remove all matches from the access control list, and set the default
1461 policy back to @code{deny}.
1462 ETEXI
1464 #if defined(TARGET_I386)
1467 .name = "mce",
1468 .args_type = "cpu_index:i,bank:i,status:l,mcg_status:l,addr:l,misc:l",
1469 .params = "cpu bank status mcgstatus addr misc",
1470 .help = "inject a MCE on the given CPU",
1471 .mhandler.cmd = do_inject_mce,
1474 #endif
1475 STEXI
1476 @item mce @var{cpu} @var{bank} @var{status} @var{mcgstatus} @var{addr} @var{misc}
1477 @findex mce (x86)
1478 Inject an MCE on the given CPU (x86 only).
1479 ETEXI
1482 .name = "getfd",
1483 .args_type = "fdname:s",
1484 .params = "getfd name",
1485 .help = "receive a file descriptor via SCM rights and assign it a name",
1486 .user_print = monitor_user_noop,
1487 .mhandler.cmd_new = do_getfd,
1490 STEXI
1491 @item getfd @var{fdname}
1492 @findex getfd
1493 If a file descriptor is passed alongside this command using the SCM_RIGHTS
1494 mechanism on unix sockets, it is stored using the name @var{fdname} for
1495 later use by other monitor commands.
1496 ETEXI
1497 SQMP
1498 getfd
1499 -----
1501 Receive a file descriptor via SCM rights and assign it a name.
1503 Arguments:
1505 - "fdname": file descriptor name (json-string)
1507 Example:
1509 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1510 <- { "return": {} }
1512 EQMP
1515 .name = "closefd",
1516 .args_type = "fdname:s",
1517 .params = "closefd name",
1518 .help = "close a file descriptor previously passed via SCM rights",
1519 .user_print = monitor_user_noop,
1520 .mhandler.cmd_new = do_closefd,
1523 STEXI
1524 @item closefd @var{fdname}
1525 @findex closefd
1526 Close the file descriptor previously assigned to @var{fdname} using the
1527 @code{getfd} command. This is only needed if the file descriptor was never
1528 used by another monitor command.
1529 ETEXI
1530 SQMP
1531 closefd
1532 -------
1534 Close a file descriptor previously passed via SCM rights.
1536 Arguments:
1538 - "fdname": file descriptor name (json-string)
1540 Example:
1542 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1543 <- { "return": {} }
1545 EQMP
1548 .name = "block_passwd",
1549 .args_type = "device:B,password:s",
1550 .params = "block_passwd device password",
1551 .help = "set the password of encrypted block devices",
1552 .user_print = monitor_user_noop,
1553 .mhandler.cmd_new = do_block_set_passwd,
1556 STEXI
1557 @item block_passwd @var{device} @var{password}
1558 @findex block_passwd
1559 Set the encrypted device @var{device} password to @var{password}
1560 ETEXI
1561 SQMP
1562 block_passwd
1563 ------------
1565 Set the password of encrypted block devices.
1567 Arguments:
1569 - "device": device name (json-string)
1570 - "password": password (json-string)
1572 Example:
1574 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1575 "password": "12345" } }
1576 <- { "return": {} }
1578 EQMP
1581 .name = "qmp_capabilities",
1582 .args_type = "",
1583 .params = "",
1584 .help = "enable QMP capabilities",
1585 .user_print = monitor_user_noop,
1586 .mhandler.cmd_new = do_qmp_capabilities,
1589 STEXI
1590 @item qmp_capabilities
1591 @findex qmp_capabilities
1592 Enable the specified QMP capabilities
1593 ETEXI
1594 SQMP
1595 qmp_capabilities
1596 ----------------
1598 Enable QMP capabilities.
1600 Arguments: None.
1602 Example:
1604 -> { "execute": "qmp_capabilities" }
1605 <- { "return": {} }
1607 Note: This command must be issued before issuing any other command.
1609 EQMP
1612 HXCOMM Keep the 'info' command at the end!
1613 HXCOMM This is required for the QMP documentation layout.
1615 SQMP
1617 3. Query Commands
1618 =================
1620 EQMP
1623 .name = "info",
1624 .args_type = "item:s?",
1625 .params = "[subcommand]",
1626 .help = "show various information about the system state",
1627 .user_print = monitor_user_noop,
1628 .mhandler.cmd_new = do_info,
1631 STEXI
1632 @item info @var{subcommand}
1633 @findex info
1634 Show various information about the system state.
1636 @table @option
1637 @item info version
1638 show the version of QEMU
1639 ETEXI
1640 SQMP
1641 query-version
1642 -------------
1644 Show QEMU version.
1646 Return a json-object with the following information:
1648 - "qemu": A json-object containing three integer values:
1649 - "major": QEMU's major version (json-int)
1650 - "minor": QEMU's minor version (json-int)
1651 - "micro": QEMU's micro version (json-int)
1652 - "package": package's version (json-string)
1654 Example:
1656 -> { "execute": "query-version" }
1657 <- {
1658 "return":{
1659 "qemu":{
1660 "major":0,
1661 "minor":11,
1662 "micro":5
1664 "package":""
1668 EQMP
1670 STEXI
1671 @item info commands
1672 list QMP available commands
1673 ETEXI
1674 SQMP
1675 query-commands
1676 --------------
1678 List QMP available commands.
1680 Each command is represented by a json-object, the returned value is a json-array
1681 of all commands.
1683 Each json-object contain:
1685 - "name": command's name (json-string)
1687 Example:
1689 -> { "execute": "query-commands" }
1690 <- {
1691 "return":[
1693 "name":"query-balloon"
1696 "name":"system_powerdown"
1701 Note: This example has been shortened as the real response is too long.
1703 EQMP
1705 STEXI
1706 @item info network
1707 show the various VLANs and the associated devices
1708 ETEXI
1710 STEXI
1711 @item info chardev
1712 show the character devices
1713 ETEXI
1714 SQMP
1715 query-chardev
1716 -------------
1718 Each device is represented by a json-object. The returned value is a json-array
1719 of all devices.
1721 Each json-object contain the following:
1723 - "label": device's label (json-string)
1724 - "filename": device's file (json-string)
1726 Example:
1728 -> { "execute": "query-chardev" }
1729 <- {
1730 "return":[
1732 "label":"monitor",
1733 "filename":"stdio"
1736 "label":"serial0",
1737 "filename":"vc"
1742 EQMP
1744 STEXI
1745 @item info block
1746 show the block devices
1747 ETEXI
1748 SQMP
1749 query-block
1750 -----------
1752 Show the block devices.
1754 Each block device information is stored in a json-object and the returned value
1755 is a json-array of all devices.
1757 Each json-object contain the following:
1759 - "device": device name (json-string)
1760 - "type": device type (json-string)
1761 - Possible values: "hd", "cdrom", "floppy", "unknown"
1762 - "removable": true if the device is removable, false otherwise (json-bool)
1763 - "locked": true if the device is locked, false otherwise (json-bool)
1764 - "inserted": only present if the device is inserted, it is a json-object
1765 containing the following:
1766 - "file": device file name (json-string)
1767 - "ro": true if read-only, false otherwise (json-bool)
1768 - "drv": driver format name (json-string)
1769 - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1770 "file", "file", "ftp", "ftps", "host_cdrom",
1771 "host_device", "host_floppy", "http", "https",
1772 "nbd", "parallels", "qcow", "qcow2", "raw",
1773 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1774 - "backing_file": backing file name (json-string, optional)
1775 - "encrypted": true if encrypted, false otherwise (json-bool)
1777 Example:
1779 -> { "execute": "query-block" }
1780 <- {
1781 "return":[
1783 "device":"ide0-hd0",
1784 "locked":false,
1785 "removable":false,
1786 "inserted":{
1787 "ro":false,
1788 "drv":"qcow2",
1789 "encrypted":false,
1790 "file":"disks/test.img"
1792 "type":"hd"
1795 "device":"ide1-cd0",
1796 "locked":false,
1797 "removable":true,
1798 "type":"cdrom"
1801 "device":"floppy0",
1802 "locked":false,
1803 "removable":true,
1804 "type": "floppy"
1807 "device":"sd0",
1808 "locked":false,
1809 "removable":true,
1810 "type":"floppy"
1815 EQMP
1817 STEXI
1818 @item info blockstats
1819 show block device statistics
1820 ETEXI
1821 SQMP
1822 query-blockstats
1823 ----------------
1825 Show block device statistics.
1827 Each device statistic information is stored in a json-object and the returned
1828 value is a json-array of all devices.
1830 Each json-object contain the following:
1832 - "device": device name (json-string)
1833 - "stats": A json-object with the statistics information, it contains:
1834 - "rd_bytes": bytes read (json-int)
1835 - "wr_bytes": bytes written (json-int)
1836 - "rd_operations": read operations (json-int)
1837 - "wr_operations": write operations (json-int)
1838 - "wr_highest_offset": Highest offset of a sector written since the
1839 BlockDriverState has been opened (json-int)
1840 - "parent": Contains recursively the statistics of the underlying
1841 protocol (e.g. the host file for a qcow2 image). If there is
1842 no underlying protocol, this field is omitted
1843 (json-object, optional)
1845 Example:
1847 -> { "execute": "query-blockstats" }
1848 <- {
1849 "return":[
1851 "device":"ide0-hd0",
1852 "parent":{
1853 "stats":{
1854 "wr_highest_offset":3686448128,
1855 "wr_bytes":9786368,
1856 "wr_operations":751,
1857 "rd_bytes":122567168,
1858 "rd_operations":36772
1861 "stats":{
1862 "wr_highest_offset":2821110784,
1863 "wr_bytes":9786368,
1864 "wr_operations":692,
1865 "rd_bytes":122739200,
1866 "rd_operations":36604
1870 "device":"ide1-cd0",
1871 "stats":{
1872 "wr_highest_offset":0,
1873 "wr_bytes":0,
1874 "wr_operations":0,
1875 "rd_bytes":0,
1876 "rd_operations":0
1880 "device":"floppy0",
1881 "stats":{
1882 "wr_highest_offset":0,
1883 "wr_bytes":0,
1884 "wr_operations":0,
1885 "rd_bytes":0,
1886 "rd_operations":0
1890 "device":"sd0",
1891 "stats":{
1892 "wr_highest_offset":0,
1893 "wr_bytes":0,
1894 "wr_operations":0,
1895 "rd_bytes":0,
1896 "rd_operations":0
1902 EQMP
1904 STEXI
1905 @item info registers
1906 show the cpu registers
1907 @item info cpus
1908 show infos for each CPU
1909 ETEXI
1910 SQMP
1911 query-cpus
1912 ----------
1914 Show CPU information.
1916 Return a json-array. Each CPU is represented by a json-object, which contains:
1918 - "CPU": CPU index (json-int)
1919 - "current": true if this is the current CPU, false otherwise (json-bool)
1920 - "halted": true if the cpu is halted, false otherwise (json-bool)
1921 - Current program counter. The key's name depends on the architecture:
1922 "pc": i386/x86_64 (json-int)
1923 "nip": PPC (json-int)
1924 "pc" and "npc": sparc (json-int)
1925 "PC": mips (json-int)
1927 Example:
1929 -> { "execute": "query-cpus" }
1930 <- {
1931 "return":[
1933 "CPU":0,
1934 "current":true,
1935 "halted":false,
1936 "pc":3227107138
1939 "CPU":1,
1940 "current":false,
1941 "halted":true,
1942 "pc":7108165
1947 EQMP
1949 STEXI
1950 @item info history
1951 show the command line history
1952 @item info irq
1953 show the interrupts statistics (if available)
1954 @item info pic
1955 show i8259 (PIC) state
1956 ETEXI
1958 STEXI
1959 @item info pci
1960 show emulated PCI device info
1961 ETEXI
1962 SQMP
1963 query-pci
1964 ---------
1966 PCI buses and devices information.
1968 The returned value is a json-array of all buses. Each bus is represented by
1969 a json-object, which has a key with a json-array of all PCI devices attached
1970 to it. Each device is represented by a json-object.
1972 The bus json-object contains the following:
1974 - "bus": bus number (json-int)
1975 - "devices": a json-array of json-objects, each json-object represents a
1976 PCI device
1978 The PCI device json-object contains the following:
1980 - "bus": identical to the parent's bus number (json-int)
1981 - "slot": slot number (json-int)
1982 - "function": function number (json-int)
1983 - "class_info": a json-object containing:
1984 - "desc": device class description (json-string, optional)
1985 - "class": device class number (json-int)
1986 - "id": a json-object containing:
1987 - "device": device ID (json-int)
1988 - "vendor": vendor ID (json-int)
1989 - "irq": device's IRQ if assigned (json-int, optional)
1990 - "qdev_id": qdev id string (json-string)
1991 - "pci_bridge": It's a json-object, only present if this device is a
1992 PCI bridge, contains:
1993 - "bus": bus number (json-int)
1994 - "secondary": secondary bus number (json-int)
1995 - "subordinate": subordinate bus number (json-int)
1996 - "io_range": I/O memory range information, a json-object with the
1997 following members:
1998 - "base": base address, in bytes (json-int)
1999 - "limit": limit address, in bytes (json-int)
2000 - "memory_range": memory range information, a json-object with the
2001 following members:
2002 - "base": base address, in bytes (json-int)
2003 - "limit": limit address, in bytes (json-int)
2004 - "prefetchable_range": Prefetchable memory range information, a
2005 json-object with the following members:
2006 - "base": base address, in bytes (json-int)
2007 - "limit": limit address, in bytes (json-int)
2008 - "devices": a json-array of PCI devices if there's any attached, each
2009 each element is represented by a json-object, which contains
2010 the same members of the 'PCI device json-object' described
2011 above (optional)
2012 - "regions": a json-array of json-objects, each json-object represents a
2013 memory region of this device
2015 The memory range json-object contains the following:
2017 - "base": base memory address (json-int)
2018 - "limit": limit value (json-int)
2020 The region json-object can be an I/O region or a memory region, an I/O region
2021 json-object contains the following:
2023 - "type": "io" (json-string, fixed)
2024 - "bar": BAR number (json-int)
2025 - "address": memory address (json-int)
2026 - "size": memory size (json-int)
2028 A memory region json-object contains the following:
2030 - "type": "memory" (json-string, fixed)
2031 - "bar": BAR number (json-int)
2032 - "address": memory address (json-int)
2033 - "size": memory size (json-int)
2034 - "mem_type_64": true or false (json-bool)
2035 - "prefetch": true or false (json-bool)
2037 Example:
2039 -> { "execute": "query-pci" }
2040 <- {
2041 "return":[
2043 "bus":0,
2044 "devices":[
2046 "bus":0,
2047 "qdev_id":"",
2048 "slot":0,
2049 "class_info":{
2050 "class":1536,
2051 "desc":"Host bridge"
2053 "id":{
2054 "device":32902,
2055 "vendor":4663
2057 "function":0,
2058 "regions":[
2063 "bus":0,
2064 "qdev_id":"",
2065 "slot":1,
2066 "class_info":{
2067 "class":1537,
2068 "desc":"ISA bridge"
2070 "id":{
2071 "device":32902,
2072 "vendor":28672
2074 "function":0,
2075 "regions":[
2080 "bus":0,
2081 "qdev_id":"",
2082 "slot":1,
2083 "class_info":{
2084 "class":257,
2085 "desc":"IDE controller"
2087 "id":{
2088 "device":32902,
2089 "vendor":28688
2091 "function":1,
2092 "regions":[
2094 "bar":4,
2095 "size":16,
2096 "address":49152,
2097 "type":"io"
2102 "bus":0,
2103 "qdev_id":"",
2104 "slot":2,
2105 "class_info":{
2106 "class":768,
2107 "desc":"VGA controller"
2109 "id":{
2110 "device":4115,
2111 "vendor":184
2113 "function":0,
2114 "regions":[
2116 "prefetch":true,
2117 "mem_type_64":false,
2118 "bar":0,
2119 "size":33554432,
2120 "address":4026531840,
2121 "type":"memory"
2124 "prefetch":false,
2125 "mem_type_64":false,
2126 "bar":1,
2127 "size":4096,
2128 "address":4060086272,
2129 "type":"memory"
2132 "prefetch":false,
2133 "mem_type_64":false,
2134 "bar":6,
2135 "size":65536,
2136 "address":-1,
2137 "type":"memory"
2142 "bus":0,
2143 "qdev_id":"",
2144 "irq":11,
2145 "slot":4,
2146 "class_info":{
2147 "class":1280,
2148 "desc":"RAM controller"
2150 "id":{
2151 "device":6900,
2152 "vendor":4098
2154 "function":0,
2155 "regions":[
2157 "bar":0,
2158 "size":32,
2159 "address":49280,
2160 "type":"io"
2169 Note: This example has been shortened as the real response is too long.
2171 EQMP
2173 STEXI
2174 @item info tlb
2175 show virtual to physical memory mappings (i386 only)
2176 @item info mem
2177 show the active virtual memory mappings (i386 only)
2178 ETEXI
2180 STEXI
2181 @item info jit
2182 show dynamic compiler info
2183 @item info kvm
2184 show KVM information
2185 @item info numa
2186 show NUMA information
2187 ETEXI
2189 STEXI
2190 @item info kvm
2191 show KVM information
2192 ETEXI
2193 SQMP
2194 query-kvm
2195 ---------
2197 Show KVM information.
2199 Return a json-object with the following information:
2201 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
2202 - "present": true if QEMU has KVM support, false otherwise (json-bool)
2204 Example:
2206 -> { "execute": "query-kvm" }
2207 <- { "return": { "enabled": true, "present": true } }
2209 EQMP
2211 STEXI
2212 @item info usb
2213 show USB devices plugged on the virtual USB hub
2214 @item info usbhost
2215 show all USB host devices
2216 @item info profile
2217 show profiling information
2218 @item info capture
2219 show information about active capturing
2220 @item info snapshots
2221 show list of VM snapshots
2222 ETEXI
2224 STEXI
2225 @item info status
2226 show the current VM status (running|paused)
2227 ETEXI
2228 SQMP
2229 query-status
2230 ------------
2232 Return a json-object with the following information:
2234 - "running": true if the VM is running, or false if it is paused (json-bool)
2235 - "singlestep": true if the VM is in single step mode,
2236 false otherwise (json-bool)
2238 Example:
2240 -> { "execute": "query-status" }
2241 <- { "return": { "running": true, "singlestep": false } }
2243 EQMP
2245 STEXI
2246 @item info pcmcia
2247 show guest PCMCIA status
2248 ETEXI
2250 STEXI
2251 @item info mice
2252 show which guest mouse is receiving events
2253 ETEXI
2254 SQMP
2255 query-mice
2256 ----------
2258 Show VM mice information.
2260 Each mouse is represented by a json-object, the returned value is a json-array
2261 of all mice.
2263 The mouse json-object contains the following:
2265 - "name": mouse's name (json-string)
2266 - "index": mouse's index (json-int)
2267 - "current": true if this mouse is receiving events, false otherwise (json-bool)
2268 - "absolute": true if the mouse generates absolute input events (json-bool)
2270 Example:
2272 -> { "execute": "query-mice" }
2273 <- {
2274 "return":[
2276 "name":"QEMU Microsoft Mouse",
2277 "index":0,
2278 "current":false,
2279 "absolute":false
2282 "name":"QEMU PS/2 Mouse",
2283 "index":1,
2284 "current":true,
2285 "absolute":true
2290 EQMP
2292 STEXI
2293 @item info vnc
2294 show the vnc server status
2295 ETEXI
2296 SQMP
2297 query-vnc
2298 ---------
2300 Show VNC server information.
2302 Return a json-object with server information. Connected clients are returned
2303 as a json-array of json-objects.
2305 The main json-object contains the following:
2307 - "enabled": true or false (json-bool)
2308 - "host": server's IP address (json-string)
2309 - "family": address family (json-string)
2310 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2311 - "service": server's port number (json-string)
2312 - "auth": authentication method (json-string)
2313 - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2314 "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2315 "vencrypt+plain", "vencrypt+tls+none",
2316 "vencrypt+tls+plain", "vencrypt+tls+sasl",
2317 "vencrypt+tls+vnc", "vencrypt+x509+none",
2318 "vencrypt+x509+plain", "vencrypt+x509+sasl",
2319 "vencrypt+x509+vnc", "vnc"
2320 - "clients": a json-array of all connected clients
2322 Clients are described by a json-object, each one contain the following:
2324 - "host": client's IP address (json-string)
2325 - "family": address family (json-string)
2326 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2327 - "service": client's port number (json-string)
2328 - "x509_dname": TLS dname (json-string, optional)
2329 - "sasl_username": SASL username (json-string, optional)
2331 Example:
2333 -> { "execute": "query-vnc" }
2334 <- {
2335 "return":{
2336 "enabled":true,
2337 "host":"0.0.0.0",
2338 "service":"50402",
2339 "auth":"vnc",
2340 "family":"ipv4",
2341 "clients":[
2343 "host":"127.0.0.1",
2344 "service":"50401",
2345 "family":"ipv4"
2351 EQMP
2353 STEXI
2354 @item info name
2355 show the current VM name
2356 ETEXI
2357 SQMP
2358 query-name
2359 ----------
2361 Show VM name.
2363 Return a json-object with the following information:
2365 - "name": VM's name (json-string, optional)
2367 Example:
2369 -> { "execute": "query-name" }
2370 <- { "return": { "name": "qemu-name" } }
2372 EQMP
2374 STEXI
2375 @item info uuid
2376 show the current VM UUID
2377 ETEXI
2378 SQMP
2379 query-uuid
2380 ----------
2382 Show VM UUID.
2384 Return a json-object with the following information:
2386 - "UUID": Universally Unique Identifier (json-string)
2388 Example:
2390 -> { "execute": "query-uuid" }
2391 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2393 EQMP
2395 STEXI
2396 @item info cpustats
2397 show CPU statistics
2398 @item info usernet
2399 show user network stack connection states
2400 ETEXI
2402 STEXI
2403 @item info migrate
2404 show migration status
2405 ETEXI
2406 SQMP
2407 query-migrate
2408 -------------
2410 Migration status.
2412 Return a json-object. If migration is active there will be another json-object
2413 with RAM migration status and if block migration is active another one with
2414 block migration status.
2416 The main json-object contains the following:
2418 - "status": migration status (json-string)
2419 - Possible values: "active", "completed", "failed", "cancelled"
2420 - "ram": only present if "status" is "active", it is a json-object with the
2421 following RAM information (in bytes):
2422 - "transferred": amount transferred (json-int)
2423 - "remaining": amount remaining (json-int)
2424 - "total": total (json-int)
2425 - "disk": only present if "status" is "active" and it is a block migration,
2426 it is a json-object with the following disk information (in bytes):
2427 - "transferred": amount transferred (json-int)
2428 - "remaining": amount remaining (json-int)
2429 - "total": total (json-int)
2431 Examples:
2433 1. Before the first migration
2435 -> { "execute": "query-migrate" }
2436 <- { "return": {} }
2438 2. Migration is done and has succeeded
2440 -> { "execute": "query-migrate" }
2441 <- { "return": { "status": "completed" } }
2443 3. Migration is done and has failed
2445 -> { "execute": "query-migrate" }
2446 <- { "return": { "status": "failed" } }
2448 4. Migration is being performed and is not a block migration:
2450 -> { "execute": "query-migrate" }
2451 <- {
2452 "return":{
2453 "status":"active",
2454 "ram":{
2455 "transferred":123,
2456 "remaining":123,
2457 "total":246
2462 5. Migration is being performed and is a block migration:
2464 -> { "execute": "query-migrate" }
2465 <- {
2466 "return":{
2467 "status":"active",
2468 "ram":{
2469 "total":1057024,
2470 "remaining":1053304,
2471 "transferred":3720
2473 "disk":{
2474 "total":20971520,
2475 "remaining":20880384,
2476 "transferred":91136
2481 EQMP
2483 STEXI
2484 @item info balloon
2485 show balloon information
2486 ETEXI
2487 SQMP
2488 query-balloon
2489 -------------
2491 Show balloon information.
2493 Make an asynchronous request for balloon info. When the request completes a
2494 json-object will be returned containing the following data:
2496 - "actual": current balloon value in bytes (json-int)
2497 - "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
2498 - "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
2499 - "major_page_faults": Number of major faults (json-int, optional)
2500 - "minor_page_faults": Number of minor faults (json-int, optional)
2501 - "free_mem": Total amount of free and unused memory in
2502 bytes (json-int, optional)
2503 - "total_mem": Total amount of available memory in bytes (json-int, optional)
2505 Example:
2507 -> { "execute": "query-balloon" }
2508 <- {
2509 "return":{
2510 "actual":1073741824,
2511 "mem_swapped_in":0,
2512 "mem_swapped_out":0,
2513 "major_page_faults":142,
2514 "minor_page_faults":239245,
2515 "free_mem":1014185984,
2516 "total_mem":1044668416
2520 EQMP
2522 STEXI
2523 @item info qtree
2524 show device tree
2525 @item info qdm
2526 show qdev device model list
2527 @item info roms
2528 show roms
2529 @end table
2530 ETEXI
2532 HXCOMM DO NOT add new commands after 'info', move your addition before it!
2534 STEXI
2535 @end table
2536 ETEXI