spapr-rtas: add CPU argument to RTAS calls
[qemu/ar7.git] / hmp-commands.hx
blob915b0d16fa4d993f279eafc10e2edd24b7f3ff4f
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
995 .name = "dump-guest-memory",
996 .args_type = "paging:-p,filename:F,begin:i?,length:i?",
997 .params = "[-p] filename [begin] [length]",
998 .help = "dump guest memory to file"
999 "\n\t\t\t begin(optional): the starting physical address"
1000 "\n\t\t\t length(optional): the memory size, in bytes",
1001 .mhandler.cmd = hmp_dump_guest_memory,
1005 STEXI
1006 @item dump-guest-memory [-p] @var{protocol} @var{begin} @var{length}
1007 @findex dump-guest-memory
1008 Dump guest memory to @var{protocol}. The file can be processed with crash or
1009 gdb.
1010 filename: dump file name
1011 paging: do paging to get guest's memory mapping
1012 begin: the starting physical address. It's optional, and should be
1013 specified with length together.
1014 length: the memory size, in bytes. It's optional, and should be specified
1015 with begin together.
1016 ETEXI
1019 .name = "snapshot_blkdev",
1020 .args_type = "reuse:-n,device:B,snapshot-file:s?,format:s?",
1021 .params = "[-n] device [new-image-file] [format]",
1022 .help = "initiates a live snapshot\n\t\t\t"
1023 "of device. If a new image file is specified, the\n\t\t\t"
1024 "new image file will become the new root image.\n\t\t\t"
1025 "If format is specified, the snapshot file will\n\t\t\t"
1026 "be created in that format. Otherwise the\n\t\t\t"
1027 "snapshot will be internal! (currently unsupported).\n\t\t\t"
1028 "The default format is qcow2. The -n flag requests QEMU\n\t\t\t"
1029 "to reuse the image found in new-image-file, instead of\n\t\t\t"
1030 "recreating it from scratch.",
1031 .mhandler.cmd = hmp_snapshot_blkdev,
1034 STEXI
1035 @item snapshot_blkdev
1036 @findex snapshot_blkdev
1037 Snapshot device, using snapshot file as target if provided
1038 ETEXI
1041 .name = "drive_mirror",
1042 .args_type = "reuse:-n,full:-f,device:B,target:s,format:s?",
1043 .params = "[-n] [-f] device target [format]",
1044 .help = "initiates live storage\n\t\t\t"
1045 "migration for a device. The device's contents are\n\t\t\t"
1046 "copied to the new image file, including data that\n\t\t\t"
1047 "is written after the command is started.\n\t\t\t"
1048 "The -n flag requests QEMU to reuse the image found\n\t\t\t"
1049 "in new-image-file, instead of recreating it from scratch.\n\t\t\t"
1050 "The -f flag requests QEMU to copy the whole disk,\n\t\t\t"
1051 "so that the result does not need a backing file.\n\t\t\t",
1052 .mhandler.cmd = hmp_drive_mirror,
1054 STEXI
1055 @item drive_mirror
1056 @findex drive_mirror
1057 Start mirroring a block device's writes to a new destination,
1058 using the specified target.
1059 ETEXI
1062 .name = "drive_add",
1063 .args_type = "pci_addr:s,opts:s",
1064 .params = "[[<domain>:]<bus>:]<slot>\n"
1065 "[file=file][,if=type][,bus=n]\n"
1066 "[,unit=m][,media=d][,index=i]\n"
1067 "[,cyls=c,heads=h,secs=s[,trans=t]]\n"
1068 "[,snapshot=on|off][,cache=on|off]\n"
1069 "[,readonly=on|off][,copy-on-read=on|off]",
1070 .help = "add drive to PCI storage controller",
1071 .mhandler.cmd = drive_hot_add,
1074 STEXI
1075 @item drive_add
1076 @findex drive_add
1077 Add drive to PCI storage controller.
1078 ETEXI
1080 #if defined(TARGET_I386)
1082 .name = "pci_add",
1083 .args_type = "pci_addr:s,type:s,opts:s?",
1084 .params = "auto|[[<domain>:]<bus>:]<slot> nic|storage [[vlan=n][,macaddr=addr][,model=type]] [file=file][,if=type][,bus=nr]...",
1085 .help = "hot-add PCI device",
1086 .mhandler.cmd = pci_device_hot_add,
1088 #endif
1090 STEXI
1091 @item pci_add
1092 @findex pci_add
1093 Hot-add PCI device.
1094 ETEXI
1096 #if defined(TARGET_I386)
1098 .name = "pci_del",
1099 .args_type = "pci_addr:s",
1100 .params = "[[<domain>:]<bus>:]<slot>",
1101 .help = "hot remove PCI device",
1102 .mhandler.cmd = do_pci_device_hot_remove,
1104 #endif
1106 STEXI
1107 @item pci_del
1108 @findex pci_del
1109 Hot remove PCI device.
1110 ETEXI
1113 .name = "pcie_aer_inject_error",
1114 .args_type = "advisory_non_fatal:-a,correctable:-c,"
1115 "id:s,error_status:s,"
1116 "header0:i?,header1:i?,header2:i?,header3:i?,"
1117 "prefix0:i?,prefix1:i?,prefix2:i?,prefix3:i?",
1118 .params = "[-a] [-c] id "
1119 "<error_status> [<tlp header> [<tlp header prefix>]]",
1120 .help = "inject pcie aer error\n\t\t\t"
1121 " -a for advisory non fatal error\n\t\t\t"
1122 " -c for correctable error\n\t\t\t"
1123 "<id> = qdev device id\n\t\t\t"
1124 "<error_status> = error string or 32bit\n\t\t\t"
1125 "<tlb header> = 32bit x 4\n\t\t\t"
1126 "<tlb header prefix> = 32bit x 4",
1127 .user_print = pcie_aer_inject_error_print,
1128 .mhandler.cmd_new = do_pcie_aer_inject_error,
1131 STEXI
1132 @item pcie_aer_inject_error
1133 @findex pcie_aer_inject_error
1134 Inject PCIe AER error
1135 ETEXI
1138 .name = "host_net_add",
1139 .args_type = "device:s,opts:s?",
1140 .params = "tap|user|socket|vde|dump [options]",
1141 .help = "add host VLAN client",
1142 .mhandler.cmd = net_host_device_add,
1145 STEXI
1146 @item host_net_add
1147 @findex host_net_add
1148 Add host VLAN client.
1149 ETEXI
1152 .name = "host_net_remove",
1153 .args_type = "vlan_id:i,device:s",
1154 .params = "vlan_id name",
1155 .help = "remove host VLAN client",
1156 .mhandler.cmd = net_host_device_remove,
1159 STEXI
1160 @item host_net_remove
1161 @findex host_net_remove
1162 Remove host VLAN client.
1163 ETEXI
1166 .name = "netdev_add",
1167 .args_type = "netdev:O",
1168 .params = "[user|tap|socket|hubport],id=str[,prop=value][,...]",
1169 .help = "add host network device",
1170 .mhandler.cmd = hmp_netdev_add,
1173 STEXI
1174 @item netdev_add
1175 @findex netdev_add
1176 Add host network device.
1177 ETEXI
1180 .name = "netdev_del",
1181 .args_type = "id:s",
1182 .params = "id",
1183 .help = "remove host network device",
1184 .mhandler.cmd = hmp_netdev_del,
1187 STEXI
1188 @item netdev_del
1189 @findex netdev_del
1190 Remove host network device.
1191 ETEXI
1193 #ifdef CONFIG_SLIRP
1195 .name = "hostfwd_add",
1196 .args_type = "arg1:s,arg2:s?,arg3:s?",
1197 .params = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport",
1198 .help = "redirect TCP or UDP connections from host to guest (requires -net user)",
1199 .mhandler.cmd = net_slirp_hostfwd_add,
1201 #endif
1202 STEXI
1203 @item hostfwd_add
1204 @findex hostfwd_add
1205 Redirect TCP or UDP connections from host to guest (requires -net user).
1206 ETEXI
1208 #ifdef CONFIG_SLIRP
1210 .name = "hostfwd_remove",
1211 .args_type = "arg1:s,arg2:s?,arg3:s?",
1212 .params = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport",
1213 .help = "remove host-to-guest TCP or UDP redirection",
1214 .mhandler.cmd = net_slirp_hostfwd_remove,
1217 #endif
1218 STEXI
1219 @item hostfwd_remove
1220 @findex hostfwd_remove
1221 Remove host-to-guest TCP or UDP redirection.
1222 ETEXI
1225 .name = "balloon",
1226 .args_type = "value:M",
1227 .params = "target",
1228 .help = "request VM to change its memory allocation (in MB)",
1229 .mhandler.cmd = hmp_balloon,
1232 STEXI
1233 @item balloon @var{value}
1234 @findex balloon
1235 Request VM to change its memory allocation to @var{value} (in MB).
1236 ETEXI
1239 .name = "set_link",
1240 .args_type = "name:s,up:b",
1241 .params = "name on|off",
1242 .help = "change the link status of a network adapter",
1243 .mhandler.cmd = hmp_set_link,
1246 STEXI
1247 @item set_link @var{name} [on|off]
1248 @findex set_link
1249 Switch link @var{name} on (i.e. up) or off (i.e. down).
1250 ETEXI
1253 .name = "watchdog_action",
1254 .args_type = "action:s",
1255 .params = "[reset|shutdown|poweroff|pause|debug|none]",
1256 .help = "change watchdog action",
1257 .mhandler.cmd = do_watchdog_action,
1260 STEXI
1261 @item watchdog_action
1262 @findex watchdog_action
1263 Change watchdog action.
1264 ETEXI
1267 .name = "acl_show",
1268 .args_type = "aclname:s",
1269 .params = "aclname",
1270 .help = "list rules in the access control list",
1271 .mhandler.cmd = do_acl_show,
1274 STEXI
1275 @item acl_show @var{aclname}
1276 @findex acl_show
1277 List all the matching rules in the access control list, and the default
1278 policy. There are currently two named access control lists,
1279 @var{vnc.x509dname} and @var{vnc.username} matching on the x509 client
1280 certificate distinguished name, and SASL username respectively.
1281 ETEXI
1284 .name = "acl_policy",
1285 .args_type = "aclname:s,policy:s",
1286 .params = "aclname allow|deny",
1287 .help = "set default access control list policy",
1288 .mhandler.cmd = do_acl_policy,
1291 STEXI
1292 @item acl_policy @var{aclname} @code{allow|deny}
1293 @findex acl_policy
1294 Set the default access control list policy, used in the event that
1295 none of the explicit rules match. The default policy at startup is
1296 always @code{deny}.
1297 ETEXI
1300 .name = "acl_add",
1301 .args_type = "aclname:s,match:s,policy:s,index:i?",
1302 .params = "aclname match allow|deny [index]",
1303 .help = "add a match rule to the access control list",
1304 .mhandler.cmd = do_acl_add,
1307 STEXI
1308 @item acl_add @var{aclname} @var{match} @code{allow|deny} [@var{index}]
1309 @findex acl_add
1310 Add a match rule to the access control list, allowing or denying access.
1311 The match will normally be an exact username or x509 distinguished name,
1312 but can optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to
1313 allow all users in the @code{EXAMPLE.COM} kerberos realm. The match will
1314 normally be appended to the end of the ACL, but can be inserted
1315 earlier in the list if the optional @var{index} parameter is supplied.
1316 ETEXI
1319 .name = "acl_remove",
1320 .args_type = "aclname:s,match:s",
1321 .params = "aclname match",
1322 .help = "remove a match rule from the access control list",
1323 .mhandler.cmd = do_acl_remove,
1326 STEXI
1327 @item acl_remove @var{aclname} @var{match}
1328 @findex acl_remove
1329 Remove the specified match rule from the access control list.
1330 ETEXI
1333 .name = "acl_reset",
1334 .args_type = "aclname:s",
1335 .params = "aclname",
1336 .help = "reset the access control list",
1337 .mhandler.cmd = do_acl_reset,
1340 STEXI
1341 @item acl_reset @var{aclname}
1342 @findex acl_reset
1343 Remove all matches from the access control list, and set the default
1344 policy back to @code{deny}.
1345 ETEXI
1348 .name = "nbd_server_start",
1349 .args_type = "all:-a,writable:-w,uri:s",
1350 .params = "nbd_server_start [-a] [-w] host:port",
1351 .help = "serve block devices on the given host and port",
1352 .mhandler.cmd = hmp_nbd_server_start,
1354 STEXI
1355 @item nbd_server_start @var{host}:@var{port}
1356 @findex nbd_server_start
1357 Start an NBD server on the given host and/or port. If the @option{-a}
1358 option is included, all of the virtual machine's block devices that
1359 have an inserted media on them are automatically exported; in this case,
1360 the @option{-w} option makes the devices writable too.
1361 ETEXI
1364 .name = "nbd_server_add",
1365 .args_type = "writable:-w,device:B",
1366 .params = "nbd_server_add [-w] device",
1367 .help = "export a block device via NBD",
1368 .mhandler.cmd = hmp_nbd_server_add,
1370 STEXI
1371 @item nbd_server_add @var{device}
1372 @findex nbd_server_add
1373 Export a block device through QEMU's NBD server, which must be started
1374 beforehand with @command{nbd_server_start}. The @option{-w} option makes the
1375 exported device writable too.
1376 ETEXI
1379 .name = "nbd_server_stop",
1380 .args_type = "",
1381 .params = "nbd_server_stop",
1382 .help = "stop serving block devices using the NBD protocol",
1383 .mhandler.cmd = hmp_nbd_server_stop,
1385 STEXI
1386 @item nbd_server_stop
1387 @findex nbd_server_stop
1388 Stop the QEMU embedded NBD server.
1389 ETEXI
1392 #if defined(TARGET_I386)
1395 .name = "mce",
1396 .args_type = "broadcast:-b,cpu_index:i,bank:i,status:l,mcg_status:l,addr:l,misc:l",
1397 .params = "[-b] cpu bank status mcgstatus addr misc",
1398 .help = "inject a MCE on the given CPU [and broadcast to other CPUs with -b option]",
1399 .mhandler.cmd = do_inject_mce,
1402 #endif
1403 STEXI
1404 @item mce @var{cpu} @var{bank} @var{status} @var{mcgstatus} @var{addr} @var{misc}
1405 @findex mce (x86)
1406 Inject an MCE on the given CPU (x86 only).
1407 ETEXI
1410 .name = "getfd",
1411 .args_type = "fdname:s",
1412 .params = "getfd name",
1413 .help = "receive a file descriptor via SCM rights and assign it a name",
1414 .mhandler.cmd = hmp_getfd,
1417 STEXI
1418 @item getfd @var{fdname}
1419 @findex getfd
1420 If a file descriptor is passed alongside this command using the SCM_RIGHTS
1421 mechanism on unix sockets, it is stored using the name @var{fdname} for
1422 later use by other monitor commands.
1423 ETEXI
1426 .name = "closefd",
1427 .args_type = "fdname:s",
1428 .params = "closefd name",
1429 .help = "close a file descriptor previously passed via SCM rights",
1430 .mhandler.cmd = hmp_closefd,
1433 STEXI
1434 @item closefd @var{fdname}
1435 @findex closefd
1436 Close the file descriptor previously assigned to @var{fdname} using the
1437 @code{getfd} command. This is only needed if the file descriptor was never
1438 used by another monitor command.
1439 ETEXI
1442 .name = "block_passwd",
1443 .args_type = "device:B,password:s",
1444 .params = "block_passwd device password",
1445 .help = "set the password of encrypted block devices",
1446 .mhandler.cmd = hmp_block_passwd,
1449 STEXI
1450 @item block_set_io_throttle @var{device} @var{bps} @var{bps_rd} @var{bps_wr} @var{iops} @var{iops_rd} @var{iops_wr}
1451 @findex block_set_io_throttle
1452 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}
1453 ETEXI
1456 .name = "block_set_io_throttle",
1457 .args_type = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l",
1458 .params = "device bps bps_rd bps_wr iops iops_rd iops_wr",
1459 .help = "change I/O throttle limits for a block drive",
1460 .mhandler.cmd = hmp_block_set_io_throttle,
1463 STEXI
1464 @item block_passwd @var{device} @var{password}
1465 @findex block_passwd
1466 Set the encrypted device @var{device} password to @var{password}
1467 ETEXI
1470 .name = "set_password",
1471 .args_type = "protocol:s,password:s,connected:s?",
1472 .params = "protocol password action-if-connected",
1473 .help = "set spice/vnc password",
1474 .mhandler.cmd = hmp_set_password,
1477 STEXI
1478 @item set_password [ vnc | spice ] password [ action-if-connected ]
1479 @findex set_password
1481 Change spice/vnc password. Use zero to make the password stay valid
1482 forever. @var{action-if-connected} specifies what should happen in
1483 case a connection is established: @var{fail} makes the password change
1484 fail. @var{disconnect} changes the password and disconnects the
1485 client. @var{keep} changes the password and keeps the connection up.
1486 @var{keep} is the default.
1487 ETEXI
1490 .name = "expire_password",
1491 .args_type = "protocol:s,time:s",
1492 .params = "protocol time",
1493 .help = "set spice/vnc password expire-time",
1494 .mhandler.cmd = hmp_expire_password,
1497 STEXI
1498 @item expire_password [ vnc | spice ] expire-time
1499 @findex expire_password
1501 Specify when a password for spice/vnc becomes
1502 invalid. @var{expire-time} accepts:
1504 @table @var
1505 @item now
1506 Invalidate password instantly.
1508 @item never
1509 Password stays valid forever.
1511 @item +nsec
1512 Password stays valid for @var{nsec} seconds starting now.
1514 @item nsec
1515 Password is invalidated at the given time. @var{nsec} are the seconds
1516 passed since 1970, i.e. unix epoch.
1518 @end table
1519 ETEXI
1522 .name = "chardev-add",
1523 .args_type = "args:s",
1524 .params = "args",
1525 .help = "add chardev",
1526 .mhandler.cmd = hmp_chardev_add,
1529 STEXI
1530 @item chardev_add args
1531 @findex chardev_add
1533 chardev_add accepts the same parameters as the -chardev command line switch.
1535 ETEXI
1538 .name = "chardev-remove",
1539 .args_type = "id:s",
1540 .params = "id",
1541 .help = "remove chardev",
1542 .mhandler.cmd = hmp_chardev_remove,
1545 STEXI
1546 @item chardev_remove id
1547 @findex chardev_remove
1549 Removes the chardev @var{id}.
1551 ETEXI
1554 .name = "qemu-io",
1555 .args_type = "device:B,command:s",
1556 .params = "[device] \"[command]\"",
1557 .help = "run a qemu-io command on a block device",
1558 .mhandler.cmd = hmp_qemu_io,
1561 STEXI
1562 @item qemu-io @var{device} @var{command}
1563 @findex qemu-io
1565 Executes a qemu-io command on the given block device.
1567 ETEXI
1570 .name = "info",
1571 .args_type = "item:s?",
1572 .params = "[subcommand]",
1573 .help = "show various information about the system state",
1574 .mhandler.cmd = do_info_help,
1575 .sub_table = info_cmds,
1578 STEXI
1579 @item info @var{subcommand}
1580 @findex info
1581 Show various information about the system state.
1583 @table @option
1584 @item info version
1585 show the version of QEMU
1586 @item info network
1587 show the various VLANs and the associated devices
1588 @item info chardev
1589 show the character devices
1590 @item info block
1591 show the block devices
1592 @item info blockstats
1593 show block device statistics
1594 @item info registers
1595 show the cpu registers
1596 @item info cpus
1597 show infos for each CPU
1598 @item info history
1599 show the command line history
1600 @item info irq
1601 show the interrupts statistics (if available)
1602 @item info pic
1603 show i8259 (PIC) state
1604 @item info pci
1605 show emulated PCI device info
1606 @item info tlb
1607 show virtual to physical memory mappings (i386, SH4, SPARC, PPC, and Xtensa only)
1608 @item info mem
1609 show the active virtual memory mappings (i386 only)
1610 @item info jit
1611 show dynamic compiler info
1612 @item info numa
1613 show NUMA information
1614 @item info kvm
1615 show KVM information
1616 @item info usb
1617 show USB devices plugged on the virtual USB hub
1618 @item info usbhost
1619 show all USB host devices
1620 @item info profile
1621 show profiling information
1622 @item info capture
1623 show information about active capturing
1624 @item info snapshots
1625 show list of VM snapshots
1626 @item info status
1627 show the current VM status (running|paused)
1628 @item info pcmcia
1629 show guest PCMCIA status
1630 @item info mice
1631 show which guest mouse is receiving events
1632 @item info vnc
1633 show the vnc server status
1634 @item info name
1635 show the current VM name
1636 @item info uuid
1637 show the current VM UUID
1638 @item info cpustats
1639 show CPU statistics
1640 @item info usernet
1641 show user network stack connection states
1642 @item info migrate
1643 show migration status
1644 @item info migrate_capabilities
1645 show current migration capabilities
1646 @item info migrate_cache_size
1647 show current migration XBZRLE cache size
1648 @item info balloon
1649 show balloon information
1650 @item info qtree
1651 show device tree
1652 @item info qdm
1653 show qdev device model list
1654 @item info roms
1655 show roms
1656 @item info tpm
1657 show the TPM device
1658 @end table
1659 ETEXI
1661 STEXI
1662 @item info trace-events
1663 show available trace events and their state
1664 ETEXI
1666 STEXI
1667 @end table
1668 ETEXI