Merge commit '5a4d701acde890a5ca134236424ece45545f70c7' into upstream-merge
[qemu-kvm.git] / hmp-commands.hx
blob13f28cfdde0c9723978d48e240e086e35e65b4f4
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 DEF(command, args, callback, arg_string, help) is used to construct
5 HXCOMM monitor commands
6 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
8 STEXI
9 @table @option
10 ETEXI
13 .name = "help|?",
14 .args_type = "name:s?",
15 .params = "[cmd]",
16 .help = "show the help",
17 .mhandler.cmd = do_help_cmd,
20 STEXI
21 @item help or ? [@var{cmd}]
22 @findex help
23 Show the help for all commands or just for command @var{cmd}.
24 ETEXI
27 .name = "commit",
28 .args_type = "device:B",
29 .params = "device|all",
30 .help = "commit changes to the disk images (if -snapshot is used) or backing files",
31 .mhandler.cmd = do_commit,
34 STEXI
35 @item commit
36 @findex commit
37 Commit changes to the disk images (if -snapshot is used) or backing files.
38 ETEXI
41 .name = "q|quit",
42 .args_type = "",
43 .params = "",
44 .help = "quit the emulator",
45 .user_print = monitor_user_noop,
46 .mhandler.cmd = hmp_quit,
49 STEXI
50 @item q or quit
51 @findex quit
52 Quit the emulator.
53 ETEXI
56 .name = "block_resize",
57 .args_type = "device:B,size:o",
58 .params = "device size",
59 .help = "resize a block image",
60 .mhandler.cmd = hmp_block_resize,
63 STEXI
64 @item block_resize
65 @findex block_resize
66 Resize a block image while a guest is running. Usually requires guest
67 action to see the updated size. Resize to a lower size is supported,
68 but should be used with extreme caution. Note that this command only
69 resizes image files, it can not resize block devices like LVM volumes.
70 ETEXI
73 .name = "block_stream",
74 .args_type = "device:B,speed:o?,base:s?",
75 .params = "device [speed [base]]",
76 .help = "copy data from a backing file into a block device",
77 .mhandler.cmd = hmp_block_stream,
80 STEXI
81 @item block_stream
82 @findex block_stream
83 Copy data from a backing file into a block device.
84 ETEXI
87 .name = "block_job_set_speed",
88 .args_type = "device:B,speed:o",
89 .params = "device speed",
90 .help = "set maximum speed for a background block operation",
91 .mhandler.cmd = hmp_block_job_set_speed,
94 STEXI
95 @item block_job_set_speed
96 @findex block_job_set_speed
97 Set maximum speed for a background block operation.
98 ETEXI
101 .name = "block_job_cancel",
102 .args_type = "device:B",
103 .params = "device",
104 .help = "stop an active background block operation",
105 .mhandler.cmd = hmp_block_job_cancel,
108 STEXI
109 @item block_job_cancel
110 @findex block_job_cancel
111 Stop an active block streaming operation.
112 ETEXI
115 .name = "eject",
116 .args_type = "force:-f,device:B",
117 .params = "[-f] device",
118 .help = "eject a removable medium (use -f to force it)",
119 .mhandler.cmd = hmp_eject,
122 STEXI
123 @item eject [-f] @var{device}
124 @findex eject
125 Eject a removable medium (use -f to force it).
126 ETEXI
129 .name = "drive_del",
130 .args_type = "id:s",
131 .params = "device",
132 .help = "remove host block device",
133 .user_print = monitor_user_noop,
134 .mhandler.cmd_new = do_drive_del,
137 STEXI
138 @item drive_del @var{device}
139 @findex drive_del
140 Remove host block device. The result is that guest generated IO is no longer
141 submitted against the host device underlying the disk. Once a drive has
142 been deleted, the QEMU Block layer returns -EIO which results in IO
143 errors in the guest for applications that are reading/writing to the device.
144 ETEXI
147 .name = "change",
148 .args_type = "device:B,target:F,arg:s?",
149 .params = "device filename [format]",
150 .help = "change a removable medium, optional format",
151 .mhandler.cmd = hmp_change,
154 STEXI
155 @item change @var{device} @var{setting}
156 @findex change
158 Change the configuration of a device.
160 @table @option
161 @item change @var{diskdevice} @var{filename} [@var{format}]
162 Change the medium for a removable disk device to point to @var{filename}. eg
164 @example
165 (qemu) change ide1-cd0 /path/to/some.iso
166 @end example
168 @var{format} is optional.
170 @item change vnc @var{display},@var{options}
171 Change the configuration of the VNC server. The valid syntax for @var{display}
172 and @var{options} are described at @ref{sec_invocation}. eg
174 @example
175 (qemu) change vnc localhost:1
176 @end example
178 @item change vnc password [@var{password}]
180 Change the password associated with the VNC server. If the new password is not
181 supplied, the monitor will prompt for it to be entered. VNC passwords are only
182 significant up to 8 letters. eg
184 @example
185 (qemu) change vnc password
186 Password: ********
187 @end example
189 @end table
190 ETEXI
193 .name = "screendump",
194 .args_type = "filename:F",
195 .params = "filename",
196 .help = "save screen into PPM image 'filename'",
197 .user_print = monitor_user_noop,
198 .mhandler.cmd_new = do_screen_dump,
201 STEXI
202 @item screendump @var{filename}
203 @findex screendump
204 Save screen into PPM image @var{filename}.
205 ETEXI
208 .name = "logfile",
209 .args_type = "filename:F",
210 .params = "filename",
211 .help = "output logs to 'filename'",
212 .mhandler.cmd = do_logfile,
215 STEXI
216 @item logfile @var{filename}
217 @findex logfile
218 Output logs to @var{filename}.
219 ETEXI
222 .name = "trace-event",
223 .args_type = "name:s,option:b",
224 .params = "name on|off",
225 .help = "changes status of a specific trace event",
226 .mhandler.cmd = do_trace_event_set_state,
229 STEXI
230 @item trace-event
231 @findex trace-event
232 changes status of a trace event
233 ETEXI
235 #if defined(CONFIG_TRACE_SIMPLE)
237 .name = "trace-file",
238 .args_type = "op:s?,arg:F?",
239 .params = "on|off|flush|set [arg]",
240 .help = "open, close, or flush trace file, or set a new file name",
241 .mhandler.cmd = do_trace_file,
244 STEXI
245 @item trace-file on|off|flush
246 @findex trace-file
247 Open, close, or flush the trace file. If no argument is given, the status of the trace file is displayed.
248 ETEXI
249 #endif
252 .name = "log",
253 .args_type = "items:s",
254 .params = "item1[,...]",
255 .help = "activate logging of the specified items to '/tmp/qemu.log'",
256 .mhandler.cmd = do_log,
259 STEXI
260 @item log @var{item1}[,...]
261 @findex log
262 Activate logging of the specified items to @file{/tmp/qemu.log}.
263 ETEXI
266 .name = "savevm",
267 .args_type = "name:s?",
268 .params = "[tag|id]",
269 .help = "save a VM snapshot. If no tag or id are provided, a new snapshot is created",
270 .mhandler.cmd = do_savevm,
273 STEXI
274 @item savevm [@var{tag}|@var{id}]
275 @findex savevm
276 Create a snapshot of the whole virtual machine. If @var{tag} is
277 provided, it is used as human readable identifier. If there is already
278 a snapshot with the same tag or ID, it is replaced. More info at
279 @ref{vm_snapshots}.
280 ETEXI
283 .name = "loadvm",
284 .args_type = "name:s",
285 .params = "tag|id",
286 .help = "restore a VM snapshot from its tag or id",
287 .mhandler.cmd = do_loadvm,
290 STEXI
291 @item loadvm @var{tag}|@var{id}
292 @findex loadvm
293 Set the whole virtual machine to the snapshot identified by the tag
294 @var{tag} or the unique snapshot ID @var{id}.
295 ETEXI
298 .name = "delvm",
299 .args_type = "name:s",
300 .params = "tag|id",
301 .help = "delete a VM snapshot from its tag or id",
302 .mhandler.cmd = do_delvm,
305 STEXI
306 @item delvm @var{tag}|@var{id}
307 @findex delvm
308 Delete the snapshot identified by @var{tag} or @var{id}.
309 ETEXI
312 .name = "singlestep",
313 .args_type = "option:s?",
314 .params = "[on|off]",
315 .help = "run emulation in singlestep mode or switch to normal mode",
316 .mhandler.cmd = do_singlestep,
319 STEXI
320 @item singlestep [off]
321 @findex singlestep
322 Run the emulation in single step mode.
323 If called with option off, the emulation returns to normal mode.
324 ETEXI
327 .name = "stop",
328 .args_type = "",
329 .params = "",
330 .help = "stop emulation",
331 .mhandler.cmd = hmp_stop,
334 STEXI
335 @item stop
336 @findex stop
337 Stop emulation.
338 ETEXI
341 .name = "c|cont",
342 .args_type = "",
343 .params = "",
344 .help = "resume emulation",
345 .mhandler.cmd = hmp_cont,
348 STEXI
349 @item c or cont
350 @findex cont
351 Resume emulation.
352 ETEXI
355 .name = "system_wakeup",
356 .args_type = "",
357 .params = "",
358 .help = "wakeup guest from suspend",
359 .mhandler.cmd = hmp_system_wakeup,
362 STEXI
363 @item system_wakeup
364 @findex system_wakeup
365 Wakeup guest from suspend.
366 ETEXI
369 .name = "gdbserver",
370 .args_type = "device:s?",
371 .params = "[device]",
372 .help = "start gdbserver on given device (default 'tcp::1234'), stop with 'none'",
373 .mhandler.cmd = do_gdbserver,
376 STEXI
377 @item gdbserver [@var{port}]
378 @findex gdbserver
379 Start gdbserver session (default @var{port}=1234)
380 ETEXI
383 .name = "x",
384 .args_type = "fmt:/,addr:l",
385 .params = "/fmt addr",
386 .help = "virtual memory dump starting at 'addr'",
387 .mhandler.cmd = do_memory_dump,
390 STEXI
391 @item x/fmt @var{addr}
392 @findex x
393 Virtual memory dump starting at @var{addr}.
394 ETEXI
397 .name = "xp",
398 .args_type = "fmt:/,addr:l",
399 .params = "/fmt addr",
400 .help = "physical memory dump starting at 'addr'",
401 .mhandler.cmd = do_physical_memory_dump,
404 STEXI
405 @item xp /@var{fmt} @var{addr}
406 @findex xp
407 Physical memory dump starting at @var{addr}.
409 @var{fmt} is a format which tells the command how to format the
410 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
412 @table @var
413 @item count
414 is the number of items to be dumped.
416 @item format
417 can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
418 c (char) or i (asm instruction).
420 @item size
421 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
422 @code{h} or @code{w} can be specified with the @code{i} format to
423 respectively select 16 or 32 bit code instruction size.
425 @end table
427 Examples:
428 @itemize
429 @item
430 Dump 10 instructions at the current instruction pointer:
431 @example
432 (qemu) x/10i $eip
433 0x90107063: ret
434 0x90107064: sti
435 0x90107065: lea 0x0(%esi,1),%esi
436 0x90107069: lea 0x0(%edi,1),%edi
437 0x90107070: ret
438 0x90107071: jmp 0x90107080
439 0x90107073: nop
440 0x90107074: nop
441 0x90107075: nop
442 0x90107076: nop
443 @end example
445 @item
446 Dump 80 16 bit values at the start of the video memory.
447 @smallexample
448 (qemu) xp/80hx 0xb8000
449 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
450 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
451 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
452 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
453 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
454 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
455 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
456 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
457 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
458 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
459 @end smallexample
460 @end itemize
461 ETEXI
464 .name = "p|print",
465 .args_type = "fmt:/,val:l",
466 .params = "/fmt expr",
467 .help = "print expression value (use $reg for CPU register access)",
468 .mhandler.cmd = do_print,
471 STEXI
472 @item p or print/@var{fmt} @var{expr}
473 @findex print
475 Print expression value. Only the @var{format} part of @var{fmt} is
476 used.
477 ETEXI
480 .name = "i",
481 .args_type = "fmt:/,addr:i,index:i.",
482 .params = "/fmt addr",
483 .help = "I/O port read",
484 .mhandler.cmd = do_ioport_read,
487 STEXI
488 Read I/O port.
489 ETEXI
492 .name = "o",
493 .args_type = "fmt:/,addr:i,val:i",
494 .params = "/fmt addr value",
495 .help = "I/O port write",
496 .mhandler.cmd = do_ioport_write,
499 STEXI
500 Write to I/O port.
501 ETEXI
504 .name = "sendkey",
505 .args_type = "string:s,hold_time:i?",
506 .params = "keys [hold_ms]",
507 .help = "send keys to the VM (e.g. 'sendkey ctrl-alt-f1', default hold time=100 ms)",
508 .mhandler.cmd = do_sendkey,
511 STEXI
512 @item sendkey @var{keys}
513 @findex sendkey
515 Send @var{keys} to the emulator. @var{keys} could be the name of the
516 key or @code{#} followed by the raw value in either decimal or hexadecimal
517 format. Use @code{-} to press several keys simultaneously. Example:
518 @example
519 sendkey ctrl-alt-f1
520 @end example
522 This command is useful to send keys that your graphical user interface
523 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
524 ETEXI
527 .name = "system_reset",
528 .args_type = "",
529 .params = "",
530 .help = "reset the system",
531 .mhandler.cmd = hmp_system_reset,
534 STEXI
535 @item system_reset
536 @findex system_reset
538 Reset the system.
539 ETEXI
542 .name = "system_powerdown",
543 .args_type = "",
544 .params = "",
545 .help = "send system power down event",
546 .mhandler.cmd = hmp_system_powerdown,
549 STEXI
550 @item system_powerdown
551 @findex system_powerdown
553 Power down the system (if supported).
554 ETEXI
557 .name = "sum",
558 .args_type = "start:i,size:i",
559 .params = "addr size",
560 .help = "compute the checksum of a memory region",
561 .mhandler.cmd = do_sum,
564 STEXI
565 @item sum @var{addr} @var{size}
566 @findex sum
568 Compute the checksum of a memory region.
569 ETEXI
572 .name = "usb_add",
573 .args_type = "devname:s",
574 .params = "device",
575 .help = "add USB device (e.g. 'host:bus.addr' or 'host:vendor_id:product_id')",
576 .mhandler.cmd = do_usb_add,
579 STEXI
580 @item usb_add @var{devname}
581 @findex usb_add
583 Add the USB device @var{devname}. For details of available devices see
584 @ref{usb_devices}
585 ETEXI
588 .name = "usb_del",
589 .args_type = "devname:s",
590 .params = "device",
591 .help = "remove USB device 'bus.addr'",
592 .mhandler.cmd = do_usb_del,
595 STEXI
596 @item usb_del @var{devname}
597 @findex usb_del
599 Remove the USB device @var{devname} from the QEMU virtual USB
600 hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
601 command @code{info usb} to see the devices you can remove.
602 ETEXI
605 .name = "device_add",
606 .args_type = "device:O",
607 .params = "driver[,prop=value][,...]",
608 .help = "add device, like -device on the command line",
609 .user_print = monitor_user_noop,
610 .mhandler.cmd_new = do_device_add,
613 STEXI
614 @item device_add @var{config}
615 @findex device_add
617 Add device.
618 ETEXI
621 .name = "device_del",
622 .args_type = "id:s",
623 .params = "device",
624 .help = "remove device",
625 .mhandler.cmd = hmp_device_del,
628 STEXI
629 @item device_del @var{id}
630 @findex device_del
632 Remove device @var{id}.
633 ETEXI
636 .name = "cpu",
637 .args_type = "index:i",
638 .params = "index",
639 .help = "set the default CPU",
640 .mhandler.cmd = hmp_cpu,
643 STEXI
644 @item cpu @var{index}
645 @findex cpu
646 Set the default CPU.
647 ETEXI
650 .name = "mouse_move",
651 .args_type = "dx_str:s,dy_str:s,dz_str:s?",
652 .params = "dx dy [dz]",
653 .help = "send mouse move events",
654 .mhandler.cmd = do_mouse_move,
657 STEXI
658 @item mouse_move @var{dx} @var{dy} [@var{dz}]
659 @findex mouse_move
660 Move the active mouse to the specified coordinates @var{dx} @var{dy}
661 with optional scroll axis @var{dz}.
662 ETEXI
665 .name = "mouse_button",
666 .args_type = "button_state:i",
667 .params = "state",
668 .help = "change mouse button state (1=L, 2=M, 4=R)",
669 .mhandler.cmd = do_mouse_button,
672 STEXI
673 @item mouse_button @var{val}
674 @findex mouse_button
675 Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
676 ETEXI
679 .name = "mouse_set",
680 .args_type = "index:i",
681 .params = "index",
682 .help = "set which mouse device receives events",
683 .mhandler.cmd = do_mouse_set,
686 STEXI
687 @item mouse_set @var{index}
688 @findex mouse_set
689 Set which mouse device receives events at given @var{index}, index
690 can be obtained with
691 @example
692 info mice
693 @end example
694 ETEXI
696 #ifdef HAS_AUDIO
698 .name = "wavcapture",
699 .args_type = "path:F,freq:i?,bits:i?,nchannels:i?",
700 .params = "path [frequency [bits [channels]]]",
701 .help = "capture audio to a wave file (default frequency=44100 bits=16 channels=2)",
702 .mhandler.cmd = do_wav_capture,
704 #endif
705 STEXI
706 @item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
707 @findex wavcapture
708 Capture audio into @var{filename}. Using sample rate @var{frequency}
709 bits per sample @var{bits} and number of channels @var{channels}.
711 Defaults:
712 @itemize @minus
713 @item Sample rate = 44100 Hz - CD quality
714 @item Bits = 16
715 @item Number of channels = 2 - Stereo
716 @end itemize
717 ETEXI
719 #ifdef HAS_AUDIO
721 .name = "stopcapture",
722 .args_type = "n:i",
723 .params = "capture index",
724 .help = "stop capture",
725 .mhandler.cmd = do_stop_capture,
727 #endif
728 STEXI
729 @item stopcapture @var{index}
730 @findex stopcapture
731 Stop capture with a given @var{index}, index can be obtained with
732 @example
733 info capture
734 @end example
735 ETEXI
738 .name = "memsave",
739 .args_type = "val:l,size:i,filename:s",
740 .params = "addr size file",
741 .help = "save to disk virtual memory dump starting at 'addr' of size 'size'",
742 .mhandler.cmd = hmp_memsave,
745 STEXI
746 @item memsave @var{addr} @var{size} @var{file}
747 @findex memsave
748 save to disk virtual memory dump starting at @var{addr} of size @var{size}.
749 ETEXI
752 .name = "pmemsave",
753 .args_type = "val:l,size:i,filename:s",
754 .params = "addr size file",
755 .help = "save to disk physical memory dump starting at 'addr' of size 'size'",
756 .mhandler.cmd = hmp_pmemsave,
759 STEXI
760 @item pmemsave @var{addr} @var{size} @var{file}
761 @findex pmemsave
762 save to disk physical memory dump starting at @var{addr} of size @var{size}.
763 ETEXI
766 .name = "boot_set",
767 .args_type = "bootdevice:s",
768 .params = "bootdevice",
769 .help = "define new values for the boot device list",
770 .mhandler.cmd = do_boot_set,
773 STEXI
774 @item boot_set @var{bootdevicelist}
775 @findex boot_set
777 Define new values for the boot device list. Those values will override
778 the values specified on the command line through the @code{-boot} option.
780 The values that can be specified here depend on the machine type, but are
781 the same that can be specified in the @code{-boot} command line option.
782 ETEXI
784 #if defined(TARGET_I386)
786 .name = "nmi",
787 .args_type = "",
788 .params = "",
789 .help = "inject an NMI on all guest's CPUs",
790 .mhandler.cmd = hmp_inject_nmi,
792 #endif
793 STEXI
794 @item nmi @var{cpu}
795 @findex nmi
796 Inject an NMI on the given CPU (x86 only).
797 ETEXI
800 .name = "migrate",
801 .args_type = "detach:-d,blk:-b,inc:-i,uri:s",
802 .params = "[-d] [-b] [-i] uri",
803 .help = "migrate to URI (using -d to not wait for completion)"
804 "\n\t\t\t -b for migration without shared storage with"
805 " full copy of disk\n\t\t\t -i for migration without "
806 "shared storage with incremental copy of disk "
807 "(base image shared between src and destination)",
808 .mhandler.cmd = hmp_migrate,
812 STEXI
813 @item migrate [-d] [-b] [-i] @var{uri}
814 @findex migrate
815 Migrate to @var{uri} (using -d to not wait for completion).
816 -b for migration with full copy of disk
817 -i for migration with incremental copy of disk (base image is shared)
818 ETEXI
821 .name = "migrate_cancel",
822 .args_type = "",
823 .params = "",
824 .help = "cancel the current VM migration",
825 .mhandler.cmd = hmp_migrate_cancel,
828 STEXI
829 @item migrate_cancel
830 @findex migrate_cancel
831 Cancel the current VM migration.
833 ETEXI
836 .name = "migrate_set_cache_size",
837 .args_type = "value:o",
838 .params = "value",
839 .help = "set cache size (in bytes) for XBZRLE migrations,"
840 "the cache size will be rounded down to the nearest "
841 "power of 2.\n"
842 "The cache size affects the number of cache misses."
843 "In case of a high cache miss ratio you need to increase"
844 " the cache size",
845 .mhandler.cmd = hmp_migrate_set_cache_size,
848 STEXI
849 @item migrate_set_cache_size @var{value}
850 @findex migrate_set_cache_size
851 Set cache size to @var{value} (in bytes) for xbzrle migrations.
852 ETEXI
855 .name = "migrate_set_speed",
856 .args_type = "value:o",
857 .params = "value",
858 .help = "set maximum speed (in bytes) for migrations. "
859 "Defaults to MB if no size suffix is specified, ie. B/K/M/G/T",
860 .mhandler.cmd = hmp_migrate_set_speed,
863 STEXI
864 @item migrate_set_speed @var{value}
865 @findex migrate_set_speed
866 Set maximum speed to @var{value} (in bytes) for migrations.
867 ETEXI
870 .name = "migrate_set_downtime",
871 .args_type = "value:T",
872 .params = "value",
873 .help = "set maximum tolerated downtime (in seconds) for migrations",
874 .mhandler.cmd = hmp_migrate_set_downtime,
877 STEXI
878 @item migrate_set_downtime @var{second}
879 @findex migrate_set_downtime
880 Set maximum tolerated downtime (in seconds) for migration.
881 ETEXI
884 .name = "migrate_set_capability",
885 .args_type = "capability:s,state:b",
886 .params = "capability state",
887 .help = "Enable/Disable the usage of a capability for migration",
888 .mhandler.cmd = hmp_migrate_set_capability,
891 STEXI
892 @item migrate_set_capability @var{capability} @var{state}
893 @findex migrate_set_capability
894 Enable/Disable the usage of a capability @var{capability} for migration.
895 ETEXI
898 .name = "client_migrate_info",
899 .args_type = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
900 .params = "protocol hostname port tls-port cert-subject",
901 .help = "send migration info to spice/vnc client",
902 .user_print = monitor_user_noop,
903 .mhandler.cmd_async = client_migrate_info,
904 .flags = MONITOR_CMD_ASYNC,
907 STEXI
908 @item client_migrate_info @var{protocol} @var{hostname} @var{port} @var{tls-port} @var{cert-subject}
909 @findex client_migrate_info
910 Set the spice/vnc connection info for the migration target. The spice/vnc
911 server will ask the spice/vnc client to automatically reconnect using the
912 new parameters (if specified) once the vm migration finished successfully.
913 ETEXI
915 #if defined(CONFIG_HAVE_CORE_DUMP)
917 .name = "dump-guest-memory",
918 .args_type = "paging:-p,protocol:s,begin:i?,length:i?",
919 .params = "[-p] protocol [begin] [length]",
920 .help = "dump guest memory to file"
921 "\n\t\t\t begin(optional): the starting physical address"
922 "\n\t\t\t length(optional): the memory size, in bytes",
923 .user_print = monitor_user_noop,
924 .mhandler.cmd = hmp_dump_guest_memory,
928 STEXI
929 @item dump-guest-memory [-p] @var{protocol} @var{begin} @var{length}
930 @findex dump-guest-memory
931 Dump guest memory to @var{protocol}. The file can be processed with crash or
932 gdb.
933 protocol: destination file(started with "file:") or destination file
934 descriptor (started with "fd:")
935 paging: do paging to get guest's memory mapping
936 begin: the starting physical address. It's optional, and should be
937 specified with length together.
938 length: the memory size, in bytes. It's optional, and should be specified
939 with begin together.
940 ETEXI
941 #endif
944 .name = "snapshot_blkdev",
945 .args_type = "reuse:-n,device:B,snapshot-file:s?,format:s?",
946 .params = "[-n] device [new-image-file] [format]",
947 .help = "initiates a live snapshot\n\t\t\t"
948 "of device. If a new image file is specified, the\n\t\t\t"
949 "new image file will become the new root image.\n\t\t\t"
950 "If format is specified, the snapshot file will\n\t\t\t"
951 "be created in that format. Otherwise the\n\t\t\t"
952 "snapshot will be internal! (currently unsupported).\n\t\t\t"
953 "The default format is qcow2. The -n flag requests QEMU\n\t\t\t"
954 "to reuse the image found in new-image-file, instead of\n\t\t\t"
955 "recreating it from scratch.",
956 .mhandler.cmd = hmp_snapshot_blkdev,
959 STEXI
960 @item snapshot_blkdev
961 @findex snapshot_blkdev
962 Snapshot device, using snapshot file as target if provided
963 ETEXI
966 .name = "drive_add",
967 .args_type = "pci_addr:s,opts:s",
968 .params = "[[<domain>:]<bus>:]<slot>\n"
969 "[file=file][,if=type][,bus=n]\n"
970 "[,unit=m][,media=d][,index=i]\n"
971 "[,cyls=c,heads=h,secs=s[,trans=t]]\n"
972 "[,snapshot=on|off][,cache=on|off]\n"
973 "[,readonly=on|off][,copy-on-read=on|off]",
974 .help = "add drive to PCI storage controller",
975 .mhandler.cmd = drive_hot_add,
978 STEXI
979 @item drive_add
980 @findex drive_add
981 Add drive to PCI storage controller.
982 ETEXI
984 #if defined(TARGET_I386)
986 .name = "pci_add",
987 .args_type = "pci_addr:s,type:s,opts:s?",
988 .params = "auto|[[<domain>:]<bus>:]<slot> nic|storage [[vlan=n][,macaddr=addr][,model=type]] [file=file][,if=type][,bus=nr]...",
989 .help = "hot-add PCI device",
990 .mhandler.cmd = pci_device_hot_add,
992 #endif
994 STEXI
995 @item pci_add
996 @findex pci_add
997 Hot-add PCI device.
998 ETEXI
1000 #if defined(TARGET_I386)
1002 .name = "pci_del",
1003 .args_type = "pci_addr:s",
1004 .params = "[[<domain>:]<bus>:]<slot>",
1005 .help = "hot remove PCI device",
1006 .mhandler.cmd = do_pci_device_hot_remove,
1008 #endif
1010 STEXI
1011 @item pci_del
1012 @findex pci_del
1013 Hot remove PCI device.
1014 ETEXI
1017 .name = "pcie_aer_inject_error",
1018 .args_type = "advisory_non_fatal:-a,correctable:-c,"
1019 "id:s,error_status:s,"
1020 "header0:i?,header1:i?,header2:i?,header3:i?,"
1021 "prefix0:i?,prefix1:i?,prefix2:i?,prefix3:i?",
1022 .params = "[-a] [-c] id "
1023 "<error_status> [<tlp header> [<tlp header prefix>]]",
1024 .help = "inject pcie aer error\n\t\t\t"
1025 " -a for advisory non fatal error\n\t\t\t"
1026 " -c for correctable error\n\t\t\t"
1027 "<id> = qdev device id\n\t\t\t"
1028 "<error_status> = error string or 32bit\n\t\t\t"
1029 "<tlb header> = 32bit x 4\n\t\t\t"
1030 "<tlb header prefix> = 32bit x 4",
1031 .user_print = pcie_aer_inject_error_print,
1032 .mhandler.cmd_new = do_pcie_aer_inject_error,
1035 STEXI
1036 @item pcie_aer_inject_error
1037 @findex pcie_aer_inject_error
1038 Inject PCIe AER error
1039 ETEXI
1042 .name = "host_net_add",
1043 .args_type = "device:s,opts:s?",
1044 .params = "tap|user|socket|vde|dump [options]",
1045 .help = "add host VLAN client",
1046 .mhandler.cmd = net_host_device_add,
1049 STEXI
1050 @item host_net_add
1051 @findex host_net_add
1052 Add host VLAN client.
1053 ETEXI
1056 .name = "host_net_remove",
1057 .args_type = "vlan_id:i,device:s",
1058 .params = "vlan_id name",
1059 .help = "remove host VLAN client",
1060 .mhandler.cmd = net_host_device_remove,
1063 STEXI
1064 @item host_net_remove
1065 @findex host_net_remove
1066 Remove host VLAN client.
1067 ETEXI
1070 .name = "netdev_add",
1071 .args_type = "netdev:O",
1072 .params = "[user|tap|socket],id=str[,prop=value][,...]",
1073 .help = "add host network device",
1074 .mhandler.cmd = hmp_netdev_add,
1077 STEXI
1078 @item netdev_add
1079 @findex netdev_add
1080 Add host network device.
1081 ETEXI
1084 .name = "netdev_del",
1085 .args_type = "id:s",
1086 .params = "id",
1087 .help = "remove host network device",
1088 .mhandler.cmd = hmp_netdev_del,
1091 STEXI
1092 @item netdev_del
1093 @findex netdev_del
1094 Remove host network device.
1095 ETEXI
1097 #ifdef CONFIG_SLIRP
1099 .name = "hostfwd_add",
1100 .args_type = "arg1:s,arg2:s?,arg3:s?",
1101 .params = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport",
1102 .help = "redirect TCP or UDP connections from host to guest (requires -net user)",
1103 .mhandler.cmd = net_slirp_hostfwd_add,
1105 #endif
1106 STEXI
1107 @item hostfwd_add
1108 @findex hostfwd_add
1109 Redirect TCP or UDP connections from host to guest (requires -net user).
1110 ETEXI
1112 #ifdef CONFIG_SLIRP
1114 .name = "hostfwd_remove",
1115 .args_type = "arg1:s,arg2:s?,arg3:s?",
1116 .params = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport",
1117 .help = "remove host-to-guest TCP or UDP redirection",
1118 .mhandler.cmd = net_slirp_hostfwd_remove,
1121 #endif
1122 STEXI
1123 @item hostfwd_remove
1124 @findex hostfwd_remove
1125 Remove host-to-guest TCP or UDP redirection.
1126 ETEXI
1129 .name = "balloon",
1130 .args_type = "value:M",
1131 .params = "target",
1132 .help = "request VM to change its memory allocation (in MB)",
1133 .mhandler.cmd = hmp_balloon,
1136 STEXI
1137 @item balloon @var{value}
1138 @findex balloon
1139 Request VM to change its memory allocation to @var{value} (in MB).
1140 ETEXI
1143 .name = "set_link",
1144 .args_type = "name:s,up:b",
1145 .params = "name on|off",
1146 .help = "change the link status of a network adapter",
1147 .mhandler.cmd = hmp_set_link,
1150 STEXI
1151 @item set_link @var{name} [on|off]
1152 @findex set_link
1153 Switch link @var{name} on (i.e. up) or off (i.e. down).
1154 ETEXI
1157 .name = "watchdog_action",
1158 .args_type = "action:s",
1159 .params = "[reset|shutdown|poweroff|pause|debug|none]",
1160 .help = "change watchdog action",
1161 .mhandler.cmd = do_watchdog_action,
1164 STEXI
1165 @item watchdog_action
1166 @findex watchdog_action
1167 Change watchdog action.
1168 ETEXI
1171 .name = "acl_show",
1172 .args_type = "aclname:s",
1173 .params = "aclname",
1174 .help = "list rules in the access control list",
1175 .mhandler.cmd = do_acl_show,
1178 STEXI
1179 @item acl_show @var{aclname}
1180 @findex acl_show
1181 List all the matching rules in the access control list, and the default
1182 policy. There are currently two named access control lists,
1183 @var{vnc.x509dname} and @var{vnc.username} matching on the x509 client
1184 certificate distinguished name, and SASL username respectively.
1185 ETEXI
1188 .name = "acl_policy",
1189 .args_type = "aclname:s,policy:s",
1190 .params = "aclname allow|deny",
1191 .help = "set default access control list policy",
1192 .mhandler.cmd = do_acl_policy,
1195 STEXI
1196 @item acl_policy @var{aclname} @code{allow|deny}
1197 @findex acl_policy
1198 Set the default access control list policy, used in the event that
1199 none of the explicit rules match. The default policy at startup is
1200 always @code{deny}.
1201 ETEXI
1204 .name = "acl_add",
1205 .args_type = "aclname:s,match:s,policy:s,index:i?",
1206 .params = "aclname match allow|deny [index]",
1207 .help = "add a match rule to the access control list",
1208 .mhandler.cmd = do_acl_add,
1211 STEXI
1212 @item acl_add @var{aclname} @var{match} @code{allow|deny} [@var{index}]
1213 @findex acl_add
1214 Add a match rule to the access control list, allowing or denying access.
1215 The match will normally be an exact username or x509 distinguished name,
1216 but can optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to
1217 allow all users in the @code{EXAMPLE.COM} kerberos realm. The match will
1218 normally be appended to the end of the ACL, but can be inserted
1219 earlier in the list if the optional @var{index} parameter is supplied.
1220 ETEXI
1223 .name = "acl_remove",
1224 .args_type = "aclname:s,match:s",
1225 .params = "aclname match",
1226 .help = "remove a match rule from the access control list",
1227 .mhandler.cmd = do_acl_remove,
1230 STEXI
1231 @item acl_remove @var{aclname} @var{match}
1232 @findex acl_remove
1233 Remove the specified match rule from the access control list.
1234 ETEXI
1237 .name = "acl_reset",
1238 .args_type = "aclname:s",
1239 .params = "aclname",
1240 .help = "reset the access control list",
1241 .mhandler.cmd = do_acl_reset,
1244 STEXI
1245 @item acl_reset @var{aclname}
1246 @findex acl_reset
1247 Remove all matches from the access control list, and set the default
1248 policy back to @code{deny}.
1249 ETEXI
1251 #if defined(TARGET_I386)
1254 .name = "mce",
1255 .args_type = "broadcast:-b,cpu_index:i,bank:i,status:l,mcg_status:l,addr:l,misc:l",
1256 .params = "[-b] cpu bank status mcgstatus addr misc",
1257 .help = "inject a MCE on the given CPU [and broadcast to other CPUs with -b option]",
1258 .mhandler.cmd = do_inject_mce,
1261 #endif
1262 STEXI
1263 @item mce @var{cpu} @var{bank} @var{status} @var{mcgstatus} @var{addr} @var{misc}
1264 @findex mce (x86)
1265 Inject an MCE on the given CPU (x86 only).
1266 ETEXI
1269 .name = "getfd",
1270 .args_type = "fdname:s",
1271 .params = "getfd name",
1272 .help = "receive a file descriptor via SCM rights and assign it a name",
1273 .mhandler.cmd = hmp_getfd,
1276 STEXI
1277 @item getfd @var{fdname}
1278 @findex getfd
1279 If a file descriptor is passed alongside this command using the SCM_RIGHTS
1280 mechanism on unix sockets, it is stored using the name @var{fdname} for
1281 later use by other monitor commands.
1282 ETEXI
1285 .name = "closefd",
1286 .args_type = "fdname:s",
1287 .params = "closefd name",
1288 .help = "close a file descriptor previously passed via SCM rights",
1289 .mhandler.cmd = hmp_closefd,
1292 STEXI
1293 @item closefd @var{fdname}
1294 @findex closefd
1295 Close the file descriptor previously assigned to @var{fdname} using the
1296 @code{getfd} command. This is only needed if the file descriptor was never
1297 used by another monitor command.
1298 ETEXI
1301 .name = "block_passwd",
1302 .args_type = "device:B,password:s",
1303 .params = "block_passwd device password",
1304 .help = "set the password of encrypted block devices",
1305 .mhandler.cmd = hmp_block_passwd,
1308 STEXI
1309 @item block_set_io_throttle @var{device} @var{bps} @var{bps_rd} @var{bps_wr} @var{iops} @var{iops_rd} @var{iops_wr}
1310 @findex block_set_io_throttle
1311 Change I/O throttle limits for a block drive to @var{bps} @var{bps_rd} @var{bps_wr} @var{iops} @var{iops_rd} @var{iops_wr}
1312 ETEXI
1315 .name = "block_set_io_throttle",
1316 .args_type = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l",
1317 .params = "device bps bps_rd bps_wr iops iops_rd iops_wr",
1318 .help = "change I/O throttle limits for a block drive",
1319 .mhandler.cmd = hmp_block_set_io_throttle,
1322 STEXI
1323 @item block_passwd @var{device} @var{password}
1324 @findex block_passwd
1325 Set the encrypted device @var{device} password to @var{password}
1326 ETEXI
1329 .name = "cpu_set",
1330 .args_type = "cpu:i,state:s",
1331 .params = "cpu [online|offline]",
1332 .help = "change cpu state",
1333 .mhandler.cmd = do_cpu_set_nr,
1336 STEXI
1337 @item cpu_set @var{cpu} [online|offline]
1338 Set CPU @var{cpu} online or offline.
1339 ETEXI
1342 .name = "set_password",
1343 .args_type = "protocol:s,password:s,connected:s?",
1344 .params = "protocol password action-if-connected",
1345 .help = "set spice/vnc password",
1346 .mhandler.cmd = hmp_set_password,
1349 STEXI
1350 @item set_password [ vnc | spice ] password [ action-if-connected ]
1351 @findex set_password
1353 Change spice/vnc password. Use zero to make the password stay valid
1354 forever. @var{action-if-connected} specifies what should happen in
1355 case a connection is established: @var{fail} makes the password change
1356 fail. @var{disconnect} changes the password and disconnects the
1357 client. @var{keep} changes the password and keeps the connection up.
1358 @var{keep} is the default.
1359 ETEXI
1362 .name = "expire_password",
1363 .args_type = "protocol:s,time:s",
1364 .params = "protocol time",
1365 .help = "set spice/vnc password expire-time",
1366 .mhandler.cmd = hmp_expire_password,
1369 STEXI
1370 @item expire_password [ vnc | spice ] expire-time
1371 @findex expire_password
1373 Specify when a password for spice/vnc becomes
1374 invalid. @var{expire-time} accepts:
1376 @table @var
1377 @item now
1378 Invalidate password instantly.
1380 @item never
1381 Password stays valid forever.
1383 @item +nsec
1384 Password stays valid for @var{nsec} seconds starting now.
1386 @item nsec
1387 Password is invalidated at the given time. @var{nsec} are the seconds
1388 passed since 1970, i.e. unix epoch.
1390 @end table
1391 ETEXI
1394 .name = "info",
1395 .args_type = "item:s?",
1396 .params = "[subcommand]",
1397 .help = "show various information about the system state",
1398 .mhandler.cmd = do_info,
1401 STEXI
1402 @item info @var{subcommand}
1403 @findex info
1404 Show various information about the system state.
1406 @table @option
1407 @item info version
1408 show the version of QEMU
1409 @item info network
1410 show the various VLANs and the associated devices
1411 @item info chardev
1412 show the character devices
1413 @item info block
1414 show the block devices
1415 @item info blockstats
1416 show block device statistics
1417 @item info registers
1418 show the cpu registers
1419 @item info cpus
1420 show infos for each CPU
1421 @item info history
1422 show the command line history
1423 @item info irq
1424 show the interrupts statistics (if available)
1425 @item info pic
1426 show i8259 (PIC) state
1427 @item info pci
1428 show emulated PCI device info
1429 @item info tlb
1430 show virtual to physical memory mappings (i386, SH4, SPARC, PPC, and Xtensa only)
1431 @item info mem
1432 show the active virtual memory mappings (i386 only)
1433 @item info jit
1434 show dynamic compiler info
1435 @item info numa
1436 show NUMA information
1437 @item info kvm
1438 show KVM information
1439 @item info usb
1440 show USB devices plugged on the virtual USB hub
1441 @item info usbhost
1442 show all USB host devices
1443 @item info profile
1444 show profiling information
1445 @item info capture
1446 show information about active capturing
1447 @item info snapshots
1448 show list of VM snapshots
1449 @item info status
1450 show the current VM status (running|paused)
1451 @item info pcmcia
1452 show guest PCMCIA status
1453 @item info mice
1454 show which guest mouse is receiving events
1455 @item info vnc
1456 show the vnc server status
1457 @item info name
1458 show the current VM name
1459 @item info uuid
1460 show the current VM UUID
1461 @item info cpustats
1462 show CPU statistics
1463 @item info usernet
1464 show user network stack connection states
1465 @item info migrate
1466 show migration status
1467 @item info migrate_capabilities
1468 show current migration capabilities
1469 @item info migrate_cache_size
1470 show current migration XBZRLE cache size
1471 @item info balloon
1472 show balloon information
1473 @item info qtree
1474 show device tree
1475 @item info qdm
1476 show qdev device model list
1477 @item info roms
1478 show roms
1479 @end table
1480 ETEXI
1482 #ifdef CONFIG_TRACE_SIMPLE
1483 STEXI
1484 @item info trace
1485 show contents of trace buffer
1486 ETEXI
1487 #endif
1489 STEXI
1490 @item info trace-events
1491 show available trace events and their state
1492 ETEXI
1494 STEXI
1495 @end table
1496 ETEXI