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