configure: Drop CONFIG_ATFILE test
[qemu/ar7.git] / hmp-commands.hx
blob396691a5d61e32753aff6f5cfd13f349cd0667fc
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 = "force:-f,device:B",
103 .params = "[-f] device",
104 .help = "stop an active background block operation (use -f"
105 "\n\t\t\t if the operation is currently paused)",
106 .mhandler.cmd = hmp_block_job_cancel,
109 STEXI
110 @item block_job_cancel
111 @findex block_job_cancel
112 Stop an active background block operation (streaming, mirroring).
113 ETEXI
116 .name = "block_job_complete",
117 .args_type = "device:B",
118 .params = "device",
119 .help = "stop an active background block operation",
120 .mhandler.cmd = hmp_block_job_complete,
123 STEXI
124 @item block_job_complete
125 @findex block_job_complete
126 Manually trigger completion of an active background block operation.
127 For mirroring, this will switch the device to the destination path.
128 ETEXI
131 .name = "block_job_pause",
132 .args_type = "device:B",
133 .params = "device",
134 .help = "pause an active background block operation",
135 .mhandler.cmd = hmp_block_job_pause,
138 STEXI
139 @item block_job_pause
140 @findex block_job_pause
141 Pause an active block streaming operation.
142 ETEXI
145 .name = "block_job_resume",
146 .args_type = "device:B",
147 .params = "device",
148 .help = "resume a paused background block operation",
149 .mhandler.cmd = hmp_block_job_resume,
152 STEXI
153 @item block_job_resume
154 @findex block_job_resume
155 Resume a paused block streaming operation.
156 ETEXI
159 .name = "eject",
160 .args_type = "force:-f,device:B",
161 .params = "[-f] device",
162 .help = "eject a removable medium (use -f to force it)",
163 .mhandler.cmd = hmp_eject,
166 STEXI
167 @item eject [-f] @var{device}
168 @findex eject
169 Eject a removable medium (use -f to force it).
170 ETEXI
173 .name = "drive_del",
174 .args_type = "id:s",
175 .params = "device",
176 .help = "remove host block device",
177 .user_print = monitor_user_noop,
178 .mhandler.cmd_new = do_drive_del,
181 STEXI
182 @item drive_del @var{device}
183 @findex drive_del
184 Remove host block device. The result is that guest generated IO is no longer
185 submitted against the host device underlying the disk. Once a drive has
186 been deleted, the QEMU Block layer returns -EIO which results in IO
187 errors in the guest for applications that are reading/writing to the device.
188 These errors are always reported to the guest, regardless of the drive's error
189 actions (drive options rerror, werror).
190 ETEXI
193 .name = "change",
194 .args_type = "device:B,target:F,arg:s?",
195 .params = "device filename [format]",
196 .help = "change a removable medium, optional format",
197 .mhandler.cmd = hmp_change,
200 STEXI
201 @item change @var{device} @var{setting}
202 @findex change
204 Change the configuration of a device.
206 @table @option
207 @item change @var{diskdevice} @var{filename} [@var{format}]
208 Change the medium for a removable disk device to point to @var{filename}. eg
210 @example
211 (qemu) change ide1-cd0 /path/to/some.iso
212 @end example
214 @var{format} is optional.
216 @item change vnc @var{display},@var{options}
217 Change the configuration of the VNC server. The valid syntax for @var{display}
218 and @var{options} are described at @ref{sec_invocation}. eg
220 @example
221 (qemu) change vnc localhost:1
222 @end example
224 @item change vnc password [@var{password}]
226 Change the password associated with the VNC server. If the new password is not
227 supplied, the monitor will prompt for it to be entered. VNC passwords are only
228 significant up to 8 letters. eg
230 @example
231 (qemu) change vnc password
232 Password: ********
233 @end example
235 @end table
236 ETEXI
239 .name = "screendump",
240 .args_type = "filename:F",
241 .params = "filename",
242 .help = "save screen into PPM image 'filename'",
243 .mhandler.cmd = hmp_screen_dump,
246 STEXI
247 @item screendump @var{filename}
248 @findex screendump
249 Save screen into PPM image @var{filename}.
250 ETEXI
253 .name = "logfile",
254 .args_type = "filename:F",
255 .params = "filename",
256 .help = "output logs to 'filename'",
257 .mhandler.cmd = do_logfile,
260 STEXI
261 @item logfile @var{filename}
262 @findex logfile
263 Output logs to @var{filename}.
264 ETEXI
267 .name = "trace-event",
268 .args_type = "name:s,option:b",
269 .params = "name on|off",
270 .help = "changes status of a specific trace event",
271 .mhandler.cmd = do_trace_event_set_state,
274 STEXI
275 @item trace-event
276 @findex trace-event
277 changes status of a trace event
278 ETEXI
280 #if defined(CONFIG_TRACE_SIMPLE)
282 .name = "trace-file",
283 .args_type = "op:s?,arg:F?",
284 .params = "on|off|flush|set [arg]",
285 .help = "open, close, or flush trace file, or set a new file name",
286 .mhandler.cmd = do_trace_file,
289 STEXI
290 @item trace-file on|off|flush
291 @findex trace-file
292 Open, close, or flush the trace file. If no argument is given, the status of the trace file is displayed.
293 ETEXI
294 #endif
297 .name = "log",
298 .args_type = "items:s",
299 .params = "item1[,...]",
300 .help = "activate logging of the specified items",
301 .mhandler.cmd = do_log,
304 STEXI
305 @item log @var{item1}[,...]
306 @findex log
307 Activate logging of the specified items.
308 ETEXI
311 .name = "savevm",
312 .args_type = "name:s?",
313 .params = "[tag|id]",
314 .help = "save a VM snapshot. If no tag or id are provided, a new snapshot is created",
315 .mhandler.cmd = do_savevm,
318 STEXI
319 @item savevm [@var{tag}|@var{id}]
320 @findex savevm
321 Create a snapshot of the whole virtual machine. If @var{tag} is
322 provided, it is used as human readable identifier. If there is already
323 a snapshot with the same tag or ID, it is replaced. More info at
324 @ref{vm_snapshots}.
325 ETEXI
328 .name = "loadvm",
329 .args_type = "name:s",
330 .params = "tag|id",
331 .help = "restore a VM snapshot from its tag or id",
332 .mhandler.cmd = do_loadvm,
335 STEXI
336 @item loadvm @var{tag}|@var{id}
337 @findex loadvm
338 Set the whole virtual machine to the snapshot identified by the tag
339 @var{tag} or the unique snapshot ID @var{id}.
340 ETEXI
343 .name = "delvm",
344 .args_type = "name:s",
345 .params = "tag|id",
346 .help = "delete a VM snapshot from its tag or id",
347 .mhandler.cmd = do_delvm,
350 STEXI
351 @item delvm @var{tag}|@var{id}
352 @findex delvm
353 Delete the snapshot identified by @var{tag} or @var{id}.
354 ETEXI
357 .name = "singlestep",
358 .args_type = "option:s?",
359 .params = "[on|off]",
360 .help = "run emulation in singlestep mode or switch to normal mode",
361 .mhandler.cmd = do_singlestep,
364 STEXI
365 @item singlestep [off]
366 @findex singlestep
367 Run the emulation in single step mode.
368 If called with option off, the emulation returns to normal mode.
369 ETEXI
372 .name = "stop",
373 .args_type = "",
374 .params = "",
375 .help = "stop emulation",
376 .mhandler.cmd = hmp_stop,
379 STEXI
380 @item stop
381 @findex stop
382 Stop emulation.
383 ETEXI
386 .name = "c|cont",
387 .args_type = "",
388 .params = "",
389 .help = "resume emulation",
390 .mhandler.cmd = hmp_cont,
393 STEXI
394 @item c or cont
395 @findex cont
396 Resume emulation.
397 ETEXI
400 .name = "system_wakeup",
401 .args_type = "",
402 .params = "",
403 .help = "wakeup guest from suspend",
404 .mhandler.cmd = hmp_system_wakeup,
407 STEXI
408 @item system_wakeup
409 @findex system_wakeup
410 Wakeup guest from suspend.
411 ETEXI
414 .name = "gdbserver",
415 .args_type = "device:s?",
416 .params = "[device]",
417 .help = "start gdbserver on given device (default 'tcp::1234'), stop with 'none'",
418 .mhandler.cmd = do_gdbserver,
421 STEXI
422 @item gdbserver [@var{port}]
423 @findex gdbserver
424 Start gdbserver session (default @var{port}=1234)
425 ETEXI
428 .name = "x",
429 .args_type = "fmt:/,addr:l",
430 .params = "/fmt addr",
431 .help = "virtual memory dump starting at 'addr'",
432 .mhandler.cmd = do_memory_dump,
435 STEXI
436 @item x/fmt @var{addr}
437 @findex x
438 Virtual memory dump starting at @var{addr}.
439 ETEXI
442 .name = "xp",
443 .args_type = "fmt:/,addr:l",
444 .params = "/fmt addr",
445 .help = "physical memory dump starting at 'addr'",
446 .mhandler.cmd = do_physical_memory_dump,
449 STEXI
450 @item xp /@var{fmt} @var{addr}
451 @findex xp
452 Physical memory dump starting at @var{addr}.
454 @var{fmt} is a format which tells the command how to format the
455 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
457 @table @var
458 @item count
459 is the number of items to be dumped.
461 @item format
462 can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
463 c (char) or i (asm instruction).
465 @item size
466 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
467 @code{h} or @code{w} can be specified with the @code{i} format to
468 respectively select 16 or 32 bit code instruction size.
470 @end table
472 Examples:
473 @itemize
474 @item
475 Dump 10 instructions at the current instruction pointer:
476 @example
477 (qemu) x/10i $eip
478 0x90107063: ret
479 0x90107064: sti
480 0x90107065: lea 0x0(%esi,1),%esi
481 0x90107069: lea 0x0(%edi,1),%edi
482 0x90107070: ret
483 0x90107071: jmp 0x90107080
484 0x90107073: nop
485 0x90107074: nop
486 0x90107075: nop
487 0x90107076: nop
488 @end example
490 @item
491 Dump 80 16 bit values at the start of the video memory.
492 @smallexample
493 (qemu) xp/80hx 0xb8000
494 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
495 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
496 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
497 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
498 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
499 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
500 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
501 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
502 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
503 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
504 @end smallexample
505 @end itemize
506 ETEXI
509 .name = "p|print",
510 .args_type = "fmt:/,val:l",
511 .params = "/fmt expr",
512 .help = "print expression value (use $reg for CPU register access)",
513 .mhandler.cmd = do_print,
516 STEXI
517 @item p or print/@var{fmt} @var{expr}
518 @findex print
520 Print expression value. Only the @var{format} part of @var{fmt} is
521 used.
522 ETEXI
525 .name = "i",
526 .args_type = "fmt:/,addr:i,index:i.",
527 .params = "/fmt addr",
528 .help = "I/O port read",
529 .mhandler.cmd = do_ioport_read,
532 STEXI
533 Read I/O port.
534 ETEXI
537 .name = "o",
538 .args_type = "fmt:/,addr:i,val:i",
539 .params = "/fmt addr value",
540 .help = "I/O port write",
541 .mhandler.cmd = do_ioport_write,
544 STEXI
545 Write to I/O port.
546 ETEXI
549 .name = "sendkey",
550 .args_type = "keys:s,hold-time:i?",
551 .params = "keys [hold_ms]",
552 .help = "send keys to the VM (e.g. 'sendkey ctrl-alt-f1', default hold time=100 ms)",
553 .mhandler.cmd = hmp_send_key,
556 STEXI
557 @item sendkey @var{keys}
558 @findex sendkey
560 Send @var{keys} to the guest. @var{keys} could be the name of the
561 key or the raw value in hexadecimal format. Use @code{-} to press
562 several keys simultaneously. Example:
563 @example
564 sendkey ctrl-alt-f1
565 @end example
567 This command is useful to send keys that your graphical user interface
568 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
569 ETEXI
572 .name = "system_reset",
573 .args_type = "",
574 .params = "",
575 .help = "reset the system",
576 .mhandler.cmd = hmp_system_reset,
579 STEXI
580 @item system_reset
581 @findex system_reset
583 Reset the system.
584 ETEXI
587 .name = "system_powerdown",
588 .args_type = "",
589 .params = "",
590 .help = "send system power down event",
591 .mhandler.cmd = hmp_system_powerdown,
594 STEXI
595 @item system_powerdown
596 @findex system_powerdown
598 Power down the system (if supported).
599 ETEXI
602 .name = "sum",
603 .args_type = "start:i,size:i",
604 .params = "addr size",
605 .help = "compute the checksum of a memory region",
606 .mhandler.cmd = do_sum,
609 STEXI
610 @item sum @var{addr} @var{size}
611 @findex sum
613 Compute the checksum of a memory region.
614 ETEXI
617 .name = "usb_add",
618 .args_type = "devname:s",
619 .params = "device",
620 .help = "add USB device (e.g. 'host:bus.addr' or 'host:vendor_id:product_id')",
621 .mhandler.cmd = do_usb_add,
624 STEXI
625 @item usb_add @var{devname}
626 @findex usb_add
628 Add the USB device @var{devname}. For details of available devices see
629 @ref{usb_devices}
630 ETEXI
633 .name = "usb_del",
634 .args_type = "devname:s",
635 .params = "device",
636 .help = "remove USB device 'bus.addr'",
637 .mhandler.cmd = do_usb_del,
640 STEXI
641 @item usb_del @var{devname}
642 @findex usb_del
644 Remove the USB device @var{devname} from the QEMU virtual USB
645 hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
646 command @code{info usb} to see the devices you can remove.
647 ETEXI
650 .name = "device_add",
651 .args_type = "device:O",
652 .params = "driver[,prop=value][,...]",
653 .help = "add device, like -device on the command line",
654 .user_print = monitor_user_noop,
655 .mhandler.cmd_new = do_device_add,
658 STEXI
659 @item device_add @var{config}
660 @findex device_add
662 Add device.
663 ETEXI
666 .name = "device_del",
667 .args_type = "id:s",
668 .params = "device",
669 .help = "remove device",
670 .mhandler.cmd = hmp_device_del,
673 STEXI
674 @item device_del @var{id}
675 @findex device_del
677 Remove device @var{id}.
678 ETEXI
681 .name = "cpu",
682 .args_type = "index:i",
683 .params = "index",
684 .help = "set the default CPU",
685 .mhandler.cmd = hmp_cpu,
688 STEXI
689 @item cpu @var{index}
690 @findex cpu
691 Set the default CPU.
692 ETEXI
695 .name = "mouse_move",
696 .args_type = "dx_str:s,dy_str:s,dz_str:s?",
697 .params = "dx dy [dz]",
698 .help = "send mouse move events",
699 .mhandler.cmd = do_mouse_move,
702 STEXI
703 @item mouse_move @var{dx} @var{dy} [@var{dz}]
704 @findex mouse_move
705 Move the active mouse to the specified coordinates @var{dx} @var{dy}
706 with optional scroll axis @var{dz}.
707 ETEXI
710 .name = "mouse_button",
711 .args_type = "button_state:i",
712 .params = "state",
713 .help = "change mouse button state (1=L, 2=M, 4=R)",
714 .mhandler.cmd = do_mouse_button,
717 STEXI
718 @item mouse_button @var{val}
719 @findex mouse_button
720 Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
721 ETEXI
724 .name = "mouse_set",
725 .args_type = "index:i",
726 .params = "index",
727 .help = "set which mouse device receives events",
728 .mhandler.cmd = do_mouse_set,
731 STEXI
732 @item mouse_set @var{index}
733 @findex mouse_set
734 Set which mouse device receives events at given @var{index}, index
735 can be obtained with
736 @example
737 info mice
738 @end example
739 ETEXI
742 .name = "wavcapture",
743 .args_type = "path:F,freq:i?,bits:i?,nchannels:i?",
744 .params = "path [frequency [bits [channels]]]",
745 .help = "capture audio to a wave file (default frequency=44100 bits=16 channels=2)",
746 .mhandler.cmd = do_wav_capture,
748 STEXI
749 @item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
750 @findex wavcapture
751 Capture audio into @var{filename}. Using sample rate @var{frequency}
752 bits per sample @var{bits} and number of channels @var{channels}.
754 Defaults:
755 @itemize @minus
756 @item Sample rate = 44100 Hz - CD quality
757 @item Bits = 16
758 @item Number of channels = 2 - Stereo
759 @end itemize
760 ETEXI
763 .name = "stopcapture",
764 .args_type = "n:i",
765 .params = "capture index",
766 .help = "stop capture",
767 .mhandler.cmd = do_stop_capture,
769 STEXI
770 @item stopcapture @var{index}
771 @findex stopcapture
772 Stop capture with a given @var{index}, index can be obtained with
773 @example
774 info capture
775 @end example
776 ETEXI
779 .name = "memsave",
780 .args_type = "val:l,size:i,filename:s",
781 .params = "addr size file",
782 .help = "save to disk virtual memory dump starting at 'addr' of size 'size'",
783 .mhandler.cmd = hmp_memsave,
786 STEXI
787 @item memsave @var{addr} @var{size} @var{file}
788 @findex memsave
789 save to disk virtual memory dump starting at @var{addr} of size @var{size}.
790 ETEXI
793 .name = "pmemsave",
794 .args_type = "val:l,size:i,filename:s",
795 .params = "addr size file",
796 .help = "save to disk physical memory dump starting at 'addr' of size 'size'",
797 .mhandler.cmd = hmp_pmemsave,
800 STEXI
801 @item pmemsave @var{addr} @var{size} @var{file}
802 @findex pmemsave
803 save to disk physical memory dump starting at @var{addr} of size @var{size}.
804 ETEXI
807 .name = "boot_set",
808 .args_type = "bootdevice:s",
809 .params = "bootdevice",
810 .help = "define new values for the boot device list",
811 .mhandler.cmd = do_boot_set,
814 STEXI
815 @item boot_set @var{bootdevicelist}
816 @findex boot_set
818 Define new values for the boot device list. Those values will override
819 the values specified on the command line through the @code{-boot} option.
821 The values that can be specified here depend on the machine type, but are
822 the same that can be specified in the @code{-boot} command line option.
823 ETEXI
825 #if defined(TARGET_I386)
827 .name = "nmi",
828 .args_type = "",
829 .params = "",
830 .help = "inject an NMI on all guest's CPUs",
831 .mhandler.cmd = hmp_inject_nmi,
833 #endif
834 STEXI
835 @item nmi @var{cpu}
836 @findex nmi
837 Inject an NMI on the given CPU (x86 only).
839 ETEXI
842 .name = "ringbuf_write",
843 .args_type = "device:s,data:s",
844 .params = "device data",
845 .help = "Write to a ring buffer character device",
846 .mhandler.cmd = hmp_ringbuf_write,
849 STEXI
850 @item ringbuf_write @var{device} @var{data}
851 @findex ringbuf_write
852 Write @var{data} to ring buffer character device @var{device}.
853 @var{data} must be a UTF-8 string.
855 ETEXI
858 .name = "ringbuf_read",
859 .args_type = "device:s,size:i",
860 .params = "device size",
861 .help = "Read from a ring buffer character device",
862 .mhandler.cmd = hmp_ringbuf_read,
865 STEXI
866 @item ringbuf_read @var{device}
867 @findex ringbuf_read
868 Read and print up to @var{size} bytes from ring buffer character
869 device @var{device}.
870 Certain non-printable characters are printed \uXXXX, where XXXX is the
871 character code in hexadecimal. Character \ is printed \\.
872 Bug: can screw up when the buffer contains invalid UTF-8 sequences,
873 NUL characters, after the ring buffer lost data, and when reading
874 stops because the size limit is reached.
876 ETEXI
879 .name = "migrate",
880 .args_type = "detach:-d,blk:-b,inc:-i,uri:s",
881 .params = "[-d] [-b] [-i] uri",
882 .help = "migrate to URI (using -d to not wait for completion)"
883 "\n\t\t\t -b for migration without shared storage with"
884 " full copy of disk\n\t\t\t -i for migration without "
885 "shared storage with incremental copy of disk "
886 "(base image shared between src and destination)",
887 .mhandler.cmd = hmp_migrate,
891 STEXI
892 @item migrate [-d] [-b] [-i] @var{uri}
893 @findex migrate
894 Migrate to @var{uri} (using -d to not wait for completion).
895 -b for migration with full copy of disk
896 -i for migration with incremental copy of disk (base image is shared)
897 ETEXI
900 .name = "migrate_cancel",
901 .args_type = "",
902 .params = "",
903 .help = "cancel the current VM migration",
904 .mhandler.cmd = hmp_migrate_cancel,
907 STEXI
908 @item migrate_cancel
909 @findex migrate_cancel
910 Cancel the current VM migration.
912 ETEXI
915 .name = "migrate_set_cache_size",
916 .args_type = "value:o",
917 .params = "value",
918 .help = "set cache size (in bytes) for XBZRLE migrations,"
919 "the cache size will be rounded down to the nearest "
920 "power of 2.\n"
921 "The cache size affects the number of cache misses."
922 "In case of a high cache miss ratio you need to increase"
923 " the cache size",
924 .mhandler.cmd = hmp_migrate_set_cache_size,
927 STEXI
928 @item migrate_set_cache_size @var{value}
929 @findex migrate_set_cache_size
930 Set cache size to @var{value} (in bytes) for xbzrle migrations.
931 ETEXI
934 .name = "migrate_set_speed",
935 .args_type = "value:o",
936 .params = "value",
937 .help = "set maximum speed (in bytes) for migrations. "
938 "Defaults to MB if no size suffix is specified, ie. B/K/M/G/T",
939 .mhandler.cmd = hmp_migrate_set_speed,
942 STEXI
943 @item migrate_set_speed @var{value}
944 @findex migrate_set_speed
945 Set maximum speed to @var{value} (in bytes) for migrations.
946 ETEXI
949 .name = "migrate_set_downtime",
950 .args_type = "value:T",
951 .params = "value",
952 .help = "set maximum tolerated downtime (in seconds) for migrations",
953 .mhandler.cmd = hmp_migrate_set_downtime,
956 STEXI
957 @item migrate_set_downtime @var{second}
958 @findex migrate_set_downtime
959 Set maximum tolerated downtime (in seconds) for migration.
960 ETEXI
963 .name = "migrate_set_capability",
964 .args_type = "capability:s,state:b",
965 .params = "capability state",
966 .help = "Enable/Disable the usage of a capability for migration",
967 .mhandler.cmd = hmp_migrate_set_capability,
970 STEXI
971 @item migrate_set_capability @var{capability} @var{state}
972 @findex migrate_set_capability
973 Enable/Disable the usage of a capability @var{capability} for migration.
974 ETEXI
977 .name = "client_migrate_info",
978 .args_type = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
979 .params = "protocol hostname port tls-port cert-subject",
980 .help = "send migration info to spice/vnc client",
981 .user_print = monitor_user_noop,
982 .mhandler.cmd_async = client_migrate_info,
983 .flags = MONITOR_CMD_ASYNC,
986 STEXI
987 @item client_migrate_info @var{protocol} @var{hostname} @var{port} @var{tls-port} @var{cert-subject}
988 @findex client_migrate_info
989 Set the spice/vnc connection info for the migration target. The spice/vnc
990 server will ask the spice/vnc client to automatically reconnect using the
991 new parameters (if specified) once the vm migration finished successfully.
992 ETEXI
994 #if defined(CONFIG_HAVE_CORE_DUMP)
996 .name = "dump-guest-memory",
997 .args_type = "paging:-p,filename:F,begin:i?,length:i?",
998 .params = "[-p] filename [begin] [length]",
999 .help = "dump guest memory to file"
1000 "\n\t\t\t begin(optional): the starting physical address"
1001 "\n\t\t\t length(optional): the memory size, in bytes",
1002 .mhandler.cmd = hmp_dump_guest_memory,
1006 STEXI
1007 @item dump-guest-memory [-p] @var{protocol} @var{begin} @var{length}
1008 @findex dump-guest-memory
1009 Dump guest memory to @var{protocol}. The file can be processed with crash or
1010 gdb.
1011 filename: dump file name
1012 paging: do paging to get guest's memory mapping
1013 begin: the starting physical address. It's optional, and should be
1014 specified with length together.
1015 length: the memory size, in bytes. It's optional, and should be specified
1016 with begin together.
1017 ETEXI
1018 #endif
1021 .name = "snapshot_blkdev",
1022 .args_type = "reuse:-n,device:B,snapshot-file:s?,format:s?",
1023 .params = "[-n] device [new-image-file] [format]",
1024 .help = "initiates a live snapshot\n\t\t\t"
1025 "of device. If a new image file is specified, the\n\t\t\t"
1026 "new image file will become the new root image.\n\t\t\t"
1027 "If format is specified, the snapshot file will\n\t\t\t"
1028 "be created in that format. Otherwise the\n\t\t\t"
1029 "snapshot will be internal! (currently unsupported).\n\t\t\t"
1030 "The default format is qcow2. The -n flag requests QEMU\n\t\t\t"
1031 "to reuse the image found in new-image-file, instead of\n\t\t\t"
1032 "recreating it from scratch.",
1033 .mhandler.cmd = hmp_snapshot_blkdev,
1036 STEXI
1037 @item snapshot_blkdev
1038 @findex snapshot_blkdev
1039 Snapshot device, using snapshot file as target if provided
1040 ETEXI
1043 .name = "drive_mirror",
1044 .args_type = "reuse:-n,full:-f,device:B,target:s,format:s?",
1045 .params = "[-n] [-f] device target [format]",
1046 .help = "initiates live storage\n\t\t\t"
1047 "migration for a device. The device's contents are\n\t\t\t"
1048 "copied to the new image file, including data that\n\t\t\t"
1049 "is written after the command is started.\n\t\t\t"
1050 "The -n flag requests QEMU to reuse the image found\n\t\t\t"
1051 "in new-image-file, instead of recreating it from scratch.\n\t\t\t"
1052 "The -f flag requests QEMU to copy the whole disk,\n\t\t\t"
1053 "so that the result does not need a backing file.\n\t\t\t",
1054 .mhandler.cmd = hmp_drive_mirror,
1056 STEXI
1057 @item drive_mirror
1058 @findex drive_mirror
1059 Start mirroring a block device's writes to a new destination,
1060 using the specified target.
1061 ETEXI
1064 .name = "drive_add",
1065 .args_type = "pci_addr:s,opts:s",
1066 .params = "[[<domain>:]<bus>:]<slot>\n"
1067 "[file=file][,if=type][,bus=n]\n"
1068 "[,unit=m][,media=d][,index=i]\n"
1069 "[,cyls=c,heads=h,secs=s[,trans=t]]\n"
1070 "[,snapshot=on|off][,cache=on|off]\n"
1071 "[,readonly=on|off][,copy-on-read=on|off]",
1072 .help = "add drive to PCI storage controller",
1073 .mhandler.cmd = drive_hot_add,
1076 STEXI
1077 @item drive_add
1078 @findex drive_add
1079 Add drive to PCI storage controller.
1080 ETEXI
1082 #if defined(TARGET_I386)
1084 .name = "pci_add",
1085 .args_type = "pci_addr:s,type:s,opts:s?",
1086 .params = "auto|[[<domain>:]<bus>:]<slot> nic|storage [[vlan=n][,macaddr=addr][,model=type]] [file=file][,if=type][,bus=nr]...",
1087 .help = "hot-add PCI device",
1088 .mhandler.cmd = pci_device_hot_add,
1090 #endif
1092 STEXI
1093 @item pci_add
1094 @findex pci_add
1095 Hot-add PCI device.
1096 ETEXI
1098 #if defined(TARGET_I386)
1100 .name = "pci_del",
1101 .args_type = "pci_addr:s",
1102 .params = "[[<domain>:]<bus>:]<slot>",
1103 .help = "hot remove PCI device",
1104 .mhandler.cmd = do_pci_device_hot_remove,
1106 #endif
1108 STEXI
1109 @item pci_del
1110 @findex pci_del
1111 Hot remove PCI device.
1112 ETEXI
1115 .name = "pcie_aer_inject_error",
1116 .args_type = "advisory_non_fatal:-a,correctable:-c,"
1117 "id:s,error_status:s,"
1118 "header0:i?,header1:i?,header2:i?,header3:i?,"
1119 "prefix0:i?,prefix1:i?,prefix2:i?,prefix3:i?",
1120 .params = "[-a] [-c] id "
1121 "<error_status> [<tlp header> [<tlp header prefix>]]",
1122 .help = "inject pcie aer error\n\t\t\t"
1123 " -a for advisory non fatal error\n\t\t\t"
1124 " -c for correctable error\n\t\t\t"
1125 "<id> = qdev device id\n\t\t\t"
1126 "<error_status> = error string or 32bit\n\t\t\t"
1127 "<tlb header> = 32bit x 4\n\t\t\t"
1128 "<tlb header prefix> = 32bit x 4",
1129 .user_print = pcie_aer_inject_error_print,
1130 .mhandler.cmd_new = do_pcie_aer_inject_error,
1133 STEXI
1134 @item pcie_aer_inject_error
1135 @findex pcie_aer_inject_error
1136 Inject PCIe AER error
1137 ETEXI
1140 .name = "host_net_add",
1141 .args_type = "device:s,opts:s?",
1142 .params = "tap|user|socket|vde|dump [options]",
1143 .help = "add host VLAN client",
1144 .mhandler.cmd = net_host_device_add,
1147 STEXI
1148 @item host_net_add
1149 @findex host_net_add
1150 Add host VLAN client.
1151 ETEXI
1154 .name = "host_net_remove",
1155 .args_type = "vlan_id:i,device:s",
1156 .params = "vlan_id name",
1157 .help = "remove host VLAN client",
1158 .mhandler.cmd = net_host_device_remove,
1161 STEXI
1162 @item host_net_remove
1163 @findex host_net_remove
1164 Remove host VLAN client.
1165 ETEXI
1168 .name = "netdev_add",
1169 .args_type = "netdev:O",
1170 .params = "[user|tap|socket|hubport],id=str[,prop=value][,...]",
1171 .help = "add host network device",
1172 .mhandler.cmd = hmp_netdev_add,
1175 STEXI
1176 @item netdev_add
1177 @findex netdev_add
1178 Add host network device.
1179 ETEXI
1182 .name = "netdev_del",
1183 .args_type = "id:s",
1184 .params = "id",
1185 .help = "remove host network device",
1186 .mhandler.cmd = hmp_netdev_del,
1189 STEXI
1190 @item netdev_del
1191 @findex netdev_del
1192 Remove host network device.
1193 ETEXI
1195 #ifdef CONFIG_SLIRP
1197 .name = "hostfwd_add",
1198 .args_type = "arg1:s,arg2:s?,arg3:s?",
1199 .params = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport",
1200 .help = "redirect TCP or UDP connections from host to guest (requires -net user)",
1201 .mhandler.cmd = net_slirp_hostfwd_add,
1203 #endif
1204 STEXI
1205 @item hostfwd_add
1206 @findex hostfwd_add
1207 Redirect TCP or UDP connections from host to guest (requires -net user).
1208 ETEXI
1210 #ifdef CONFIG_SLIRP
1212 .name = "hostfwd_remove",
1213 .args_type = "arg1:s,arg2:s?,arg3:s?",
1214 .params = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport",
1215 .help = "remove host-to-guest TCP or UDP redirection",
1216 .mhandler.cmd = net_slirp_hostfwd_remove,
1219 #endif
1220 STEXI
1221 @item hostfwd_remove
1222 @findex hostfwd_remove
1223 Remove host-to-guest TCP or UDP redirection.
1224 ETEXI
1227 .name = "balloon",
1228 .args_type = "value:M",
1229 .params = "target",
1230 .help = "request VM to change its memory allocation (in MB)",
1231 .mhandler.cmd = hmp_balloon,
1234 STEXI
1235 @item balloon @var{value}
1236 @findex balloon
1237 Request VM to change its memory allocation to @var{value} (in MB).
1238 ETEXI
1241 .name = "set_link",
1242 .args_type = "name:s,up:b",
1243 .params = "name on|off",
1244 .help = "change the link status of a network adapter",
1245 .mhandler.cmd = hmp_set_link,
1248 STEXI
1249 @item set_link @var{name} [on|off]
1250 @findex set_link
1251 Switch link @var{name} on (i.e. up) or off (i.e. down).
1252 ETEXI
1255 .name = "watchdog_action",
1256 .args_type = "action:s",
1257 .params = "[reset|shutdown|poweroff|pause|debug|none]",
1258 .help = "change watchdog action",
1259 .mhandler.cmd = do_watchdog_action,
1262 STEXI
1263 @item watchdog_action
1264 @findex watchdog_action
1265 Change watchdog action.
1266 ETEXI
1269 .name = "acl_show",
1270 .args_type = "aclname:s",
1271 .params = "aclname",
1272 .help = "list rules in the access control list",
1273 .mhandler.cmd = do_acl_show,
1276 STEXI
1277 @item acl_show @var{aclname}
1278 @findex acl_show
1279 List all the matching rules in the access control list, and the default
1280 policy. There are currently two named access control lists,
1281 @var{vnc.x509dname} and @var{vnc.username} matching on the x509 client
1282 certificate distinguished name, and SASL username respectively.
1283 ETEXI
1286 .name = "acl_policy",
1287 .args_type = "aclname:s,policy:s",
1288 .params = "aclname allow|deny",
1289 .help = "set default access control list policy",
1290 .mhandler.cmd = do_acl_policy,
1293 STEXI
1294 @item acl_policy @var{aclname} @code{allow|deny}
1295 @findex acl_policy
1296 Set the default access control list policy, used in the event that
1297 none of the explicit rules match. The default policy at startup is
1298 always @code{deny}.
1299 ETEXI
1302 .name = "acl_add",
1303 .args_type = "aclname:s,match:s,policy:s,index:i?",
1304 .params = "aclname match allow|deny [index]",
1305 .help = "add a match rule to the access control list",
1306 .mhandler.cmd = do_acl_add,
1309 STEXI
1310 @item acl_add @var{aclname} @var{match} @code{allow|deny} [@var{index}]
1311 @findex acl_add
1312 Add a match rule to the access control list, allowing or denying access.
1313 The match will normally be an exact username or x509 distinguished name,
1314 but can optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to
1315 allow all users in the @code{EXAMPLE.COM} kerberos realm. The match will
1316 normally be appended to the end of the ACL, but can be inserted
1317 earlier in the list if the optional @var{index} parameter is supplied.
1318 ETEXI
1321 .name = "acl_remove",
1322 .args_type = "aclname:s,match:s",
1323 .params = "aclname match",
1324 .help = "remove a match rule from the access control list",
1325 .mhandler.cmd = do_acl_remove,
1328 STEXI
1329 @item acl_remove @var{aclname} @var{match}
1330 @findex acl_remove
1331 Remove the specified match rule from the access control list.
1332 ETEXI
1335 .name = "acl_reset",
1336 .args_type = "aclname:s",
1337 .params = "aclname",
1338 .help = "reset the access control list",
1339 .mhandler.cmd = do_acl_reset,
1342 STEXI
1343 @item acl_reset @var{aclname}
1344 @findex acl_reset
1345 Remove all matches from the access control list, and set the default
1346 policy back to @code{deny}.
1347 ETEXI
1350 .name = "nbd_server_start",
1351 .args_type = "all:-a,writable:-w,uri:s",
1352 .params = "nbd_server_start [-a] [-w] host:port",
1353 .help = "serve block devices on the given host and port",
1354 .mhandler.cmd = hmp_nbd_server_start,
1356 STEXI
1357 @item nbd_server_start @var{host}:@var{port}
1358 @findex nbd_server_start
1359 Start an NBD server on the given host and/or port. If the @option{-a}
1360 option is included, all of the virtual machine's block devices that
1361 have an inserted media on them are automatically exported; in this case,
1362 the @option{-w} option makes the devices writable too.
1363 ETEXI
1366 .name = "nbd_server_add",
1367 .args_type = "writable:-w,device:B",
1368 .params = "nbd_server_add [-w] device",
1369 .help = "export a block device via NBD",
1370 .mhandler.cmd = hmp_nbd_server_add,
1372 STEXI
1373 @item nbd_server_add @var{device}
1374 @findex nbd_server_add
1375 Export a block device through QEMU's NBD server, which must be started
1376 beforehand with @command{nbd_server_start}. The @option{-w} option makes the
1377 exported device writable too.
1378 ETEXI
1381 .name = "nbd_server_stop",
1382 .args_type = "",
1383 .params = "nbd_server_stop",
1384 .help = "stop serving block devices using the NBD protocol",
1385 .mhandler.cmd = hmp_nbd_server_stop,
1387 STEXI
1388 @item nbd_server_stop
1389 @findex nbd_server_stop
1390 Stop the QEMU embedded NBD server.
1391 ETEXI
1394 #if defined(TARGET_I386)
1397 .name = "mce",
1398 .args_type = "broadcast:-b,cpu_index:i,bank:i,status:l,mcg_status:l,addr:l,misc:l",
1399 .params = "[-b] cpu bank status mcgstatus addr misc",
1400 .help = "inject a MCE on the given CPU [and broadcast to other CPUs with -b option]",
1401 .mhandler.cmd = do_inject_mce,
1404 #endif
1405 STEXI
1406 @item mce @var{cpu} @var{bank} @var{status} @var{mcgstatus} @var{addr} @var{misc}
1407 @findex mce (x86)
1408 Inject an MCE on the given CPU (x86 only).
1409 ETEXI
1412 .name = "getfd",
1413 .args_type = "fdname:s",
1414 .params = "getfd name",
1415 .help = "receive a file descriptor via SCM rights and assign it a name",
1416 .mhandler.cmd = hmp_getfd,
1419 STEXI
1420 @item getfd @var{fdname}
1421 @findex getfd
1422 If a file descriptor is passed alongside this command using the SCM_RIGHTS
1423 mechanism on unix sockets, it is stored using the name @var{fdname} for
1424 later use by other monitor commands.
1425 ETEXI
1428 .name = "closefd",
1429 .args_type = "fdname:s",
1430 .params = "closefd name",
1431 .help = "close a file descriptor previously passed via SCM rights",
1432 .mhandler.cmd = hmp_closefd,
1435 STEXI
1436 @item closefd @var{fdname}
1437 @findex closefd
1438 Close the file descriptor previously assigned to @var{fdname} using the
1439 @code{getfd} command. This is only needed if the file descriptor was never
1440 used by another monitor command.
1441 ETEXI
1444 .name = "block_passwd",
1445 .args_type = "device:B,password:s",
1446 .params = "block_passwd device password",
1447 .help = "set the password of encrypted block devices",
1448 .mhandler.cmd = hmp_block_passwd,
1451 STEXI
1452 @item block_set_io_throttle @var{device} @var{bps} @var{bps_rd} @var{bps_wr} @var{iops} @var{iops_rd} @var{iops_wr}
1453 @findex block_set_io_throttle
1454 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}
1455 ETEXI
1458 .name = "block_set_io_throttle",
1459 .args_type = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l",
1460 .params = "device bps bps_rd bps_wr iops iops_rd iops_wr",
1461 .help = "change I/O throttle limits for a block drive",
1462 .mhandler.cmd = hmp_block_set_io_throttle,
1465 STEXI
1466 @item block_passwd @var{device} @var{password}
1467 @findex block_passwd
1468 Set the encrypted device @var{device} password to @var{password}
1469 ETEXI
1472 .name = "set_password",
1473 .args_type = "protocol:s,password:s,connected:s?",
1474 .params = "protocol password action-if-connected",
1475 .help = "set spice/vnc password",
1476 .mhandler.cmd = hmp_set_password,
1479 STEXI
1480 @item set_password [ vnc | spice ] password [ action-if-connected ]
1481 @findex set_password
1483 Change spice/vnc password. Use zero to make the password stay valid
1484 forever. @var{action-if-connected} specifies what should happen in
1485 case a connection is established: @var{fail} makes the password change
1486 fail. @var{disconnect} changes the password and disconnects the
1487 client. @var{keep} changes the password and keeps the connection up.
1488 @var{keep} is the default.
1489 ETEXI
1492 .name = "expire_password",
1493 .args_type = "protocol:s,time:s",
1494 .params = "protocol time",
1495 .help = "set spice/vnc password expire-time",
1496 .mhandler.cmd = hmp_expire_password,
1499 STEXI
1500 @item expire_password [ vnc | spice ] expire-time
1501 @findex expire_password
1503 Specify when a password for spice/vnc becomes
1504 invalid. @var{expire-time} accepts:
1506 @table @var
1507 @item now
1508 Invalidate password instantly.
1510 @item never
1511 Password stays valid forever.
1513 @item +nsec
1514 Password stays valid for @var{nsec} seconds starting now.
1516 @item nsec
1517 Password is invalidated at the given time. @var{nsec} are the seconds
1518 passed since 1970, i.e. unix epoch.
1520 @end table
1521 ETEXI
1524 .name = "chardev-add",
1525 .args_type = "args:s",
1526 .params = "args",
1527 .help = "add chardev",
1528 .mhandler.cmd = hmp_chardev_add,
1531 STEXI
1532 @item chardev_add args
1533 @findex chardev_add
1535 chardev_add accepts the same parameters as the -chardev command line switch.
1537 ETEXI
1540 .name = "chardev-remove",
1541 .args_type = "id:s",
1542 .params = "id",
1543 .help = "remove chardev",
1544 .mhandler.cmd = hmp_chardev_remove,
1547 STEXI
1548 @item chardev_remove id
1549 @findex chardev_remove
1551 Removes the chardev @var{id}.
1553 ETEXI
1556 .name = "qemu-io",
1557 .args_type = "device:B,command:s",
1558 .params = "[device] \"[command]\"",
1559 .help = "run a qemu-io command on a block device",
1560 .mhandler.cmd = hmp_qemu_io,
1563 STEXI
1564 @item qemu-io @var{device} @var{command}
1565 @findex qemu-io
1567 Executes a qemu-io command on the given block device.
1569 ETEXI
1572 .name = "info",
1573 .args_type = "item:s?",
1574 .params = "[subcommand]",
1575 .help = "show various information about the system state",
1576 .mhandler.cmd = do_info_help,
1577 .sub_table = info_cmds,
1580 STEXI
1581 @item info @var{subcommand}
1582 @findex info
1583 Show various information about the system state.
1585 @table @option
1586 @item info version
1587 show the version of QEMU
1588 @item info network
1589 show the various VLANs and the associated devices
1590 @item info chardev
1591 show the character devices
1592 @item info block
1593 show the block devices
1594 @item info blockstats
1595 show block device statistics
1596 @item info registers
1597 show the cpu registers
1598 @item info cpus
1599 show infos for each CPU
1600 @item info history
1601 show the command line history
1602 @item info irq
1603 show the interrupts statistics (if available)
1604 @item info pic
1605 show i8259 (PIC) state
1606 @item info pci
1607 show emulated PCI device info
1608 @item info tlb
1609 show virtual to physical memory mappings (i386, SH4, SPARC, PPC, and Xtensa only)
1610 @item info mem
1611 show the active virtual memory mappings (i386 only)
1612 @item info jit
1613 show dynamic compiler info
1614 @item info numa
1615 show NUMA information
1616 @item info kvm
1617 show KVM information
1618 @item info usb
1619 show USB devices plugged on the virtual USB hub
1620 @item info usbhost
1621 show all USB host devices
1622 @item info profile
1623 show profiling information
1624 @item info capture
1625 show information about active capturing
1626 @item info snapshots
1627 show list of VM snapshots
1628 @item info status
1629 show the current VM status (running|paused)
1630 @item info pcmcia
1631 show guest PCMCIA status
1632 @item info mice
1633 show which guest mouse is receiving events
1634 @item info vnc
1635 show the vnc server status
1636 @item info name
1637 show the current VM name
1638 @item info uuid
1639 show the current VM UUID
1640 @item info cpustats
1641 show CPU statistics
1642 @item info usernet
1643 show user network stack connection states
1644 @item info migrate
1645 show migration status
1646 @item info migrate_capabilities
1647 show current migration capabilities
1648 @item info migrate_cache_size
1649 show current migration XBZRLE cache size
1650 @item info balloon
1651 show balloon information
1652 @item info qtree
1653 show device tree
1654 @item info qdm
1655 show qdev device model list
1656 @item info roms
1657 show roms
1658 @item info tpm
1659 show the TPM device
1660 @end table
1661 ETEXI
1663 STEXI
1664 @item info trace-events
1665 show available trace events and their state
1666 ETEXI
1668 STEXI
1669 @end table
1670 ETEXI