qemu-monitor.hx

   1 HXCOMM Use DEFHEADING() to define headings in both help text and texi
   2 HXCOMM Text between STEXI and ETEXI are copied to texi version and
   3 HXCOMM discarded from C version
   4 HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and
   5 HXCOMM does not show up in the other formats.
   6 HXCOMM DEF(command, args, callback, arg_string, help) is used to construct
   7 HXCOMM monitor commands
   8 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
   9
  10 SQMP
  11                         QMP Supported Commands
  12                         ----------------------
  13
  14 This document describes all commands currently supported by QMP.
  15
  16 Most of the time their usage is exactly the same as in the user Monitor, this
  17 means that any other document which also describe commands (the manpage,
  18 QEMU's manual, etc) can and should be consulted.
  19
  20 QMP has two types of commands: regular and query commands. Regular commands
  21 usually change the Virtual Machine's state someway, while query commands just
  22 return information. The sections below are divided accordingly.
  23
  24 It's important to observe that all communication examples are formatted in
  25 a reader-friendly way, so that they're easier to understand. However, in real
  26 protocol usage, they're emitted as a single line.
  27
  28 Also, the following notation is used to denote data flow:
  29
  30 -> data issued by the Client
  31 <- Server data response
  32
  33 Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
  34 information on the Server command and response formats.
  35
  36 NOTE: This document is temporary and will be replaced soon.
  37
  38 1. Regular Commands
  39 ===================
  40
  41 Server's responses in the examples below are always a success response, please
  42 refer to the QMP specification for more details on error responses.
  43
  44 EQMP
  45
  46 STEXI
  47 @table @option
  48 ETEXI
  49
  50     {
  51         .name       = "help|?",
  52         .args_type  = "name:s?",
  53         .params     = "[cmd]",
  54         .help       = "show the help",
  55         .mhandler.cmd = do_help_cmd,
  56     },
  57
  58 STEXI
  59 @item help or ? [@var{cmd}]
  60 @findex help
  61 Show the help for all commands or just for command @var{cmd}.
  62 ETEXI
  63
  64     {
  65         .name       = "commit",
  66         .args_type  = "device:B",
  67         .params     = "device|all",
  68         .help       = "commit changes to the disk images (if -snapshot is used) or backing files",
  69         .mhandler.cmd = do_commit,
  70     },
  71
  72 STEXI
  73 @item commit
  74 @findex commit
  75 Commit changes to the disk images (if -snapshot is used) or backing files.
  76 ETEXI
  77
  78     {
  79         .name       = "q|quit",
  80         .args_type  = "",
  81         .params     = "",
  82         .help       = "quit the emulator",
  83         .user_print = monitor_user_noop,
  84         .mhandler.cmd_new = do_quit,
  85     },
  86
  87 STEXI
  88 @item q or quit
  89 @findex quit
  90 Quit the emulator.
  91 ETEXI
  92 SQMP
  93 quit
  94 ----
  95
  96 Quit the emulator.
  97
  98 Arguments: None.
  99
 100 Example:
 101
 102 -> { "execute": "quit" }
 103 <- { "return": {} }
 104
 105 EQMP
 106
 107     {
 108         .name       = "eject",
 109         .args_type  = "force:-f,device:B",
 110         .params     = "[-f] device",
 111         .help       = "eject a removable medium (use -f to force it)",
 112         .user_print = monitor_user_noop,
 113         .mhandler.cmd_new = do_eject,
 114     },
 115
 116 STEXI
 117 @item eject [-f] @var{device}
 118 @findex eject
 119 Eject a removable medium (use -f to force it).
 120 ETEXI
 121 SQMP
 122 eject
 123 -----
 124
 125 Eject a removable medium.
 126
 127 Arguments:
 128
 129 - force: force ejection (json-bool, optional)
 130 - device: device name (json-string)
 131
 132 Example:
 133
 134 -> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
 135 <- { "return": {} }
 136
 137 Note: The "force" argument defaults to false.
 138
 139 EQMP
 140
 141     {
 142         .name       = "change",
 143         .args_type  = "device:B,target:F,arg:s?",
 144         .params     = "device filename [format]",
 145         .help       = "change a removable medium, optional format",
 146         .user_print = monitor_user_noop,
 147         .mhandler.cmd_new = do_change,
 148     },
 149
 150 STEXI
 151 @item change @var{device} @var{setting}
 152 @findex change
 153
 154 Change the configuration of a device.
 155
 156 @table @option
 157 @item change @var{diskdevice} @var{filename} [@var{format}]
 158 Change the medium for a removable disk device to point to @var{filename}. eg
 159
 160 @example
 161 (qemu) change ide1-cd0 /path/to/some.iso
 162 @end example
 163
 164 @var{format} is optional.
 165
 166 @item change vnc @var{display},@var{options}
 167 Change the configuration of the VNC server. The valid syntax for @var{display}
 168 and @var{options} are described at @ref{sec_invocation}. eg
 169
 170 @example
 171 (qemu) change vnc localhost:1
 172 @end example
 173
 174 @item change vnc password [@var{password}]
 175
 176 Change the password associated with the VNC server. If the new password is not
 177 supplied, the monitor will prompt for it to be entered. VNC passwords are only
 178 significant up to 8 letters. eg
 179
 180 @example
 181 (qemu) change vnc password
 182 Password: ********
 183 @end example
 184
 185 @end table
 186 ETEXI
 187 SQMP
 188 change
 189 ------
 190
 191 Change a removable medium or VNC configuration.
 192
 193 Arguments:
 194
 195 - "device": device name (json-string)
 196 - "target": filename or item (json-string)
 197 - "arg": additional argument (json-string, optional)
 198
 199 Examples:
 200
 201 1. Change a removable medium
 202
 203 -> { "execute": "change",
 204              "arguments": { "device": "ide1-cd0",
 205                             "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
 206 <- { "return": {} }
 207
 208 2. Change VNC password
 209
 210 -> { "execute": "change",
 211              "arguments": { "device": "vnc", "target": "password",
 212                             "arg": "foobar1" } }
 213 <- { "return": {} }
 214
 215 EQMP
 216
 217     {
 218         .name       = "screendump",
 219         .args_type  = "filename:F",
 220         .params     = "filename",
 221         .help       = "save screen into PPM image 'filename'",
 222         .user_print = monitor_user_noop,
 223         .mhandler.cmd_new = do_screen_dump,
 224     },
 225
 226 STEXI
 227 @item screendump @var{filename}
 228 @findex screendump
 229 Save screen into PPM image @var{filename}.
 230 ETEXI
 231 SQMP
 232 screendump
 233 ----------
 234
 235 Save screen into PPM image.
 236
 237 Arguments:
 238
 239 - "filename": file path (json-string)
 240
 241 Example:
 242
 243 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 244 <- { "return": {} }
 245
 246 EQMP
 247
 248     {
 249         .name       = "logfile",
 250         .args_type  = "filename:F",
 251         .params     = "filename",
 252         .help       = "output logs to 'filename'",
 253         .mhandler.cmd = do_logfile,
 254     },
 255
 256 STEXI
 257 @item logfile @var{filename}
 258 @findex logfile
 259 Output logs to @var{filename}.
 260 ETEXI
 261
 262     {
 263         .name       = "log",
 264         .args_type  = "items:s",
 265         .params     = "item1[,...]",
 266         .help       = "activate logging of the specified items to '/tmp/qemu.log'",
 267         .mhandler.cmd = do_log,
 268     },
 269
 270 STEXI
 271 @item log @var{item1}[,...]
 272 @findex log
 273 Activate logging of the specified items to @file{/tmp/qemu.log}.
 274 ETEXI
 275
 276     {
 277         .name       = "savevm",
 278         .args_type  = "name:s?",
 279         .params     = "[tag|id]",
 280         .help       = "save a VM snapshot. If no tag or id are provided, a new snapshot is created",
 281         .mhandler.cmd = do_savevm,
 282     },
 283
 284 STEXI
 285 @item savevm [@var{tag}|@var{id}]
 286 @findex savevm
 287 Create a snapshot of the whole virtual machine. If @var{tag} is
 288 provided, it is used as human readable identifier. If there is already
 289 a snapshot with the same tag or ID, it is replaced. More info at
 290 @ref{vm_snapshots}.
 291 ETEXI
 292
 293     {
 294         .name       = "loadvm",
 295         .args_type  = "name:s",
 296         .params     = "tag|id",
 297         .help       = "restore a VM snapshot from its tag or id",
 298         .mhandler.cmd = do_loadvm,
 299     },
 300
 301 STEXI
 302 @item loadvm @var{tag}|@var{id}
 303 @findex loadvm
 304 Set the whole virtual machine to the snapshot identified by the tag
 305 @var{tag} or the unique snapshot ID @var{id}.
 306 ETEXI
 307
 308     {
 309         .name       = "delvm",
 310         .args_type  = "name:s",
 311         .params     = "tag|id",
 312         .help       = "delete a VM snapshot from its tag or id",
 313         .mhandler.cmd = do_delvm,
 314     },
 315
 316 STEXI
 317 @item delvm @var{tag}|@var{id}
 318 @findex delvm
 319 Delete the snapshot identified by @var{tag} or @var{id}.
 320 ETEXI
 321
 322     {
 323         .name       = "singlestep",
 324         .args_type  = "option:s?",
 325         .params     = "[on|off]",
 326         .help       = "run emulation in singlestep mode or switch to normal mode",
 327         .mhandler.cmd = do_singlestep,
 328     },
 329
 330 STEXI
 331 @item singlestep [off]
 332 @findex singlestep
 333 Run the emulation in single step mode.
 334 If called with option off, the emulation returns to normal mode.
 335 ETEXI
 336
 337     {
 338         .name       = "stop",
 339         .args_type  = "",
 340         .params     = "",
 341         .help       = "stop emulation",
 342         .user_print = monitor_user_noop,
 343         .mhandler.cmd_new = do_stop,
 344     },
 345
 346 STEXI
 347 @item stop
 348 @findex stop
 349 Stop emulation.
 350 ETEXI
 351 SQMP
 352 stop
 353 ----
 354
 355 Stop the emulator.
 356
 357 Arguments: None.
 358
 359 Example:
 360
 361 -> { "execute": "stop" }
 362 <- { "return": {} }
 363
 364 EQMP
 365
 366     {
 367         .name       = "c|cont",
 368         .args_type  = "",
 369         .params     = "",
 370         .help       = "resume emulation",
 371         .user_print = monitor_user_noop,
 372         .mhandler.cmd_new = do_cont,
 373     },
 374
 375 STEXI
 376 @item c or cont
 377 @findex cont
 378 Resume emulation.
 379 ETEXI
 380 SQMP
 381 cont
 382 ----
 383
 384 Resume emulation.
 385
 386 Arguments: None.
 387
 388 Example:
 389
 390 -> { "execute": "cont" }
 391 <- { "return": {} }
 392
 393 EQMP
 394
 395     {
 396         .name       = "gdbserver",
 397         .args_type  = "device:s?",
 398         .params     = "[device]",
 399         .help       = "start gdbserver on given device (default 'tcp::1234'), stop with 'none'",
 400         .mhandler.cmd = do_gdbserver,
 401     },
 402
 403 STEXI
 404 @item gdbserver [@var{port}]
 405 @findex gdbserver
 406 Start gdbserver session (default @var{port}=1234)
 407 ETEXI
 408
 409     {
 410         .name       = "x",
 411         .args_type  = "fmt:/,addr:l",
 412         .params     = "/fmt addr",
 413         .help       = "virtual memory dump starting at 'addr'",
 414         .mhandler.cmd = do_memory_dump,
 415     },
 416
 417 STEXI
 418 @item x/fmt @var{addr}
 419 @findex x
 420 Virtual memory dump starting at @var{addr}.
 421 ETEXI
 422
 423     {
 424         .name       = "xp",
 425         .args_type  = "fmt:/,addr:l",
 426         .params     = "/fmt addr",
 427         .help       = "physical memory dump starting at 'addr'",
 428         .mhandler.cmd = do_physical_memory_dump,
 429     },
 430
 431 STEXI
 432 @item xp /@var{fmt} @var{addr}
 433 @findex xp
 434 Physical memory dump starting at @var{addr}.
 435
 436 @var{fmt} is a format which tells the command how to format the
 437 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
 438
 439 @table @var
 440 @item count
 441 is the number of items to be dumped.
 442
 443 @item format
 444 can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
 445 c (char) or i (asm instruction).
 446
 447 @item size
 448 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
 449 @code{h} or @code{w} can be specified with the @code{i} format to
 450 respectively select 16 or 32 bit code instruction size.
 451
 452 @end table
 453
 454 Examples:
 455 @itemize
 456 @item
 457 Dump 10 instructions at the current instruction pointer:
 458 @example
 459 (qemu) x/10i $eip
 460 0x90107063:  ret
 461 0x90107064:  sti
 462 0x90107065:  lea    0x0(%esi,1),%esi
 463 0x90107069:  lea    0x0(%edi,1),%edi
 464 0x90107070:  ret
 465 0x90107071:  jmp    0x90107080
 466 0x90107073:  nop
 467 0x90107074:  nop
 468 0x90107075:  nop
 469 0x90107076:  nop
 470 @end example
 471
 472 @item
 473 Dump 80 16 bit values at the start of the video memory.
 474 @smallexample
 475 (qemu) xp/80hx 0xb8000
 476 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
 477 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
 478 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
 479 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
 480 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
 481 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
 482 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 483 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 484 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 485 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 486 @end smallexample
 487 @end itemize
 488 ETEXI
 489
 490     {
 491         .name       = "p|print",
 492         .args_type  = "fmt:/,val:l",
 493         .params     = "/fmt expr",
 494         .help       = "print expression value (use $reg for CPU register access)",
 495         .mhandler.cmd = do_print,
 496     },
 497
 498 STEXI
 499 @item p or print/@var{fmt} @var{expr}
 500 @findex print
 501
 502 Print expression value. Only the @var{format} part of @var{fmt} is
 503 used.
 504 ETEXI
 505
 506     {
 507         .name       = "i",
 508         .args_type  = "fmt:/,addr:i,index:i.",
 509         .params     = "/fmt addr",
 510         .help       = "I/O port read",
 511         .mhandler.cmd = do_ioport_read,
 512     },
 513
 514 STEXI
 515 Read I/O port.
 516 ETEXI
 517
 518     {
 519         .name       = "o",
 520         .args_type  = "fmt:/,addr:i,val:i",
 521         .params     = "/fmt addr value",
 522         .help       = "I/O port write",
 523         .mhandler.cmd = do_ioport_write,
 524     },
 525
 526 STEXI
 527 Write to I/O port.
 528 ETEXI
 529
 530     {
 531         .name       = "sendkey",
 532         .args_type  = "string:s,hold_time:i?",
 533         .params     = "keys [hold_ms]",
 534         .help       = "send keys to the VM (e.g. 'sendkey ctrl-alt-f1', default hold time=100 ms)",
 535         .mhandler.cmd = do_sendkey,
 536     },
 537
 538 STEXI
 539 @item sendkey @var{keys}
 540 @findex sendkey
 541
 542 Send @var{keys} to the emulator. @var{keys} could be the name of the
 543 key or @code{#} followed by the raw value in either decimal or hexadecimal
 544 format. Use @code{-} to press several keys simultaneously. Example:
 545 @example
 546 sendkey ctrl-alt-f1
 547 @end example
 548
 549 This command is useful to send keys that your graphical user interface
 550 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
 551 ETEXI
 552
 553     {
 554         .name       = "system_reset",
 555         .args_type  = "",
 556         .params     = "",
 557         .help       = "reset the system",
 558         .user_print = monitor_user_noop,
 559         .mhandler.cmd_new = do_system_reset,
 560     },
 561
 562 STEXI
 563 @item system_reset
 564 @findex system_reset
 565
 566 Reset the system.
 567 ETEXI
 568 SQMP
 569 system_reset
 570 ------------
 571
 572 Reset the system.
 573
 574 Arguments: None.
 575
 576 Example:
 577
 578 -> { "execute": "system_reset" }
 579 <- { "return": {} }
 580
 581 EQMP
 582
 583     {
 584         .name       = "system_powerdown",
 585         .args_type  = "",
 586         .params     = "",
 587         .help       = "send system power down event",
 588         .user_print = monitor_user_noop,
 589         .mhandler.cmd_new = do_system_powerdown,
 590     },
 591
 592 STEXI
 593 @item system_powerdown
 594 @findex system_powerdown
 595
 596 Power down the system (if supported).
 597 ETEXI
 598 SQMP
 599 system_powerdown
 600 ----------------
 601
 602 Send system power down event.
 603
 604 Arguments: None.
 605
 606 Example:
 607
 608 -> { "execute": "system_powerdown" }
 609 <- { "return": {} }
 610
 611 EQMP
 612
 613     {
 614         .name       = "sum",
 615         .args_type  = "start:i,size:i",
 616         .params     = "addr size",
 617         .help       = "compute the checksum of a memory region",
 618         .mhandler.cmd = do_sum,
 619     },
 620
 621 STEXI
 622 @item sum @var{addr} @var{size}
 623 @findex sum
 624
 625 Compute the checksum of a memory region.
 626 ETEXI
 627
 628     {
 629         .name       = "usb_add",
 630         .args_type  = "devname:s",
 631         .params     = "device",
 632         .help       = "add USB device (e.g. 'host:bus.addr' or 'host:vendor_id:product_id')",
 633         .mhandler.cmd = do_usb_add,
 634     },
 635
 636 STEXI
 637 @item usb_add @var{devname}
 638 @findex usb_add
 639
 640 Add the USB device @var{devname}.  For details of available devices see
 641 @ref{usb_devices}
 642 ETEXI
 643
 644     {
 645         .name       = "usb_del",
 646         .args_type  = "devname:s",
 647         .params     = "device",
 648         .help       = "remove USB device 'bus.addr'",
 649         .mhandler.cmd = do_usb_del,
 650     },
 651
 652 STEXI
 653 @item usb_del @var{devname}
 654 @findex usb_del
 655
 656 Remove the USB device @var{devname} from the QEMU virtual USB
 657 hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
 658 command @code{info usb} to see the devices you can remove.
 659 ETEXI
 660
 661     {
 662         .name       = "device_add",
 663         .args_type  = "device:O",
 664         .params     = "driver[,prop=value][,...]",
 665         .help       = "add device, like -device on the command line",
 666         .user_print = monitor_user_noop,
 667         .mhandler.cmd_new = do_device_add,
 668     },
 669
 670 STEXI
 671 @item device_add @var{config}
 672 @findex device_add
 673
 674 Add device.
 675 ETEXI
 676 SQMP
 677 device_add
 678 ----------
 679
 680 Add a device.
 681
 682 Arguments:
 683
 684 - "driver": the name of the new device's driver (json-string)
 685 - "bus": the device's parent bus (device tree path, json-string, optional)
 686 - "id": the device's ID, must be unique (json-string)
 687 - device properties
 688
 689 Example:
 690
 691 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
 692 <- { "return": {} }
 693
 694 Notes:
 695
 696 (1) For detailed information about this command, please refer to the
 697     'docs/qdev-device-use.txt' file.
 698
 699 (2) It's possible to list device properties by running QEMU with the
 700     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
 701
 702 EQMP
 703
 704     {
 705         .name       = "device_del",
 706         .args_type  = "id:s",
 707         .params     = "device",
 708         .help       = "remove device",
 709         .user_print = monitor_user_noop,
 710         .mhandler.cmd_new = do_device_del,
 711     },
 712
 713 STEXI
 714 @item device_del @var{id}
 715 @findex device_del
 716
 717 Remove device @var{id}.
 718 ETEXI
 719 SQMP
 720 device_del
 721 ----------
 722
 723 Remove a device.
 724
 725 Arguments:
 726
 727 - "id": the device's ID (json-string)
 728
 729 Example:
 730
 731 -> { "execute": "device_del", "arguments": { "id": "net1" } }
 732 <- { "return": {} }
 733
 734 EQMP
 735
 736     {
 737         .name       = "cpu",
 738         .args_type  = "index:i",
 739         .params     = "index",
 740         .help       = "set the default CPU",
 741         .user_print = monitor_user_noop,
 742         .mhandler.cmd_new = do_cpu_set,
 743     },
 744
 745 STEXI
 746 @item cpu @var{index}
 747 @findex cpu
 748 Set the default CPU.
 749 ETEXI
 750 SQMP
 751 cpu
 752 ---
 753
 754 Set the default CPU.
 755
 756 Arguments:
 757
 758 - "index": the CPU's index (json-int)
 759
 760 Example:
 761
 762 -> { "execute": "cpu", "arguments": { "index": 0 } }
 763 <- { "return": {} }
 764
 765 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 766
 767 EQMP
 768
 769     {
 770         .name       = "mouse_move",
 771         .args_type  = "dx_str:s,dy_str:s,dz_str:s?",
 772         .params     = "dx dy [dz]",
 773         .help       = "send mouse move events",
 774         .mhandler.cmd = do_mouse_move,
 775     },
 776
 777 STEXI
 778 @item mouse_move @var{dx} @var{dy} [@var{dz}]
 779 @findex mouse_move
 780 Move the active mouse to the specified coordinates @var{dx} @var{dy}
 781 with optional scroll axis @var{dz}.
 782 ETEXI
 783
 784     {
 785         .name       = "mouse_button",
 786         .args_type  = "button_state:i",
 787         .params     = "state",
 788         .help       = "change mouse button state (1=L, 2=M, 4=R)",
 789         .mhandler.cmd = do_mouse_button,
 790     },
 791
 792 STEXI
 793 @item mouse_button @var{val}
 794 @findex mouse_button
 795 Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
 796 ETEXI
 797
 798     {
 799         .name       = "mouse_set",
 800         .args_type  = "index:i",
 801         .params     = "index",
 802         .help       = "set which mouse device receives events",
 803         .mhandler.cmd = do_mouse_set,
 804     },
 805
 806 STEXI
 807 @item mouse_set @var{index}
 808 @findex mouse_set
 809 Set which mouse device receives events at given @var{index}, index
 810 can be obtained with
 811 @example
 812 info mice
 813 @end example
 814 ETEXI
 815
 816 #ifdef HAS_AUDIO
 817     {
 818         .name       = "wavcapture",
 819         .args_type  = "path:F,freq:i?,bits:i?,nchannels:i?",
 820         .params     = "path [frequency [bits [channels]]]",
 821         .help       = "capture audio to a wave file (default frequency=44100 bits=16 channels=2)",
 822         .mhandler.cmd = do_wav_capture,
 823     },
 824 #endif
 825 STEXI
 826 @item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
 827 @findex wavcapture
 828 Capture audio into @var{filename}. Using sample rate @var{frequency}
 829 bits per sample @var{bits} and number of channels @var{channels}.
 830
 831 Defaults:
 832 @itemize @minus
 833 @item Sample rate = 44100 Hz - CD quality
 834 @item Bits = 16
 835 @item Number of channels = 2 - Stereo
 836 @end itemize
 837 ETEXI
 838
 839 #ifdef HAS_AUDIO
 840     {
 841         .name       = "stopcapture",
 842         .args_type  = "n:i",
 843         .params     = "capture index",
 844         .help       = "stop capture",
 845         .mhandler.cmd = do_stop_capture,
 846     },
 847 #endif
 848 STEXI
 849 @item stopcapture @var{index}
 850 @findex stopcapture
 851 Stop capture with a given @var{index}, index can be obtained with
 852 @example
 853 info capture
 854 @end example
 855 ETEXI
 856
 857     {
 858         .name       = "memsave",
 859         .args_type  = "val:l,size:i,filename:s",
 860         .params     = "addr size file",
 861         .help       = "save to disk virtual memory dump starting at 'addr' of size 'size'",
 862         .user_print = monitor_user_noop,
 863         .mhandler.cmd_new = do_memory_save,
 864     },
 865
 866 STEXI
 867 @item memsave @var{addr} @var{size} @var{file}
 868 @findex memsave
 869 save to disk virtual memory dump starting at @var{addr} of size @var{size}.
 870 ETEXI
 871 SQMP
 872 memsave
 873 -------
 874
 875 Save to disk virtual memory dump starting at 'val' of size 'size'.
 876
 877 Arguments:
 878
 879 - "val": the starting address (json-int)
 880 - "size": the memory size, in bytes (json-int)
 881 - "filename": file path (json-string)
 882
 883 Example:
 884
 885 -> { "execute": "memsave",
 886              "arguments": { "val": 10,
 887                             "size": 100,
 888                             "filename": "/tmp/virtual-mem-dump" } }
 889 <- { "return": {} }
 890
 891 Note: Depends on the current CPU.
 892
 893 EQMP
 894
 895     {
 896         .name       = "pmemsave",
 897         .args_type  = "val:l,size:i,filename:s",
 898         .params     = "addr size file",
 899         .help       = "save to disk physical memory dump starting at 'addr' of size 'size'",
 900         .user_print = monitor_user_noop,
 901         .mhandler.cmd_new = do_physical_memory_save,
 902     },
 903
 904 STEXI
 905 @item pmemsave @var{addr} @var{size} @var{file}
 906 @findex pmemsave
 907 save to disk physical memory dump starting at @var{addr} of size @var{size}.
 908 ETEXI
 909 SQMP
 910 pmemsave
 911 --------
 912
 913 Save to disk physical memory dump starting at 'val' of size 'size'.
 914
 915 Arguments:
 916
 917 - "val": the starting address (json-int)
 918 - "size": the memory size, in bytes (json-int)
 919 - "filename": file path (json-string)
 920
 921 Example:
 922
 923 -> { "execute": "pmemsave",
 924              "arguments": { "val": 10,
 925                             "size": 100,
 926                             "filename": "/tmp/physical-mem-dump" } }
 927 <- { "return": {} }
 928
 929 EQMP
 930
 931     {
 932         .name       = "boot_set",
 933         .args_type  = "bootdevice:s",
 934         .params     = "bootdevice",
 935         .help       = "define new values for the boot device list",
 936         .mhandler.cmd = do_boot_set,
 937     },
 938
 939 STEXI
 940 @item boot_set @var{bootdevicelist}
 941 @findex boot_set
 942
 943 Define new values for the boot device list. Those values will override
 944 the values specified on the command line through the @code{-boot} option.
 945
 946 The values that can be specified here depend on the machine type, but are
 947 the same that can be specified in the @code{-boot} command line option.
 948 ETEXI
 949
 950 #if defined(TARGET_I386)
 951     {
 952         .name       = "nmi",
 953         .args_type  = "cpu_index:i",
 954         .params     = "cpu",
 955         .help       = "inject an NMI on the given CPU",
 956         .mhandler.cmd = do_inject_nmi,
 957     },
 958 #endif
 959 STEXI
 960 @item nmi @var{cpu}
 961 @findex nmi
 962 Inject an NMI on the given CPU (x86 only).
 963 ETEXI
 964
 965     {
 966         .name       = "migrate",
 967         .args_type  = "detach:-d,blk:-b,inc:-i,uri:s",
 968         .params     = "[-d] [-b] [-i] uri",
 969         .help       = "migrate to URI (using -d to not wait for completion)"
 970                       "\n\t\t\t -b for migration without shared storage with"
 971                       " full copy of disk\n\t\t\t -i for migration without "
 972                       "shared storage with incremental copy of disk "
 973                       "(base image shared between src and destination)",
 974         .user_print = monitor_user_noop,
 975         .mhandler.cmd_new = do_migrate,
 976     },
 977
 978
 979 STEXI
 980 @item migrate [-d] [-b] [-i] @var{uri}
 981 @findex migrate
 982 Migrate to @var{uri} (using -d to not wait for completion).
 983         -b for migration with full copy of disk
 984         -i for migration with incremental copy of disk (base image is shared)
 985 ETEXI
 986 SQMP
 987 migrate
 988 -------
 989
 990 Migrate to URI.
 991
 992 Arguments:
 993
 994 - "blk": block migration, full disk copy (json-bool, optional)
 995 - "inc": incremental disk copy (json-bool, optional)
 996 - "uri": Destination URI (json-string)
 997
 998 Example:
 999
1000 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
1001 <- { "return": {} }
1002
1003 Notes:
1004
1005 (1) The 'query-migrate' command should be used to check migration's progress
1006     and final result (this information is provided by the 'status' member)
1007 (2) All boolean arguments default to false
1008 (3) The user Monitor's "detach" argument is invalid in QMP and should not
1009     be used
1010
1011 EQMP
1012
1013     {
1014         .name       = "migrate_cancel",
1015         .args_type  = "",
1016         .params     = "",
1017         .help       = "cancel the current VM migration",
1018         .user_print = monitor_user_noop,
1019         .mhandler.cmd_new = do_migrate_cancel,
1020     },
1021
1022 STEXI
1023 @item migrate_cancel
1024 @findex migrate_cancel
1025 Cancel the current VM migration.
1026 ETEXI
1027 SQMP
1028 migrate_cancel
1029 --------------
1030
1031 Cancel the current migration.
1032
1033 Arguments: None.
1034
1035 Example:
1036
1037 -> { "execute": "migrate_cancel" }
1038 <- { "return": {} }
1039
1040 EQMP
1041
1042     {
1043         .name       = "migrate_set_speed",
1044         .args_type  = "value:f",
1045         .params     = "value",
1046         .help       = "set maximum speed (in bytes) for migrations",
1047         .user_print = monitor_user_noop,
1048         .mhandler.cmd_new = do_migrate_set_speed,
1049     },
1050
1051 STEXI
1052 @item migrate_set_speed @var{value}
1053 @findex migrate_set_speed
1054 Set maximum speed to @var{value} (in bytes) for migrations.
1055 ETEXI
1056 SQMP
1057 migrate_set_speed
1058 -----------------
1059
1060 Set maximum speed for migrations.
1061
1062 Arguments:
1063
1064 - "value": maximum speed, in bytes per second (json-number)
1065
1066 Example:
1067
1068 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
1069 <- { "return": {} }
1070
1071 EQMP
1072
1073     {
1074         .name       = "migrate_set_downtime",
1075         .args_type  = "value:T",
1076         .params     = "value",
1077         .help       = "set maximum tolerated downtime (in seconds) for migrations",
1078         .user_print = monitor_user_noop,
1079         .mhandler.cmd_new = do_migrate_set_downtime,
1080     },
1081
1082 STEXI
1083 @item migrate_set_downtime @var{second}
1084 @findex migrate_set_downtime
1085 Set maximum tolerated downtime (in seconds) for migration.
1086 ETEXI
1087 SQMP
1088 migrate_set_downtime
1089 --------------------
1090
1091 Set maximum tolerated downtime (in seconds) for migrations.
1092
1093 Arguments:
1094
1095 - "value": maximum downtime (json-number)
1096
1097 Example:
1098
1099 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
1100 <- { "return": {} }
1101
1102 EQMP
1103
1104 #if defined(TARGET_I386)
1105     {
1106         .name       = "drive_add",
1107         .args_type  = "pci_addr:s,opts:s",
1108         .params     = "[[<domain>:]<bus>:]<slot>\n"
1109                       "[file=file][,if=type][,bus=n]\n"
1110                       "[,unit=m][,media=d][index=i]\n"
1111                       "[,cyls=c,heads=h,secs=s[,trans=t]]\n"
1112                       "[snapshot=on|off][,cache=on|off]",
1113         .help       = "add drive to PCI storage controller",
1114         .mhandler.cmd = drive_hot_add,
1115     },
1116 #endif
1117
1118 STEXI
1119 @item drive_add
1120 @findex drive_add
1121 Add drive to PCI storage controller.
1122 ETEXI
1123
1124 #if defined(TARGET_I386)
1125     {
1126         .name       = "pci_add",
1127         .args_type  = "pci_addr:s,type:s,opts:s?",
1128         .params     = "auto|[[<domain>:]<bus>:]<slot> nic|storage [[vlan=n][,macaddr=addr][,model=type]] [file=file][,if=type][,bus=nr]...",
1129         .help       = "hot-add PCI device",
1130         .mhandler.cmd = pci_device_hot_add,
1131     },
1132 #endif
1133
1134 STEXI
1135 @item pci_add
1136 @findex pci_add
1137 Hot-add PCI device.
1138 ETEXI
1139
1140 #if defined(TARGET_I386)
1141     {
1142         .name       = "pci_del",
1143         .args_type  = "pci_addr:s",
1144         .params     = "[[<domain>:]<bus>:]<slot>",
1145         .help       = "hot remove PCI device",
1146         .mhandler.cmd = do_pci_device_hot_remove,
1147     },
1148 #endif
1149
1150 STEXI
1151 @item pci_del
1152 @findex pci_del
1153 Hot remove PCI device.
1154 ETEXI
1155
1156     {
1157         .name       = "host_net_add",
1158         .args_type  = "device:s,opts:s?",
1159         .params     = "tap|user|socket|vde|dump [options]",
1160         .help       = "add host VLAN client",
1161         .mhandler.cmd = net_host_device_add,
1162     },
1163
1164 STEXI
1165 @item host_net_add
1166 @findex host_net_add
1167 Add host VLAN client.
1168 ETEXI
1169
1170     {
1171         .name       = "host_net_remove",
1172         .args_type  = "vlan_id:i,device:s",
1173         .params     = "vlan_id name",
1174         .help       = "remove host VLAN client",
1175         .mhandler.cmd = net_host_device_remove,
1176     },
1177
1178 STEXI
1179 @item host_net_remove
1180 @findex host_net_remove
1181 Remove host VLAN client.
1182 ETEXI
1183
1184     {
1185         .name       = "netdev_add",
1186         .args_type  = "netdev:O",
1187         .params     = "[user|tap|socket],id=str[,prop=value][,...]",
1188         .help       = "add host network device",
1189         .user_print = monitor_user_noop,
1190         .mhandler.cmd_new = do_netdev_add,
1191     },
1192
1193 STEXI
1194 @item netdev_add
1195 @findex netdev_add
1196 Add host network device.
1197 ETEXI
1198 SQMP
1199 netdev_add
1200 ----------
1201
1202 Add host network device.
1203
1204 Arguments:
1205
1206 - "type": the device type, "tap", "user", ... (json-string)
1207 - "id": the device's ID, must be unique (json-string)
1208 - device options
1209
1210 Example:
1211
1212 -> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
1213 <- { "return": {} }
1214
1215 Note: The supported device options are the same ones supported by the '-net'
1216       command-line argument, which are listed in the '-help' output or QEMU's
1217       manual
1218
1219 EQMP
1220
1221     {
1222         .name       = "netdev_del",
1223         .args_type  = "id:s",
1224         .params     = "id",
1225         .help       = "remove host network device",
1226         .user_print = monitor_user_noop,
1227         .mhandler.cmd_new = do_netdev_del,
1228     },
1229
1230 STEXI
1231 @item netdev_del
1232 @findex netdev_del
1233 Remove host network device.
1234 ETEXI
1235 SQMP
1236 netdev_del
1237 ----------
1238
1239 Remove host network device.
1240
1241 Arguments:
1242
1243 - "id": the device's ID, must be unique (json-string)
1244
1245 Example:
1246
1247 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
1248 <- { "return": {} }
1249
1250 EQMP
1251
1252 #ifdef CONFIG_SLIRP
1253     {
1254         .name       = "hostfwd_add",
1255         .args_type  = "arg1:s,arg2:s?,arg3:s?",
1256         .params     = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport",
1257         .help       = "redirect TCP or UDP connections from host to guest (requires -net user)",
1258         .mhandler.cmd = net_slirp_hostfwd_add,
1259     },
1260 #endif
1261 STEXI
1262 @item hostfwd_add
1263 @findex hostfwd_add
1264 Redirect TCP or UDP connections from host to guest (requires -net user).
1265 ETEXI
1266
1267 #ifdef CONFIG_SLIRP
1268     {
1269         .name       = "hostfwd_remove",
1270         .args_type  = "arg1:s,arg2:s?,arg3:s?",
1271         .params     = "[vlan_id name] [tcp|udp]:[hostaddr]:hostport",
1272         .help       = "remove host-to-guest TCP or UDP redirection",
1273         .mhandler.cmd = net_slirp_hostfwd_remove,
1274     },
1275
1276 #endif
1277 STEXI
1278 @item hostfwd_remove
1279 @findex hostfwd_remove
1280 Remove host-to-guest TCP or UDP redirection.
1281 ETEXI
1282
1283     {
1284         .name       = "balloon",
1285         .args_type  = "value:M",
1286         .params     = "target",
1287         .help       = "request VM to change its memory allocation (in MB)",
1288         .user_print = monitor_user_noop,
1289         .mhandler.cmd_async = do_balloon,
1290         .flags      = MONITOR_CMD_ASYNC,
1291     },
1292
1293 STEXI
1294 @item balloon @var{value}
1295 @findex balloon
1296 Request VM to change its memory allocation to @var{value} (in MB).
1297 ETEXI
1298 SQMP
1299 balloon
1300 -------
1301
1302 Request VM to change its memory allocation (in bytes).
1303
1304 Arguments:
1305
1306 - "value": New memory allocation (json-int)
1307
1308 Example:
1309
1310 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1311 <- { "return": {} }
1312
1313 EQMP
1314
1315     {
1316         .name       = "set_link",
1317         .args_type  = "name:s,up:b",
1318         .params     = "name on|off",
1319         .help       = "change the link status of a network adapter",
1320         .user_print = monitor_user_noop,
1321         .mhandler.cmd_new = do_set_link,
1322     },
1323
1324 STEXI
1325 @item set_link @var{name} [on|off]
1326 @findex set_link
1327 Switch link @var{name} on (i.e. up) or off (i.e. down).
1328 ETEXI
1329 SQMP
1330 set_link
1331 --------
1332
1333 Change the link status of a network adapter.
1334
1335 Arguments:
1336
1337 - "name": network device name (json-string)
1338 - "up": status is up (json-bool)
1339
1340 Example:
1341
1342 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1343 <- { "return": {} }
1344
1345 EQMP
1346
1347     {
1348         .name       = "watchdog_action",
1349         .args_type  = "action:s",
1350         .params     = "[reset|shutdown|poweroff|pause|debug|none]",
1351         .help       = "change watchdog action",
1352         .mhandler.cmd = do_watchdog_action,
1353     },
1354
1355 STEXI
1356 @item watchdog_action
1357 @findex watchdog_action
1358 Change watchdog action.
1359 ETEXI
1360
1361     {
1362         .name       = "acl_show",
1363         .args_type  = "aclname:s",
1364         .params     = "aclname",
1365         .help       = "list rules in the access control list",
1366         .mhandler.cmd = do_acl_show,
1367     },
1368
1369 STEXI
1370 @item acl_show @var{aclname}
1371 @findex acl_show
1372 List all the matching rules in the access control list, and the default
1373 policy. There are currently two named access control lists,
1374 @var{vnc.x509dname} and @var{vnc.username} matching on the x509 client
1375 certificate distinguished name, and SASL username respectively.
1376 ETEXI
1377
1378     {
1379         .name       = "acl_policy",
1380         .args_type  = "aclname:s,policy:s",
1381         .params     = "aclname allow|deny",
1382         .help       = "set default access control list policy",
1383         .mhandler.cmd = do_acl_policy,
1384     },
1385
1386 STEXI
1387 @item acl_policy @var{aclname} @code{allow|deny}
1388 @findex acl_policy
1389 Set the default access control list policy, used in the event that
1390 none of the explicit rules match. The default policy at startup is
1391 always @code{deny}.
1392 ETEXI
1393
1394     {
1395         .name       = "acl_add",
1396         .args_type  = "aclname:s,match:s,policy:s,index:i?",
1397         .params     = "aclname match allow|deny [index]",
1398         .help       = "add a match rule to the access control list",
1399         .mhandler.cmd = do_acl_add,
1400     },
1401
1402 STEXI
1403 @item acl_add @var{aclname} @var{match} @code{allow|deny} [@var{index}]
1404 @findex acl_add
1405 Add a match rule to the access control list, allowing or denying access.
1406 The match will normally be an exact username or x509 distinguished name,
1407 but can optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to
1408 allow all users in the @code{EXAMPLE.COM} kerberos realm. The match will
1409 normally be appended to the end of the ACL, but can be inserted
1410 earlier in the list if the optional @var{index} parameter is supplied.
1411 ETEXI
1412
1413     {
1414         .name       = "acl_remove",
1415         .args_type  = "aclname:s,match:s",
1416         .params     = "aclname match",
1417         .help       = "remove a match rule from the access control list",
1418         .mhandler.cmd = do_acl_remove,
1419     },
1420
1421 STEXI
1422 @item acl_remove @var{aclname} @var{match}
1423 @findex acl_remove
1424 Remove the specified match rule from the access control list.
1425 ETEXI
1426
1427     {
1428         .name       = "acl_reset",
1429         .args_type  = "aclname:s",
1430         .params     = "aclname",
1431         .help       = "reset the access control list",
1432         .mhandler.cmd = do_acl_reset,
1433     },
1434
1435 STEXI
1436 @item acl_reset @var{aclname}
1437 @findex acl_reset
1438 Remove all matches from the access control list, and set the default
1439 policy back to @code{deny}.
1440 ETEXI
1441
1442 #if defined(TARGET_I386)
1443
1444     {
1445         .name       = "mce",
1446         .args_type  = "cpu_index:i,bank:i,status:l,mcg_status:l,addr:l,misc:l",
1447         .params     = "cpu bank status mcgstatus addr misc",
1448         .help       = "inject a MCE on the given CPU",
1449         .mhandler.cmd = do_inject_mce,
1450     },
1451
1452 #endif
1453 STEXI
1454 @item mce @var{cpu} @var{bank} @var{status} @var{mcgstatus} @var{addr} @var{misc}
1455 @findex mce (x86)
1456 Inject an MCE on the given CPU (x86 only).
1457 ETEXI
1458
1459     {
1460         .name       = "getfd",
1461         .args_type  = "fdname:s",
1462         .params     = "getfd name",
1463         .help       = "receive a file descriptor via SCM rights and assign it a name",
1464         .user_print = monitor_user_noop,
1465         .mhandler.cmd_new = do_getfd,
1466     },
1467
1468 STEXI
1469 @item getfd @var{fdname}
1470 @findex getfd
1471 If a file descriptor is passed alongside this command using the SCM_RIGHTS
1472 mechanism on unix sockets, it is stored using the name @var{fdname} for
1473 later use by other monitor commands.
1474 ETEXI
1475 SQMP
1476 getfd
1477 -----
1478
1479 Receive a file descriptor via SCM rights and assign it a name.
1480
1481 Arguments:
1482
1483 - "fdname": file descriptor name (json-string)
1484
1485 Example:
1486
1487 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1488 <- { "return": {} }
1489
1490 EQMP
1491
1492     {
1493         .name       = "closefd",
1494         .args_type  = "fdname:s",
1495         .params     = "closefd name",
1496         .help       = "close a file descriptor previously passed via SCM rights",
1497         .user_print = monitor_user_noop,
1498         .mhandler.cmd_new = do_closefd,
1499     },
1500
1501 STEXI
1502 @item closefd @var{fdname}
1503 @findex closefd
1504 Close the file descriptor previously assigned to @var{fdname} using the
1505 @code{getfd} command. This is only needed if the file descriptor was never
1506 used by another monitor command.
1507 ETEXI
1508 SQMP
1509 closefd
1510 -------
1511
1512 Close a file descriptor previously passed via SCM rights.
1513
1514 Arguments:
1515
1516 - "fdname": file descriptor name (json-string)
1517
1518 Example:
1519
1520 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1521 <- { "return": {} }
1522
1523 EQMP
1524
1525     {
1526         .name       = "block_passwd",
1527         .args_type  = "device:B,password:s",
1528         .params     = "block_passwd device password",
1529         .help       = "set the password of encrypted block devices",
1530         .user_print = monitor_user_noop,
1531         .mhandler.cmd_new = do_block_set_passwd,
1532     },
1533
1534 STEXI
1535 @item block_passwd @var{device} @var{password}
1536 @findex block_passwd
1537 Set the encrypted device @var{device} password to @var{password}
1538 ETEXI
1539 SQMP
1540 block_passwd
1541 ------------
1542
1543 Set the password of encrypted block devices.
1544
1545 Arguments:
1546
1547 - "device": device name (json-string)
1548 - "password": password (json-string)
1549
1550 Example:
1551
1552 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1553                                                "password": "12345" } }
1554 <- { "return": {} }
1555
1556 EQMP
1557
1558     {
1559         .name       = "qmp_capabilities",
1560         .args_type  = "",
1561         .params     = "",
1562         .help       = "enable QMP capabilities",
1563         .user_print = monitor_user_noop,
1564         .mhandler.cmd_new = do_qmp_capabilities,
1565     },
1566
1567 STEXI
1568 @item qmp_capabilities
1569 @findex qmp_capabilities
1570 Enable the specified QMP capabilities
1571 ETEXI
1572 SQMP
1573 qmp_capabilities
1574 ----------------
1575
1576 Enable QMP capabilities.
1577
1578 Arguments: None.
1579
1580 Example:
1581
1582 -> { "execute": "qmp_capabilities" }
1583 <- { "return": {} }
1584
1585 Note: This command must be issued before issuing any other command.
1586
1587 EQMP
1588
1589
1590 HXCOMM Keep the 'info' command at the end!
1591 HXCOMM This is required for the QMP documentation layout.
1592
1593 SQMP
1594
1595 2. Query Commands
1596 =================
1597
1598 EQMP
1599
1600     {
1601         .name       = "info",
1602         .args_type  = "item:s?",
1603         .params     = "[subcommand]",
1604         .help       = "show various information about the system state",
1605         .user_print = monitor_user_noop,
1606         .mhandler.cmd_new = do_info,
1607     },
1608
1609 STEXI
1610 @item info @var{subcommand}
1611 @findex info
1612 Show various information about the system state.
1613
1614 @table @option
1615 @item info version
1616 show the version of QEMU
1617 ETEXI
1618 SQMP
1619 query-version
1620 -------------
1621
1622 Show QEMU version.
1623
1624 Return a json-object with the following information:
1625
1626 - "qemu": QEMU's version (json-string)
1627 - "package": package's version (json-string)
1628
1629 Example:
1630
1631 -> { "execute": "query-version" }
1632 <- { "return": { "qemu": "0.11.50", "package": "" } }
1633
1634 EQMP
1635
1636 STEXI
1637 @item info commands
1638 list QMP available commands
1639 ETEXI
1640 SQMP
1641 query-commands
1642 --------------
1643
1644 List QMP available commands.
1645
1646 Each command is represented by a json-object, the returned value is a json-array
1647 of all commands.
1648
1649 Each json-object contain:
1650
1651 - "name": command's name (json-string)
1652
1653 Example:
1654
1655 -> { "execute": "query-commands" }
1656 <- {
1657       "return":[
1658          {
1659             "name":"query-balloon"
1660          },
1661          {
1662             "name":"system_powerdown"
1663          }
1664       ]
1665    }
1666
1667 Note: This example has been shortened as the real response is too long.
1668
1669 EQMP
1670
1671 STEXI
1672 @item info network
1673 show the various VLANs and the associated devices
1674 ETEXI
1675
1676 STEXI
1677 @item info chardev
1678 show the character devices
1679 ETEXI
1680 SQMP
1681 query-chardev
1682 -------------
1683
1684 Each device is represented by a json-object. The returned value is a json-array
1685 of all devices.
1686
1687 Each json-object contain the following:
1688
1689 - "label": device's label (json-string)
1690 - "filename": device's file (json-string)
1691
1692 Example:
1693
1694 -> { "execute": "query-chardev" }
1695 <- {
1696       "return":[
1697          {
1698             "label":"monitor",
1699             "filename":"stdio"
1700          },
1701          {
1702             "label":"serial0",
1703             "filename":"vc"
1704          }
1705       ]
1706    }
1707
1708 EQMP
1709
1710 STEXI
1711 @item info block
1712 show the block devices
1713 ETEXI
1714 SQMP
1715 query-block
1716 -----------
1717
1718 Show the block devices.
1719
1720 Each block device information is stored in a json-object and the returned value
1721 is a json-array of all devices.
1722
1723 Each json-object contain the following:
1724
1725 - "device": device name (json-string)
1726 - "type": device type (json-string)
1727          - Possible values: "hd", "cdrom", "floppy", "unknown"
1728 - "removable": true if the device is removable, false otherwise (json-bool)
1729 - "locked": true if the device is locked, false otherwise (json-bool)
1730 - "inserted": only present if the device is inserted, it is a json-object
1731    containing the following:
1732          - "file": device file name (json-string)
1733          - "ro": true if read-only, false otherwise (json-bool)
1734          - "drv": driver format name (json-string)
1735              - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1736                                 "file", "file", "ftp", "ftps", "host_cdrom",
1737                                 "host_device", "host_floppy", "http", "https",
1738                                 "nbd", "parallels", "qcow", "qcow2", "raw",
1739                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1740          - "backing_file": backing file name (json-string, optional)
1741          - "encrypted": true if encrypted, false otherwise (json-bool)
1742
1743 Example:
1744
1745 -> { "execute": "query-block" }
1746 <- {
1747       "return":[
1748          {
1749             "device":"ide0-hd0",
1750             "locked":false,
1751             "removable":false,
1752             "inserted":{
1753                "ro":false,
1754                "drv":"qcow2",
1755                "encrypted":false,
1756                "file":"disks/test.img"
1757             },
1758             "type":"hd"
1759          },
1760          {
1761             "device":"ide1-cd0",
1762             "locked":false,
1763             "removable":true,
1764             "type":"cdrom"
1765          },
1766          {
1767             "device":"floppy0",
1768             "locked":false,
1769             "removable":true,
1770             "type": "floppy"
1771          },
1772          {
1773             "device":"sd0",
1774             "locked":false,
1775             "removable":true,
1776             "type":"floppy"
1777          }
1778       ]
1779    }
1780
1781 EQMP
1782
1783 STEXI
1784 @item info blockstats
1785 show block device statistics
1786 ETEXI
1787 SQMP
1788 query-blockstats
1789 ----------------
1790
1791 Show block device statistics.
1792
1793 Each device statistic information is stored in a json-object and the returned
1794 value is a json-array of all devices.
1795
1796 Each json-object contain the following:
1797
1798 - "device": device name (json-string)
1799 - "stats": A json-object with the statistics information, it contains:
1800     - "rd_bytes": bytes read (json-int)
1801     - "wr_bytes": bytes written (json-int)
1802     - "rd_operations": read operations (json-int)
1803     - "wr_operations": write operations (json-int)
1804     - "wr_highest_offset": Highest offset of a sector written since the
1805                            BlockDriverState has been opened (json-int)
1806 - "parent": Contains recursively the statistics of the underlying
1807             protocol (e.g. the host file for a qcow2 image). If there is
1808             no underlying protocol, this field is omitted
1809             (json-object, optional)
1810
1811 Example:
1812
1813 -> { "execute": "query-blockstats" }
1814 <- {
1815       "return":[
1816          {
1817             "device":"ide0-hd0",
1818             "parent":{
1819                "stats":{
1820                   "wr_highest_offset":3686448128,
1821                   "wr_bytes":9786368,
1822                   "wr_operations":751,
1823                   "rd_bytes":122567168,
1824                   "rd_operations":36772
1825                }
1826             },
1827             "stats":{
1828                "wr_highest_offset":2821110784,
1829                "wr_bytes":9786368,
1830                "wr_operations":692,
1831                "rd_bytes":122739200,
1832                "rd_operations":36604
1833             }
1834          },
1835          {
1836             "device":"ide1-cd0",
1837             "stats":{
1838                "wr_highest_offset":0,
1839                "wr_bytes":0,
1840                "wr_operations":0,
1841                "rd_bytes":0,
1842                "rd_operations":0
1843             }
1844          },
1845          {
1846             "device":"floppy0",
1847             "stats":{
1848                "wr_highest_offset":0,
1849                "wr_bytes":0,
1850                "wr_operations":0,
1851                "rd_bytes":0,
1852                "rd_operations":0
1853             }
1854          },
1855          {
1856             "device":"sd0",
1857             "stats":{
1858                "wr_highest_offset":0,
1859                "wr_bytes":0,
1860                "wr_operations":0,
1861                "rd_bytes":0,
1862                "rd_operations":0
1863             }
1864          }
1865       ]
1866    }
1867
1868 EQMP
1869
1870 STEXI
1871 @item info registers
1872 show the cpu registers
1873 @item info cpus
1874 show infos for each CPU
1875 ETEXI
1876 SQMP
1877 query-cpus
1878 ----------
1879
1880 Show CPU information.
1881
1882 Return a json-array. Each CPU is represented by a json-object, which contains:
1883
1884 - "CPU": CPU index (json-int)
1885 - "current": true if this is the current CPU, false otherwise (json-bool)
1886 - "halted": true if the cpu is halted, false otherwise (json-bool)
1887 - Current program counter. The key's name depends on the architecture:
1888      "pc": i386/x86_64 (json-int)
1889      "nip": PPC (json-int)
1890      "pc" and "npc": sparc (json-int)
1891      "PC": mips (json-int)
1892
1893 Example:
1894
1895 -> { "execute": "query-cpus" }
1896 <- {
1897       "return":[
1898          {
1899             "CPU":0,
1900             "current":true,
1901             "halted":false,
1902             "pc":3227107138
1903          },
1904          {
1905             "CPU":1,
1906             "current":false,
1907             "halted":true,
1908             "pc":7108165
1909          }
1910       ]
1911    }
1912
1913 EQMP
1914
1915 STEXI
1916 @item info history
1917 show the command line history
1918 @item info irq
1919 show the interrupts statistics (if available)
1920 @item info pic
1921 show i8259 (PIC) state
1922 ETEXI
1923
1924 STEXI
1925 @item info pci
1926 show emulated PCI device info
1927 ETEXI
1928 SQMP
1929 query-pci
1930 ---------
1931
1932 PCI buses and devices information.
1933
1934 The returned value is a json-array of all buses. Each bus is represented by
1935 a json-object, which has a key with a json-array of all PCI devices attached
1936 to it. Each device is represented by a json-object.
1937
1938 The bus json-object contains the following:
1939
1940 - "bus": bus number (json-int)
1941 - "devices": a json-array of json-objects, each json-object represents a
1942              PCI device
1943
1944 The PCI device json-object contains the following:
1945
1946 - "bus": identical to the parent's bus number (json-int)
1947 - "slot": slot number (json-int)
1948 - "function": function number (json-int)
1949 - "class_info": a json-object containing:
1950      - "desc": device class description (json-string, optional)
1951      - "class": device class number (json-int)
1952 - "id": a json-object containing:
1953      - "device": device ID (json-int)
1954      - "vendor": vendor ID (json-int)
1955 - "irq": device's IRQ if assigned (json-int, optional)
1956 - "qdev_id": qdev id string (json-string)
1957 - "pci_bridge": It's a json-object, only present if this device is a
1958                 PCI bridge, contains:
1959      - "bus": bus number (json-int)
1960      - "secondary": secondary bus number (json-int)
1961      - "subordinate": subordinate bus number (json-int)
1962      - "io_range": I/O memory range information, a json-object with the
1963                    following members:
1964                  - "base": base address, in bytes (json-int)
1965                  - "limit": limit address, in bytes (json-int)
1966      - "memory_range": memory range information, a json-object with the
1967                        following members:
1968                  - "base": base address, in bytes (json-int)
1969                  - "limit": limit address, in bytes (json-int)
1970      - "prefetchable_range": Prefetchable memory range information, a
1971                              json-object with the following members:
1972                  - "base": base address, in bytes (json-int)
1973                  - "limit": limit address, in bytes (json-int)
1974      - "devices": a json-array of PCI devices if there's any attached, each
1975                   each element is represented by a json-object, which contains
1976                   the same members of the 'PCI device json-object' described
1977                   above (optional)
1978 - "regions": a json-array of json-objects, each json-object represents a
1979              memory region of this device
1980
1981 The memory range json-object contains the following:
1982
1983 - "base": base memory address (json-int)
1984 - "limit": limit value (json-int)
1985
1986 The region json-object can be an I/O region or a memory region, an I/O region
1987 json-object contains the following:
1988
1989 - "type": "io" (json-string, fixed)
1990 - "bar": BAR number (json-int)
1991 - "address": memory address (json-int)
1992 - "size": memory size (json-int)
1993
1994 A memory region json-object contains the following:
1995
1996 - "type": "memory" (json-string, fixed)
1997 - "bar": BAR number (json-int)
1998 - "address": memory address (json-int)
1999 - "size": memory size (json-int)
2000 - "mem_type_64": true or false (json-bool)
2001 - "prefetch": true or false (json-bool)
2002
2003 Example:
2004
2005 -> { "execute": "query-pci" }
2006 <- {
2007       "return":[
2008          {
2009             "bus":0,
2010             "devices":[
2011                {
2012                   "bus":0,
2013                   "qdev_id":"",
2014                   "slot":0,
2015                   "class_info":{
2016                      "class":1536,
2017                      "desc":"Host bridge"
2018                   },
2019                   "id":{
2020                      "device":32902,
2021                      "vendor":4663
2022                   },
2023                   "function":0,
2024                   "regions":[
2025
2026                   ]
2027                },
2028                {
2029                   "bus":0,
2030                   "qdev_id":"",
2031                   "slot":1,
2032                   "class_info":{
2033                      "class":1537,
2034                      "desc":"ISA bridge"
2035                   },
2036                   "id":{
2037                      "device":32902,
2038                      "vendor":28672
2039                   },
2040                   "function":0,
2041                   "regions":[
2042
2043                   ]
2044                },
2045                {
2046                   "bus":0,
2047                   "qdev_id":"",
2048                   "slot":1,
2049                   "class_info":{
2050                      "class":257,
2051                      "desc":"IDE controller"
2052                   },
2053                   "id":{
2054                      "device":32902,
2055                      "vendor":28688
2056                   },
2057                   "function":1,
2058                   "regions":[
2059                      {
2060                         "bar":4,
2061                         "size":16,
2062                         "address":49152,
2063                         "type":"io"
2064                      }
2065                   ]
2066                },
2067                {
2068                   "bus":0,
2069                   "qdev_id":"",
2070                   "slot":2,
2071                   "class_info":{
2072                      "class":768,
2073                      "desc":"VGA controller"
2074                   },
2075                   "id":{
2076                      "device":4115,
2077                      "vendor":184
2078                   },
2079                   "function":0,
2080                   "regions":[
2081                      {
2082                         "prefetch":true,
2083                         "mem_type_64":false,
2084                         "bar":0,
2085                         "size":33554432,
2086                         "address":4026531840,
2087                         "type":"memory"
2088                      },
2089                      {
2090                         "prefetch":false,
2091                         "mem_type_64":false,
2092                         "bar":1,
2093                         "size":4096,
2094                         "address":4060086272,
2095                         "type":"memory"
2096                      },
2097                      {
2098                         "prefetch":false,
2099                         "mem_type_64":false,
2100                         "bar":6,
2101                         "size":65536,
2102                         "address":-1,
2103                         "type":"memory"
2104                      }
2105                   ]
2106                },
2107                {
2108                   "bus":0,
2109                   "qdev_id":"",
2110                   "irq":11,
2111                   "slot":4,
2112                   "class_info":{
2113                      "class":1280,
2114                      "desc":"RAM controller"
2115                   },
2116                   "id":{
2117                      "device":6900,
2118                      "vendor":4098
2119                   },
2120                   "function":0,
2121                   "regions":[
2122                      {
2123                         "bar":0,
2124                         "size":32,
2125                         "address":49280,
2126                         "type":"io"
2127                      }
2128                   ]
2129                }
2130             ]
2131          }
2132       ]
2133    }
2134
2135 Note: This example has been shortened as the real response is too long.
2136
2137 EQMP
2138
2139 STEXI
2140 @item info tlb
2141 show virtual to physical memory mappings (i386 only)
2142 @item info mem
2143 show the active virtual memory mappings (i386 only)
2144 ETEXI
2145
2146 STEXI
2147 @item info jit
2148 show dynamic compiler info
2149 @item info kvm
2150 show KVM information
2151 @item info numa
2152 show NUMA information
2153 ETEXI
2154
2155 STEXI
2156 @item info kvm
2157 show KVM information
2158 ETEXI
2159 SQMP
2160 query-kvm
2161 ---------
2162
2163 Show KVM information.
2164
2165 Return a json-object with the following information:
2166
2167 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
2168 - "present": true if QEMU has KVM support, false otherwise (json-bool)
2169
2170 Example:
2171
2172 -> { "execute": "query-kvm" }
2173 <- { "return": { "enabled": true, "present": true } }
2174
2175 EQMP
2176
2177 STEXI
2178 @item info usb
2179 show USB devices plugged on the virtual USB hub
2180 @item info usbhost
2181 show all USB host devices
2182 @item info profile
2183 show profiling information
2184 @item info capture
2185 show information about active capturing
2186 @item info snapshots
2187 show list of VM snapshots
2188 ETEXI
2189
2190 STEXI
2191 @item info status
2192 show the current VM status (running|paused)
2193 ETEXI
2194 SQMP
2195 query-status
2196 ------------
2197
2198 Return a json-object with the following information:
2199
2200 - "running": true if the VM is running, or false if it is paused (json-bool)
2201 - "singlestep": true if the VM is in single step mode,
2202                 false otherwise (json-bool)
2203
2204 Example:
2205
2206 -> { "execute": "query-status" }
2207 <- { "return": { "running": true, "singlestep": false } }
2208
2209 EQMP
2210
2211 STEXI
2212 @item info pcmcia
2213 show guest PCMCIA status
2214 ETEXI
2215
2216 STEXI
2217 @item info mice
2218 show which guest mouse is receiving events
2219 ETEXI
2220 SQMP
2221 query-mice
2222 ----------
2223
2224 Show VM mice information.
2225
2226 Each mouse is represented by a json-object, the returned value is a json-array
2227 of all mice.
2228
2229 The mouse json-object contains the following:
2230
2231 - "name": mouse's name (json-string)
2232 - "index": mouse's index (json-int)
2233 - "current": true if this mouse is receiving events, false otherwise (json-bool)
2234 - "absolute": true if the mouse generates absolute input events (json-bool)
2235
2236 Example:
2237
2238 -> { "execute": "query-mice" }
2239 <- {
2240       "return":[
2241          {
2242             "name":"QEMU Microsoft Mouse",
2243             "index":0,
2244             "current":false,
2245             "absolute":false
2246          },
2247          {
2248             "name":"QEMU PS/2 Mouse",
2249             "index":1,
2250             "current":true,
2251             "absolute":true
2252          }
2253       ]
2254    }
2255
2256 EQMP
2257
2258 STEXI
2259 @item info vnc
2260 show the vnc server status
2261 ETEXI
2262 SQMP
2263 query-vnc
2264 ---------
2265
2266 Show VNC server information.
2267
2268 Return a json-object with server information. Connected clients are returned
2269 as a json-array of json-objects.
2270
2271 The main json-object contains the following:
2272
2273 - "enabled": true or false (json-bool)
2274 - "host": server's IP address (json-string)
2275 - "family": address family (json-string)
2276          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2277 - "service": server's port number (json-string)
2278 - "auth": authentication method (json-string)
2279          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2280                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2281                             "vencrypt+plain", "vencrypt+tls+none",
2282                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
2283                             "vencrypt+tls+vnc", "vencrypt+x509+none",
2284                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
2285                             "vencrypt+x509+vnc", "vnc"
2286 - "clients": a json-array of all connected clients
2287
2288 Clients are described by a json-object, each one contain the following:
2289
2290 - "host": client's IP address (json-string)
2291 - "family": address family (json-string)
2292          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2293 - "service": client's port number (json-string)
2294 - "x509_dname": TLS dname (json-string, optional)
2295 - "sasl_username": SASL username (json-string, optional)
2296
2297 Example:
2298
2299 -> { "execute": "query-vnc" }
2300 <- {
2301       "return":{
2302          "enabled":true,
2303          "host":"0.0.0.0",
2304          "service":"50402",
2305          "auth":"vnc",
2306          "family":"ipv4",
2307          "clients":[
2308             {
2309                "host":"127.0.0.1",
2310                "service":"50401",
2311                "family":"ipv4"
2312             }
2313          ]
2314       }
2315    }
2316
2317 EQMP
2318
2319 STEXI
2320 @item info name
2321 show the current VM name
2322 ETEXI
2323 SQMP
2324 query-name
2325 ----------
2326
2327 Show VM name.
2328
2329 Return a json-object with the following information:
2330
2331 - "name": VM's name (json-string, optional)
2332
2333 Example:
2334
2335 -> { "execute": "query-name" }
2336 <- { "return": { "name": "qemu-name" } }
2337
2338 EQMP
2339
2340 STEXI
2341 @item info uuid
2342 show the current VM UUID
2343 ETEXI
2344 SQMP
2345 query-uuid
2346 ----------
2347
2348 Show VM UUID.
2349
2350 Return a json-object with the following information:
2351
2352 - "UUID": Universally Unique Identifier (json-string)
2353
2354 Example:
2355
2356 -> { "execute": "query-uuid" }
2357 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2358
2359 EQMP
2360
2361 STEXI
2362 @item info cpustats
2363 show CPU statistics
2364 @item info usernet
2365 show user network stack connection states
2366 ETEXI
2367
2368 STEXI
2369 @item info migrate
2370 show migration status
2371 ETEXI
2372 SQMP
2373 query-migrate
2374 -------------
2375
2376 Migration status.
2377
2378 Return a json-object. If migration is active there will be another json-object
2379 with RAM migration status and if block migration is active another one with
2380 block migration status.
2381
2382 The main json-object contains the following:
2383
2384 - "status": migration status (json-string)
2385      - Possible values: "active", "completed", "failed", "cancelled"
2386 - "ram": only present if "status" is "active", it is a json-object with the
2387   following RAM information (in bytes):
2388          - "transferred": amount transferred (json-int)
2389          - "remaining": amount remaining (json-int)
2390          - "total": total (json-int)
2391 - "disk": only present if "status" is "active" and it is a block migration,
2392   it is a json-object with the following disk information (in bytes):
2393          - "transferred": amount transferred (json-int)
2394          - "remaining": amount remaining (json-int)
2395          - "total": total (json-int)
2396
2397 Examples:
2398
2399 1. Before the first migration
2400
2401 -> { "execute": "query-migrate" }
2402 <- { "return": {} }
2403
2404 2. Migration is done and has succeeded
2405
2406 -> { "execute": "query-migrate" }
2407 <- { "return": { "status": "completed" } }
2408
2409 3. Migration is done and has failed
2410
2411 -> { "execute": "query-migrate" }
2412 <- { "return": { "status": "failed" } }
2413
2414 4. Migration is being performed and is not a block migration:
2415
2416 -> { "execute": "query-migrate" }
2417 <- {
2418       "return":{
2419          "status":"active",
2420          "ram":{
2421             "transferred":123,
2422             "remaining":123,
2423             "total":246
2424          }
2425       }
2426    }
2427
2428 5. Migration is being performed and is a block migration:
2429
2430 -> { "execute": "query-migrate" }
2431 <- {
2432       "return":{
2433          "status":"active",
2434          "ram":{
2435             "total":1057024,
2436             "remaining":1053304,
2437             "transferred":3720
2438          },
2439          "disk":{
2440             "total":20971520,
2441             "remaining":20880384,
2442             "transferred":91136
2443          }
2444       }
2445    }
2446
2447 EQMP
2448
2449 STEXI
2450 @item info balloon
2451 show balloon information
2452 ETEXI
2453 SQMP
2454 query-balloon
2455 -------------
2456
2457 Show balloon information.
2458
2459 Make an asynchronous request for balloon info. When the request completes a
2460 json-object will be returned containing the following data:
2461
2462 - "actual": current balloon value in bytes (json-int)
2463 - "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
2464 - "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
2465 - "major_page_faults": Number of major faults (json-int, optional)
2466 - "minor_page_faults": Number of minor faults (json-int, optional)
2467 - "free_mem": Total amount of free and unused memory in
2468               bytes (json-int, optional)
2469 - "total_mem": Total amount of available memory in bytes (json-int, optional)
2470
2471 Example:
2472
2473 -> { "execute": "query-balloon" }
2474 <- {
2475       "return":{
2476          "actual":1073741824,
2477          "mem_swapped_in":0,
2478          "mem_swapped_out":0,
2479          "major_page_faults":142,
2480          "minor_page_faults":239245,
2481          "free_mem":1014185984,
2482          "total_mem":1044668416
2483       }
2484    }
2485
2486 EQMP
2487
2488 STEXI
2489 @item info qtree
2490 show device tree
2491 @item info qdm
2492 show qdev device model list
2493 @item info roms
2494 show roms
2495 @end table
2496 ETEXI
2497
2498 HXCOMM DO NOT add new commands after 'info', move your addition before it!
2499
2500 STEXI
2501 @end table
2502 ETEXI