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-commit",
 796         .args_type  = "device:B,base:s?,top:s,speed:o?",
 797         .mhandler.cmd_new = qmp_marshal_input_block_commit,
 798     },
 799
 800     {
 801         .name       = "block-job-set-speed",
 802         .args_type  = "device:B,speed:o",
 803         .mhandler.cmd_new = qmp_marshal_input_block_job_set_speed,
 804     },
 805
 806     {
 807         .name       = "block-job-cancel",
 808         .args_type  = "device:B",
 809         .mhandler.cmd_new = qmp_marshal_input_block_job_cancel,
 810     },
 811     {
 812         .name       = "transaction",
 813         .args_type  = "actions:q",
 814         .mhandler.cmd_new = qmp_marshal_input_transaction,
 815     },
 816
 817 SQMP
 818 transaction
 819 -----------
 820
 821 Atomically operate on one or more block devices.  The only supported
 822 operation for now is snapshotting.  If there is any failure performing
 823 any of the operations, all snapshots for the group are abandoned, and
 824 the original disks pre-snapshot attempt are used.
 825
 826 A list of dictionaries is accepted, that contains the actions to be performed.
 827 For snapshots this is the device, the file to use for the new snapshot,
 828 and the format.  The default format, if not specified, is qcow2.
 829
 830 Each new snapshot defaults to being created by QEMU (wiping any
 831 contents if the file already exists), but it is also possible to reuse
 832 an externally-created file.  In the latter case, you should ensure that
 833 the new image file has the same contents as the current one; QEMU cannot
 834 perform any meaningful check.  Typically this is achieved by using the
 835 current image file as the backing file for the new image.
 836
 837 Arguments:
 838
 839 actions array:
 840     - "type": the operation to perform.  The only supported
 841       value is "blockdev-snapshot-sync". (json-string)
 842     - "data": a dictionary.  The contents depend on the value
 843       of "type".  When "type" is "blockdev-snapshot-sync":
 844       - "device": device name to snapshot (json-string)
 845       - "snapshot-file": name of new image file (json-string)
 846       - "format": format of new image (json-string, optional)
 847       - "mode": whether and how QEMU should create the snapshot file
 848         (NewImageMode, optional, default "absolute-paths")
 849
 850 Example:
 851
 852 -> { "execute": "transaction",
 853      "arguments": { "actions": [
 854          { 'type': 'blockdev-snapshot-sync', 'data' : { "device": "ide-hd0",
 855                                          "snapshot-file": "/some/place/my-image",
 856                                          "format": "qcow2" } },
 857          { 'type': 'blockdev-snapshot-sync', 'data' : { "device": "ide-hd1",
 858                                          "snapshot-file": "/some/place/my-image2",
 859                                          "mode": "existing",
 860                                          "format": "qcow2" } } ] } }
 861 <- { "return": {} }
 862
 863 EQMP
 864
 865     {
 866         .name       = "blockdev-snapshot-sync",
 867         .args_type  = "device:B,snapshot-file:s,format:s?,mode:s?",
 868         .mhandler.cmd_new = qmp_marshal_input_blockdev_snapshot_sync,
 869     },
 870
 871 SQMP
 872 blockdev-snapshot-sync
 873 ----------------------
 874
 875 Synchronous snapshot of a block device. snapshot-file specifies the
 876 target of the new image. If the file exists, or if it is a device, the
 877 snapshot will be created in the existing file/device. If does not
 878 exist, a new file will be created. format specifies the format of the
 879 snapshot image, default is qcow2.
 880
 881 Arguments:
 882
 883 - "device": device name to snapshot (json-string)
 884 - "snapshot-file": name of new image file (json-string)
 885 - "mode": whether and how QEMU should create the snapshot file
 886   (NewImageMode, optional, default "absolute-paths")
 887 - "format": format of new image (json-string, optional)
 888
 889 Example:
 890
 891 -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
 892                                                          "snapshot-file":
 893                                                         "/some/place/my-image",
 894                                                         "format": "qcow2" } }
 895 <- { "return": {} }
 896
 897 EQMP
 898
 899     {
 900         .name       = "balloon",
 901         .args_type  = "value:M",
 902         .mhandler.cmd_new = qmp_marshal_input_balloon,
 903     },
 904
 905 SQMP
 906 balloon
 907 -------
 908
 909 Request VM to change its memory allocation (in bytes).
 910
 911 Arguments:
 912
 913 - "value": New memory allocation (json-int)
 914
 915 Example:
 916
 917 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
 918 <- { "return": {} }
 919
 920 EQMP
 921
 922     {
 923         .name       = "set_link",
 924         .args_type  = "name:s,up:b",
 925         .mhandler.cmd_new = qmp_marshal_input_set_link,
 926     },
 927
 928 SQMP
 929 set_link
 930 --------
 931
 932 Change the link status of a network adapter.
 933
 934 Arguments:
 935
 936 - "name": network device name (json-string)
 937 - "up": status is up (json-bool)
 938
 939 Example:
 940
 941 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
 942 <- { "return": {} }
 943
 944 EQMP
 945
 946     {
 947         .name       = "getfd",
 948         .args_type  = "fdname:s",
 949         .params     = "getfd name",
 950         .help       = "receive a file descriptor via SCM rights and assign it a name",
 951         .mhandler.cmd_new = qmp_marshal_input_getfd,
 952     },
 953
 954 SQMP
 955 getfd
 956 -----
 957
 958 Receive a file descriptor via SCM rights and assign it a name.
 959
 960 Arguments:
 961
 962 - "fdname": file descriptor name (json-string)
 963
 964 Example:
 965
 966 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
 967 <- { "return": {} }
 968
 969 Notes:
 970
 971 (1) If the name specified by the "fdname" argument already exists,
 972     the file descriptor assigned to it will be closed and replaced
 973     by the received file descriptor.
 974 (2) The 'closefd' command can be used to explicitly close the file
 975     descriptor when it is no longer needed.
 976
 977 EQMP
 978
 979     {
 980         .name       = "closefd",
 981         .args_type  = "fdname:s",
 982         .params     = "closefd name",
 983         .help       = "close a file descriptor previously passed via SCM rights",
 984         .mhandler.cmd_new = qmp_marshal_input_closefd,
 985     },
 986
 987 SQMP
 988 closefd
 989 -------
 990
 991 Close a file descriptor previously passed via SCM rights.
 992
 993 Arguments:
 994
 995 - "fdname": file descriptor name (json-string)
 996
 997 Example:
 998
 999 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1000 <- { "return": {} }
