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|host [[vlan=n][,macaddr=addr][,model=type]] [file=file][,if=type][,bus=nr]... [host=02:00.0[,name=string][,dma=none]",
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         .async      = 1,
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       = "cpu_set",
1560         .args_type  = "cpu:i,state:s",
1561         .params     = "cpu [online|offline]",
1562         .help       = "change cpu state",
1563         .mhandler.cmd  = do_cpu_set_nr,
1564     },
1565
1566 STEXI
1567 @item cpu_set @var{cpu} [online|offline]
1568 Set CPU @var{cpu} online or offline.
1569 ETEXI
1570
1571     {
1572         .name       = "qmp_capabilities",
1573         .args_type  = "",
1574         .params     = "",
1575         .help       = "enable QMP capabilities",
1576         .user_print = monitor_user_noop,
1577         .mhandler.cmd_new = do_qmp_capabilities,
1578     },
1579
1580 STEXI
1581 @item qmp_capabilities
1582 @findex qmp_capabilities
1583 Enable the specified QMP capabilities
1584 ETEXI
1585 SQMP
1586 qmp_capabilities
1587 ----------------
1588
1589 Enable QMP capabilities.
1590
1591 Arguments: None.
1592
1593 Example:
1594
1595 -> { "execute": "qmp_capabilities" }
1596 <- { "return": {} }
1597
1598 Note: This command must be issued before issuing any other command.
1599
1600 EQMP
1601
1602
1603 HXCOMM Keep the 'info' command at the end!
1604 HXCOMM This is required for the QMP documentation layout.
1605
1606 SQMP
1607
1608 2. Query Commands
1609 =================
1610
1611 EQMP
1612
1613     {
1614         .name       = "info",
1615         .args_type  = "item:s?",
1616         .params     = "[subcommand]",
1617         .help       = "show various information about the system state",
1618         .user_print = monitor_user_noop,
1619         .mhandler.cmd_new = do_info,
1620     },
1621
1622 STEXI
1623 @item info @var{subcommand}
1624 @findex info
1625 Show various information about the system state.
1626
1627 @table @option
1628 @item info version
1629 show the version of QEMU
1630 ETEXI
1631 SQMP
1632 query-version
1633 -------------
1634
1635 Show QEMU version.
1636
1637 Return a json-object with the following information:
1638
1639 - "qemu": QEMU's version (json-string)
1640 - "package": package's version (json-string)
1641
1642 Example:
1643
1644 -> { "execute": "query-version" }
1645 <- { "return": { "qemu": "0.11.50", "package": "" } }
1646
1647 EQMP
1648
1649 STEXI
1650 @item info commands
1651 list QMP available commands
1652 ETEXI
1653 SQMP
1654 query-commands
1655 --------------
1656
1657 List QMP available commands.
1658
1659 Each command is represented by a json-object, the returned value is a json-array
1660 of all commands.
1661
1662 Each json-object contain:
1663
1664 - "name": command's name (json-string)
1665
1666 Example:
1667
1668 -> { "execute": "query-commands" }
1669 <- {
1670       "return":[
1671          {
1672             "name":"query-balloon"
1673          },
1674          {
1675             "name":"system_powerdown"
1676          }
1677       ]
1678    }
1679
1680 Note: This example has been shortened as the real response is too long.
1681
1682 EQMP
1683
1684 STEXI
1685 @item info network
1686 show the various VLANs and the associated devices
1687 ETEXI
1688
1689 STEXI
1690 @item info chardev
1691 show the character devices
1692 ETEXI
1693 SQMP
1694 query-chardev
1695 -------------
1696
1697 Each device is represented by a json-object. The returned value is a json-array
1698 of all devices.
1699
1700 Each json-object contain the following:
1701
1702 - "label": device's label (json-string)
1703 - "filename": device's file (json-string)
1704
1705 Example:
1706
1707 -> { "execute": "query-chardev" }
1708 <- {
1709       "return":[
1710          {
1711             "label":"monitor",
1712             "filename":"stdio"
1713          },
1714          {
1715             "label":"serial0",
1716             "filename":"vc"
1717          }
1718       ]
1719    }
1720
1721 EQMP
1722
1723 STEXI
1724 @item info block
1725 show the block devices
1726 ETEXI
1727 SQMP
1728 query-block
1729 -----------
1730
1731 Show the block devices.
1732
1733 Each block device information is stored in a json-object and the returned value
1734 is a json-array of all devices.
1735
1736 Each json-object contain the following:
1737
1738 - "device": device name (json-string)
1739 - "type": device type (json-string)
1740          - Possible values: "hd", "cdrom", "floppy", "unknown"
1741 - "removable": true if the device is removable, false otherwise (json-bool)
1742 - "locked": true if the device is locked, false otherwise (json-bool)
1743 - "inserted": only present if the device is inserted, it is a json-object
1744    containing the following:
1745          - "file": device file name (json-string)
1746          - "ro": true if read-only, false otherwise (json-bool)
1747          - "drv": driver format name (json-string)
1748              - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1749                                 "file", "file", "ftp", "ftps", "host_cdrom",
1750                                 "host_device", "host_floppy", "http", "https",
1751                                 "nbd", "parallels", "qcow", "qcow2", "raw",
1752                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1753          - "backing_file": backing file name (json-string, optional)
1754          - "encrypted": true if encrypted, false otherwise (json-bool)
1755
1756 Example:
1757
1758 -> { "execute": "query-block" }
1759 <- {
1760       "return":[
1761          {
1762             "device":"ide0-hd0",
1763             "locked":false,
1764             "removable":false,
1765             "inserted":{
1766                "ro":false,
1767                "drv":"qcow2",
1768                "encrypted":false,
1769                "file":"disks/test.img"
1770             },
1771             "type":"hd"
1772          },
1773          {
1774             "device":"ide1-cd0",
1775             "locked":false,
1776             "removable":true,
1777             "type":"cdrom"
1778          },
1779          {
1780             "device":"floppy0",
1781             "locked":false,
1782             "removable":true,
1783             "type": "floppy"
1784          },
1785          {
1786             "device":"sd0",
1787             "locked":false,
1788             "removable":true,
1789             "type":"floppy"
1790          }
1791       ]
1792    }
1793
1794 EQMP
1795
1796 STEXI
1797 @item info blockstats
1798 show block device statistics
1799 ETEXI
1800 SQMP
1801 query-blockstats
1802 ----------------
1803
1804 Show block device statistics.
1805
1806 Each device statistic information is stored in a json-object and the returned
1807 value is a json-array of all devices.
1808
1809 Each json-object contain the following:
1810
1811 - "device": device name (json-string)
1812 - "stats": A json-object with the statistics information, it contains:
1813     - "rd_bytes": bytes read (json-int)
1814     - "wr_bytes": bytes written (json-int)
1815     - "rd_operations": read operations (json-int)
1816     - "wr_operations": write operations (json-int)
1817     - "wr_highest_offset": Highest offset of a sector written since the
1818                            BlockDriverState has been opened (json-int)
1819 - "parent": Contains recursively the statistics of the underlying
1820             protocol (e.g. the host file for a qcow2 image). If there is
1821             no underlying protocol, this field is omitted
1822             (json-object, optional)
1823
1824 Example:
1825
1826 -> { "execute": "query-blockstats" }
1827 <- {
1828       "return":[
1829          {
1830             "device":"ide0-hd0",
1831             "parent":{
1832                "stats":{
1833                   "wr_highest_offset":3686448128,
1834                   "wr_bytes":9786368,
1835                   "wr_operations":751,
1836                   "rd_bytes":122567168,
1837                   "rd_operations":36772
1838                }
1839             },
1840             "stats":{
1841                "wr_highest_offset":2821110784,
1842                "wr_bytes":9786368,
1843                "wr_operations":692,
1844                "rd_bytes":122739200,
1845                "rd_operations":36604
1846             }
1847          },
1848          {
1849             "device":"ide1-cd0",
1850             "stats":{
1851                "wr_highest_offset":0,
1852                "wr_bytes":0,
1853                "wr_operations":0,
1854                "rd_bytes":0,
1855                "rd_operations":0
1856             }
1857          },
1858          {
1859             "device":"floppy0",
1860             "stats":{
1861                "wr_highest_offset":0,
1862                "wr_bytes":0,
1863                "wr_operations":0,
1864                "rd_bytes":0,
1865                "rd_operations":0
1866             }
1867          },
1868          {
1869             "device":"sd0",
1870             "stats":{
1871                "wr_highest_offset":0,
1872                "wr_bytes":0,
1873                "wr_operations":0,
1874                "rd_bytes":0,
1875                "rd_operations":0
1876             }
1877          }
1878       ]
1879    }
1880
1881 EQMP
1882
1883 STEXI
1884 @item info registers
1885 show the cpu registers
1886 @item info cpus
1887 show infos for each CPU
1888 ETEXI
1889 SQMP
1890 query-cpus
1891 ----------
1892
1893 Show CPU information.
1894
1895 Return a json-array. Each CPU is represented by a json-object, which contains:
1896
1897 - "CPU": CPU index (json-int)
1898 - "current": true if this is the current CPU, false otherwise (json-bool)
1899 - "halted": true if the cpu is halted, false otherwise (json-bool)
1900 - Current program counter. The key's name depends on the architecture:
1901      "pc": i386/x86_64 (json-int)
1902      "nip": PPC (json-int)
1903      "pc" and "npc": sparc (json-int)
1904      "PC": mips (json-int)
1905
1906 Example:
1907
1908 -> { "execute": "query-cpus" }
1909 <- {
1910       "return":[
1911          {
1912             "CPU":0,
1913             "current":true,
1914             "halted":false,
1915             "pc":3227107138
1916          },
1917          {
1918             "CPU":1,
1919             "current":false,
1920             "halted":true,
1921             "pc":7108165
1922          }
1923       ]
1924    }
1925
1926 EQMP
1927
1928 STEXI
1929 @item info history
1930 show the command line history
1931 @item info irq
1932 show the interrupts statistics (if available)
1933 @item info pic
1934 show i8259 (PIC) state
1935 ETEXI
1936
1937 STEXI
1938 @item info pci
1939 show emulated PCI device info
1940 ETEXI
1941 SQMP
1942 query-pci
1943 ---------
1944
1945 PCI buses and devices information.
1946
1947 The returned value is a json-array of all buses. Each bus is represented by
1948 a json-object, which has a key with a json-array of all PCI devices attached
1949 to it. Each device is represented by a json-object.
1950
1951 The bus json-object contains the following:
1952
1953 - "bus": bus number (json-int)
1954 - "devices": a json-array of json-objects, each json-object represents a
1955              PCI device
1956
1957 The PCI device json-object contains the following:
1958
1959 - "bus": identical to the parent's bus number (json-int)
1960 - "slot": slot number (json-int)
1961 - "function": function number (json-int)
1962 - "class_info": a json-object containing:
1963      - "desc": device class description (json-string, optional)
1964      - "class": device class number (json-int)
1965 - "id": a json-object containing:
1966      - "device": device ID (json-int)
1967      - "vendor": vendor ID (json-int)
1968 - "irq": device's IRQ if assigned (json-int, optional)
1969 - "qdev_id": qdev id string (json-string)
1970 - "pci_bridge": It's a json-object, only present if this device is a
1971                 PCI bridge, contains:
1972      - "bus": bus number (json-int)
1973      - "secondary": secondary bus number (json-int)
1974      - "subordinate": subordinate bus number (json-int)
1975      - "io_range": I/O memory range information, a json-object with the
1976                    following members:
1977                  - "base": base address, in bytes (json-int)
1978                  - "limit": limit address, in bytes (json-int)
1979      - "memory_range": memory range information, a json-object with the
1980                        following members:
1981                  - "base": base address, in bytes (json-int)
1982                  - "limit": limit address, in bytes (json-int)
1983      - "prefetchable_range": Prefetchable memory range information, a
1984                              json-object with the following members:
1985                  - "base": base address, in bytes (json-int)
1986                  - "limit": limit address, in bytes (json-int)
1987      - "devices": a json-array of PCI devices if there's any attached, each
1988                   each element is represented by a json-object, which contains
1989                   the same members of the 'PCI device json-object' described
1990                   above (optional)
1991 - "regions": a json-array of json-objects, each json-object represents a
1992              memory region of this device
1993
1994 The memory range json-object contains the following:
1995
1996 - "base": base memory address (json-int)
1997 - "limit": limit value (json-int)
1998
1999 The region json-object can be an I/O region or a memory region, an I/O region
2000 json-object contains the following:
2001
2002 - "type": "io" (json-string, fixed)
2003 - "bar": BAR number (json-int)
2004 - "address": memory address (json-int)
2005 - "size": memory size (json-int)
2006
2007 A memory region json-object contains the following:
2008
2009 - "type": "memory" (json-string, fixed)
2010 - "bar": BAR number (json-int)
2011 - "address": memory address (json-int)
2012 - "size": memory size (json-int)
2013 - "mem_type_64": true or false (json-bool)
2014 - "prefetch": true or false (json-bool)
2015
2016 Example:
2017
2018 -> { "execute": "query-pci" }
2019 <- {
2020       "return":[
2021          {
2022             "bus":0,
2023             "devices":[
2024                {
2025                   "bus":0,
2026                   "qdev_id":"",
2027                   "slot":0,
2028                   "class_info":{
2029                      "class":1536,
2030                      "desc":"Host bridge"
2031                   },
2032                   "id":{
2033                      "device":32902,
2034                      "vendor":4663
2035                   },
2036                   "function":0,
2037                   "regions":[
2038
2039                   ]
2040                },
2041                {
2042                   "bus":0,
2043                   "qdev_id":"",
2044                   "slot":1,
2045                   "class_info":{
2046                      "class":1537,
2047                      "desc":"ISA bridge"
2048                   },
2049                   "id":{
2050                      "device":32902,
2051                      "vendor":28672
2052                   },
2053                   "function":0,
2054                   "regions":[
2055
2056                   ]
2057                },
2058                {
2059                   "bus":0,
2060                   "qdev_id":"",
2061                   "slot":1,
2062                   "class_info":{
2063                      "class":257,
2064                      "desc":"IDE controller"
2065                   },
2066                   "id":{
2067                      "device":32902,
2068                      "vendor":28688
2069                   },
2070                   "function":1,
2071                   "regions":[
2072                      {
2073                         "bar":4,
2074                         "size":16,
2075                         "address":49152,
2076                         "type":"io"
2077                      }
2078                   ]
2079                },
2080                {
2081                   "bus":0,
2082                   "qdev_id":"",
2083                   "slot":2,
2084                   "class_info":{
2085                      "class":768,
2086                      "desc":"VGA controller"
2087                   },
2088                   "id":{
2089                      "device":4115,
2090                      "vendor":184
2091                   },
2092                   "function":0,
2093                   "regions":[
2094                      {
2095                         "prefetch":true,
2096                         "mem_type_64":false,
2097                         "bar":0,
2098                         "size":33554432,
2099                         "address":4026531840,
2100                         "type":"memory"
2101                      },
2102                      {
2103                         "prefetch":false,
2104                         "mem_type_64":false,
2105                         "bar":1,
2106                         "size":4096,
2107                         "address":4060086272,
2108                         "type":"memory"
2109                      },
2110                      {
2111                         "prefetch":false,
2112                         "mem_type_64":false,
2113                         "bar":6,
2114                         "size":65536,
2115                         "address":-1,
2116                         "type":"memory"
2117                      }
2118                   ]
2119                },
2120                {
2121                   "bus":0,
2122                   "qdev_id":"",
2123                   "irq":11,
2124                   "slot":4,
2125                   "class_info":{
2126                      "class":1280,
2127                      "desc":"RAM controller"
2128                   },
2129                   "id":{
2130                      "device":6900,
2131                      "vendor":4098
2132                   },
2133                   "function":0,
2134                   "regions":[
2135                      {
2136                         "bar":0,
2137                         "size":32,
2138                         "address":49280,
2139                         "type":"io"
2140                      }
2141                   ]
2142                }
2143             ]
2144          }
2145       ]
2146    }
2147
2148 Note: This example has been shortened as the real response is too long.
2149
2150 EQMP
2151
2152 STEXI
2153 @item info tlb
2154 show virtual to physical memory mappings (i386 only)
2155 @item info mem
2156 show the active virtual memory mappings (i386 only)
2157 ETEXI
2158
2159 STEXI
2160 @item info hpet
2161 show state of HPET (i386 only)
2162 ETEXI
2163 SQMP
2164 query-hpet
2165 ----------
2166
2167 Show HPET state.
2168
2169 Return a json-object with the following information:
2170
2171 - "enabled": true if hpet if enabled, false otherwise (json-bool)
2172
2173 Example:
2174
2175 -> { "execute": "query-hpet" }
2176 <- { "return": { "enabled": true } }
2177
2178 EQMP
2179
2180 STEXI
2181 @item info jit
2182 show dynamic compiler info
2183 @item info kvm
2184 show KVM information
2185 @item info numa
2186 show NUMA information
2187 ETEXI
2188
2189 STEXI
2190 @item info kvm
2191 show KVM information
2192 ETEXI
2193 SQMP
2194 query-kvm
2195 ---------
2196
2197 Show KVM information.
2198
2199 Return a json-object with the following information:
2200
2201 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
2202 - "present": true if QEMU has KVM support, false otherwise (json-bool)
2203
2204 Example:
2205
2206 -> { "execute": "query-kvm" }
2207 <- { "return": { "enabled": true, "present": true } }
2208
2209 EQMP
2210
2211 STEXI
2212 @item info usb
2213 show USB devices plugged on the virtual USB hub
2214 @item info usbhost
2215 show all USB host devices
2216 @item info profile
2217 show profiling information
2218 @item info capture
2219 show information about active capturing
2220 @item info snapshots
2221 show list of VM snapshots
2222 ETEXI
2223
2224 STEXI
2225 @item info status
2226 show the current VM status (running|paused)
2227 ETEXI
2228 SQMP
2229 query-status
2230 ------------
2231
2232 Return a json-object with the following information:
2233
2234 - "running": true if the VM is running, or false if it is paused (json-bool)
2235 - "singlestep": true if the VM is in single step mode,
2236                 false otherwise (json-bool)
2237
2238 Example:
2239
2240 -> { "execute": "query-status" }
2241 <- { "return": { "running": true, "singlestep": false } }
2242
2243 EQMP
2244
2245 STEXI
2246 @item info pcmcia
2247 show guest PCMCIA status
2248 ETEXI
2249
2250 STEXI
2251 @item info mice
2252 show which guest mouse is receiving events
2253 ETEXI
2254 SQMP
2255 query-mice
2256 ----------
2257
2258 Show VM mice information.
2259
2260 Each mouse is represented by a json-object, the returned value is a json-array
2261 of all mice.
2262
2263 The mouse json-object contains the following:
2264
2265 - "name": mouse's name (json-string)
2266 - "index": mouse's index (json-int)
2267 - "current": true if this mouse is receiving events, false otherwise (json-bool)
2268 - "absolute": true if the mouse generates absolute input events (json-bool)
2269
2270 Example:
2271
2272 -> { "execute": "query-mice" }
2273 <- {
2274       "return":[
2275          {
2276             "name":"QEMU Microsoft Mouse",
2277             "index":0,
2278             "current":false,
2279             "absolute":false
2280          },
2281          {
2282             "name":"QEMU PS/2 Mouse",
2283             "index":1,
2284             "current":true,
2285             "absolute":true
2286          }
2287       ]
2288    }
2289
2290 EQMP
2291
2292 STEXI
2293 @item info vnc
2294 show the vnc server status
2295 ETEXI
2296 SQMP
2297 query-vnc
2298 ---------
2299
2300 Show VNC server information.
2301
2302 Return a json-object with server information. Connected clients are returned
2303 as a json-array of json-objects.
2304
2305 The main json-object contains the following:
2306
2307 - "enabled": true or false (json-bool)
2308 - "host": server's IP address (json-string)
2309 - "family": address family (json-string)
2310          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2311 - "service": server's port number (json-string)
2312 - "auth": authentication method (json-string)
2313          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2314                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2315                             "vencrypt+plain", "vencrypt+tls+none",
2316                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
2317                             "vencrypt+tls+vnc", "vencrypt+x509+none",
2318                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
2319                             "vencrypt+x509+vnc", "vnc"
2320 - "clients": a json-array of all connected clients
2321
2322 Clients are described by a json-object, each one contain the following:
2323
2324 - "host": client's IP address (json-string)
2325 - "family": address family (json-string)
2326          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2327 - "service": client's port number (json-string)
2328 - "x509_dname": TLS dname (json-string, optional)
2329 - "sasl_username": SASL username (json-string, optional)
2330
2331 Example:
2332
2333 -> { "execute": "query-vnc" }
2334 <- {
2335       "return":{
2336          "enabled":true,
2337          "host":"0.0.0.0",
2338          "service":"50402",
2339          "auth":"vnc",
2340          "family":"ipv4",
2341          "clients":[
2342             {
2343                "host":"127.0.0.1",
2344                "service":"50401",
2345                "family":"ipv4"
2346             }
2347          ]
2348       }
2349    }
2350
2351 EQMP
2352
2353 STEXI
2354 @item info name
2355 show the current VM name
2356 ETEXI
2357 SQMP
2358 query-name
2359 ----------
2360
2361 Show VM name.
2362
2363 Return a json-object with the following information:
2364
2365 - "name": VM's name (json-string, optional)
2366
2367 Example:
2368
2369 -> { "execute": "query-name" }
2370 <- { "return": { "name": "qemu-name" } }
2371
2372 EQMP
2373
2374 STEXI
2375 @item info uuid
2376 show the current VM UUID
2377 ETEXI
2378 SQMP
2379 query-uuid
2380 ----------
2381
2382 Show VM UUID.
2383
2384 Return a json-object with the following information:
2385
2386 - "UUID": Universally Unique Identifier (json-string)
2387
2388 Example:
2389
2390 -> { "execute": "query-uuid" }
2391 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2392
2393 EQMP
2394
2395 STEXI
2396 @item info cpustats
2397 show CPU statistics
2398 @item info usernet
2399 show user network stack connection states
2400 ETEXI
2401
2402 STEXI
2403 @item info migrate
2404 show migration status
2405 ETEXI
2406 SQMP
2407 query-migrate
2408 -------------
2409
2410 Migration status.
2411
2412 Return a json-object. If migration is active there will be another json-object
2413 with RAM migration status and if block migration is active another one with
2414 block migration status.
2415
2416 The main json-object contains the following:
2417
2418 - "status": migration status (json-string)
2419      - Possible values: "active", "completed", "failed", "cancelled"
2420 - "ram": only present if "status" is "active", it is a json-object with the
2421   following RAM information (in bytes):
2422          - "transferred": amount transferred (json-int)
2423          - "remaining": amount remaining (json-int)
2424          - "total": total (json-int)
2425 - "disk": only present if "status" is "active" and it is a block migration,
2426   it is a json-object with the following disk information (in bytes):
2427          - "transferred": amount transferred (json-int)
2428          - "remaining": amount remaining (json-int)
2429          - "total": total (json-int)
2430
2431 Examples:
2432
2433 1. Before the first migration
2434
2435 -> { "execute": "query-migrate" }
2436 <- { "return": {} }
2437
2438 2. Migration is done and has succeeded
2439
2440 -> { "execute": "query-migrate" }
2441 <- { "return": { "status": "completed" } }
2442
2443 3. Migration is done and has failed
2444
2445 -> { "execute": "query-migrate" }
2446 <- { "return": { "status": "failed" } }
2447
2448 4. Migration is being performed and is not a block migration:
2449
2450 -> { "execute": "query-migrate" }
2451 <- {
2452       "return":{
2453          "status":"active",
2454          "ram":{
2455             "transferred":123,
2456             "remaining":123,
2457             "total":246
2458          }
2459       }
2460    }
2461
2462 5. Migration is being performed and is a block migration:
2463
2464 -> { "execute": "query-migrate" }
2465 <- {
2466       "return":{
2467          "status":"active",
2468          "ram":{
2469             "total":1057024,
2470             "remaining":1053304,
2471             "transferred":3720
2472          },
2473          "disk":{
2474             "total":20971520,
2475             "remaining":20880384,
2476             "transferred":91136
2477          }
2478       }
2479    }
2480
2481 EQMP
2482
2483 STEXI
2484 @item info balloon
2485 show balloon information
2486 ETEXI
2487 SQMP
2488 query-balloon
2489 -------------
2490
2491 Show balloon information.
2492
2493 Make an asynchronous request for balloon info. When the request completes a
2494 json-object will be returned containing the following data:
2495
2496 - "actual": current balloon value in bytes (json-int)
2497 - "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
2498 - "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
2499 - "major_page_faults": Number of major faults (json-int, optional)
2500 - "minor_page_faults": Number of minor faults (json-int, optional)
2501 - "free_mem": Total amount of free and unused memory in
2502               bytes (json-int, optional)
2503 - "total_mem": Total amount of available memory in bytes (json-int, optional)
2504
2505 Example:
2506
2507 -> { "execute": "query-balloon" }
2508 <- {
2509       "return":{
2510          "actual":1073741824,
2511          "mem_swapped_in":0,
2512          "mem_swapped_out":0,
2513          "major_page_faults":142,
2514          "minor_page_faults":239245,
2515          "free_mem":1014185984,
2516          "total_mem":1044668416
2517       }
2518    }
2519
2520 EQMP
2521
2522 STEXI
2523 @item info qtree
2524 show device tree
2525 @item info qdm
2526 show qdev device model list
2527 @item info roms
2528 show roms
2529 @end table
2530 ETEXI
2531
2532 HXCOMM DO NOT add new commands after 'info', move your addition before it!
2533
2534 STEXI
2535 @end table
2536 ETEXI