qmp-commands.hx

   1 HXCOMM QMP dispatch table and documentation
   2 HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and
   3 HXCOMM does not show up in the other formats.
   4
   5 SQMP
   6                         QMP Supported Commands
   7                         ----------------------
   8
   9 This document describes all commands currently supported by QMP.
  10
  11 Most of the time their usage is exactly the same as in the user Monitor, this
  12 means that any other document which also describe commands (the manpage,
  13 QEMU's manual, etc) can and should be consulted.
  14
  15 QMP has two types of commands: regular and query commands. Regular commands
  16 usually change the Virtual Machine's state someway, while query commands just
  17 return information. The sections below are divided accordingly.
  18
  19 It's important to observe that all communication examples are formatted in
  20 a reader-friendly way, so that they're easier to understand. However, in real
  21 protocol usage, they're emitted as a single line.
  22
  23 Also, the following notation is used to denote data flow:
  24
  25 -> data issued by the Client
  26 <- Server data response
  27
  28 Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
  29 information on the Server command and response formats.
  30
  31 NOTE: This document is temporary and will be replaced soon.
  32
  33 1. Stability Considerations
  34 ===========================
  35
  36 The current QMP command set (described in this file) may be useful for a
  37 number of use cases, however it's limited and several commands have bad
  38 defined semantics, specially with regard to command completion.
  39
  40 These problems are going to be solved incrementally in the next QEMU releases
  41 and we're going to establish a deprecation policy for badly defined commands.
  42
  43 If you're planning to adopt QMP, please observe the following:
  44
  45     1. The deprecation policy will take effect and be documented soon, please
  46        check the documentation of each used command as soon as a new release of
  47        QEMU is available
  48
  49     2. DO NOT rely on anything which is not explicit documented
  50
  51     3. Errors, in special, are not documented. Applications should NOT check
  52        for specific errors classes or data (it's strongly recommended to only
  53        check for the "error" key)
  54
  55 2. Regular Commands
  56 ===================
  57
  58 Server's responses in the examples below are always a success response, please
  59 refer to the QMP specification for more details on error responses.
  60
  61 EQMP
  62
  63     {
  64         .name       = "quit",
  65         .args_type  = "",
  66         .mhandler.cmd_new = qmp_marshal_input_quit,
  67     },
  68
  69 SQMP
  70 quit
  71 ----
  72
  73 Quit the emulator.
  74
  75 Arguments: None.
  76
  77 Example:
  78
  79 -> { "execute": "quit" }
  80 <- { "return": {} }
  81
  82 EQMP
  83
  84     {
  85         .name       = "eject",
  86         .args_type  = "force:-f,device:B",
  87         .mhandler.cmd_new = qmp_marshal_input_eject,
  88     },
  89
  90 SQMP
  91 eject
  92 -----
  93
  94 Eject a removable medium.
  95
  96 Arguments:
  97
  98 - force: force ejection (json-bool, optional)
  99 - device: device name (json-string)
 100
 101 Example:
 102
 103 -> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
 104 <- { "return": {} }
 105
 106 Note: The "force" argument defaults to false.
 107
 108 EQMP
 109
 110     {
 111         .name       = "change",
 112         .args_type  = "device:B,target:F,arg:s?",
 113         .mhandler.cmd_new = qmp_marshal_input_change,
 114     },
 115
 116 SQMP
 117 change
 118 ------
 119
 120 Change a removable medium or VNC configuration.
 121
 122 Arguments:
 123
 124 - "device": device name (json-string)
 125 - "target": filename or item (json-string)
 126 - "arg": additional argument (json-string, optional)
 127
 128 Examples:
 129
 130 1. Change a removable medium
 131
 132 -> { "execute": "change",
 133              "arguments": { "device": "ide1-cd0",
 134                             "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
 135 <- { "return": {} }
 136
 137 2. Change VNC password
 138
 139 -> { "execute": "change",
 140              "arguments": { "device": "vnc", "target": "password",
 141                             "arg": "foobar1" } }
 142 <- { "return": {} }
 143
 144 EQMP
 145
 146     {
 147         .name       = "screendump",
 148         .args_type  = "filename:F",
 149         .mhandler.cmd_new = qmp_marshal_input_screendump,
 150     },
 151
 152 SQMP
 153 screendump
 154 ----------
 155
 156 Save screen into PPM image.
 157
 158 Arguments:
 159
 160 - "filename": file path (json-string)
 161
 162 Example:
 163
 164 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 165 <- { "return": {} }
 166
 167 EQMP
 168
 169     {
 170         .name       = "stop",
 171         .args_type  = "",
 172         .mhandler.cmd_new = qmp_marshal_input_stop,
 173     },
 174
 175 SQMP
 176 stop
 177 ----
 178
 179 Stop the emulator.
 180
 181 Arguments: None.
 182
 183 Example:
 184
 185 -> { "execute": "stop" }
 186 <- { "return": {} }
 187
 188 EQMP
 189
 190     {
 191         .name       = "cont",
 192         .args_type  = "",
 193         .mhandler.cmd_new = qmp_marshal_input_cont,
 194     },
 195
 196 SQMP
 197 cont
 198 ----
 199
 200 Resume emulation.
 201
 202 Arguments: None.
 203
 204 Example:
 205
 206 -> { "execute": "cont" }
 207 <- { "return": {} }
 208
 209 EQMP
 210
 211     {
 212         .name       = "system_wakeup",
 213         .args_type  = "",
 214         .mhandler.cmd_new = qmp_marshal_input_system_wakeup,
 215     },
 216
 217 SQMP
 218 system_wakeup
 219 -------------
 220
 221 Wakeup guest from suspend.
 222
 223 Arguments: None.
 224
 225 Example:
 226
 227 -> { "execute": "system_wakeup" }
 228 <- { "return": {} }
 229
 230 EQMP
 231
 232     {
 233         .name       = "system_reset",
 234         .args_type  = "",
 235         .mhandler.cmd_new = qmp_marshal_input_system_reset,
 236     },
 237
 238 SQMP
 239 system_reset
 240 ------------
 241
 242 Reset the system.
 243
 244 Arguments: None.
 245
 246 Example:
 247
 248 -> { "execute": "system_reset" }
 249 <- { "return": {} }
 250
 251 EQMP
 252
 253     {
 254         .name       = "system_powerdown",
 255         .args_type  = "",
 256         .mhandler.cmd_new = qmp_marshal_input_system_powerdown,
 257     },
 258
 259 SQMP
 260 system_powerdown
 261 ----------------
 262
 263 Send system power down event.
 264
 265 Arguments: None.
 266
 267 Example:
 268
 269 -> { "execute": "system_powerdown" }
 270 <- { "return": {} }
 271
 272 EQMP
 273
 274     {
 275         .name       = "device_add",
 276         .args_type  = "device:O",
 277         .params     = "driver[,prop=value][,...]",
 278         .help       = "add device, like -device on the command line",
 279         .user_print = monitor_user_noop,
 280         .mhandler.cmd_new = do_device_add,
 281     },
 282
 283 SQMP
 284 device_add
 285 ----------
 286
 287 Add a device.
 288
 289 Arguments:
 290
 291 - "driver": the name of the new device's driver (json-string)
 292 - "bus": the device's parent bus (device tree path, json-string, optional)
 293 - "id": the device's ID, must be unique (json-string)
 294 - device properties
 295
 296 Example:
 297
 298 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
 299 <- { "return": {} }
 300
 301 Notes:
 302
 303 (1) For detailed information about this command, please refer to the
 304     'docs/qdev-device-use.txt' file.
 305
 306 (2) It's possible to list device properties by running QEMU with the
 307     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
 308
 309 EQMP
 310
 311     {
 312         .name       = "device_del",
 313         .args_type  = "id:s",
 314         .mhandler.cmd_new = qmp_marshal_input_device_del,
 315     },
 316
 317 SQMP
 318 device_del
 319 ----------
 320
 321 Remove a device.
 322
 323 Arguments:
 324
 325 - "id": the device's ID (json-string)
 326
 327 Example:
 328
 329 -> { "execute": "device_del", "arguments": { "id": "net1" } }
 330 <- { "return": {} }
 331
 332 EQMP
 333
 334     {
 335         .name       = "send-key",
 336         .args_type  = "keys:O,hold-time:i?",
 337         .mhandler.cmd_new = qmp_marshal_input_send_key,
 338     },
 339
 340 SQMP
 341 send-key
 342 ----------
 343
 344 Send keys to VM.
 345
 346 Arguments:
 347
 348 keys array:
 349     - "key": key sequence (a json-array of key enum values)
 350
 351 - hold-time: time to delay key up events, milliseconds. Defaults to 100
 352              (json-int, optional)
 353
 354 Example:
 355
 356 -> { "execute": "send-key",
 357      "arguments": { 'keys': [ 'ctrl', 'alt', 'delete' ] } }
 358 <- { "return": {} }
 359
 360 EQMP
 361
 362     {
 363         .name       = "cpu",
 364         .args_type  = "index:i",
 365         .mhandler.cmd_new = qmp_marshal_input_cpu,
 366     },
 367
 368 SQMP
 369 cpu
 370 ---
 371
 372 Set the default CPU.
 373
 374 Arguments:
 375
 376 - "index": the CPU's index (json-int)
 377
 378 Example:
 379
 380 -> { "execute": "cpu", "arguments": { "index": 0 } }
 381 <- { "return": {} }
 382
 383 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 384
 385 EQMP
 386
 387     {
 388         .name       = "memsave",
 389         .args_type  = "val:l,size:i,filename:s,cpu:i?",
 390         .mhandler.cmd_new = qmp_marshal_input_memsave,
 391     },
 392
 393 SQMP
 394 memsave
 395 -------
 396
 397 Save to disk virtual memory dump starting at 'val' of size 'size'.
 398
 399 Arguments:
 400
 401 - "val": the starting address (json-int)
 402 - "size": the memory size, in bytes (json-int)
 403 - "filename": file path (json-string)
 404 - "cpu": virtual CPU index (json-int, optional)
 405
 406 Example:
 407
 408 -> { "execute": "memsave",
 409              "arguments": { "val": 10,
 410                             "size": 100,
 411                             "filename": "/tmp/virtual-mem-dump" } }
 412 <- { "return": {} }
 413
 414 EQMP
 415
 416     {
 417         .name       = "pmemsave",
 418         .args_type  = "val:l,size:i,filename:s",
 419         .mhandler.cmd_new = qmp_marshal_input_pmemsave,
 420     },
 421
 422 SQMP
 423 pmemsave
 424 --------
 425
 426 Save to disk physical memory dump starting at 'val' of size 'size'.
 427
 428 Arguments:
 429
 430 - "val": the starting address (json-int)
 431 - "size": the memory size, in bytes (json-int)
 432 - "filename": file path (json-string)
 433
 434 Example:
 435
 436 -> { "execute": "pmemsave",
 437              "arguments": { "val": 10,
 438                             "size": 100,
 439                             "filename": "/tmp/physical-mem-dump" } }
 440 <- { "return": {} }
 441
 442 EQMP
 443
 444     {
 445         .name       = "inject-nmi",
 446         .args_type  = "",
 447         .mhandler.cmd_new = qmp_marshal_input_inject_nmi,
 448     },
 449
 450 SQMP
 451 inject-nmi
 452 ----------
 453
 454 Inject an NMI on guest's CPUs.
 455
 456 Arguments: None.
 457
 458 Example:
 459
 460 -> { "execute": "inject-nmi" }
 461 <- { "return": {} }
 462
 463 Note: inject-nmi fails when the guest doesn't support injecting.
 464       Currently, only x86 guests do.
 465
 466 EQMP
 467
 468     {
 469         .name       = "xen-save-devices-state",
 470         .args_type  = "filename:F",
 471     .mhandler.cmd_new = qmp_marshal_input_xen_save_devices_state,
 472     },
 473
 474 SQMP
 475 xen-save-devices-state
 476 -------
 477
 478 Save the state of all devices to file. The RAM and the block devices
 479 of the VM are not saved by this command.
 480
 481 Arguments:
 482
 483 - "filename": the file to save the state of the devices to as binary
 484 data. See xen-save-devices-state.txt for a description of the binary
 485 format.
 486
 487 Example:
 488
 489 -> { "execute": "xen-save-devices-state",
 490      "arguments": { "filename": "/tmp/save" } }
 491 <- { "return": {} }
 492
 493 EQMP
 494
 495     {
 496         .name       = "migrate",
 497         .args_type  = "detach:-d,blk:-b,inc:-i,uri:s",
 498         .mhandler.cmd_new = qmp_marshal_input_migrate,
 499     },
 500
 501 SQMP
 502 migrate
 503 -------
 504
 505 Migrate to URI.
 506
 507 Arguments:
 508
 509 - "blk": block migration, full disk copy (json-bool, optional)
 510 - "inc": incremental disk copy (json-bool, optional)
 511 - "uri": Destination URI (json-string)
 512
 513 Example:
 514
 515 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
 516 <- { "return": {} }
 517
 518 Notes:
 519
 520 (1) The 'query-migrate' command should be used to check migration's progress
 521     and final result (this information is provided by the 'status' member)
 522 (2) All boolean arguments default to false
 523 (3) The user Monitor's "detach" argument is invalid in QMP and should not
 524     be used
 525
 526 EQMP
 527
 528     {
 529         .name       = "migrate_cancel",
 530         .args_type  = "",
 531         .mhandler.cmd_new = qmp_marshal_input_migrate_cancel,
 532     },
 533
 534 SQMP
 535 migrate_cancel
 536 --------------
 537
 538 Cancel the current migration.
 539
 540 Arguments: None.
 541
 542 Example:
 543
 544 -> { "execute": "migrate_cancel" }
 545 <- { "return": {} }
 546
 547 EQMP
 548 {
 549         .name       = "migrate-set-cache-size",
 550         .args_type  = "value:o",
 551         .mhandler.cmd_new = qmp_marshal_input_migrate_set_cache_size,
 552     },
 553
 554 SQMP
 555 migrate-set-cache-size
 556 ---------------------
 557
 558 Set cache size to be used by XBZRLE migration, the cache size will be rounded
 559 down to the nearest power of 2
 560
 561 Arguments:
 562
 563 - "value": cache size in bytes (json-int)
 564
 565 Example:
 566
 567 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 568 <- { "return": {} }
 569
 570 EQMP
 571     {
 572         .name       = "query-migrate-cache-size",
 573         .args_type  = "",
 574         .mhandler.cmd_new = qmp_marshal_input_query_migrate_cache_size,
 575     },
 576
 577 SQMP
 578 query-migrate-cache-size
 579 ---------------------
 580
 581 Show cache size to be used by XBZRLE migration
 582
 583 returns a json-object with the following information:
 584 - "size" : json-int
 585
 586 Example:
 587
 588 -> { "execute": "query-migrate-cache-size" }
 589 <- { "return": 67108864 }
 590
 591 EQMP
 592
 593     {
 594         .name       = "migrate_set_speed",
 595         .args_type  = "value:o",
 596         .mhandler.cmd_new = qmp_marshal_input_migrate_set_speed,
 597     },
 598
 599 SQMP
 600 migrate_set_speed
 601 -----------------
 602
 603 Set maximum speed for migrations.
 604
 605 Arguments:
 606
 607 - "value": maximum speed, in bytes per second (json-int)
 608
 609 Example:
 610
 611 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
 612 <- { "return": {} }
 613
 614 EQMP
 615
 616     {
 617         .name       = "migrate_set_downtime",
 618         .args_type  = "value:T",
 619         .mhandler.cmd_new = qmp_marshal_input_migrate_set_downtime,
 620     },
 621
 622 SQMP
 623 migrate_set_downtime
 624 --------------------
 625
 626 Set maximum tolerated downtime (in seconds) for migrations.
 627
 628 Arguments:
 629
 630 - "value": maximum downtime (json-number)
 631
 632 Example:
 633
 634 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
 635 <- { "return": {} }
 636
 637 EQMP
 638
 639     {
 640         .name       = "client_migrate_info",
 641         .args_type  = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
 642         .params     = "protocol hostname port tls-port cert-subject",
 643         .help       = "send migration info to spice/vnc client",
 644         .user_print = monitor_user_noop,
 645         .mhandler.cmd_async = client_migrate_info,
 646         .flags      = MONITOR_CMD_ASYNC,
 647     },
 648
 649 SQMP
 650 client_migrate_info
 651 ------------------
 652
 653 Set the spice/vnc connection info for the migration target.  The spice/vnc
 654 server will ask the spice/vnc client to automatically reconnect using the
 655 new parameters (if specified) once the vm migration finished successfully.
 656
 657 Arguments:
 658
 659 - "protocol":     protocol: "spice" or "vnc" (json-string)
 660 - "hostname":     migration target hostname (json-string)
 661 - "port":         spice/vnc tcp port for plaintext channels (json-int, optional)
 662 - "tls-port":     spice tcp port for tls-secured channels (json-int, optional)
 663 - "cert-subject": server certificate subject (json-string, optional)
 664
 665 Example:
 666
 667 -> { "execute": "client_migrate_info",
 668      "arguments": { "protocol": "spice",
 669                     "hostname": "virt42.lab.kraxel.org",
 670                     "port": 1234 } }
 671 <- { "return": {} }
 672
 673 EQMP
 674
 675     {
 676         .name       = "dump-guest-memory",
 677         .args_type  = "paging:b,protocol:s,begin:i?,end:i?",
 678         .params     = "-p protocol [begin] [length]",
 679         .help       = "dump guest memory to file",
 680         .user_print = monitor_user_noop,
 681         .mhandler.cmd_new = qmp_marshal_input_dump_guest_memory,
 682     },
 683
 684 SQMP
 685 dump
 686
 687
 688 Dump guest memory to file. The file can be processed with crash or gdb.
 689
 690 Arguments:
 691
 692 - "paging": do paging to get guest's memory mapping (json-bool)
 693 - "protocol": destination file(started with "file:") or destination file
 694               descriptor (started with "fd:") (json-string)
 695 - "begin": the starting physical address. It's optional, and should be specified
 696            with length together (json-int)
 697 - "length": the memory size, in bytes. It's optional, and should be specified
 698             with begin together (json-int)
 699
 700 Example:
 701
 702 -> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
 703 <- { "return": {} }
 704
 705 Notes:
 706
 707 (1) All boolean arguments default to false
 708
 709 EQMP
 710
 711     {
 712         .name       = "netdev_add",
 713         .args_type  = "netdev:O",
 714         .mhandler.cmd_new = qmp_netdev_add,
 715     },
 716
 717 SQMP
 718 netdev_add
 719 ----------
 720
 721 Add host network device.
 722
 723 Arguments:
 724
 725 - "type": the device type, "tap", "user", ... (json-string)
 726 - "id": the device's ID, must be unique (json-string)
 727 - device options
 728
 729 Example:
 730
 731 -> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
 732 <- { "return": {} }
 733
 734 Note: The supported device options are the same ones supported by the '-net'
 735       command-line argument, which are listed in the '-help' output or QEMU's
 736       manual
 737
 738 EQMP
 739
 740     {
 741         .name       = "netdev_del",
 742         .args_type  = "id:s",
 743         .mhandler.cmd_new = qmp_marshal_input_netdev_del,
 744     },
 745
 746 SQMP
 747 netdev_del
 748 ----------
 749
 750 Remove host network device.
 751
 752 Arguments:
 753
 754 - "id": the device's ID, must be unique (json-string)
 755
 756 Example:
 757
 758 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
 759 <- { "return": {} }
 760
 761
 762 EQMP
 763
 764     {
 765         .name       = "block_resize",
 766         .args_type  = "device:B,size:o",
 767         .mhandler.cmd_new = qmp_marshal_input_block_resize,
 768     },
 769
 770 SQMP
 771 block_resize
 772 ------------
 773
 774 Resize a block image while a guest is running.
 775
 776 Arguments:
 777
 778 - "device": the device's ID, must be unique (json-string)
 779 - "size": new size
 780
 781 Example:
 782
 783 -> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
 784 <- { "return": {} }
 785
 786 EQMP
 787
 788     {
 789         .name       = "block-stream",
 790         .args_type  = "device:B,base:s?,speed:o?",
 791         .mhandler.cmd_new = qmp_marshal_input_block_stream,
 792     },
 793
 794     {
 795         .name       = "block-job-set-speed",
 796         .args_type  = "device:B,speed:o",
 797         .mhandler.cmd_new = qmp_marshal_input_block_job_set_speed,
 798     },
 799
 800     {
 801         .name       = "block-job-cancel",
 802         .args_type  = "device:B",
 803         .mhandler.cmd_new = qmp_marshal_input_block_job_cancel,
 804     },
 805     {
 806         .name       = "transaction",
 807         .args_type  = "actions:q",
 808         .mhandler.cmd_new = qmp_marshal_input_transaction,
 809     },
 810
 811 SQMP
 812 transaction
 813 -----------
 814
 815 Atomically operate on one or more block devices.  The only supported
 816 operation for now is snapshotting.  If there is any failure performing
 817 any of the operations, all snapshots for the group are abandoned, and
 818 the original disks pre-snapshot attempt are used.
 819
 820 A list of dictionaries is accepted, that contains the actions to be performed.
 821 For snapshots this is the device, the file to use for the new snapshot,
 822 and the format.  The default format, if not specified, is qcow2.
 823
 824 Each new snapshot defaults to being created by QEMU (wiping any
 825 contents if the file already exists), but it is also possible to reuse
 826 an externally-created file.  In the latter case, you should ensure that
 827 the new image file has the same contents as the current one; QEMU cannot
 828 perform any meaningful check.  Typically this is achieved by using the
 829 current image file as the backing file for the new image.
 830
 831 Arguments:
 832
 833 actions array:
 834     - "type": the operation to perform.  The only supported
 835       value is "blockdev-snapshot-sync". (json-string)
 836     - "data": a dictionary.  The contents depend on the value
 837       of "type".  When "type" is "blockdev-snapshot-sync":
 838       - "device": device name to snapshot (json-string)
 839       - "snapshot-file": name of new image file (json-string)
 840       - "format": format of new image (json-string, optional)
 841       - "mode": whether and how QEMU should create the snapshot file
 842         (NewImageMode, optional, default "absolute-paths")
 843
 844 Example:
 845
 846 -> { "execute": "transaction",
 847      "arguments": { "actions": [
 848          { 'type': 'blockdev-snapshot-sync', 'data' : { "device": "ide-hd0",
 849                                          "snapshot-file": "/some/place/my-image",
 850                                          "format": "qcow2" } },
 851          { 'type': 'blockdev-snapshot-sync', 'data' : { "device": "ide-hd1",
 852                                          "snapshot-file": "/some/place/my-image2",
 853                                          "mode": "existing",
 854                                          "format": "qcow2" } } ] } }
 855 <- { "return": {} }
 856
 857 EQMP
 858
 859     {
 860         .name       = "blockdev-snapshot-sync",
 861         .args_type  = "device:B,snapshot-file:s,format:s?,mode:s?",
 862         .mhandler.cmd_new = qmp_marshal_input_blockdev_snapshot_sync,
 863     },
 864
 865 SQMP
 866 blockdev-snapshot-sync
 867 ----------------------
 868
 869 Synchronous snapshot of a block device. snapshot-file specifies the
 870 target of the new image. If the file exists, or if it is a device, the
 871 snapshot will be created in the existing file/device. If does not
 872 exist, a new file will be created. format specifies the format of the
 873 snapshot image, default is qcow2.
 874
 875 Arguments:
 876
 877 - "device": device name to snapshot (json-string)
 878 - "snapshot-file": name of new image file (json-string)
 879 - "mode": whether and how QEMU should create the snapshot file
 880   (NewImageMode, optional, default "absolute-paths")
 881 - "format": format of new image (json-string, optional)
 882
 883 Example:
 884
 885 -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
 886                                                          "snapshot-file":
 887                                                         "/some/place/my-image",
 888                                                         "format": "qcow2" } }
 889 <- { "return": {} }
 890
 891 EQMP
 892
 893     {
 894         .name       = "balloon",
 895         .args_type  = "value:M",
 896         .mhandler.cmd_new = qmp_marshal_input_balloon,
 897     },
 898
 899 SQMP
 900 balloon
 901 -------
 902
 903 Request VM to change its memory allocation (in bytes).
 904
 905 Arguments:
 906
 907 - "value": New memory allocation (json-int)
 908
 909 Example:
 910
 911 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
 912 <- { "return": {} }
 913
 914 EQMP
 915
 916     {
 917         .name       = "set_link",
 918         .args_type  = "name:s,up:b",
 919         .mhandler.cmd_new = qmp_marshal_input_set_link,
 920     },
 921
 922 SQMP
 923 set_link
 924 --------
 925
 926 Change the link status of a network adapter.
 927
 928 Arguments:
 929
 930 - "name": network device name (json-string)
 931 - "up": status is up (json-bool)
 932
 933 Example:
 934
 935 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
 936 <- { "return": {} }
 937
 938 EQMP
 939
 940     {
 941         .name       = "getfd",
 942         .args_type  = "fdname:s",
 943         .params     = "getfd name",
 944         .help       = "receive a file descriptor via SCM rights and assign it a name",
 945         .mhandler.cmd_new = qmp_marshal_input_getfd,
 946     },
 947
 948 SQMP
 949 getfd
 950 -----
 951
 952 Receive a file descriptor via SCM rights and assign it a name.
 953
 954 Arguments:
 955
 956 - "fdname": file descriptor name (json-string)
 957
 958 Example:
 959
 960 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
 961 <- { "return": {} }
 962
 963 Notes:
 964
 965 (1) If the name specified by the "fdname" argument already exists,
 966     the file descriptor assigned to it will be closed and replaced
 967     by the received file descriptor.
 968 (2) The 'closefd' command can be used to explicitly close the file
 969     descriptor when it is no longer needed.
 970
 971 EQMP
 972
 973     {
 974         .name       = "closefd",
 975         .args_type  = "fdname:s",
 976         .params     = "closefd name",
 977         .help       = "close a file descriptor previously passed via SCM rights",
 978         .mhandler.cmd_new = qmp_marshal_input_closefd,
 979     },
 980
 981 SQMP
 982 closefd
 983 -------
 984
 985 Close a file descriptor previously passed via SCM rights.
 986
 987 Arguments:
 988
 989 - "fdname": file descriptor name (json-string)
 990
 991 Example:
 992
 993 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
 994 <- { "return": {} }
 995
 996 EQMP
 997
 998      {
 999         .name       = "add-fd",
1000         .args_type  = "fdset-id:i?,opaque:s?",
1001         .params     = "add-fd fdset-id opaque",
1002         .help       = "Add a file descriptor, that was passed via SCM rights, to an fd set",
1003         .mhandler.cmd_new = qmp_marshal_input_add_fd,
1004     },
1005
1006 SQMP
1007 add-fd
1008 -------
1009
1010 Add a file descriptor, that was passed via SCM rights, to an fd set.
1011
1012 Arguments:
1013
1014 - "fdset-id": The ID of the fd set to add the file descriptor to.
1015               (json-int, optional)
1016 - "opaque": A free-form string that can be used to describe the fd.
1017             (json-string, optional)
1018
1019 Return a json-object with the following information:
1020
1021 - "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1022 - "fd": The file descriptor that was received via SCM rights and added to the
1023         fd set. (json-int)
1024
1025 Example:
1026
1027 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1028 <- { "return": { "fdset-id": 1, "fd": 3 } }
1029
1030 Notes:
1031
1032 (1) The list of fd sets is shared by all monitor connections.
1033 (2) If "fdset-id" is not specified, a new fd set will be created.
1034
1035 EQMP
1036
1037      {
1038         .name       = "remove-fd",
1039         .args_type  = "fdset-id:i,fd:i?",
1040         .params     = "remove-fd fdset-id fd",
1041         .help       = "Remove a file descriptor from an fd set",
1042         .mhandler.cmd_new = qmp_marshal_input_remove_fd,
1043     },
1044
1045 SQMP
1046 remove-fd
1047 ---------
1048
1049 Remove a file descriptor from an fd set.
1050
1051 Arguments:
1052
1053 - "fdset-id": The ID of the fd set that the file descriptor belongs to.
1054               (json-int)
1055 - "fd": The file descriptor that is to be removed. (json-int, optional)
1056
1057 Example:
1058
1059 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1060 <- { "return": {} }
1061
1062 Notes:
1063
1064 (1) The list of fd sets is shared by all monitor connections.
1065 (2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1066     removed.
1067
1068 EQMP
1069
1070     {
1071         .name       = "query-fdsets",
1072         .args_type  = "",
1073         .help       = "Return information describing all fd sets",
1074         .mhandler.cmd_new = qmp_marshal_input_query_fdsets,
1075     },
1076
1077 SQMP
1078 query-fdsets
1079 -------------
1080
1081 Return information describing all fd sets.
1082
1083 Arguments: None
1084
1085 Example:
1086
1087 -> { "execute": "query-fdsets" }
1088 <- { "return": [
1089        {
1090          "fds": [
1091            {
1092              "fd": 30,
1093              "opaque": "rdonly:/path/to/file"
1094            },
1095            {
1096              "fd": 24,
1097              "opaque": "rdwr:/path/to/file"
1098            }
1099          ],
1100          "fdset-id": 1
1101        },
1102        {
1103          "fds": [
1104            {
1105              "fd": 28
1106            },
1107            {
1108              "fd": 29
1109            }
1110          ],
1111          "fdset-id": 0
1112        }
1113      ]
1114    }
1115
1116 Note: The list of fd sets is shared by all monitor connections.
1117
1118 EQMP
1119
1120     {
1121         .name       = "block_passwd",
1122         .args_type  = "device:B,password:s",
1123         .mhandler.cmd_new = qmp_marshal_input_block_passwd,
1124     },
1125
1126 SQMP
1127 block_passwd
1128 ------------
1129
1130 Set the password of encrypted block devices.
1131
1132 Arguments:
1133
1134 - "device": device name (json-string)
1135 - "password": password (json-string)
1136
1137 Example:
1138
1139 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1140                                                "password": "12345" } }
1141 <- { "return": {} }
1142
1143 EQMP
1144
1145     {
1146         .name       = "block_set_io_throttle",
1147         .args_type  = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l",
1148         .mhandler.cmd_new = qmp_marshal_input_block_set_io_throttle,
1149     },
1150
1151 SQMP
1152 block_set_io_throttle
1153 ------------
1154
1155 Change I/O throttle limits for a block drive.
1156
1157 Arguments:
1158
1159 - "device": device name (json-string)
1160 - "bps":  total throughput limit in bytes per second(json-int)
1161 - "bps_rd":  read throughput limit in bytes per second(json-int)
1162 - "bps_wr":  read throughput limit in bytes per second(json-int)
1163 - "iops":  total I/O operations per second(json-int)
1164 - "iops_rd":  read I/O operations per second(json-int)
1165 - "iops_wr":  write I/O operations per second(json-int)
1166
1167 Example:
1168
1169 -> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
1170                                                "bps": "1000000",
1171                                                "bps_rd": "0",
1172                                                "bps_wr": "0",
1173                                                "iops": "0",
1174                                                "iops_rd": "0",
1175                                                "iops_wr": "0" } }
1176 <- { "return": {} }
1177
1178 EQMP
1179
1180     {
1181         .name       = "set_password",
1182         .args_type  = "protocol:s,password:s,connected:s?",
1183         .mhandler.cmd_new = qmp_marshal_input_set_password,
1184     },
1185
1186 SQMP
1187 set_password
1188 ------------
1189
1190 Set the password for vnc/spice protocols.
1191
1192 Arguments:
1193
1194 - "protocol": protocol name (json-string)
1195 - "password": password (json-string)
1196 - "connected": [ keep | disconnect | fail ] (josn-string, optional)
1197
1198 Example:
1199
1200 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
1201                                                "password": "secret" } }
1202 <- { "return": {} }
1203
1204 EQMP
1205
1206     {
1207         .name       = "expire_password",
1208         .args_type  = "protocol:s,time:s",
1209         .mhandler.cmd_new = qmp_marshal_input_expire_password,
1210     },
1211
1212 SQMP
1213 expire_password
1214 ---------------
1215
1216 Set the password expire time for vnc/spice protocols.
1217
1218 Arguments:
1219
1220 - "protocol": protocol name (json-string)
1221 - "time": [ now | never | +secs | secs ] (json-string)
1222
1223 Example:
1224
1225 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
1226                                                   "time": "+60" } }
1227 <- { "return": {} }
1228
1229 EQMP
1230
1231     {
1232         .name       = "add_client",
1233         .args_type  = "protocol:s,fdname:s,skipauth:b?,tls:b?",
1234         .params     = "protocol fdname skipauth tls",
1235         .help       = "add a graphics client",
1236         .user_print = monitor_user_noop,
1237         .mhandler.cmd_new = add_graphics_client,
1238     },
1239
1240 SQMP
1241 add_client
1242 ----------
1243
1244 Add a graphics client
1245
1246 Arguments:
1247
1248 - "protocol": protocol name (json-string)
1249 - "fdname": file descriptor name (json-string)
1250 - "skipauth": whether to skip authentication (json-bool, optional)
1251 - "tls": whether to perform TLS (json-bool, optional)
1252
1253 Example:
1254
1255 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
1256                                              "fdname": "myclient" } }
1257 <- { "return": {} }
1258
1259 EQMP
1260     {
1261         .name       = "qmp_capabilities",
1262         .args_type  = "",
1263         .params     = "",
1264         .help       = "enable QMP capabilities",
1265         .user_print = monitor_user_noop,
1266         .mhandler.cmd_new = do_qmp_capabilities,
1267     },
1268
1269 SQMP
1270 qmp_capabilities
1271 ----------------
1272
1273 Enable QMP capabilities.
1274
1275 Arguments: None.
1276
1277 Example:
1278
1279 -> { "execute": "qmp_capabilities" }
1280 <- { "return": {} }
1281
1282 Note: This command must be issued before issuing any other command.
1283
1284 EQMP
1285
1286     {
1287         .name       = "human-monitor-command",
1288         .args_type  = "command-line:s,cpu-index:i?",
1289         .mhandler.cmd_new = qmp_marshal_input_human_monitor_command,
1290     },
1291
1292 SQMP
1293 human-monitor-command
1294 ---------------------
1295
1296 Execute a Human Monitor command.
1297
1298 Arguments:
1299
1300 - command-line: the command name and its arguments, just like the
1301                 Human Monitor's shell (json-string)
1302 - cpu-index: select the CPU number to be used by commands which access CPU
1303              data, like 'info registers'. The Monitor selects CPU 0 if this
1304              argument is not provided (json-int, optional)
1305
1306 Example:
1307
1308 -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
1309 <- { "return": "kvm support: enabled\r\n" }
1310
1311 Notes:
1312
1313 (1) The Human Monitor is NOT an stable interface, this means that command
1314     names, arguments and responses can change or be removed at ANY time.
1315     Applications that rely on long term stability guarantees should NOT
1316     use this command
1317
1318 (2) Limitations:
1319
1320     o This command is stateless, this means that commands that depend
1321       on state information (such as getfd) might not work
1322
1323     o Commands that prompt the user for data (eg. 'cont' when the block
1324       device is encrypted) don't currently work
1325
1326 3. Query Commands
1327 =================
1328
1329 HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
1330 HXCOMM this! We will possibly move query commands definitions inside those
1331 HXCOMM sections, just like regular commands.
1332
1333 EQMP
1334
1335 SQMP
1336 query-version
1337 -------------
1338
1339 Show QEMU version.
1340
1341 Return a json-object with the following information:
1342
1343 - "qemu": A json-object containing three integer values:
1344     - "major": QEMU's major version (json-int)
1345     - "minor": QEMU's minor version (json-int)
1346     - "micro": QEMU's micro version (json-int)
1347 - "package": package's version (json-string)
1348
1349 Example:
1350
1351 -> { "execute": "query-version" }
1352 <- {
1353       "return":{
1354          "qemu":{
1355             "major":0,
1356             "minor":11,
1357             "micro":5
1358          },
1359          "package":""
1360       }
1361    }
1362
1363 EQMP
1364
1365     {
1366         .name       = "query-version",
1367         .args_type  = "",
1368         .mhandler.cmd_new = qmp_marshal_input_query_version,
1369     },
1370
1371 SQMP
1372 query-commands
1373 --------------
1374
1375 List QMP available commands.
1376
1377 Each command is represented by a json-object, the returned value is a json-array
1378 of all commands.
1379
1380 Each json-object contain:
1381
1382 - "name": command's name (json-string)
1383
1384 Example:
1385
1386 -> { "execute": "query-commands" }
1387 <- {
1388       "return":[
1389          {
1390             "name":"query-balloon"
1391          },
1392          {
1393             "name":"system_powerdown"
1394          }
1395       ]
1396    }
1397
1398 Note: This example has been shortened as the real response is too long.
1399
1400 EQMP
1401
1402     {
1403         .name       = "query-commands",
1404         .args_type  = "",
1405         .mhandler.cmd_new = qmp_marshal_input_query_commands,
1406     },
1407
1408 SQMP
1409 query-events
1410 --------------
1411
1412 List QMP available events.
1413
1414 Each event is represented by a json-object, the returned value is a json-array
1415 of all events.
1416
1417 Each json-object contains:
1418
1419 - "name": event's name (json-string)
1420
1421 Example:
1422
1423 -> { "execute": "query-events" }
1424 <- {
1425       "return":[
1426          {
1427             "name":"SHUTDOWN"
1428          },
1429          {
1430             "name":"RESET"
1431          }
1432       ]
1433    }
1434
1435 Note: This example has been shortened as the real response is too long.
1436
1437 EQMP
1438
1439     {
1440         .name       = "query-events",
1441         .args_type  = "",
1442         .mhandler.cmd_new = qmp_marshal_input_query_events,
1443     },
1444
1445 SQMP
1446 query-chardev
1447 -------------
1448
1449 Each device is represented by a json-object. The returned value is a json-array
1450 of all devices.
1451
1452 Each json-object contain the following:
1453
1454 - "label": device's label (json-string)
1455 - "filename": device's file (json-string)
1456
1457 Example:
1458
1459 -> { "execute": "query-chardev" }
1460 <- {
1461       "return":[
1462          {
1463             "label":"monitor",
1464             "filename":"stdio"
1465          },
1466          {
1467             "label":"serial0",
1468             "filename":"vc"
1469          }
1470       ]
1471    }
1472
1473 EQMP
1474
1475     {
1476         .name       = "query-chardev",
1477         .args_type  = "",
1478         .mhandler.cmd_new = qmp_marshal_input_query_chardev,
1479     },
1480
1481 SQMP
1482 query-block
1483 -----------
1484
1485 Show the block devices.
1486
1487 Each block device information is stored in a json-object and the returned value
1488 is a json-array of all devices.
1489
1490 Each json-object contain the following:
1491
1492 - "device": device name (json-string)
1493 - "type": device type (json-string)
1494          - deprecated, retained for backward compatibility
1495          - Possible values: "unknown"
1496 - "removable": true if the device is removable, false otherwise (json-bool)
1497 - "locked": true if the device is locked, false otherwise (json-bool)
1498 - "tray-open": only present if removable, true if the device has a tray,
1499                and it is open (json-bool)
1500 - "inserted": only present if the device is inserted, it is a json-object
1501    containing the following:
1502          - "file": device file name (json-string)
1503          - "ro": true if read-only, false otherwise (json-bool)
1504          - "drv": driver format name (json-string)
1505              - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1506                                 "file", "file", "ftp", "ftps", "host_cdrom",
1507                                 "host_device", "host_floppy", "http", "https",
1508                                 "nbd", "parallels", "qcow", "qcow2", "raw",
1509                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1510          - "backing_file": backing file name (json-string, optional)
1511          - "backing_file_depth": number of files in the backing file chain (json-int)
1512          - "encrypted": true if encrypted, false otherwise (json-bool)
1513          - "bps": limit total bytes per second (json-int)
1514          - "bps_rd": limit read bytes per second (json-int)
1515          - "bps_wr": limit write bytes per second (json-int)
1516          - "iops": limit total I/O operations per second (json-int)
1517          - "iops_rd": limit read operations per second (json-int)
1518          - "iops_wr": limit write operations per second (json-int)
1519
1520 - "io-status": I/O operation status, only present if the device supports it
1521                and the VM is configured to stop on errors. It's always reset
1522                to "ok" when the "cont" command is issued (json_string, optional)
1523              - Possible values: "ok", "failed", "nospace"
1524
1525 Example:
1526
1527 -> { "execute": "query-block" }
1528 <- {
1529       "return":[
1530          {
1531             "io-status": "ok",
1532             "device":"ide0-hd0",
1533             "locked":false,
1534             "removable":false,
1535             "inserted":{
1536                "ro":false,
1537                "drv":"qcow2",
1538                "encrypted":false,
1539                "file":"disks/test.img",
1540                "backing_file_depth":0,
1541                "bps":1000000,
1542                "bps_rd":0,
1543                "bps_wr":0,
1544                "iops":1000000,
1545                "iops_rd":0,
1546                "iops_wr":0,
1547             },
1548             "type":"unknown"
1549          },
1550          {
1551             "io-status": "ok",
1552             "device":"ide1-cd0",
1553             "locked":false,
1554             "removable":true,
1555             "type":"unknown"
1556          },
1557          {
1558             "device":"floppy0",
1559             "locked":false,
1560             "removable":true,
1561             "type":"unknown"
1562          },
1563          {
1564             "device":"sd0",
1565             "locked":false,
1566             "removable":true,
1567             "type":"unknown"
1568          }
1569       ]
1570    }
1571
1572 EQMP
1573
1574     {
1575         .name       = "query-block",
1576         .args_type  = "",
1577         .mhandler.cmd_new = qmp_marshal_input_query_block,
1578     },
1579
1580 SQMP
1581 query-blockstats
1582 ----------------
1583
1584 Show block device statistics.
1585
1586 Each device statistic information is stored in a json-object and the returned
1587 value is a json-array of all devices.
1588
1589 Each json-object contain the following:
1590
1591 - "device": device name (json-string)
1592 - "stats": A json-object with the statistics information, it contains:
1593     - "rd_bytes": bytes read (json-int)
1594     - "wr_bytes": bytes written (json-int)
1595     - "rd_operations": read operations (json-int)
1596     - "wr_operations": write operations (json-int)
1597     - "flush_operations": cache flush operations (json-int)
1598     - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
1599     - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
1600     - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
1601     - "wr_highest_offset": Highest offset of a sector written since the
1602                            BlockDriverState has been opened (json-int)
1603 - "parent": Contains recursively the statistics of the underlying
1604             protocol (e.g. the host file for a qcow2 image). If there is
1605             no underlying protocol, this field is omitted
1606             (json-object, optional)
1607
1608 Example:
1609
1610 -> { "execute": "query-blockstats" }
1611 <- {
1612       "return":[
1613          {
1614             "device":"ide0-hd0",
1615             "parent":{
1616                "stats":{
1617                   "wr_highest_offset":3686448128,
1618                   "wr_bytes":9786368,
1619                   "wr_operations":751,
1620                   "rd_bytes":122567168,
1621                   "rd_operations":36772
1622                   "wr_total_times_ns":313253456
1623                   "rd_total_times_ns":3465673657
1624                   "flush_total_times_ns":49653
1625                   "flush_operations":61,
1626                }
1627             },
1628             "stats":{
1629                "wr_highest_offset":2821110784,
1630                "wr_bytes":9786368,
1631                "wr_operations":692,
1632                "rd_bytes":122739200,
1633                "rd_operations":36604
1634                "flush_operations":51,
1635                "wr_total_times_ns":313253456
1636                "rd_total_times_ns":3465673657
1637                "flush_total_times_ns":49653
1638             }
1639          },
1640          {
1641             "device":"ide1-cd0",
1642             "stats":{
1643                "wr_highest_offset":0,
1644                "wr_bytes":0,
1645                "wr_operations":0,
1646                "rd_bytes":0,
1647                "rd_operations":0
1648                "flush_operations":0,
1649                "wr_total_times_ns":0
1650                "rd_total_times_ns":0
1651                "flush_total_times_ns":0
1652             }
1653          },
1654          {
1655             "device":"floppy0",
1656             "stats":{
1657                "wr_highest_offset":0,
1658                "wr_bytes":0,
1659                "wr_operations":0,
1660                "rd_bytes":0,
1661                "rd_operations":0
1662                "flush_operations":0,
1663                "wr_total_times_ns":0
1664                "rd_total_times_ns":0
1665                "flush_total_times_ns":0
1666             }
1667          },
1668          {
1669             "device":"sd0",
1670             "stats":{
1671                "wr_highest_offset":0,
1672                "wr_bytes":0,
1673                "wr_operations":0,
1674                "rd_bytes":0,
1675                "rd_operations":0
1676                "flush_operations":0,
1677                "wr_total_times_ns":0
1678                "rd_total_times_ns":0
1679                "flush_total_times_ns":0
1680             }
1681          }
1682       ]
1683    }
1684
1685 EQMP
1686
1687     {
1688         .name       = "query-blockstats",
1689         .args_type  = "",
1690         .mhandler.cmd_new = qmp_marshal_input_query_blockstats,
1691     },
1692
1693 SQMP
1694 query-cpus
1695 ----------
1696
1697 Show CPU information.
1698
1699 Return a json-array. Each CPU is represented by a json-object, which contains:
1700
1701 - "CPU": CPU index (json-int)
1702 - "current": true if this is the current CPU, false otherwise (json-bool)
1703 - "halted": true if the cpu is halted, false otherwise (json-bool)
1704 - Current program counter. The key's name depends on the architecture:
1705      "pc": i386/x86_64 (json-int)
1706      "nip": PPC (json-int)
1707      "pc" and "npc": sparc (json-int)
1708      "PC": mips (json-int)
1709 - "thread_id": ID of the underlying host thread (json-int)
1710
1711 Example:
1712
1713 -> { "execute": "query-cpus" }
1714 <- {
1715       "return":[
1716          {
1717             "CPU":0,
1718             "current":true,
1719             "halted":false,
1720             "pc":3227107138
1721             "thread_id":3134
1722          },
1723          {
1724             "CPU":1,
1725             "current":false,
1726             "halted":true,
1727             "pc":7108165
1728             "thread_id":3135
1729          }
1730       ]
1731    }
1732
1733 EQMP
1734
1735     {
1736         .name       = "query-cpus",
1737         .args_type  = "",
1738         .mhandler.cmd_new = qmp_marshal_input_query_cpus,
1739     },
1740
1741 SQMP
1742 query-pci
1743 ---------
1744
1745 PCI buses and devices information.
1746
1747 The returned value is a json-array of all buses. Each bus is represented by
1748 a json-object, which has a key with a json-array of all PCI devices attached
1749 to it. Each device is represented by a json-object.
1750
1751 The bus json-object contains the following:
1752
1753 - "bus": bus number (json-int)
1754 - "devices": a json-array of json-objects, each json-object represents a
1755              PCI device
1756
1757 The PCI device json-object contains the following:
1758
1759 - "bus": identical to the parent's bus number (json-int)
1760 - "slot": slot number (json-int)
1761 - "function": function number (json-int)
1762 - "class_info": a json-object containing:
1763      - "desc": device class description (json-string, optional)
1764      - "class": device class number (json-int)
1765 - "id": a json-object containing:
1766      - "device": device ID (json-int)
1767      - "vendor": vendor ID (json-int)
1768 - "irq": device's IRQ if assigned (json-int, optional)
1769 - "qdev_id": qdev id string (json-string)
1770 - "pci_bridge": It's a json-object, only present if this device is a
1771                 PCI bridge, contains:
1772      - "bus": bus number (json-int)
1773      - "secondary": secondary bus number (json-int)
1774      - "subordinate": subordinate bus number (json-int)
1775      - "io_range": I/O memory range information, a json-object with the
1776                    following members:
1777                  - "base": base address, in bytes (json-int)
1778                  - "limit": limit address, in bytes (json-int)
1779      - "memory_range": memory range information, a json-object with the
1780                        following members:
1781                  - "base": base address, in bytes (json-int)
1782                  - "limit": limit address, in bytes (json-int)
1783      - "prefetchable_range": Prefetchable memory range information, a
1784                              json-object with the following members:
1785                  - "base": base address, in bytes (json-int)
1786                  - "limit": limit address, in bytes (json-int)
1787      - "devices": a json-array of PCI devices if there's any attached, each
1788                   each element is represented by a json-object, which contains
1789                   the same members of the 'PCI device json-object' described
1790                   above (optional)
1791 - "regions": a json-array of json-objects, each json-object represents a
1792              memory region of this device
1793
1794 The memory range json-object contains the following:
1795
1796 - "base": base memory address (json-int)
1797 - "limit": limit value (json-int)
1798
1799 The region json-object can be an I/O region or a memory region, an I/O region
1800 json-object contains the following:
1801
1802 - "type": "io" (json-string, fixed)
1803 - "bar": BAR number (json-int)
1804 - "address": memory address (json-int)
1805 - "size": memory size (json-int)
1806
1807 A memory region json-object contains the following:
1808
1809 - "type": "memory" (json-string, fixed)
1810 - "bar": BAR number (json-int)
1811 - "address": memory address (json-int)
1812 - "size": memory size (json-int)
1813 - "mem_type_64": true or false (json-bool)
1814 - "prefetch": true or false (json-bool)
1815
1816 Example:
1817
1818 -> { "execute": "query-pci" }
1819 <- {
1820       "return":[
1821          {
1822             "bus":0,
1823             "devices":[
1824                {
1825                   "bus":0,
1826                   "qdev_id":"",
1827                   "slot":0,
1828                   "class_info":{
1829                      "class":1536,
1830                      "desc":"Host bridge"
1831                   },
1832                   "id":{
1833                      "device":32902,
1834                      "vendor":4663
1835                   },
1836                   "function":0,
1837                   "regions":[
1838
1839                   ]
1840                },
1841                {
1842                   "bus":0,
1843                   "qdev_id":"",
1844                   "slot":1,
1845                   "class_info":{
1846                      "class":1537,
1847                      "desc":"ISA bridge"
1848                   },
1849                   "id":{
1850                      "device":32902,
1851                      "vendor":28672
1852                   },
1853                   "function":0,
1854                   "regions":[
1855
1856                   ]
1857                },
1858                {
1859                   "bus":0,
1860                   "qdev_id":"",
1861                   "slot":1,
1862                   "class_info":{
1863                      "class":257,
1864                      "desc":"IDE controller"
1865                   },
1866                   "id":{
1867                      "device":32902,
1868                      "vendor":28688
1869                   },
1870                   "function":1,
1871                   "regions":[
1872                      {
1873                         "bar":4,
1874                         "size":16,
1875                         "address":49152,
1876                         "type":"io"
1877                      }
1878                   ]
1879                },
1880                {
1881                   "bus":0,
1882                   "qdev_id":"",
1883                   "slot":2,
1884                   "class_info":{
1885                      "class":768,
1886                      "desc":"VGA controller"
1887                   },
1888                   "id":{
1889                      "device":4115,
1890                      "vendor":184
1891                   },
1892                   "function":0,
1893                   "regions":[
1894                      {
1895                         "prefetch":true,
1896                         "mem_type_64":false,
1897                         "bar":0,
1898                         "size":33554432,
1899                         "address":4026531840,
1900                         "type":"memory"
1901                      },
1902                      {
1903                         "prefetch":false,
1904                         "mem_type_64":false,
1905                         "bar":1,
1906                         "size":4096,
1907                         "address":4060086272,
1908                         "type":"memory"
1909                      },
1910                      {
1911                         "prefetch":false,
1912                         "mem_type_64":false,
1913                         "bar":6,
1914                         "size":65536,
1915                         "address":-1,
1916                         "type":"memory"
1917                      }
1918                   ]
1919                },
1920                {
1921                   "bus":0,
1922                   "qdev_id":"",
1923                   "irq":11,
1924                   "slot":4,
1925                   "class_info":{
1926                      "class":1280,
1927                      "desc":"RAM controller"
1928                   },
1929                   "id":{
1930                      "device":6900,
1931                      "vendor":4098
1932                   },
1933                   "function":0,
1934                   "regions":[
1935                      {
1936                         "bar":0,
1937                         "size":32,
1938                         "address":49280,
1939                         "type":"io"
1940                      }
1941                   ]
1942                }
1943             ]
1944          }
1945       ]
1946    }
1947
1948 Note: This example has been shortened as the real response is too long.
1949
1950 EQMP
1951
1952     {
1953         .name       = "query-pci",
1954         .args_type  = "",
1955         .mhandler.cmd_new = qmp_marshal_input_query_pci,
1956     },
1957
1958 SQMP
1959 query-kvm
1960 ---------
1961
1962 Show KVM information.
1963
1964 Return a json-object with the following information:
1965
1966 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
1967 - "present": true if QEMU has KVM support, false otherwise (json-bool)
1968
1969 Example:
1970
1971 -> { "execute": "query-kvm" }
1972 <- { "return": { "enabled": true, "present": true } }
1973
1974 EQMP
1975
1976     {
1977         .name       = "query-kvm",
1978         .args_type  = "",
1979         .mhandler.cmd_new = qmp_marshal_input_query_kvm,
1980     },
1981
1982 SQMP
1983 query-status
1984 ------------
1985
1986 Return a json-object with the following information:
1987
1988 - "running": true if the VM is running, or false if it is paused (json-bool)
1989 - "singlestep": true if the VM is in single step mode,
1990                 false otherwise (json-bool)
1991 - "status": one of the following values (json-string)
1992     "debug" - QEMU is running on a debugger
1993     "inmigrate" - guest is paused waiting for an incoming migration
1994     "internal-error" - An internal error that prevents further guest
1995     execution has occurred
1996     "io-error" - the last IOP has failed and the device is configured
1997     to pause on I/O errors
1998     "paused" - guest has been paused via the 'stop' command
1999     "postmigrate" - guest is paused following a successful 'migrate'
2000     "prelaunch" - QEMU was started with -S and guest has not started
2001     "finish-migrate" - guest is paused to finish the migration process
2002     "restore-vm" - guest is paused to restore VM state
2003     "running" - guest is actively running
2004     "save-vm" - guest is paused to save the VM state
2005     "shutdown" - guest is shut down (and -no-shutdown is in use)
2006     "watchdog" - the watchdog action is configured to pause and
2007      has been triggered
2008
2009 Example:
2010
2011 -> { "execute": "query-status" }
2012 <- { "return": { "running": true, "singlestep": false, "status": "running" } }
2013
2014 EQMP
2015
2016     {
2017         .name       = "query-status",
2018         .args_type  = "",
2019         .mhandler.cmd_new = qmp_marshal_input_query_status,
2020     },
2021
2022 SQMP
2023 query-mice
2024 ----------
2025
2026 Show VM mice information.
2027
2028 Each mouse is represented by a json-object, the returned value is a json-array
2029 of all mice.
2030
2031 The mouse json-object contains the following:
2032
2033 - "name": mouse's name (json-string)
2034 - "index": mouse's index (json-int)
2035 - "current": true if this mouse is receiving events, false otherwise (json-bool)
2036 - "absolute": true if the mouse generates absolute input events (json-bool)
2037
2038 Example:
2039
2040 -> { "execute": "query-mice" }
2041 <- {
2042       "return":[
2043          {
2044             "name":"QEMU Microsoft Mouse",
2045             "index":0,
2046             "current":false,
2047             "absolute":false
2048          },
2049          {
2050             "name":"QEMU PS/2 Mouse",
2051             "index":1,
2052             "current":true,
2053             "absolute":true
2054          }
2055       ]
2056    }
2057
2058 EQMP
2059
2060     {
2061         .name       = "query-mice",
2062         .args_type  = "",
2063         .mhandler.cmd_new = qmp_marshal_input_query_mice,
2064     },
2065
2066 SQMP
2067 query-vnc
2068 ---------
2069
2070 Show VNC server information.
2071
2072 Return a json-object with server information. Connected clients are returned
2073 as a json-array of json-objects.
2074
2075 The main json-object contains the following:
2076
2077 - "enabled": true or false (json-bool)
2078 - "host": server's IP address (json-string)
2079 - "family": address family (json-string)
2080          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2081 - "service": server's port number (json-string)
2082 - "auth": authentication method (json-string)
2083          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2084                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2085                             "vencrypt+plain", "vencrypt+tls+none",
2086                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
2087                             "vencrypt+tls+vnc", "vencrypt+x509+none",
2088                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
2089                             "vencrypt+x509+vnc", "vnc"
2090 - "clients": a json-array of all connected clients
2091
2092 Clients are described by a json-object, each one contain the following:
2093
2094 - "host": client's IP address (json-string)
2095 - "family": address family (json-string)
2096          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2097 - "service": client's port number (json-string)
2098 - "x509_dname": TLS dname (json-string, optional)
2099 - "sasl_username": SASL username (json-string, optional)
2100
2101 Example:
2102
2103 -> { "execute": "query-vnc" }
2104 <- {
2105       "return":{
2106          "enabled":true,
2107          "host":"0.0.0.0",
2108          "service":"50402",
2109          "auth":"vnc",
2110          "family":"ipv4",
2111          "clients":[
2112             {
2113                "host":"127.0.0.1",
2114                "service":"50401",
2115                "family":"ipv4"
2116             }
2117          ]
2118       }
2119    }
2120
2121 EQMP
2122
2123     {
2124         .name       = "query-vnc",
2125         .args_type  = "",
2126         .mhandler.cmd_new = qmp_marshal_input_query_vnc,
2127     },
2128
2129 SQMP
2130 query-spice
2131 -----------
2132
2133 Show SPICE server information.
2134
2135 Return a json-object with server information. Connected clients are returned
2136 as a json-array of json-objects.
2137
2138 The main json-object contains the following:
2139
2140 - "enabled": true or false (json-bool)
2141 - "host": server's IP address (json-string)
2142 - "port": server's port number (json-int, optional)
2143 - "tls-port": server's port number (json-int, optional)
2144 - "auth": authentication method (json-string)
2145          - Possible values: "none", "spice"
2146 - "channels": a json-array of all active channels clients
2147
2148 Channels are described by a json-object, each one contain the following:
2149
2150 - "host": client's IP address (json-string)
2151 - "family": address family (json-string)
2152          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2153 - "port": client's port number (json-string)
2154 - "connection-id": spice connection id.  All channels with the same id
2155                    belong to the same spice session (json-int)
2156 - "channel-type": channel type.  "1" is the main control channel, filter for
2157                   this one if you want track spice sessions only (json-int)
2158 - "channel-id": channel id.  Usually "0", might be different needed when
2159                 multiple channels of the same type exist, such as multiple
2160                 display channels in a multihead setup (json-int)
2161 - "tls": whevener the channel is encrypted (json-bool)
2162
2163 Example:
2164
2165 -> { "execute": "query-spice" }
2166 <- {
2167       "return": {
2168          "enabled": true,
2169          "auth": "spice",
2170          "port": 5920,
2171          "tls-port": 5921,
2172          "host": "0.0.0.0",
2173          "channels": [
2174             {
2175                "port": "54924",
2176                "family": "ipv4",
2177                "channel-type": 1,
2178                "connection-id": 1804289383,
2179                "host": "127.0.0.1",
2180                "channel-id": 0,
2181                "tls": true
2182             },
2183             {
2184                "port": "36710",
2185                "family": "ipv4",
2186                "channel-type": 4,
2187                "connection-id": 1804289383,
2188                "host": "127.0.0.1",
2189                "channel-id": 0,
2190                "tls": false
2191             },
2192             [ ... more channels follow ... ]
2193          ]
2194       }
2195    }
2196
2197 EQMP
2198
2199 #if defined(CONFIG_SPICE)
2200     {
2201         .name       = "query-spice",
2202         .args_type  = "",
2203         .mhandler.cmd_new = qmp_marshal_input_query_spice,
2204     },
2205 #endif
2206
2207 SQMP
2208 query-name
2209 ----------
2210
2211 Show VM name.
2212
2213 Return a json-object with the following information:
2214
2215 - "name": VM's name (json-string, optional)
2216
2217 Example:
2218
2219 -> { "execute": "query-name" }
2220 <- { "return": { "name": "qemu-name" } }
2221
2222 EQMP
2223
2224     {
2225         .name       = "query-name",
2226         .args_type  = "",
2227         .mhandler.cmd_new = qmp_marshal_input_query_name,
2228     },
2229
2230 SQMP
2231 query-uuid
2232 ----------
2233
2234 Show VM UUID.
2235
2236 Return a json-object with the following information:
2237
2238 - "UUID": Universally Unique Identifier (json-string)
2239
2240 Example:
2241
2242 -> { "execute": "query-uuid" }
2243 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2244
2245 EQMP
2246
2247     {
2248         .name       = "query-uuid",
2249         .args_type  = "",
2250         .mhandler.cmd_new = qmp_marshal_input_query_uuid,
2251     },
2252
2253 SQMP
2254 query-migrate
2255 -------------
2256
2257 Migration status.
2258
2259 Return a json-object. If migration is active there will be another json-object
2260 with RAM migration status and if block migration is active another one with
2261 block migration status.
2262
2263 The main json-object contains the following:
2264
2265 - "status": migration status (json-string)
2266      - Possible values: "active", "completed", "failed", "cancelled"
2267 - "total-time": total amount of ms since migration started.  If
2268                 migration has ended, it returns the total migration
2269                  time (json-int)
2270 - "ram": only present if "status" is "active", it is a json-object with the
2271   following RAM information (in bytes):
2272          - "transferred": amount transferred (json-int)
2273          - "remaining": amount remaining (json-int)
2274          - "total": total (json-int)
2275          - "duplicate": number of duplicated pages (json-int)
2276          - "normal" : number of normal pages transferred (json-int)
2277          - "normal-bytes" : number of normal bytes transferred (json-int)
2278 - "disk": only present if "status" is "active" and it is a block migration,
2279   it is a json-object with the following disk information (in bytes):
2280          - "transferred": amount transferred (json-int)
2281          - "remaining": amount remaining (json-int)
2282          - "total": total (json-int)
2283 - "xbzrle-cache": only present if XBZRLE is active.
2284   It is a json-object with the following XBZRLE information:
2285          - "cache-size": XBZRLE cache size
2286          - "bytes": total XBZRLE bytes transferred
2287          - "pages": number of XBZRLE compressed pages
2288          - "cache-miss": number of cache misses
2289          - "overflow": number of XBZRLE overflows
2290 Examples:
2291
2292 1. Before the first migration
2293
2294 -> { "execute": "query-migrate" }
2295 <- { "return": {} }
2296
2297 2. Migration is done and has succeeded
2298
2299 -> { "execute": "query-migrate" }
2300 <- { "return": {
2301         "status": "completed",
2302         "ram":{
2303           "transferred":123,
2304           "remaining":123,
2305           "total":246,
2306           "total-time":12345,
2307           "duplicate":123,
2308           "normal":123,
2309           "normal-bytes":123456
2310         }
2311      }
2312    }
2313
2314 3. Migration is done and has failed
2315
2316 -> { "execute": "query-migrate" }
2317 <- { "return": { "status": "failed" } }
2318
2319 4. Migration is being performed and is not a block migration:
2320
2321 -> { "execute": "query-migrate" }
2322 <- {
2323       "return":{
2324          "status":"active",
2325          "ram":{
2326             "transferred":123,
2327             "remaining":123,
2328             "total":246,
2329             "total-time":12345,
2330             "duplicate":123,
2331             "normal":123,
2332             "normal-bytes":123456
2333          }
2334       }
2335    }
2336
2337 5. Migration is being performed and is a block migration:
2338
2339 -> { "execute": "query-migrate" }
2340 <- {
2341       "return":{
2342          "status":"active",
2343          "ram":{
2344             "total":1057024,
2345             "remaining":1053304,
2346             "transferred":3720,
2347             "total-time":12345,
2348             "duplicate":123,
2349             "normal":123,
2350             "normal-bytes":123456
2351          },
2352          "disk":{
2353             "total":20971520,
2354             "remaining":20880384,
2355             "transferred":91136
2356          }
2357       }
2358    }
2359
2360 6. Migration is being performed and XBZRLE is active:
2361
2362 -> { "execute": "query-migrate" }
2363 <- {
2364       "return":{
2365          "status":"active",
2366          "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
2367          "ram":{
2368             "total":1057024,
2369             "remaining":1053304,
2370             "transferred":3720,
2371             "total-time":12345,
2372             "duplicate":10,
2373             "normal":3333,
2374             "normal-bytes":3412992
2375          },
2376          "xbzrle-cache":{
2377             "cache-size":67108864,
2378             "bytes":20971520,
2379             "pages":2444343,
2380             "cache-miss":2244,
2381             "overflow":34434
2382          }
2383       }
2384    }
2385
2386 EQMP
2387
2388     {
2389         .name       = "query-migrate",
2390         .args_type  = "",
2391         .mhandler.cmd_new = qmp_marshal_input_query_migrate,
2392     },
2393
2394 SQMP
2395 migrate-set-capabilities
2396 -------
2397
2398 Enable/Disable migration capabilities
2399
2400 - "xbzrle": xbzrle support
2401
2402 Arguments:
2403
2404 Example:
2405
2406 -> { "execute": "migrate-set-capabilities" , "arguments":
2407      { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
2408
2409 EQMP
2410
2411     {
2412         .name       = "migrate-set-capabilities",
2413         .args_type  = "capabilities:O",
2414         .params     = "capability:s,state:b",
2415         .mhandler.cmd_new = qmp_marshal_input_migrate_set_capabilities,
2416     },
2417 SQMP
2418 query-migrate-capabilities
2419 -------
2420
2421 Query current migration capabilities
2422
2423 - "capabilities": migration capabilities state
2424          - "xbzrle" : XBZRLE state (json-bool)
2425
2426 Arguments:
2427
2428 Example:
2429
2430 -> { "execute": "query-migrate-capabilities" }
2431 <- { "return": {
2432         "capabilities" :  [ { "capability" : "xbzrle", "state" : false } ]
2433      }
2434    }
2435 EQMP
2436
2437     {
2438         .name       = "query-migrate-capabilities",
2439         .args_type  = "",
2440         .mhandler.cmd_new = qmp_marshal_input_query_migrate_capabilities,
2441     },
2442
2443 SQMP
2444 query-balloon
2445 -------------
2446
2447 Show balloon information.
2448
2449 Make an asynchronous request for balloon info. When the request completes a
2450 json-object will be returned containing the following data:
2451
2452 - "actual": current balloon value in bytes (json-int)
2453 - "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
2454 - "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
2455 - "major_page_faults": Number of major faults (json-int, optional)
2456 - "minor_page_faults": Number of minor faults (json-int, optional)
2457 - "free_mem": Total amount of free and unused memory in
2458               bytes (json-int, optional)
2459 - "total_mem": Total amount of available memory in bytes (json-int, optional)
2460
2461 Example:
2462
2463 -> { "execute": "query-balloon" }
2464 <- {
2465       "return":{
2466          "actual":1073741824,
2467          "mem_swapped_in":0,
2468          "mem_swapped_out":0,
2469          "major_page_faults":142,
2470          "minor_page_faults":239245,
2471          "free_mem":1014185984,
2472          "total_mem":1044668416
2473       }
2474    }
2475
2476 EQMP
2477
2478     {
2479         .name       = "query-balloon",
2480         .args_type  = "",
2481         .mhandler.cmd_new = qmp_marshal_input_query_balloon,
2482     },
2483
2484     {
2485         .name       = "query-block-jobs",
2486         .args_type  = "",
2487         .mhandler.cmd_new = qmp_marshal_input_query_block_jobs,
2488     },
2489
2490     {
2491         .name       = "qom-list",
2492         .args_type  = "path:s",
2493         .mhandler.cmd_new = qmp_marshal_input_qom_list,
2494     },
2495
2496     {
2497         .name       = "qom-set",
2498         .args_type  = "path:s,property:s,value:q",
2499         .mhandler.cmd_new = qmp_qom_set,
2500     },
2501
2502     {
2503         .name       = "qom-get",
2504         .args_type  = "path:s,property:s",
2505         .mhandler.cmd_new = qmp_qom_get,
2506     },
2507
2508     {
2509         .name       = "change-vnc-password",
2510         .args_type  = "password:s",
2511         .mhandler.cmd_new = qmp_marshal_input_change_vnc_password,
2512     },
2513     {
2514         .name       = "qom-list-types",
2515         .args_type  = "implements:s?,abstract:b?",
2516         .mhandler.cmd_new = qmp_marshal_input_qom_list_types,
2517     },
2518
2519     {
2520         .name       = "device-list-properties",
2521         .args_type  = "typename:s",
2522         .mhandler.cmd_new = qmp_marshal_input_device_list_properties,
2523     },
2524
2525     {
2526         .name       = "query-machines",
2527         .args_type  = "",
2528         .mhandler.cmd_new = qmp_marshal_input_query_machines,
2529     },
2530
2531     {
2532         .name       = "query-cpu-definitions",
2533         .args_type  = "",
2534         .mhandler.cmd_new = qmp_marshal_input_query_cpu_definitions,
2535     },
2536
2537     {
2538         .name       = "query-target",
2539         .args_type  = "",
2540         .mhandler.cmd_new = qmp_marshal_input_query_target,
2541     },