1001
1002 EQMP
1003
1004      {
1005         .name       = "add-fd",
1006         .args_type  = "fdset-id:i?,opaque:s?",
1007         .params     = "add-fd fdset-id opaque",
1008         .help       = "Add a file descriptor, that was passed via SCM rights, to an fd set",
1009         .mhandler.cmd_new = qmp_marshal_input_add_fd,
1010     },
1011
1012 SQMP
1013 add-fd
1014 -------
1015
1016 Add a file descriptor, that was passed via SCM rights, to an fd set.
1017
1018 Arguments:
1019
1020 - "fdset-id": The ID of the fd set to add the file descriptor to.
1021               (json-int, optional)
1022 - "opaque": A free-form string that can be used to describe the fd.
1023             (json-string, optional)
1024
1025 Return a json-object with the following information:
1026
1027 - "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1028 - "fd": The file descriptor that was received via SCM rights and added to the
1029         fd set. (json-int)
1030
1031 Example:
1032
1033 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1034 <- { "return": { "fdset-id": 1, "fd": 3 } }
1035
1036 Notes:
1037
1038 (1) The list of fd sets is shared by all monitor connections.
1039 (2) If "fdset-id" is not specified, a new fd set will be created.
1040
1041 EQMP
1042
1043      {
1044         .name       = "remove-fd",
1045         .args_type  = "fdset-id:i,fd:i?",
1046         .params     = "remove-fd fdset-id fd",
1047         .help       = "Remove a file descriptor from an fd set",
1048         .mhandler.cmd_new = qmp_marshal_input_remove_fd,
1049     },
1050
1051 SQMP
1052 remove-fd
1053 ---------
1054
1055 Remove a file descriptor from an fd set.
1056
1057 Arguments:
1058
1059 - "fdset-id": The ID of the fd set that the file descriptor belongs to.
1060               (json-int)
1061 - "fd": The file descriptor that is to be removed. (json-int, optional)
1062
1063 Example:
1064
1065 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1066 <- { "return": {} }
1067
1068 Notes:
1069
1070 (1) The list of fd sets is shared by all monitor connections.
1071 (2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1072     removed.
1073
1074 EQMP
1075
1076     {
1077         .name       = "query-fdsets",
1078         .args_type  = "",
1079         .help       = "Return information describing all fd sets",
1080         .mhandler.cmd_new = qmp_marshal_input_query_fdsets,
1081     },
1082
1083 SQMP
1084 query-fdsets
1085 -------------
1086
1087 Return information describing all fd sets.
1088
1089 Arguments: None
1090
1091 Example:
1092
1093 -> { "execute": "query-fdsets" }
1094 <- { "return": [
1095        {
1096          "fds": [
1097            {
1098              "fd": 30,
1099              "opaque": "rdonly:/path/to/file"
1100            },
1101            {
1102              "fd": 24,
1103              "opaque": "rdwr:/path/to/file"
1104            }
1105          ],
1106          "fdset-id": 1
1107        },
1108        {
1109          "fds": [
1110            {
1111              "fd": 28
1112            },
1113            {
1114              "fd": 29
1115            }
1116          ],
1117          "fdset-id": 0
1118        }
1119      ]
1120    }
1121
1122 Note: The list of fd sets is shared by all monitor connections.
1123
1124 EQMP
1125
1126     {
1127         .name       = "block_passwd",
1128         .args_type  = "device:B,password:s",
1129         .mhandler.cmd_new = qmp_marshal_input_block_passwd,
1130     },
1131
1132 SQMP
1133 block_passwd
1134 ------------
1135
1136 Set the password of encrypted block devices.
1137
1138 Arguments:
1139
1140 - "device": device name (json-string)
1141 - "password": password (json-string)
1142
1143 Example:
1144
1145 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1146                                                "password": "12345" } }
1147 <- { "return": {} }
1148
1149 EQMP
1150
1151     {
1152         .name       = "block_set_io_throttle",
1153         .args_type  = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l",
1154         .mhandler.cmd_new = qmp_marshal_input_block_set_io_throttle,
1155     },
1156
1157 SQMP
1158 block_set_io_throttle
1159 ------------
1160
1161 Change I/O throttle limits for a block drive.
1162
1163 Arguments:
1164
1165 - "device": device name (json-string)
1166 - "bps":  total throughput limit in bytes per second(json-int)
1167 - "bps_rd":  read throughput limit in bytes per second(json-int)
1168 - "bps_wr":  read throughput limit in bytes per second(json-int)
1169 - "iops":  total I/O operations per second(json-int)
1170 - "iops_rd":  read I/O operations per second(json-int)
1171 - "iops_wr":  write I/O operations per second(json-int)
1172
1173 Example:
1174
1175 -> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
1176                                                "bps": "1000000",
1177                                                "bps_rd": "0",
1178                                                "bps_wr": "0",
1179                                                "iops": "0",
1180                                                "iops_rd": "0",
1181                                                "iops_wr": "0" } }
1182 <- { "return": {} }
1183
1184 EQMP
1185
1186     {
1187         .name       = "set_password",
1188         .args_type  = "protocol:s,password:s,connected:s?",
1189         .mhandler.cmd_new = qmp_marshal_input_set_password,
1190     },
1191
1192 SQMP
1193 set_password
1194 ------------
1195
1196 Set the password for vnc/spice protocols.
1197
1198 Arguments:
1199
1200 - "protocol": protocol name (json-string)
1201 - "password": password (json-string)
1202 - "connected": [ keep | disconnect | fail ] (josn-string, optional)
1203
1204 Example:
1205
1206 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
1207                                                "password": "secret" } }
1208 <- { "return": {} }
1209
1210 EQMP
1211
1212     {
1213         .name       = "expire_password",
1214         .args_type  = "protocol:s,time:s",
1215         .mhandler.cmd_new = qmp_marshal_input_expire_password,
1216     },
1217
1218 SQMP
1219 expire_password
1220 ---------------
1221
1222 Set the password expire time for vnc/spice protocols.
1223
1224 Arguments:
1225
1226 - "protocol": protocol name (json-string)
1227 - "time": [ now | never | +secs | secs ] (json-string)
1228
1229 Example:
1230
1231 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
1232                                                   "time": "+60" } }
1233 <- { "return": {} }
1234
1235 EQMP
1236
1237     {
1238         .name       = "add_client",
1239         .args_type  = "protocol:s,fdname:s,skipauth:b?,tls:b?",
1240         .params     = "protocol fdname skipauth tls",
1241         .help       = "add a graphics client",
1242         .user_print = monitor_user_noop,
1243         .mhandler.cmd_new = add_graphics_client,
1244     },
1245
1246 SQMP
1247 add_client
1248 ----------
1249
1250 Add a graphics client
1251
1252 Arguments:
1253
1254 - "protocol": protocol name (json-string)
1255 - "fdname": file descriptor name (json-string)
1256 - "skipauth": whether to skip authentication (json-bool, optional)
1257 - "tls": whether to perform TLS (json-bool, optional)
1258
1259 Example:
1260
1261 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
1262                                              "fdname": "myclient" } }
1263 <- { "return": {} }
1264
1265 EQMP
1266     {
1267         .name       = "qmp_capabilities",
1268         .args_type  = "",
1269         .params     = "",
1270         .help       = "enable QMP capabilities",
1271         .user_print = monitor_user_noop,
1272         .mhandler.cmd_new = do_qmp_capabilities,
1273     },
1274
1275 SQMP
1276 qmp_capabilities
1277 ----------------
1278
1279 Enable QMP capabilities.
1280
1281 Arguments: None.
1282
1283 Example:
1284
1285 -> { "execute": "qmp_capabilities" }
1286 <- { "return": {} }
1287
1288 Note: This command must be issued before issuing any other command.
1289
1290 EQMP
1291
1292     {
1293         .name       = "human-monitor-command",
1294         .args_type  = "command-line:s,cpu-index:i?",
1295         .mhandler.cmd_new = qmp_marshal_input_human_monitor_command,
1296     },
1297
1298 SQMP
1299 human-monitor-command
1300 ---------------------
1301
1302 Execute a Human Monitor command.
1303
1304 Arguments:
1305
1306 - command-line: the command name and its arguments, just like the
1307                 Human Monitor's shell (json-string)
1308 - cpu-index: select the CPU number to be used by commands which access CPU
1309              data, like 'info registers'. The Monitor selects CPU 0 if this
1310              argument is not provided (json-int, optional)
1311
1312 Example:
1313
1314 -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
1315 <- { "return": "kvm support: enabled\r\n" }
1316
1317 Notes:
1318
1319 (1) The Human Monitor is NOT an stable interface, this means that command
1320     names, arguments and responses can change or be removed at ANY time.
1321     Applications that rely on long term stability guarantees should NOT
1322     use this command
1323
1324 (2) Limitations:
1325
1326     o This command is stateless, this means that commands that depend
1327       on state information (such as getfd) might not work
1328
1329     o Commands that prompt the user for data (eg. 'cont' when the block
1330       device is encrypted) don't currently work
1331
1332 3. Query Commands
1333 =================
1334
1335 HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
1336 HXCOMM this! We will possibly move query commands definitions inside those
1337 HXCOMM sections, just like regular commands.
1338
1339 EQMP
1340
1341 SQMP
1342 query-version
1343 -------------
1344
1345 Show QEMU version.
1346
1347 Return a json-object with the following information:
1348
1349 - "qemu": A json-object containing three integer values:
1350     - "major": QEMU's major version (json-int)
1351     - "minor": QEMU's minor version (json-int)
1352     - "micro": QEMU's micro version (json-int)
1353 - "package": package's version (json-string)
1354
1355 Example:
1356
1357 -> { "execute": "query-version" }
1358 <- {
1359       "return":{
1360          "qemu":{
1361             "major":0,
1362             "minor":11,
1363             "micro":5
1364          },
1365          "package":""
1366       }
1367    }
1368
1369 EQMP
1370
1371     {
1372         .name       = "query-version",
1373         .args_type  = "",
1374         .mhandler.cmd_new = qmp_marshal_input_query_version,
1375     },
1376
1377 SQMP
1378 query-commands
1379 --------------
1380
1381 List QMP available commands.
1382
1383 Each command is represented by a json-object, the returned value is a json-array
1384 of all commands.
1385
1386 Each json-object contain:
1387
1388 - "name": command's name (json-string)
1389
1390 Example:
1391
1392 -> { "execute": "query-commands" }
1393 <- {
1394       "return":[
1395          {
1396             "name":"query-balloon"
1397          },
1398          {
1399             "name":"system_powerdown"
1400          }
1401       ]
1402    }
1403
1404 Note: This example has been shortened as the real response is too long.
1405
1406 EQMP
1407
1408     {
1409         .name       = "query-commands",
1410         .args_type  = "",
1411         .mhandler.cmd_new = qmp_marshal_input_query_commands,
1412     },
1413
1414 SQMP
1415 query-events
1416 --------------
1417
1418 List QMP available events.
1419
1420 Each event is represented by a json-object, the returned value is a json-array
1421 of all events.
1422
1423 Each json-object contains:
1424
1425 - "name": event's name (json-string)
1426
1427 Example:
1428
1429 -> { "execute": "query-events" }
1430 <- {
1431       "return":[
1432          {
1433             "name":"SHUTDOWN"
1434          },
1435          {
1436             "name":"RESET"
1437          }
1438       ]
1439    }
1440
1441 Note: This example has been shortened as the real response is too long.
1442
1443 EQMP
1444
1445     {
1446         .name       = "query-events",
1447         .args_type  = "",
1448         .mhandler.cmd_new = qmp_marshal_input_query_events,
1449     },
1450
1451 SQMP
1452 query-chardev
1453 -------------
1454
1455 Each device is represented by a json-object. The returned value is a json-array
1456 of all devices.
1457
1458 Each json-object contain the following:
1459
1460 - "label": device's label (json-string)
1461 - "filename": device's file (json-string)
1462
1463 Example:
1464
1465 -> { "execute": "query-chardev" }
1466 <- {
1467       "return":[
1468          {
1469             "label":"monitor",
1470             "filename":"stdio"
1471          },
1472          {
1473             "label":"serial0",
1474             "filename":"vc"
1475          }
1476       ]
1477    }
1478
1479 EQMP
1480
1481     {
1482         .name       = "query-chardev",
1483         .args_type  = "",
1484         .mhandler.cmd_new = qmp_marshal_input_query_chardev,
1485     },
1486
1487 SQMP
1488 query-block
1489 -----------
1490
1491 Show the block devices.
1492
1493 Each block device information is stored in a json-object and the returned value
1494 is a json-array of all devices.
1495
1496 Each json-object contain the following:
1497
1498 - "device": device name (json-string)
1499 - "type": device type (json-string)
1500          - deprecated, retained for backward compatibility
1501          - Possible values: "unknown"
1502 - "removable": true if the device is removable, false otherwise (json-bool)
1503 - "locked": true if the device is locked, false otherwise (json-bool)
1504 - "tray-open": only present if removable, true if the device has a tray,
1505                and it is open (json-bool)
1506 - "inserted": only present if the device is inserted, it is a json-object
1507    containing the following:
1508          - "file": device file name (json-string)
1509          - "ro": true if read-only, false otherwise (json-bool)
1510          - "drv": driver format name (json-string)
1511              - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1512                                 "file", "file", "ftp", "ftps", "host_cdrom",
1513                                 "host_device", "host_floppy", "http", "https",
1514                                 "nbd", "parallels", "qcow", "qcow2", "raw",
1515                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1516          - "backing_file": backing file name (json-string, optional)
1517          - "backing_file_depth": number of files in the backing file chain (json-int)
1518          - "encrypted": true if encrypted, false otherwise (json-bool)
1519          - "bps": limit total bytes per second (json-int)
1520          - "bps_rd": limit read bytes per second (json-int)
1521          - "bps_wr": limit write bytes per second (json-int)
1522          - "iops": limit total I/O operations per second (json-int)
1523          - "iops_rd": limit read operations per second (json-int)
1524          - "iops_wr": limit write operations per second (json-int)
1525
1526 - "io-status": I/O operation status, only present if the device supports it
1527                and the VM is configured to stop on errors. It's always reset
1528                to "ok" when the "cont" command is issued (json_string, optional)
1529              - Possible values: "ok", "failed", "nospace"
1530
1531 Example:
1532
1533 -> { "execute": "query-block" }
1534 <- {
1535       "return":[
1536          {
1537             "io-status": "ok",
1538             "device":"ide0-hd0",
1539             "locked":false,
1540             "removable":false,
1541             "inserted":{
1542                "ro":false,
1543                "drv":"qcow2",
1544                "encrypted":false,
1545                "file":"disks/test.img",
1546                "backing_file_depth":0,
1547                "bps":1000000,
1548                "bps_rd":0,
1549                "bps_wr":0,
1550                "iops":1000000,
1551                "iops_rd":0,
1552                "iops_wr":0,
1553             },
1554             "type":"unknown"
1555          },
1556          {
1557             "io-status": "ok",
1558             "device":"ide1-cd0",
1559             "locked":false,
1560             "removable":true,
1561             "type":"unknown"
1562          },
1563          {
1564             "device":"floppy0",
1565             "locked":false,
1566             "removable":true,
1567             "type":"unknown"
1568          },
1569          {
1570             "device":"sd0",
1571             "locked":false,
1572             "removable":true,
1573             "type":"unknown"
1574          }
1575       ]
1576    }
1577
1578 EQMP
1579
1580     {
1581         .name       = "query-block",
1582         .args_type  = "",
1583         .mhandler.cmd_new = qmp_marshal_input_query_block,
1584     },
1585
1586 SQMP
1587 query-blockstats
1588 ----------------
1589
1590 Show block device statistics.
1591
1592 Each device statistic information is stored in a json-object and the returned
1593 value is a json-array of all devices.
1594
1595 Each json-object contain the following:
1596
1597 - "device": device name (json-string)
1598 - "stats": A json-object with the statistics information, it contains:
1599     - "rd_bytes": bytes read (json-int)
1600     - "wr_bytes": bytes written (json-int)
1601     - "rd_operations": read operations (json-int)
1602     - "wr_operations": write operations (json-int)
1603     - "flush_operations": cache flush operations (json-int)
1604     - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
1605     - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
1606     - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
1607     - "wr_highest_offset": Highest offset of a sector written since the
1608                            BlockDriverState has been opened (json-int)
1609 - "parent": Contains recursively the statistics of the underlying
1610             protocol (e.g. the host file for a qcow2 image). If there is
1611             no underlying protocol, this field is omitted
1612             (json-object, optional)
1613
1614 Example:
1615
1616 -> { "execute": "query-blockstats" }
1617 <- {
1618       "return":[
1619          {
1620             "device":"ide0-hd0",
1621             "parent":{
1622                "stats":{
1623                   "wr_highest_offset":3686448128,
1624                   "wr_bytes":9786368,
1625                   "wr_operations":751,
1626                   "rd_bytes":122567168,
1627                   "rd_operations":36772
1628                   "wr_total_times_ns":313253456
1629                   "rd_total_times_ns":3465673657
1630                   "flush_total_times_ns":49653
1631                   "flush_operations":61,
1632                }
1633             },
1634             "stats":{
1635                "wr_highest_offset":2821110784,
1636                "wr_bytes":9786368,
1637                "wr_operations":692,
1638                "rd_bytes":122739200,
1639                "rd_operations":36604
1640                "flush_operations":51,
1641                "wr_total_times_ns":313253456
1642                "rd_total_times_ns":3465673657
1643                "flush_total_times_ns":49653
1644             }
1645          },
1646          {
1647             "device":"ide1-cd0",
1648             "stats":{
1649                "wr_highest_offset":0,
1650                "wr_bytes":0,
1651                "wr_operations":0,
1652                "rd_bytes":0,
1653                "rd_operations":0
1654                "flush_operations":0,
1655                "wr_total_times_ns":0
1656                "rd_total_times_ns":0
1657                "flush_total_times_ns":0
1658             }
1659          },
1660          {
1661             "device":"floppy0",
1662             "stats":{
1663                "wr_highest_offset":0,
1664                "wr_bytes":0,
1665                "wr_operations":0,
1666                "rd_bytes":0,
1667                "rd_operations":0
1668                "flush_operations":0,
1669                "wr_total_times_ns":0
1670                "rd_total_times_ns":0
1671                "flush_total_times_ns":0
1672             }
1673          },
1674          {
1675             "device":"sd0",
1676             "stats":{
1677                "wr_highest_offset":0,
1678                "wr_bytes":0,
1679                "wr_operations":0,
1680                "rd_bytes":0,
1681                "rd_operations":0
1682                "flush_operations":0,
1683                "wr_total_times_ns":0
1684                "rd_total_times_ns":0
1685                "flush_total_times_ns":0
1686             }
1687          }
1688       ]
1689    }
1690
1691 EQMP
1692
1693     {
1694         .name       = "query-blockstats",
1695         .args_type  = "",
1696         .mhandler.cmd_new = qmp_marshal_input_query_blockstats,
1697     },
1698
1699 SQMP
1700 query-cpus
1701 ----------
1702
1703 Show CPU information.
1704
1705 Return a json-array. Each CPU is represented by a json-object, which contains:
1706
1707 - "CPU": CPU index (json-int)
1708 - "current": true if this is the current CPU, false otherwise (json-bool)
1709 - "halted": true if the cpu is halted, false otherwise (json-bool)
1710 - Current program counter. The key's name depends on the architecture:
1711      "pc": i386/x86_64 (json-int)
1712      "nip": PPC (json-int)
1713      "pc" and "npc": sparc (json-int)
1714      "PC": mips (json-int)
1715 - "thread_id": ID of the underlying host thread (json-int)
1716
1717 Example:
1718
1719 -> { "execute": "query-cpus" }
1720 <- {
1721       "return":[
1722          {
1723             "CPU":0,
1724             "current":true,
1725             "halted":false,
1726             "pc":3227107138
1727             "thread_id":3134
1728          },
1729          {
1730             "CPU":1,
1731             "current":false,
1732             "halted":true,
1733             "pc":7108165
1734             "thread_id":3135
1735          }
1736       ]
1737    }
1738
1739 EQMP
1740
1741     {
1742         .name       = "query-cpus",
1743         .args_type  = "",
1744         .mhandler.cmd_new = qmp_marshal_input_query_cpus,
1745     },
1746
1747 SQMP
1748 query-pci
1749 ---------
1750
1751 PCI buses and devices information.
1752
1753 The returned value is a json-array of all buses. Each bus is represented by
1754 a json-object, which has a key with a json-array of all PCI devices attached
1755 to it. Each device is represented by a json-object.
1756
1757 The bus json-object contains the following:
1758
1759 - "bus": bus number (json-int)
1760 - "devices": a json-array of json-objects, each json-object represents a
1761              PCI device
1762
1763 The PCI device json-object contains the following:
1764
1765 - "bus": identical to the parent's bus number (json-int)
1766 - "slot": slot number (json-int)
1767 - "function": function number (json-int)
1768 - "class_info": a json-object containing:
1769      - "desc": device class description (json-string, optional)
1770      - "class": device class number (json-int)
1771 - "id": a json-object containing:
1772      - "device": device ID (json-int)
1773      - "vendor": vendor ID (json-int)
1774 - "irq": device's IRQ if assigned (json-int, optional)
1775 - "qdev_id": qdev id string (json-string)
1776 - "pci_bridge": It's a json-object, only present if this device is a
1777                 PCI bridge, contains:
1778      - "bus": bus number (json-int)
1779      - "secondary": secondary bus number (json-int)
1780      - "subordinate": subordinate bus number (json-int)
1781      - "io_range": I/O memory range information, a json-object with the
1782                    following members:
1783                  - "base": base address, in bytes (json-int)
1784                  - "limit": limit address, in bytes (json-int)
1785      - "memory_range": memory range information, a json-object with the
1786                        following members:
1787                  - "base": base address, in bytes (json-int)
1788                  - "limit": limit address, in bytes (json-int)
1789      - "prefetchable_range": Prefetchable memory range information, a
1790                              json-object with the following members:
1791                  - "base": base address, in bytes (json-int)
1792                  - "limit": limit address, in bytes (json-int)
1793      - "devices": a json-array of PCI devices if there's any attached, each
1794                   each element is represented by a json-object, which contains
1795                   the same members of the 'PCI device json-object' described
1796                   above (optional)
1797 - "regions": a json-array of json-objects, each json-object represents a
1798              memory region of this device
1799
1800 The memory range json-object contains the following:
1801
1802 - "base": base memory address (json-int)
1803 - "limit": limit value (json-int)
1804
1805 The region json-object can be an I/O region or a memory region, an I/O region
1806 json-object contains the following:
1807
1808 - "type": "io" (json-string, fixed)
1809 - "bar": BAR number (json-int)
1810 - "address": memory address (json-int)
1811 - "size": memory size (json-int)
1812
1813 A memory region json-object contains the following:
1814
1815 - "type": "memory" (json-string, fixed)
1816 - "bar": BAR number (json-int)
1817 - "address": memory address (json-int)
1818 - "size": memory size (json-int)
1819 - "mem_type_64": true or false (json-bool)
1820 - "prefetch": true or false (json-bool)
1821
1822 Example:
1823
1824 -> { "execute": "query-pci" }
1825 <- {
1826       "return":[
1827          {
1828             "bus":0,
1829             "devices":[
1830                {
1831                   "bus":0,
1832                   "qdev_id":"",
1833                   "slot":0,
1834                   "class_info":{
1835                      "class":1536,
1836                      "desc":"Host bridge"
1837                   },
1838                   "id":{
1839                      "device":32902,
1840                      "vendor":4663
1841                   },
1842                   "function":0,
1843                   "regions":[
1844
1845                   ]
1846                },
1847                {
1848                   "bus":0,
1849                   "qdev_id":"",
1850                   "slot":1,
1851                   "class_info":{
1852                      "class":1537,
1853                      "desc":"ISA bridge"
1854                   },
1855                   "id":{
1856                      "device":32902,
1857                      "vendor":28672
1858                   },
1859                   "function":0,
1860                   "regions":[
1861
1862                   ]
1863                },
1864                {
1865                   "bus":0,
1866                   "qdev_id":"",
1867                   "slot":1,
1868                   "class_info":{
1869                      "class":257,
1870                      "desc":"IDE controller"
1871                   },
1872                   "id":{
1873                      "device":32902,
1874                      "vendor":28688
1875                   },
1876                   "function":1,
1877                   "regions":[
1878                      {
1879                         "bar":4,
1880                         "size":16,
1881                         "address":49152,
1882                         "type":"io"
1883                      }
1884                   ]
1885                },
1886                {
1887                   "bus":0,
1888                   "qdev_id":"",
1889                   "slot":2,
1890                   "class_info":{
1891                      "class":768,
1892                      "desc":"VGA controller"
1893                   },
1894                   "id":{
1895                      "device":4115,
1896                      "vendor":184
1897                   },
1898                   "function":0,
1899                   "regions":[
1900                      {
1901                         "prefetch":true,
1902                         "mem_type_64":false,
1903                         "bar":0,
1904                         "size":33554432,
1905                         "address":4026531840,
1906                         "type":"memory"
1907                      },
1908                      {
1909                         "prefetch":false,
1910                         "mem_type_64":false,
1911                         "bar":1,
1912                         "size":4096,
1913                         "address":4060086272,
1914                         "type":"memory"
1915                      },
1916                      {
1917                         "prefetch":false,
1918                         "mem_type_64":false,
1919                         "bar":6,
1920                         "size":65536,
1921                         "address":-1,
1922                         "type":"memory"
1923                      }
1924                   ]
1925                },
1926                {
1927                   "bus":0,
1928                   "qdev_id":"",
1929                   "irq":11,
1930                   "slot":4,
1931                   "class_info":{
1932                      "class":1280,
1933                      "desc":"RAM controller"
1934                   },
1935                   "id":{
1936                      "device":6900,
1937                      "vendor":4098
1938                   },
1939                   "function":0,
1940                   "regions":[
1941                      {
1942                         "bar":0,
1943                         "size":32,
1944                         "address":49280,
1945                         "type":"io"
1946                      }
1947                   ]
1948                }
1949             ]
1950          }
1951       ]
1952    }
1953
1954 Note: This example has been shortened as the real response is too long.
1955
1956 EQMP
1957
1958     {
1959         .name       = "query-pci",
1960         .args_type  = "",
1961         .mhandler.cmd_new = qmp_marshal_input_query_pci,
1962     },
1963
1964 SQMP
1965 query-kvm
1966 ---------
1967
1968 Show KVM information.
1969
1970 Return a json-object with the following information:
1971
1972 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
1973 - "present": true if QEMU has KVM support, false otherwise (json-bool)
1974
1975 Example:
1976
1977 -> { "execute": "query-kvm" }
1978 <- { "return": { "enabled": true, "present": true } }
1979
1980 EQMP
1981
1982     {
1983         .name       = "query-kvm",
1984         .args_type  = "",
1985         .mhandler.cmd_new = qmp_marshal_input_query_kvm,
1986     },
1987
1988 SQMP
1989 query-status
1990 ------------
1991
1992 Return a json-object with the following information:
1993
1994 - "running": true if the VM is running, or false if it is paused (json-bool)
1995 - "singlestep": true if the VM is in single step mode,
1996                 false otherwise (json-bool)
1997 - "status": one of the following values (json-string)
1998     "debug" - QEMU is running on a debugger
1999     "inmigrate" - guest is paused waiting for an incoming migration
2000     "internal-error" - An internal error that prevents further guest
2001     execution has occurred
2002     "io-error" - the last IOP has failed and the device is configured
2003     to pause on I/O errors
2004     "paused" - guest has been paused via the 'stop' command
2005     "postmigrate" - guest is paused following a successful 'migrate'
2006     "prelaunch" - QEMU was started with -S and guest has not started
2007     "finish-migrate" - guest is paused to finish the migration process
2008     "restore-vm" - guest is paused to restore VM state
2009     "running" - guest is actively running
2010     "save-vm" - guest is paused to save the VM state
2011     "shutdown" - guest is shut down (and -no-shutdown is in use)
2012     "watchdog" - the watchdog action is configured to pause and
2013      has been triggered
2014
2015 Example:
2016
2017 -> { "execute": "query-status" }
2018 <- { "return": { "running": true, "singlestep": false, "status": "running" } }
2019
2020 EQMP
2021
2022     {
2023         .name       = "query-status",
2024         .args_type  = "",
2025         .mhandler.cmd_new = qmp_marshal_input_query_status,
2026     },
2027
2028 SQMP
2029 query-mice
2030 ----------
2031
2032 Show VM mice information.
2033
2034 Each mouse is represented by a json-object, the returned value is a json-array
2035 of all mice.
2036
2037 The mouse json-object contains the following:
2038
2039 - "name": mouse's name (json-string)
2040 - "index": mouse's index (json-int)
2041 - "current": true if this mouse is receiving events, false otherwise (json-bool)
2042 - "absolute": true if the mouse generates absolute input events (json-bool)
2043
2044 Example:
2045
2046 -> { "execute": "query-mice" }
2047 <- {
2048       "return":[
2049          {
2050             "name":"QEMU Microsoft Mouse",
2051             "index":0,
2052             "current":false,
2053             "absolute":false
2054          },
2055          {
2056             "name":"QEMU PS/2 Mouse",
2057             "index":1,
2058             "current":true,
2059             "absolute":true
2060          }
2061       ]
2062    }
2063
2064 EQMP
2065
2066     {
2067         .name       = "query-mice",
2068         .args_type  = "",
2069         .mhandler.cmd_new = qmp_marshal_input_query_mice,
2070     },
2071
2072 SQMP
2073 query-vnc
2074 ---------
2075
2076 Show VNC server information.
2077
2078 Return a json-object with server information. Connected clients are returned
2079 as a json-array of json-objects.
2080
2081 The main json-object contains the following:
2082
2083 - "enabled": true or false (json-bool)
2084 - "host": server's IP address (json-string)
2085 - "family": address family (json-string)
2086          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2087 - "service": server's port number (json-string)
2088 - "auth": authentication method (json-string)
2089          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2090                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2091                             "vencrypt+plain", "vencrypt+tls+none",
2092                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
2093                             "vencrypt+tls+vnc", "vencrypt+x509+none",
2094                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
2095                             "vencrypt+x509+vnc", "vnc"
2096 - "clients": a json-array of all connected clients
2097
2098 Clients are described by a json-object, each one contain the following:
2099
2100 - "host": client's IP address (json-string)
2101 - "family": address family (json-string)
2102          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2103 - "service": client's port number (json-string)
2104 - "x509_dname": TLS dname (json-string, optional)
2105 - "sasl_username": SASL username (json-string, optional)
2106
2107 Example:
2108
2109 -> { "execute": "query-vnc" }
2110 <- {
2111       "return":{
2112          "enabled":true,
2113          "host":"0.0.0.0",
2114          "service":"50402",
2115          "auth":"vnc",
2116          "family":"ipv4",
2117          "clients":[
2118             {
2119                "host":"127.0.0.1",
2120                "service":"50401",
2121                "family":"ipv4"
2122             }
2123          ]
2124       }
2125    }
2126
2127 EQMP
2128
2129     {
2130         .name       = "query-vnc",
2131         .args_type  = "",
2132         .mhandler.cmd_new = qmp_marshal_input_query_vnc,
2133     },
2134
2135 SQMP
2136 query-spice
2137 -----------
2138
2139 Show SPICE server information.
2140
2141 Return a json-object with server information. Connected clients are returned
2142 as a json-array of json-objects.
2143
2144 The main json-object contains the following:
2145
2146 - "enabled": true or false (json-bool)
2147 - "host": server's IP address (json-string)
2148 - "port": server's port number (json-int, optional)
2149 - "tls-port": server's port number (json-int, optional)
2150 - "auth": authentication method (json-string)
2151          - Possible values: "none", "spice"
2152 - "channels": a json-array of all active channels clients
2153
2154 Channels are described by a json-object, each one contain the following:
2155
2156 - "host": client's IP address (json-string)
2157 - "family": address family (json-string)
2158          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2159 - "port": client's port number (json-string)
2160 - "connection-id": spice connection id.  All channels with the same id
2161                    belong to the same spice session (json-int)
2162 - "channel-type": channel type.  "1" is the main control channel, filter for
2163                   this one if you want track spice sessions only (json-int)
2164 - "channel-id": channel id.  Usually "0", might be different needed when
2165                 multiple channels of the same type exist, such as multiple
2166                 display channels in a multihead setup (json-int)
2167 - "tls": whevener the channel is encrypted (json-bool)
2168
2169 Example:
2170
2171 -> { "execute": "query-spice" }
2172 <- {
2173       "return": {
2174          "enabled": true,
2175          "auth": "spice",
2176          "port": 5920,
2177          "tls-port": 5921,
2178          "host": "0.0.0.0",
2179          "channels": [
2180             {
2181                "port": "54924",
2182                "family": "ipv4",
2183                "channel-type": 1,
2184                "connection-id": 1804289383,
2185                "host": "127.0.0.1",
2186                "channel-id": 0,
2187                "tls": true
2188             },
2189             {
2190                "port": "36710",
2191                "family": "ipv4",
2192                "channel-type": 4,
2193                "connection-id": 1804289383,
2194                "host": "127.0.0.1",
2195                "channel-id": 0,
2196                "tls": false
2197             },
2198             [ ... more channels follow ... ]
2199          ]
2200       }
2201    }
2202
2203 EQMP
2204
2205 #if defined(CONFIG_SPICE)
2206     {
2207         .name       = "query-spice",
2208         .args_type  = "",
2209         .mhandler.cmd_new = qmp_marshal_input_query_spice,
2210     },
2211 #endif
2212
2213 SQMP
2214 query-name
2215 ----------
2216
2217 Show VM name.
2218
2219 Return a json-object with the following information:
2220
2221 - "name": VM's name (json-string, optional)
2222
2223 Example:
2224
2225 -> { "execute": "query-name" }
2226 <- { "return": { "name": "qemu-name" } }
2227
2228 EQMP
2229
2230     {
2231         .name       = "query-name",
2232         .args_type  = "",
2233         .mhandler.cmd_new = qmp_marshal_input_query_name,
2234     },
2235
2236 SQMP
2237 query-uuid
2238 ----------
2239
2240 Show VM UUID.
2241
2242 Return a json-object with the following information:
2243
2244 - "UUID": Universally Unique Identifier (json-string)
2245
2246 Example:
2247
2248 -> { "execute": "query-uuid" }
2249 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2250
2251 EQMP
2252
2253     {
2254         .name       = "query-uuid",
2255         .args_type  = "",
2256         .mhandler.cmd_new = qmp_marshal_input_query_uuid,
2257     },
2258
2259 SQMP
2260 query-migrate
2261 -------------
2262
2263 Migration status.
2264
2265 Return a json-object. If migration is active there will be another json-object
2266 with RAM migration status and if block migration is active another one with
2267 block migration status.
2268
2269 The main json-object contains the following:
2270
2271 - "status": migration status (json-string)
2272      - Possible values: "active", "completed", "failed", "cancelled"
2273 - "total-time": total amount of ms since migration started.  If
2274                 migration has ended, it returns the total migration
2275                  time (json-int)
2276 - "ram": only present if "status" is "active", it is a json-object with the
2277   following RAM information (in bytes):
2278          - "transferred": amount transferred (json-int)
2279          - "remaining": amount remaining (json-int)
2280          - "total": total (json-int)
2281          - "duplicate": number of duplicated pages (json-int)
2282          - "normal" : number of normal pages transferred (json-int)
2283          - "normal-bytes" : number of normal bytes transferred (json-int)
2284 - "disk": only present if "status" is "active" and it is a block migration,
2285   it is a json-object with the following disk information (in bytes):
2286          - "transferred": amount transferred (json-int)
2287          - "remaining": amount remaining (json-int)
2288          - "total": total (json-int)
2289 - "xbzrle-cache": only present if XBZRLE is active.
2290   It is a json-object with the following XBZRLE information:
2291          - "cache-size": XBZRLE cache size
2292          - "bytes": total XBZRLE bytes transferred
2293          - "pages": number of XBZRLE compressed pages
2294          - "cache-miss": number of cache misses
2295          - "overflow": number of XBZRLE overflows
2296 Examples:
2297
2298 1. Before the first migration
2299
2300 -> { "execute": "query-migrate" }
2301 <- { "return": {} }
2302
2303 2. Migration is done and has succeeded
2304
2305 -> { "execute": "query-migrate" }
2306 <- { "return": {
2307         "status": "completed",
2308         "ram":{
2309           "transferred":123,
2310           "remaining":123,
2311           "total":246,
2312           "total-time":12345,
2313           "duplicate":123,
2314           "normal":123,
2315           "normal-bytes":123456
2316         }
2317      }
2318    }
2319
2320 3. Migration is done and has failed
2321
2322 -> { "execute": "query-migrate" }
2323 <- { "return": { "status": "failed" } }
2324
2325 4. Migration is being performed and is not a block migration:
2326
2327 -> { "execute": "query-migrate" }
2328 <- {
2329       "return":{
2330          "status":"active",
2331          "ram":{
2332             "transferred":123,
2333             "remaining":123,
2334             "total":246,
2335             "total-time":12345,
2336             "duplicate":123,
2337             "normal":123,
2338             "normal-bytes":123456
2339          }
2340       }
2341    }
2342
2343 5. Migration is being performed and is a block migration:
2344
2345 -> { "execute": "query-migrate" }
2346 <- {
2347       "return":{
2348          "status":"active",
2349          "ram":{
2350             "total":1057024,
2351             "remaining":1053304,
2352             "transferred":3720,
2353             "total-time":12345,
2354             "duplicate":123,
2355             "normal":123,
2356             "normal-bytes":123456
2357          },
2358          "disk":{
2359             "total":20971520,
2360             "remaining":20880384,
2361             "transferred":91136
2362          }
2363       }
2364    }
2365
2366 6. Migration is being performed and XBZRLE is active:
2367
2368 -> { "execute": "query-migrate" }
2369 <- {
2370       "return":{
2371          "status":"active",
2372          "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
2373          "ram":{
2374             "total":1057024,
2375             "remaining":1053304,
2376             "transferred":3720,
2377             "total-time":12345,
2378             "duplicate":10,
2379             "normal":3333,
2380             "normal-bytes":3412992
2381          },
2382          "xbzrle-cache":{
2383             "cache-size":67108864,
2384             "bytes":20971520,
2385             "pages":2444343,
2386             "cache-miss":2244,
2387             "overflow":34434
2388          }
2389       }
2390    }
2391
2392 EQMP
2393
2394     {
2395         .name       = "query-migrate",
2396         .args_type  = "",
2397         .mhandler.cmd_new = qmp_marshal_input_query_migrate,
2398     },
2399
2400 SQMP
2401 migrate-set-capabilities
2402 -------
2403
2404 Enable/Disable migration capabilities
2405
2406 - "xbzrle": xbzrle support
2407
2408 Arguments:
2409
2410 Example:
2411
2412 -> { "execute": "migrate-set-capabilities" , "arguments":
2413      { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
2414
2415 EQMP
2416
2417     {
2418         .name       = "migrate-set-capabilities",
2419         .args_type  = "capabilities:O",
2420         .params     = "capability:s,state:b",
2421         .mhandler.cmd_new = qmp_marshal_input_migrate_set_capabilities,
2422     },
2423 SQMP
2424 query-migrate-capabilities
2425 -------
2426
2427 Query current migration capabilities
2428
2429 - "capabilities": migration capabilities state
2430          - "xbzrle" : XBZRLE state (json-bool)
2431
2432 Arguments:
2433
2434 Example:
2435
2436 -> { "execute": "query-migrate-capabilities" }
2437 <- { "return": {
2438         "capabilities" :  [ { "capability" : "xbzrle", "state" : false } ]
2439      }
2440    }
2441 EQMP
2442
2443     {
2444         .name       = "query-migrate-capabilities",
2445         .args_type  = "",
2446         .mhandler.cmd_new = qmp_marshal_input_query_migrate_capabilities,
2447     },
2448
2449 SQMP
2450 query-balloon
2451 -------------
2452
2453 Show balloon information.
2454
2455 Make an asynchronous request for balloon info. When the request completes a
2456 json-object will be returned containing the following data:
2457
2458 - "actual": current balloon value in bytes (json-int)
2459 - "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
2460 - "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
2461 - "major_page_faults": Number of major faults (json-int, optional)
2462 - "minor_page_faults": Number of minor faults (json-int, optional)
2463 - "free_mem": Total amount of free and unused memory in
2464               bytes (json-int, optional)
2465 - "total_mem": Total amount of available memory in bytes (json-int, optional)
2466
2467 Example:
2468
2469 -> { "execute": "query-balloon" }
2470 <- {
2471       "return":{
2472          "actual":1073741824,
2473          "mem_swapped_in":0,
2474          "mem_swapped_out":0,
2475          "major_page_faults":142,
2476          "minor_page_faults":239245,
2477          "free_mem":1014185984,
2478          "total_mem":1044668416
2479       }
2480    }
2481
2482 EQMP
2483
2484     {
2485         .name       = "query-balloon",
2486         .args_type  = "",
2487         .mhandler.cmd_new = qmp_marshal_input_query_balloon,
2488     },
2489
2490     {
2491         .name       = "query-block-jobs",
2492         .args_type  = "",
2493         .mhandler.cmd_new = qmp_marshal_input_query_block_jobs,
2494     },
2495
2496     {
2497         .name       = "qom-list",
2498         .args_type  = "path:s",
2499         .mhandler.cmd_new = qmp_marshal_input_qom_list,
2500     },
2501
2502     {
2503         .name       = "qom-set",
2504         .args_type  = "path:s,property:s,value:q",
2505         .mhandler.cmd_new = qmp_qom_set,
2506     },
2507
2508     {
2509         .name       = "qom-get",
2510         .args_type  = "path:s,property:s",
2511         .mhandler.cmd_new = qmp_qom_get,
2512     },
2513
2514     {
2515         .name       = "change-vnc-password",
2516         .args_type  = "password:s",
2517         .mhandler.cmd_new = qmp_marshal_input_change_vnc_password,
2518     },
2519     {
2520         .name       = "qom-list-types",
2521         .args_type  = "implements:s?,abstract:b?",
2522         .mhandler.cmd_new = qmp_marshal_input_qom_list_types,
2523     },
2524
2525     {
2526         .name       = "device-list-properties",
2527         .args_type  = "typename:s",
2528         .mhandler.cmd_new = qmp_marshal_input_device_list_properties,
2529     },
2530
2531     {
2532         .name       = "query-machines",
2533         .args_type  = "",
2534         .mhandler.cmd_new = qmp_marshal_input_query_machines,
2535     },
2536
2537     {
2538         .name       = "query-cpu-definitions",
2539         .args_type  = "",
2540         .mhandler.cmd_new = qmp_marshal_input_query_cpu_definitions,
2541     },
2542
2543     {
2544         .name       = "query-target",
2545         .args_type  = "",
2546         .mhandler.cmd_new = qmp_marshal_input_query_target,
2547     },