qemu-img: add support for rate limit in qemu-img commit
[qemu.git] / hmp-commands.hx
1 HXCOMM Use DEFHEADING() to define headings in both help text and rST.
2 HXCOMM Text between SRST and ERST is copied to the rST 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 rST and C.
7
8
9     {
10         .name       = "help|?",
11         .args_type  = "name:S?",
12         .params     = "[cmd]",
13         .help       = "show the help",
14         .cmd        = do_help_cmd,
15         .flags      = "p",
16     },
17
18 SRST
19 ``help`` or ``?`` [*cmd*]
20   Show the help for all commands or just for command *cmd*.
21 ERST
22
23     {
24         .name       = "commit",
25         .args_type  = "device:B",
26         .params     = "device|all",
27         .help       = "commit changes to the disk images (if -snapshot is used) or backing files",
28         .cmd        = hmp_commit,
29     },
30
31 SRST
32 ``commit``
33   Commit changes to the disk images (if -snapshot is used) or backing files.
34   If the backing file is smaller than the snapshot, then the backing file
35   will be resized to be the same size as the snapshot.  If the snapshot is
36   smaller than the backing file, the backing file will not be truncated.
37   If you want the backing file to match the size of the smaller snapshot,
38   you can safely truncate it yourself once the commit operation successfully
39   completes.
40 ERST
41
42     {
43         .name       = "q|quit",
44         .args_type  = "",
45         .params     = "",
46         .help       = "quit the emulator",
47         .cmd        = hmp_quit,
48     },
49
50 SRST
51 ``q`` or ``quit``
52   Quit the emulator.
53 ERST
54
55     {
56         .name       = "exit_preconfig",
57         .args_type  = "",
58         .params     = "",
59         .help       = "exit the preconfig state",
60         .cmd        = hmp_exit_preconfig,
61         .flags      = "p",
62     },
63
64 SRST
65 ``exit_preconfig``
66   This command makes QEMU exit the preconfig state and proceed with
67   VM initialization using configuration data provided on the command line
68   and via the QMP monitor during the preconfig state. The command is only
69   available during the preconfig state (i.e. when the --preconfig command
70   line option was in use).
71 ERST
72
73     {
74         .name       = "block_resize",
75         .args_type  = "device:B,size:o",
76         .params     = "device size",
77         .help       = "resize a block image",
78         .cmd        = hmp_block_resize,
79         .coroutine  = true,
80     },
81
82 SRST
83 ``block_resize``
84   Resize a block image while a guest is running.  Usually requires guest
85   action to see the updated size.  Resize to a lower size is supported,
86   but should be used with extreme caution.  Note that this command only
87   resizes image files, it can not resize block devices like LVM volumes.
88 ERST
89
90     {
91         .name       = "block_stream",
92         .args_type  = "device:B,speed:o?,base:s?",
93         .params     = "device [speed [base]]",
94         .help       = "copy data from a backing file into a block device",
95         .cmd        = hmp_block_stream,
96     },
97
98 SRST
99 ``block_stream``
100   Copy data from a backing file into a block device.
101 ERST
102
103     {
104         .name       = "block_job_set_speed",
105         .args_type  = "device:B,speed:o",
106         .params     = "device speed",
107         .help       = "set maximum speed for a background block operation",
108         .cmd        = hmp_block_job_set_speed,
109     },
110
111 SRST
112 ``block_job_set_speed``
113   Set maximum speed for a background block operation.
114 ERST
115
116     {
117         .name       = "block_job_cancel",
118         .args_type  = "force:-f,device:B",
119         .params     = "[-f] device",
120         .help       = "stop an active background block operation (use -f"
121                       "\n\t\t\t if you want to abort the operation immediately"
122                       "\n\t\t\t instead of keep running until data is in sync)",
123         .cmd        = hmp_block_job_cancel,
124     },
125
126 SRST
127 ``block_job_cancel``
128   Stop an active background block operation (streaming, mirroring).
129 ERST
130
131     {
132         .name       = "block_job_complete",
133         .args_type  = "device:B",
134         .params     = "device",
135         .help       = "stop an active background block operation",
136         .cmd        = hmp_block_job_complete,
137     },
138
139 SRST
140 ``block_job_complete``
141   Manually trigger completion of an active background block operation.
142   For mirroring, this will switch the device to the destination path.
143 ERST
144
145     {
146         .name       = "block_job_pause",
147         .args_type  = "device:B",
148         .params     = "device",
149         .help       = "pause an active background block operation",
150         .cmd        = hmp_block_job_pause,
151     },
152
153 SRST
154 ``block_job_pause``
155   Pause an active block streaming operation.
156 ERST
157
158     {
159         .name       = "block_job_resume",
160         .args_type  = "device:B",
161         .params     = "device",
162         .help       = "resume a paused background block operation",
163         .cmd        = hmp_block_job_resume,
164     },
165
166 SRST
167 ``block_job_resume``
168   Resume a paused block streaming operation.
169 ERST
170
171     {
172         .name       = "eject",
173         .args_type  = "force:-f,device:B",
174         .params     = "[-f] device",
175         .help       = "eject a removable medium (use -f to force it)",
176         .cmd        = hmp_eject,
177     },
178
179 SRST
180 ``eject [-f]`` *device*
181   Eject a removable medium (use -f to force it).
182 ERST
183
184     {
185         .name       = "drive_del",
186         .args_type  = "id:B",
187         .params     = "device",
188         .help       = "remove host block device",
189         .cmd        = hmp_drive_del,
190     },
191
192 SRST
193 ``drive_del`` *device*
194   Remove host block device.  The result is that guest generated IO is no longer
195   submitted against the host device underlying the disk.  Once a drive has
196   been deleted, the QEMU Block layer returns -EIO which results in IO
197   errors in the guest for applications that are reading/writing to the device.
198   These errors are always reported to the guest, regardless of the drive's error
199   actions (drive options rerror, werror).
200 ERST
201
202     {
203         .name       = "change",
204         .args_type  = "device:B,target:F,arg:s?,read-only-mode:s?",
205         .params     = "device filename [format [read-only-mode]]",
206         .help       = "change a removable medium, optional format",
207         .cmd        = hmp_change,
208     },
209
210 SRST
211 ``change`` *device* *setting*
212   Change the configuration of a device.
213
214   ``change`` *diskdevice* *filename* [*format* [*read-only-mode*]]
215     Change the medium for a removable disk device to point to *filename*. eg::
216
217       (qemu) change ide1-cd0 /path/to/some.iso
218
219     *format* is optional.
220
221     *read-only-mode* may be used to change the read-only status of the device.
222     It accepts the following values:
223
224     retain
225       Retains the current status; this is the default.
226
227     read-only
228       Makes the device read-only.
229
230     read-write
231       Makes the device writable.
232
233   ``change vnc`` *display*,\ *options*
234     Change the configuration of the VNC server. The valid syntax for *display*
235     and *options* are described at :ref:`sec_005finvocation`. eg::
236
237       (qemu) change vnc localhost:1
238
239   ``change vnc password`` [*password*]
240
241     Change the password associated with the VNC server. If the new password
242     is not supplied, the monitor will prompt for it to be entered. VNC
243     passwords are only significant up to 8 letters. eg::
244
245       (qemu) change vnc password
246       Password: ********
247
248 ERST
249
250     {
251         .name       = "screendump",
252         .args_type  = "filename:F,device:s?,head:i?",
253         .params     = "filename [device [head]]",
254         .help       = "save screen from head 'head' of display device 'device' "
255                       "into PPM image 'filename'",
256         .cmd        = hmp_screendump,
257     },
258
259 SRST
260 ``screendump`` *filename*
261   Save screen into PPM image *filename*.
262 ERST
263
264     {
265         .name       = "logfile",
266         .args_type  = "filename:F",
267         .params     = "filename",
268         .help       = "output logs to 'filename'",
269         .cmd        = hmp_logfile,
270     },
271
272 SRST
273 ``logfile`` *filename*
274   Output logs to *filename*.
275 ERST
276
277     {
278         .name       = "trace-event",
279         .args_type  = "name:s,option:b,vcpu:i?",
280         .params     = "name on|off [vcpu]",
281         .help       = "changes status of a specific trace event "
282                       "(vcpu: vCPU to set, default is all)",
283         .cmd = hmp_trace_event,
284         .command_completion = trace_event_completion,
285     },
286
287 SRST
288 ``trace-event``
289   changes status of a trace event
290 ERST
291
292 #if defined(CONFIG_TRACE_SIMPLE)
293     {
294         .name       = "trace-file",
295         .args_type  = "op:s?,arg:F?",
296         .params     = "on|off|flush|set [arg]",
297         .help       = "open, close, or flush trace file, or set a new file name",
298         .cmd        = hmp_trace_file,
299     },
300
301 SRST
302 ``trace-file on|off|flush``
303   Open, close, or flush the trace file.  If no argument is given, the
304   status of the trace file is displayed.
305 ERST
306 #endif
307
308     {
309         .name       = "log",
310         .args_type  = "items:s",
311         .params     = "item1[,...]",
312         .help       = "activate logging of the specified items",
313         .cmd        = hmp_log,
314     },
315
316 SRST
317 ``log`` *item1*\ [,...]
318   Activate logging of the specified items.
319 ERST
320
321     {
322         .name       = "savevm",
323         .args_type  = "name:s?",
324         .params     = "tag",
325         .help       = "save a VM snapshot. If no tag is provided, a new snapshot is created",
326         .cmd        = hmp_savevm,
327     },
328
329 SRST
330 ``savevm`` *tag*
331   Create a snapshot of the whole virtual machine. If *tag* is
332   provided, it is used as human readable identifier. If there is already
333   a snapshot with the same tag, it is replaced. More info at
334   :ref:`vm_005fsnapshots`.
335
336   Since 4.0, savevm stopped allowing the snapshot id to be set, accepting
337   only *tag* as parameter.
338 ERST
339
340     {
341         .name       = "loadvm",
342         .args_type  = "name:s",
343         .params     = "tag",
344         .help       = "restore a VM snapshot from its tag",
345         .cmd        = hmp_loadvm,
346         .command_completion = loadvm_completion,
347     },
348
349 SRST
350 ``loadvm`` *tag*
351   Set the whole virtual machine to the snapshot identified by the tag
352   *tag*.
353
354   Since 4.0, loadvm stopped accepting snapshot id as parameter.
355 ERST
356
357     {
358         .name       = "delvm",
359         .args_type  = "name:s",
360         .params     = "tag",
361         .help       = "delete a VM snapshot from its tag",
362         .cmd        = hmp_delvm,
363         .command_completion = delvm_completion,
364     },
365
366 SRST
367 ``delvm`` *tag*
368   Delete the snapshot identified by *tag*.
369
370   Since 4.0, delvm stopped deleting snapshots by snapshot id, accepting
371   only *tag* as parameter.
372 ERST
373
374     {
375         .name       = "singlestep",
376         .args_type  = "option:s?",
377         .params     = "[on|off]",
378         .help       = "run emulation in singlestep mode or switch to normal mode",
379         .cmd        = hmp_singlestep,
380     },
381
382 SRST
383 ``singlestep [off]``
384   Run the emulation in single step mode.
385   If called with option off, the emulation returns to normal mode.
386 ERST
387
388     {
389         .name       = "stop",
390         .args_type  = "",
391         .params     = "",
392         .help       = "stop emulation",
393         .cmd        = hmp_stop,
394     },
395
396 SRST
397 ``stop``
398   Stop emulation.
399 ERST
400
401     {
402         .name       = "c|cont",
403         .args_type  = "",
404         .params     = "",
405         .help       = "resume emulation",
406         .cmd        = hmp_cont,
407     },
408
409 SRST
410 ``c`` or ``cont``
411   Resume emulation.
412 ERST
413
414     {
415         .name       = "system_wakeup",
416         .args_type  = "",
417         .params     = "",
418         .help       = "wakeup guest from suspend",
419         .cmd        = hmp_system_wakeup,
420     },
421
422 SRST
423 ``system_wakeup``
424   Wakeup guest from suspend.
425 ERST
426
427     {
428         .name       = "gdbserver",
429         .args_type  = "device:s?",
430         .params     = "[device]",
431         .help       = "start gdbserver on given device (default 'tcp::1234'), stop with 'none'",
432         .cmd        = hmp_gdbserver,
433     },
434
435 SRST
436 ``gdbserver`` [*port*]
437   Start gdbserver session (default *port*\=1234)
438 ERST
439
440     {
441         .name       = "x",
442         .args_type  = "fmt:/,addr:l",
443         .params     = "/fmt addr",
444         .help       = "virtual memory dump starting at 'addr'",
445         .cmd        = hmp_memory_dump,
446     },
447
448 SRST
449 ``x/``\ *fmt* *addr*
450   Virtual memory dump starting at *addr*.
451 ERST
452
453     {
454         .name       = "xp",
455         .args_type  = "fmt:/,addr:l",
456         .params     = "/fmt addr",
457         .help       = "physical memory dump starting at 'addr'",
458         .cmd        = hmp_physical_memory_dump,
459     },
460
461 SRST
462 ``xp /``\ *fmt* *addr*
463   Physical memory dump starting at *addr*.
464
465   *fmt* is a format which tells the command how to format the
466   data. Its syntax is: ``/{count}{format}{size}``
467
468   *count*
469     is the number of items to be dumped.
470   *format*
471     can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
472     c (char) or i (asm instruction).
473   *size*
474     can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
475     ``h`` or ``w`` can be specified with the ``i`` format to
476     respectively select 16 or 32 bit code instruction size.
477
478   Examples:
479
480   Dump 10 instructions at the current instruction pointer::
481
482     (qemu) x/10i $eip
483     0x90107063:  ret
484     0x90107064:  sti
485     0x90107065:  lea    0x0(%esi,1),%esi
486     0x90107069:  lea    0x0(%edi,1),%edi
487     0x90107070:  ret
488     0x90107071:  jmp    0x90107080
489     0x90107073:  nop
490     0x90107074:  nop
491     0x90107075:  nop
492     0x90107076:  nop
493
494   Dump 80 16 bit values at the start of the video memory::
495
496     (qemu) xp/80hx 0xb8000
497     0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
498     0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
499     0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
500     0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
501     0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
502     0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
503     0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
504     0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
505     0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
506     0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
507
508 ERST
509
510     {
511         .name       = "gpa2hva",
512         .args_type  = "addr:l",
513         .params     = "addr",
514         .help       = "print the host virtual address corresponding to a guest physical address",
515         .cmd        = hmp_gpa2hva,
516     },
517
518 SRST
519 ``gpa2hva`` *addr*
520   Print the host virtual address at which the guest's physical address *addr*
521   is mapped.
522 ERST
523
524 #ifdef CONFIG_LINUX
525     {
526         .name       = "gpa2hpa",
527         .args_type  = "addr:l",
528         .params     = "addr",
529         .help       = "print the host physical address corresponding to a guest physical address",
530         .cmd        = hmp_gpa2hpa,
531     },
532 #endif
533
534 SRST
535 ``gpa2hpa`` *addr*
536   Print the host physical address at which the guest's physical address *addr*
537   is mapped.
538 ERST
539
540     {
541         .name       = "gva2gpa",
542         .args_type  = "addr:l",
543         .params     = "addr",
544         .help       = "print the guest physical address corresponding to a guest virtual address",
545         .cmd        = hmp_gva2gpa,
546     },
547
548 SRST
549 ``gva2gpa`` *addr*
550   Print the guest physical address at which the guest's virtual address *addr*
551   is mapped based on the mapping for the current CPU.
552 ERST
553
554     {
555         .name       = "p|print",
556         .args_type  = "fmt:/,val:l",
557         .params     = "/fmt expr",
558         .help       = "print expression value (use $reg for CPU register access)",
559         .cmd        = do_print,
560     },
561
562 SRST
563 ``p`` or ``print/``\ *fmt* *expr*
564   Print expression value. Only the *format* part of *fmt* is
565   used.
566 ERST
567
568     {
569         .name       = "i",
570         .args_type  = "fmt:/,addr:i,index:i.",
571         .params     = "/fmt addr",
572         .help       = "I/O port read",
573         .cmd        = hmp_ioport_read,
574     },
575
576 SRST
577 ``i/``\ *fmt* *addr* [.\ *index*\ ]
578   Read I/O port.
579 ERST
580
581     {
582         .name       = "o",
583         .args_type  = "fmt:/,addr:i,val:i",
584         .params     = "/fmt addr value",
585         .help       = "I/O port write",
586         .cmd        = hmp_ioport_write,
587     },
588
589 SRST
590 ``o/``\ *fmt* *addr* *val*
591   Write to I/O port.
592 ERST
593
594     {
595         .name       = "sendkey",
596         .args_type  = "keys:s,hold-time:i?",
597         .params     = "keys [hold_ms]",
598         .help       = "send keys to the VM (e.g. 'sendkey ctrl-alt-f1', default hold time=100 ms)",
599         .cmd        = hmp_sendkey,
600         .command_completion = sendkey_completion,
601     },
602
603 SRST
604 ``sendkey`` *keys*
605   Send *keys* to the guest. *keys* could be the name of the
606   key or the raw value in hexadecimal format. Use ``-`` to press
607   several keys simultaneously. Example::
608
609     sendkey ctrl-alt-f1
610
611   This command is useful to send keys that your graphical user interface
612   intercepts at low level, such as ``ctrl-alt-f1`` in X Window.
613 ERST
614     {
615         .name       = "sync-profile",
616         .args_type  = "op:s?",
617         .params     = "[on|off|reset]",
618         .help       = "enable, disable or reset synchronization profiling. "
619                       "With no arguments, prints whether profiling is on or off.",
620         .cmd        = hmp_sync_profile,
621     },
622
623 SRST
624 ``sync-profile [on|off|reset]``
625   Enable, disable or reset synchronization profiling. With no arguments, prints
626   whether profiling is on or off.
627 ERST
628
629     {
630         .name       = "system_reset",
631         .args_type  = "",
632         .params     = "",
633         .help       = "reset the system",
634         .cmd        = hmp_system_reset,
635     },
636
637 SRST
638 ``system_reset``
639   Reset the system.
640 ERST
641
642     {
643         .name       = "system_powerdown",
644         .args_type  = "",
645         .params     = "",
646         .help       = "send system power down event",
647         .cmd        = hmp_system_powerdown,
648     },
649
650 SRST
651 ``system_powerdown``
652   Power down the system (if supported).
653 ERST
654
655     {
656         .name       = "sum",
657         .args_type  = "start:i,size:i",
658         .params     = "addr size",
659         .help       = "compute the checksum of a memory region",
660         .cmd        = hmp_sum,
661     },
662
663 SRST
664 ``sum`` *addr* *size*
665   Compute the checksum of a memory region.
666 ERST
667
668     {
669         .name       = "device_add",
670         .args_type  = "device:O",
671         .params     = "driver[,prop=value][,...]",
672         .help       = "add device, like -device on the command line",
673         .cmd        = hmp_device_add,
674         .command_completion = device_add_completion,
675     },
676
677 SRST
678 ``device_add`` *config*
679   Add device.
680 ERST
681
682     {
683         .name       = "device_del",
684         .args_type  = "id:s",
685         .params     = "device",
686         .help       = "remove device",
687         .cmd        = hmp_device_del,
688         .command_completion = device_del_completion,
689     },
690
691 SRST
692 ``device_del`` *id*
693   Remove device *id*. *id* may be a short ID
694   or a QOM object path.
695 ERST
696
697     {
698         .name       = "cpu",
699         .args_type  = "index:i",
700         .params     = "index",
701         .help       = "set the default CPU",
702         .cmd        = hmp_cpu,
703     },
704
705 SRST
706 ``cpu`` *index*
707   Set the default CPU.
708 ERST
709
710     {
711         .name       = "mouse_move",
712         .args_type  = "dx_str:s,dy_str:s,dz_str:s?",
713         .params     = "dx dy [dz]",
714         .help       = "send mouse move events",
715         .cmd        = hmp_mouse_move,
716     },
717
718 SRST
719 ``mouse_move`` *dx* *dy* [*dz*]
720   Move the active mouse to the specified coordinates *dx* *dy*
721   with optional scroll axis *dz*.
722 ERST
723
724     {
725         .name       = "mouse_button",
726         .args_type  = "button_state:i",
727         .params     = "state",
728         .help       = "change mouse button state (1=L, 2=M, 4=R)",
729         .cmd        = hmp_mouse_button,
730     },
731
732 SRST
733 ``mouse_button`` *val*
734   Change the active mouse button state *val* (1=L, 2=M, 4=R).
735 ERST
736
737     {
738         .name       = "mouse_set",
739         .args_type  = "index:i",
740         .params     = "index",
741         .help       = "set which mouse device receives events",
742         .cmd        = hmp_mouse_set,
743     },
744
745 SRST
746 ``mouse_set`` *index*
747   Set which mouse device receives events at given *index*, index
748   can be obtained with::
749
750     info mice
751
752 ERST
753
754     {
755         .name       = "wavcapture",
756         .args_type  = "path:F,audiodev:s,freq:i?,bits:i?,nchannels:i?",
757         .params     = "path audiodev [frequency [bits [channels]]]",
758         .help       = "capture audio to a wave file (default frequency=44100 bits=16 channels=2)",
759         .cmd        = hmp_wavcapture,
760     },
761 SRST
762 ``wavcapture`` *filename* *audiodev* [*frequency* [*bits* [*channels*]]]
763   Capture audio into *filename* from *audiodev*, using sample rate
764   *frequency* bits per sample *bits* and number of channels
765   *channels*.
766
767   Defaults:
768
769   - Sample rate = 44100 Hz - CD quality
770   - Bits = 16
771   - Number of channels = 2 - Stereo
772 ERST
773
774     {
775         .name       = "stopcapture",
776         .args_type  = "n:i",
777         .params     = "capture index",
778         .help       = "stop capture",
779         .cmd        = hmp_stopcapture,
780     },
781 SRST
782 ``stopcapture`` *index*
783   Stop capture with a given *index*, index can be obtained with::
784
785     info capture
786
787 ERST
788
789     {
790         .name       = "memsave",
791         .args_type  = "val:l,size:i,filename:s",
792         .params     = "addr size file",
793         .help       = "save to disk virtual memory dump starting at 'addr' of size 'size'",
794         .cmd        = hmp_memsave,
795     },
796
797 SRST
798 ``memsave`` *addr* *size* *file*
799   save to disk virtual memory dump starting at *addr* of size *size*.
800 ERST
801
802     {
803         .name       = "pmemsave",
804         .args_type  = "val:l,size:i,filename:s",
805         .params     = "addr size file",
806         .help       = "save to disk physical memory dump starting at 'addr' of size 'size'",
807         .cmd        = hmp_pmemsave,
808     },
809
810 SRST
811 ``pmemsave`` *addr* *size* *file*
812   save to disk physical memory dump starting at *addr* of size *size*.
813 ERST
814
815     {
816         .name       = "boot_set",
817         .args_type  = "bootdevice:s",
818         .params     = "bootdevice",
819         .help       = "define new values for the boot device list",
820         .cmd        = hmp_boot_set,
821     },
822
823 SRST
824 ``boot_set`` *bootdevicelist*
825   Define new values for the boot device list. Those values will override
826   the values specified on the command line through the ``-boot`` option.
827
828   The values that can be specified here depend on the machine type, but are
829   the same that can be specified in the ``-boot`` command line option.
830 ERST
831
832     {
833         .name       = "nmi",
834         .args_type  = "",
835         .params     = "",
836         .help       = "inject an NMI",
837         .cmd        = hmp_nmi,
838     },
839 SRST
840 ``nmi`` *cpu*
841   Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64).
842 ERST
843
844     {
845         .name       = "ringbuf_write",
846         .args_type  = "device:s,data:s",
847         .params     = "device data",
848         .help       = "Write to a ring buffer character device",
849         .cmd        = hmp_ringbuf_write,
850         .command_completion = ringbuf_write_completion,
851     },
852
853 SRST
854 ``ringbuf_write`` *device* *data*
855   Write *data* to ring buffer character device *device*.
856   *data* must be a UTF-8 string.
857 ERST
858
859     {
860         .name       = "ringbuf_read",
861         .args_type  = "device:s,size:i",
862         .params     = "device size",
863         .help       = "Read from a ring buffer character device",
864         .cmd        = hmp_ringbuf_read,
865         .command_completion = ringbuf_write_completion,
866     },
867
868 SRST
869 ``ringbuf_read`` *device*
870   Read and print up to *size* bytes from ring buffer character
871   device *device*.
872   Certain non-printable characters are printed ``\uXXXX``, where ``XXXX`` is the
873   character code in hexadecimal.  Character ``\`` is printed ``\\``.
874   Bug: can screw up when the buffer contains invalid UTF-8 sequences,
875   NUL characters, after the ring buffer lost data, and when reading
876   stops because the size limit is reached.
877 ERST
878
879     {
880         .name       = "announce_self",
881         .args_type  = "interfaces:s?,id:s?",
882         .params     = "[interfaces] [id]",
883         .help       = "Trigger GARP/RARP announcements",
884         .cmd        = hmp_announce_self,
885     },
886
887 SRST
888 ``announce_self``
889   Trigger a round of GARP/RARP broadcasts; this is useful for explicitly
890   updating the network infrastructure after a reconfiguration or some forms
891   of migration. The timings of the round are set by the migration announce
892   parameters. An optional comma separated *interfaces* list restricts the
893   announce to the named set of interfaces. An optional *id* can be used to
894   start a separate announce timer and to change the parameters of it later.
895 ERST
896
897     {
898         .name       = "migrate",
899         .args_type  = "detach:-d,blk:-b,inc:-i,resume:-r,uri:s",
900         .params     = "[-d] [-b] [-i] [-r] uri",
901         .help       = "migrate to URI (using -d to not wait for completion)"
902                       "\n\t\t\t -b for migration without shared storage with"
903                       " full copy of disk\n\t\t\t -i for migration without "
904                       "shared storage with incremental copy of disk "
905                       "(base image shared between src and destination)"
906                       "\n\t\t\t -r to resume a paused migration",
907         .cmd        = hmp_migrate,
908     },
909
910
911 SRST
912 ``migrate [-d] [-b] [-i]`` *uri*
913   Migrate to *uri* (using -d to not wait for completion).
914
915   ``-b``
916     for migration with full copy of disk
917   ``-i``
918     for migration with incremental copy of disk (base image is shared)
919 ERST
920
921     {
922         .name       = "migrate_cancel",
923         .args_type  = "",
924         .params     = "",
925         .help       = "cancel the current VM migration",
926         .cmd        = hmp_migrate_cancel,
927     },
928
929 SRST
930 ``migrate_cancel``
931   Cancel the current VM migration.
932 ERST
933
934     {
935         .name       = "migrate_continue",
936         .args_type  = "state:s",
937         .params     = "state",
938         .help       = "Continue migration from the given paused state",
939         .cmd        = hmp_migrate_continue,
940     },
941 SRST
942 ``migrate_continue`` *state*
943   Continue migration from the paused state *state*
944 ERST
945
946     {
947         .name       = "migrate_incoming",
948         .args_type  = "uri:s",
949         .params     = "uri",
950         .help       = "Continue an incoming migration from an -incoming defer",
951         .cmd        = hmp_migrate_incoming,
952     },
953
954 SRST
955 ``migrate_incoming`` *uri*
956   Continue an incoming migration using the *uri* (that has the same syntax
957   as the ``-incoming`` option).
958 ERST
959
960     {
961         .name       = "migrate_recover",
962         .args_type  = "uri:s",
963         .params     = "uri",
964         .help       = "Continue a paused incoming postcopy migration",
965         .cmd        = hmp_migrate_recover,
966     },
967
968 SRST
969 ``migrate_recover`` *uri*
970   Continue a paused incoming postcopy migration using the *uri*.
971 ERST
972
973     {
974         .name       = "migrate_pause",
975         .args_type  = "",
976         .params     = "",
977         .help       = "Pause an ongoing migration (postcopy-only)",
978         .cmd        = hmp_migrate_pause,
979     },
980
981 SRST
982 ``migrate_pause``
983   Pause an ongoing migration.  Currently it only supports postcopy.
984 ERST
985
986     {
987         .name       = "migrate_set_cache_size",
988         .args_type  = "value:o",
989         .params     = "value",
990         .help       = "set cache size (in bytes) for XBZRLE migrations,"
991                       "the cache size will be rounded down to the nearest "
992                       "power of 2.\n"
993                       "The cache size affects the number of cache misses."
994                       "In case of a high cache miss ratio you need to increase"
995                       " the cache size",
996         .cmd        = hmp_migrate_set_cache_size,
997     },
998
999 SRST
1000 ``migrate_set_cache_size`` *value*
1001   Set cache size to *value* (in bytes) for xbzrle migrations.
1002 ERST
1003
1004     {
1005         .name       = "migrate_set_speed",
1006         .args_type  = "value:o",
1007         .params     = "value",
1008         .help       = "set maximum speed (in bytes) for migrations. "
1009         "Defaults to MB if no size suffix is specified, ie. B/K/M/G/T",
1010         .cmd        = hmp_migrate_set_speed,
1011     },
1012
1013 SRST
1014 ``migrate_set_speed`` *value*
1015   Set maximum speed to *value* (in bytes) for migrations.
1016 ERST
1017
1018     {
1019         .name       = "migrate_set_downtime",
1020         .args_type  = "value:T",
1021         .params     = "value",
1022         .help       = "set maximum tolerated downtime (in seconds) for migrations",
1023         .cmd        = hmp_migrate_set_downtime,
1024     },
1025
1026 SRST
1027 ``migrate_set_downtime`` *second*
1028   Set maximum tolerated downtime (in seconds) for migration.
1029 ERST
1030
1031     {
1032         .name       = "migrate_set_capability",
1033         .args_type  = "capability:s,state:b",
1034         .params     = "capability state",
1035         .help       = "Enable/Disable the usage of a capability for migration",
1036         .cmd        = hmp_migrate_set_capability,
1037         .command_completion = migrate_set_capability_completion,
1038     },
1039
1040 SRST
1041 ``migrate_set_capability`` *capability* *state*
1042   Enable/Disable the usage of a capability *capability* for migration.
1043 ERST
1044
1045     {
1046         .name       = "migrate_set_parameter",
1047         .args_type  = "parameter:s,value:s",
1048         .params     = "parameter value",
1049         .help       = "Set the parameter for migration",
1050         .cmd        = hmp_migrate_set_parameter,
1051         .command_completion = migrate_set_parameter_completion,
1052     },
1053
1054 SRST
1055 ``migrate_set_parameter`` *parameter* *value*
1056   Set the parameter *parameter* for migration.
1057 ERST
1058
1059     {
1060         .name       = "migrate_start_postcopy",
1061         .args_type  = "",
1062         .params     = "",
1063         .help       = "Followup to a migration command to switch the migration"
1064                       " to postcopy mode. The postcopy-ram capability must "
1065                       "be set on both source and destination before the "
1066                       "original migration command .",
1067         .cmd        = hmp_migrate_start_postcopy,
1068     },
1069
1070 SRST
1071 ``migrate_start_postcopy``
1072   Switch in-progress migration to postcopy mode. Ignored after the end of
1073   migration (or once already in postcopy).
1074 ERST
1075
1076     {
1077         .name       = "x_colo_lost_heartbeat",
1078         .args_type  = "",
1079         .params     = "",
1080         .help       = "Tell COLO that heartbeat is lost,\n\t\t\t"
1081                       "a failover or takeover is needed.",
1082         .cmd = hmp_x_colo_lost_heartbeat,
1083     },
1084
1085 SRST
1086 ``x_colo_lost_heartbeat``
1087   Tell COLO that heartbeat is lost, a failover or takeover is needed.
1088 ERST
1089
1090     {
1091         .name       = "client_migrate_info",
1092         .args_type  = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
1093         .params     = "protocol hostname port tls-port cert-subject",
1094         .help       = "set migration information for remote display",
1095         .cmd        = hmp_client_migrate_info,
1096     },
1097
1098 SRST
1099 ``client_migrate_info`` *protocol* *hostname* *port* *tls-port* *cert-subject*
1100   Set migration information for remote display.  This makes the server
1101   ask the client to automatically reconnect using the new parameters
1102   once migration finished successfully.  Only implemented for SPICE.
1103 ERST
1104
1105     {
1106         .name       = "dump-guest-memory",
1107         .args_type  = "paging:-p,detach:-d,windmp:-w,zlib:-z,lzo:-l,snappy:-s,filename:F,begin:l?,length:l?",
1108         .params     = "[-p] [-d] [-z|-l|-s|-w] filename [begin length]",
1109         .help       = "dump guest memory into file 'filename'.\n\t\t\t"
1110                       "-p: do paging to get guest's memory mapping.\n\t\t\t"
1111                       "-d: return immediately (do not wait for completion).\n\t\t\t"
1112                       "-z: dump in kdump-compressed format, with zlib compression.\n\t\t\t"
1113                       "-l: dump in kdump-compressed format, with lzo compression.\n\t\t\t"
1114                       "-s: dump in kdump-compressed format, with snappy compression.\n\t\t\t"
1115                       "-w: dump in Windows crashdump format (can be used instead of ELF-dump converting),\n\t\t\t"
1116                       "    for Windows x64 guests with vmcoreinfo driver only.\n\t\t\t"
1117                       "begin: the starting physical address.\n\t\t\t"
1118                       "length: the memory size, in bytes.",
1119         .cmd        = hmp_dump_guest_memory,
1120     },
1121
1122 SRST
1123 ``dump-guest-memory [-p]`` *filename* *begin* *length*
1124   \ 
1125 ``dump-guest-memory [-z|-l|-s|-w]`` *filename*
1126   Dump guest memory to *protocol*. The file can be processed with crash or
1127   gdb. Without ``-z|-l|-s|-w``, the dump format is ELF.
1128
1129   ``-p``
1130     do paging to get guest's memory mapping.
1131   ``-z``
1132     dump in kdump-compressed format, with zlib compression.
1133   ``-l``
1134     dump in kdump-compressed format, with lzo compression.
1135   ``-s``
1136     dump in kdump-compressed format, with snappy compression.
1137   ``-w``
1138     dump in Windows crashdump format (can be used instead of ELF-dump converting),
1139     for Windows x64 guests with vmcoreinfo driver only
1140   *filename*
1141     dump file name.
1142   *begin*
1143     the starting physical address. It's optional, and should be
1144     specified together with *length*.
1145   *length*
1146     the memory size, in bytes. It's optional, and should be specified
1147     together with *begin*.
1148
1149 ERST
1150
1151 #if defined(TARGET_S390X)
1152     {
1153         .name       = "dump-skeys",
1154         .args_type  = "filename:F",
1155         .params     = "",
1156         .help       = "Save guest storage keys into file 'filename'.\n",
1157         .cmd        = hmp_dump_skeys,
1158     },
1159 #endif
1160
1161 SRST
1162 ``dump-skeys`` *filename*
1163   Save guest storage keys to a file.
1164 ERST
1165
1166 #if defined(TARGET_S390X)
1167     {
1168         .name       = "migration_mode",
1169         .args_type  = "mode:i",
1170         .params     = "mode",
1171         .help       = "Enables or disables migration mode\n",
1172         .cmd        = hmp_migrationmode,
1173     },
1174 #endif
1175
1176 SRST
1177 ``migration_mode`` *mode*
1178   Enables or disables migration mode.
1179 ERST
1180
1181     {
1182         .name       = "snapshot_blkdev",
1183         .args_type  = "reuse:-n,device:B,snapshot-file:s?,format:s?",
1184         .params     = "[-n] device [new-image-file] [format]",
1185         .help       = "initiates a live snapshot\n\t\t\t"
1186                       "of device. If a new image file is specified, the\n\t\t\t"
1187                       "new image file will become the new root image.\n\t\t\t"
1188                       "If format is specified, the snapshot file will\n\t\t\t"
1189                       "be created in that format.\n\t\t\t"
1190                       "The default format is qcow2.  The -n flag requests QEMU\n\t\t\t"
1191                       "to reuse the image found in new-image-file, instead of\n\t\t\t"
1192                       "recreating it from scratch.",
1193         .cmd        = hmp_snapshot_blkdev,
1194     },
1195
1196 SRST
1197 ``snapshot_blkdev``
1198   Snapshot device, using snapshot file as target if provided
1199 ERST
1200
1201     {
1202         .name       = "snapshot_blkdev_internal",
1203         .args_type  = "device:B,name:s",
1204         .params     = "device name",
1205         .help       = "take an internal snapshot of device.\n\t\t\t"
1206                       "The format of the image used by device must\n\t\t\t"
1207                       "support it, such as qcow2.\n\t\t\t",
1208         .cmd        = hmp_snapshot_blkdev_internal,
1209     },
1210
1211 SRST
1212 ``snapshot_blkdev_internal``
1213   Take an internal snapshot on device if it support
1214 ERST
1215
1216     {
1217         .name       = "snapshot_delete_blkdev_internal",
1218         .args_type  = "device:B,name:s,id:s?",
1219         .params     = "device name [id]",
1220         .help       = "delete an internal snapshot of device.\n\t\t\t"
1221                       "If id is specified, qemu will try delete\n\t\t\t"
1222                       "the snapshot matching both id and name.\n\t\t\t"
1223                       "The format of the image used by device must\n\t\t\t"
1224                       "support it, such as qcow2.\n\t\t\t",
1225         .cmd        = hmp_snapshot_delete_blkdev_internal,
1226     },
1227
1228 SRST
1229 ``snapshot_delete_blkdev_internal``
1230   Delete an internal snapshot on device if it support
1231 ERST
1232
1233     {
1234         .name       = "drive_mirror",
1235         .args_type  = "reuse:-n,full:-f,device:B,target:s,format:s?",
1236         .params     = "[-n] [-f] device target [format]",
1237         .help       = "initiates live storage\n\t\t\t"
1238                       "migration for a device. The device's contents are\n\t\t\t"
1239                       "copied to the new image file, including data that\n\t\t\t"
1240                       "is written after the command is started.\n\t\t\t"
1241                       "The -n flag requests QEMU to reuse the image found\n\t\t\t"
1242                       "in new-image-file, instead of recreating it from scratch.\n\t\t\t"
1243                       "The -f flag requests QEMU to copy the whole disk,\n\t\t\t"
1244                       "so that the result does not need a backing file.\n\t\t\t",
1245         .cmd        = hmp_drive_mirror,
1246     },
1247 SRST
1248 ``drive_mirror``
1249   Start mirroring a block device's writes to a new destination,
1250   using the specified target.
1251 ERST
1252
1253     {
1254         .name       = "drive_backup",
1255         .args_type  = "reuse:-n,full:-f,compress:-c,device:B,target:s,format:s?",
1256         .params     = "[-n] [-f] [-c] device target [format]",
1257         .help       = "initiates a point-in-time\n\t\t\t"
1258                       "copy for a device. The device's contents are\n\t\t\t"
1259                       "copied to the new image file, excluding data that\n\t\t\t"
1260                       "is written after the command is started.\n\t\t\t"
1261                       "The -n flag requests QEMU to reuse the image found\n\t\t\t"
1262                       "in new-image-file, instead of recreating it from scratch.\n\t\t\t"
1263                       "The -f flag requests QEMU to copy the whole disk,\n\t\t\t"
1264                       "so that the result does not need a backing file.\n\t\t\t"
1265                       "The -c flag requests QEMU to compress backup data\n\t\t\t"
1266                       "(if the target format supports it).\n\t\t\t",
1267         .cmd        = hmp_drive_backup,
1268     },
1269 SRST
1270 ``drive_backup``
1271   Start a point-in-time copy of a block device to a specified target.
1272 ERST
1273
1274     {
1275         .name       = "drive_add",
1276         .args_type  = "node:-n,pci_addr:s,opts:s",
1277         .params     = "[-n] [[<domain>:]<bus>:]<slot>\n"
1278                       "[file=file][,if=type][,bus=n]\n"
1279                       "[,unit=m][,media=d][,index=i]\n"
1280                       "[,snapshot=on|off][,cache=on|off]\n"
1281                       "[,readonly=on|off][,copy-on-read=on|off]",
1282         .help       = "add drive to PCI storage controller",
1283         .cmd        = hmp_drive_add,
1284     },
1285
1286 SRST
1287 ``drive_add``
1288   Add drive to PCI storage controller.
1289 ERST
1290
1291     {
1292         .name       = "pcie_aer_inject_error",
1293         .args_type  = "advisory_non_fatal:-a,correctable:-c,"
1294                       "id:s,error_status:s,"
1295                       "header0:i?,header1:i?,header2:i?,header3:i?,"
1296                       "prefix0:i?,prefix1:i?,prefix2:i?,prefix3:i?",
1297         .params     = "[-a] [-c] id "
1298                       "<error_status> [<tlp header> [<tlp header prefix>]]",
1299         .help       = "inject pcie aer error\n\t\t\t"
1300                       " -a for advisory non fatal error\n\t\t\t"
1301                       " -c for correctable error\n\t\t\t"
1302                       "<id> = qdev device id\n\t\t\t"
1303                       "<error_status> = error string or 32bit\n\t\t\t"
1304                       "<tlb header> = 32bit x 4\n\t\t\t"
1305                       "<tlb header prefix> = 32bit x 4",
1306         .cmd        = hmp_pcie_aer_inject_error,
1307     },
1308
1309 SRST
1310 ``pcie_aer_inject_error``
1311   Inject PCIe AER error
1312 ERST
1313
1314     {
1315         .name       = "netdev_add",
1316         .args_type  = "netdev:O",
1317         .params     = "[user|tap|socket|vde|bridge|hubport|netmap|vhost-user],id=str[,prop=value][,...]",
1318         .help       = "add host network device",
1319         .cmd        = hmp_netdev_add,
1320         .command_completion = netdev_add_completion,
1321     },
1322
1323 SRST
1324 ``netdev_add``
1325   Add host network device.
1326 ERST
1327
1328     {
1329         .name       = "netdev_del",
1330         .args_type  = "id:s",
1331         .params     = "id",
1332         .help       = "remove host network device",
1333         .cmd        = hmp_netdev_del,
1334         .command_completion = netdev_del_completion,
1335     },
1336
1337 SRST
1338 ``netdev_del``
1339   Remove host network device.
1340 ERST
1341
1342     {
1343         .name       = "object_add",
1344         .args_type  = "object:O",
1345         .params     = "[qom-type=]type,id=str[,prop=value][,...]",
1346         .help       = "create QOM object",
1347         .cmd        = hmp_object_add,
1348         .command_completion = object_add_completion,
1349     },
1350
1351 SRST
1352 ``object_add``
1353   Create QOM object.
1354 ERST
1355
1356     {
1357         .name       = "object_del",
1358         .args_type  = "id:s",
1359         .params     = "id",
1360         .help       = "destroy QOM object",
1361         .cmd        = hmp_object_del,
1362         .command_completion = object_del_completion,
1363     },
1364
1365 SRST
1366 ``object_del``
1367   Destroy QOM object.
1368 ERST
1369
1370 #ifdef CONFIG_SLIRP
1371     {
1372         .name       = "hostfwd_add",
1373         .args_type  = "arg1:s,arg2:s?",
1374         .params     = "[netdev_id] [tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport",
1375         .help       = "redirect TCP or UDP connections from host to guest (requires -net user)",
1376         .cmd        = hmp_hostfwd_add,
1377     },
1378 #endif
1379 SRST
1380 ``hostfwd_add``
1381   Redirect TCP or UDP connections from host to guest (requires -net user).
1382 ERST
1383
1384 #ifdef CONFIG_SLIRP
1385     {
1386         .name       = "hostfwd_remove",
1387         .args_type  = "arg1:s,arg2:s?",
1388         .params     = "[netdev_id] [tcp|udp]:[hostaddr]:hostport",
1389         .help       = "remove host-to-guest TCP or UDP redirection",
1390         .cmd        = hmp_hostfwd_remove,
1391     },
1392
1393 #endif
1394 SRST
1395 ``hostfwd_remove``
1396   Remove host-to-guest TCP or UDP redirection.
1397 ERST
1398
1399     {
1400         .name       = "balloon",
1401         .args_type  = "value:M",
1402         .params     = "target",
1403         .help       = "request VM to change its memory allocation (in MB)",
1404         .cmd        = hmp_balloon,
1405     },
1406
1407 SRST
1408 ``balloon`` *value*
1409   Request VM to change its memory allocation to *value* (in MB).
1410 ERST
1411
1412     {
1413         .name       = "set_link",
1414         .args_type  = "name:s,up:b",
1415         .params     = "name on|off",
1416         .help       = "change the link status of a network adapter",
1417         .cmd        = hmp_set_link,
1418         .command_completion = set_link_completion,
1419     },
1420
1421 SRST
1422 ``set_link`` *name* ``[on|off]``
1423   Switch link *name* on (i.e. up) or off (i.e. down).
1424 ERST
1425
1426     {
1427         .name       = "watchdog_action",
1428         .args_type  = "action:s",
1429         .params     = "[reset|shutdown|poweroff|pause|debug|none]",
1430         .help       = "change watchdog action",
1431         .cmd        = hmp_watchdog_action,
1432         .command_completion = watchdog_action_completion,
1433     },
1434
1435 SRST
1436 ``watchdog_action``
1437   Change watchdog action.
1438 ERST
1439
1440     {
1441         .name       = "acl_show",
1442         .args_type  = "aclname:s",
1443         .params     = "aclname",
1444         .help       = "list rules in the access control list",
1445         .cmd        = hmp_acl_show,
1446     },
1447
1448 SRST
1449 ``acl_show`` *aclname*
1450   List all the matching rules in the access control list, and the default
1451   policy. There are currently two named access control lists,
1452   *vnc.x509dname* and *vnc.username* matching on the x509 client
1453   certificate distinguished name, and SASL username respectively.
1454 ERST
1455
1456     {
1457         .name       = "acl_policy",
1458         .args_type  = "aclname:s,policy:s",
1459         .params     = "aclname allow|deny",
1460         .help       = "set default access control list policy",
1461         .cmd        = hmp_acl_policy,
1462     },
1463
1464 SRST
1465 ``acl_policy`` *aclname* ``allow|deny``
1466   Set the default access control list policy, used in the event that
1467   none of the explicit rules match. The default policy at startup is
1468   always ``deny``.
1469 ERST
1470
1471     {
1472         .name       = "acl_add",
1473         .args_type  = "aclname:s,match:s,policy:s,index:i?",
1474         .params     = "aclname match allow|deny [index]",
1475         .help       = "add a match rule to the access control list",
1476         .cmd        = hmp_acl_add,
1477     },
1478
1479 SRST
1480 ``acl_add`` *aclname* *match* ``allow|deny`` [*index*]
1481   Add a match rule to the access control list, allowing or denying access.
1482   The match will normally be an exact username or x509 distinguished name,
1483   but can optionally include wildcard globs. eg ``*@EXAMPLE.COM`` to
1484   allow all users in the ``EXAMPLE.COM`` kerberos realm. The match will
1485   normally be appended to the end of the ACL, but can be inserted
1486   earlier in the list if the optional *index* parameter is supplied.
1487 ERST
1488
1489     {
1490         .name       = "acl_remove",
1491         .args_type  = "aclname:s,match:s",
1492         .params     = "aclname match",
1493         .help       = "remove a match rule from the access control list",
1494         .cmd        = hmp_acl_remove,
1495     },
1496
1497 SRST
1498 ``acl_remove`` *aclname* *match*
1499   Remove the specified match rule from the access control list.
1500 ERST
1501
1502     {
1503         .name       = "acl_reset",
1504         .args_type  = "aclname:s",
1505         .params     = "aclname",
1506         .help       = "reset the access control list",
1507         .cmd        = hmp_acl_reset,
1508     },
1509
1510 SRST
1511 ``acl_reset`` *aclname*
1512   Remove all matches from the access control list, and set the default
1513   policy back to ``deny``.
1514 ERST
1515
1516     {
1517         .name       = "nbd_server_start",
1518         .args_type  = "all:-a,writable:-w,uri:s",
1519         .params     = "nbd_server_start [-a] [-w] host:port",
1520         .help       = "serve block devices on the given host and port",
1521         .cmd        = hmp_nbd_server_start,
1522     },
1523 SRST
1524 ``nbd_server_start`` *host*:*port*
1525   Start an NBD server on the given host and/or port.  If the ``-a``
1526   option is included, all of the virtual machine's block devices that
1527   have an inserted media on them are automatically exported; in this case,
1528   the ``-w`` option makes the devices writable too.
1529 ERST
1530
1531     {
1532         .name       = "nbd_server_add",
1533         .args_type  = "writable:-w,device:B,name:s?",
1534         .params     = "nbd_server_add [-w] device [name]",
1535         .help       = "export a block device via NBD",
1536         .cmd        = hmp_nbd_server_add,
1537     },
1538 SRST
1539 ``nbd_server_add`` *device* [ *name* ]
1540   Export a block device through QEMU's NBD server, which must be started
1541   beforehand with ``nbd_server_start``.  The ``-w`` option makes the
1542   exported device writable too.  The export name is controlled by *name*,
1543   defaulting to *device*.
1544 ERST
1545
1546     {
1547         .name       = "nbd_server_remove",
1548         .args_type  = "force:-f,name:s",
1549         .params     = "nbd_server_remove [-f] name",
1550         .help       = "remove an export previously exposed via NBD",
1551         .cmd        = hmp_nbd_server_remove,
1552     },
1553 SRST
1554 ``nbd_server_remove [-f]`` *name*
1555   Stop exporting a block device through QEMU's NBD server, which was
1556   previously started with ``nbd_server_add``.  The ``-f``
1557   option forces the server to drop the export immediately even if
1558   clients are connected; otherwise the command fails unless there are no
1559   clients.
1560 ERST
1561
1562     {
1563         .name       = "nbd_server_stop",
1564         .args_type  = "",
1565         .params     = "nbd_server_stop",
1566         .help       = "stop serving block devices using the NBD protocol",
1567         .cmd        = hmp_nbd_server_stop,
1568     },
1569 SRST
1570 ``nbd_server_stop``
1571   Stop the QEMU embedded NBD server.
1572 ERST
1573
1574
1575 #if defined(TARGET_I386)
1576
1577     {
1578         .name       = "mce",
1579         .args_type  = "broadcast:-b,cpu_index:i,bank:i,status:l,mcg_status:l,addr:l,misc:l",
1580         .params     = "[-b] cpu bank status mcgstatus addr misc",
1581         .help       = "inject a MCE on the given CPU [and broadcast to other CPUs with -b option]",
1582         .cmd        = hmp_mce,
1583     },
1584
1585 #endif
1586 SRST
1587 ``mce`` *cpu* *bank* *status* *mcgstatus* *addr* *misc*
1588   Inject an MCE on the given CPU (x86 only).
1589 ERST
1590
1591     {
1592         .name       = "getfd",
1593         .args_type  = "fdname:s",
1594         .params     = "getfd name",
1595         .help       = "receive a file descriptor via SCM rights and assign it a name",
1596         .cmd        = hmp_getfd,
1597     },
1598
1599 SRST
1600 ``getfd`` *fdname*
1601   If a file descriptor is passed alongside this command using the SCM_RIGHTS
1602   mechanism on unix sockets, it is stored using the name *fdname* for
1603   later use by other monitor commands.
1604 ERST
1605
1606     {
1607         .name       = "closefd",
1608         .args_type  = "fdname:s",
1609         .params     = "closefd name",
1610         .help       = "close a file descriptor previously passed via SCM rights",
1611         .cmd        = hmp_closefd,
1612     },
1613
1614 SRST
1615 ``closefd`` *fdname*
1616   Close the file descriptor previously assigned to *fdname* using the
1617   ``getfd`` command. This is only needed if the file descriptor was never
1618   used by another monitor command.
1619 ERST
1620
1621     {
1622         .name       = "block_passwd",
1623         .args_type  = "device:B,password:s",
1624         .params     = "block_passwd device password",
1625         .help       = "set the password of encrypted block devices",
1626         .cmd        = hmp_block_passwd,
1627     },
1628
1629 SRST
1630 ``block_passwd`` *device* *password*
1631   Set the encrypted device *device* password to *password*
1632
1633   This command is now obsolete and will always return an error since 2.10
1634 ERST
1635
1636     {
1637         .name       = "block_set_io_throttle",
1638         .args_type  = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l",
1639         .params     = "device bps bps_rd bps_wr iops iops_rd iops_wr",
1640         .help       = "change I/O throttle limits for a block drive",
1641         .cmd        = hmp_block_set_io_throttle,
1642     },
1643
1644 SRST
1645 ``block_set_io_throttle`` *device* *bps* *bps_rd* *bps_wr* *iops* *iops_rd* *iops_wr*
1646   Change I/O throttle limits for a block drive to
1647   *bps* *bps_rd* *bps_wr* *iops* *iops_rd* *iops_wr*.
1648   *device* can be a block device name, a qdev ID or a QOM path.
1649 ERST
1650
1651     {
1652         .name       = "set_password",
1653         .args_type  = "protocol:s,password:s,connected:s?",
1654         .params     = "protocol password action-if-connected",
1655         .help       = "set spice/vnc password",
1656         .cmd        = hmp_set_password,
1657     },
1658
1659 SRST
1660 ``set_password [ vnc | spice ] password [ action-if-connected ]``
1661   Change spice/vnc password.  Use zero to make the password stay valid
1662   forever.  *action-if-connected* specifies what should happen in
1663   case a connection is established: *fail* makes the password change
1664   fail.  *disconnect* changes the password and disconnects the
1665   client.  *keep* changes the password and keeps the connection up.
1666   *keep* is the default.
1667 ERST
1668
1669     {
1670         .name       = "expire_password",
1671         .args_type  = "protocol:s,time:s",
1672         .params     = "protocol time",
1673         .help       = "set spice/vnc password expire-time",
1674         .cmd        = hmp_expire_password,
1675     },
1676
1677 SRST
1678 ``expire_password [ vnc | spice ]`` *expire-time*
1679   Specify when a password for spice/vnc becomes
1680   invalid. *expire-time* accepts:
1681
1682   ``now``
1683     Invalidate password instantly.
1684   ``never``
1685     Password stays valid forever.
1686   ``+``\ *nsec*
1687     Password stays valid for *nsec* seconds starting now.
1688   *nsec*
1689     Password is invalidated at the given time.  *nsec* are the seconds
1690     passed since 1970, i.e. unix epoch.
1691
1692 ERST
1693
1694     {
1695         .name       = "chardev-add",
1696         .args_type  = "args:s",
1697         .params     = "args",
1698         .help       = "add chardev",
1699         .cmd        = hmp_chardev_add,
1700         .command_completion = chardev_add_completion,
1701     },
1702
1703 SRST
1704 ``chardev-add`` *args*
1705   chardev-add accepts the same parameters as the -chardev command line switch.
1706 ERST
1707
1708     {
1709         .name       = "chardev-change",
1710         .args_type  = "id:s,args:s",
1711         .params     = "id args",
1712         .help       = "change chardev",
1713         .cmd        = hmp_chardev_change,
1714     },
1715
1716 SRST
1717 ``chardev-change`` *args*
1718   chardev-change accepts existing chardev *id* and then the same arguments
1719   as the -chardev command line switch (except for "id").
1720 ERST
1721
1722     {
1723         .name       = "chardev-remove",
1724         .args_type  = "id:s",
1725         .params     = "id",
1726         .help       = "remove chardev",
1727         .cmd        = hmp_chardev_remove,
1728         .command_completion = chardev_remove_completion,
1729     },
1730
1731 SRST
1732 ``chardev-remove`` *id*
1733   Removes the chardev *id*.
1734 ERST
1735
1736     {
1737         .name       = "chardev-send-break",
1738         .args_type  = "id:s",
1739         .params     = "id",
1740         .help       = "send a break on chardev",
1741         .cmd        = hmp_chardev_send_break,
1742         .command_completion = chardev_remove_completion,
1743     },
1744
1745 SRST
1746 ``chardev-send-break`` *id*
1747   Send a break on the chardev *id*.
1748 ERST
1749
1750     {
1751         .name       = "qemu-io",
1752         .args_type  = "qdev:-d,device:B,command:s",
1753         .params     = "[-d] [device] \"[command]\"",
1754         .help       = "run a qemu-io command on a block device\n\t\t\t"
1755                       "-d: [device] is a device ID rather than a "
1756                       "drive ID or node name",
1757         .cmd        = hmp_qemu_io,
1758     },
1759
1760 SRST
1761 ``qemu-io`` *device* *command*
1762   Executes a qemu-io command on the given block device.
1763 ERST
1764
1765     {
1766         .name       = "qom-list",
1767         .args_type  = "path:s?",
1768         .params     = "path",
1769         .help       = "list QOM properties",
1770         .cmd        = hmp_qom_list,
1771         .flags      = "p",
1772     },
1773
1774 SRST
1775 ``qom-list`` [*path*]
1776   Print QOM properties of object at location *path*
1777 ERST
1778
1779     {
1780         .name       = "qom-get",
1781         .args_type  = "path:s,property:s",
1782         .params     = "path property",
1783         .help       = "print QOM property",
1784         .cmd        = hmp_qom_get,
1785         .flags      = "p",
1786     },
1787
1788 SRST
1789 ``qom-get`` *path* *property*
1790   Print QOM property *property* of object at location *path*
1791 ERST
1792
1793     {
1794         .name       = "qom-set",
1795         .args_type  = "json:-j,path:s,property:s,value:S",
1796         .params     = "[-j] path property value",
1797         .help       = "set QOM property.\n\t\t\t"
1798                       "-j: the value is specified in json format.",
1799         .cmd        = hmp_qom_set,
1800         .flags      = "p",
1801     },
1802
1803 SRST
1804 ``qom-set`` *path* *property* *value*
1805   Set QOM property *property* of object at location *path* to value *value*
1806 ERST
1807
1808     {
1809         .name       = "replay_break",
1810         .args_type  = "icount:i",
1811         .params     = "icount",
1812         .help       = "set breakpoint at the specified instruction count",
1813         .cmd        = hmp_replay_break,
1814     },
1815
1816 SRST
1817 ``replay_break`` *icount*
1818   Set replay breakpoint at instruction count *icount*.
1819   Execution stops when the specified instruction is reached.
1820   There can be at most one breakpoint. When breakpoint is set, any prior
1821   one is removed.  The breakpoint may be set only in replay mode and only
1822   "in the future", i.e. at instruction counts greater than the current one.
1823   The current instruction count can be observed with ``info replay``.
1824 ERST
1825
1826     {
1827         .name       = "replay_delete_break",
1828         .args_type  = "",
1829         .params     = "",
1830         .help       = "remove replay breakpoint",
1831         .cmd        = hmp_replay_delete_break,
1832     },
1833
1834 SRST
1835 ``replay_delete_break``
1836   Remove replay breakpoint which was previously set with ``replay_break``.
1837   The command is ignored when there are no replay breakpoints.
1838 ERST
1839
1840     {
1841         .name       = "replay_seek",
1842         .args_type  = "icount:i",
1843         .params     = "icount",
1844         .help       = "replay execution to the specified instruction count",
1845         .cmd        = hmp_replay_seek,
1846     },
1847
1848 SRST
1849 ``replay_seek`` *icount*
1850   Automatically proceed to the instruction count *icount*, when
1851   replaying the execution. The command automatically loads nearest
1852   snapshot and replays the execution to find the desired instruction.
1853   When there is no preceding snapshot or the execution is not replayed,
1854   then the command fails.
1855   *icount* for the reference may be observed with ``info replay`` command.
1856 ERST
1857
1858     {
1859         .name       = "info",
1860         .args_type  = "item:s?",
1861         .params     = "[subcommand]",
1862         .help       = "show various information about the system state",
1863         .cmd        = hmp_info_help,
1864         .sub_table  = hmp_info_cmds,
1865         .flags      = "p",
1866     },
1867