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