qmp-commands.hx

   1 HXCOMM QMP dispatch table and documentation
   2 HXCOMM Text between SQMP and EQMP is copied to the QMP documentation 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_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_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_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_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_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_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_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_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_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         .mhandler.cmd_new = qmp_device_add,
 280     },
 281
 282 SQMP
 283 device_add
 284 ----------
 285
 286 Add a device.
 287
 288 Arguments:
 289
 290 - "driver": the name of the new device's driver (json-string)
 291 - "bus": the device's parent bus (device tree path, json-string, optional)
 292 - "id": the device's ID, must be unique (json-string)
 293 - device properties
 294
 295 Example:
 296
 297 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
 298 <- { "return": {} }
 299
 300 Notes:
 301
 302 (1) For detailed information about this command, please refer to the
 303     'docs/qdev-device-use.txt' file.
 304
 305 (2) It's possible to list device properties by running QEMU with the
 306     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
 307
 308 EQMP
 309
 310     {
 311         .name       = "device_del",
 312         .args_type  = "id:s",
 313         .mhandler.cmd_new = qmp_marshal_device_del,
 314     },
 315
 316 SQMP
 317 device_del
 318 ----------
 319
 320 Remove a device.
 321
 322 Arguments:
 323
 324 - "id": the device's ID or QOM path (json-string)
 325
 326 Example:
 327
 328 -> { "execute": "device_del", "arguments": { "id": "net1" } }
 329 <- { "return": {} }
 330
 331 Example:
 332
 333 -> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
 334 <- { "return": {} }
 335
 336 EQMP
 337
 338     {
 339         .name       = "send-key",
 340         .args_type  = "keys:q,hold-time:i?",
 341         .mhandler.cmd_new = qmp_marshal_send_key,
 342     },
 343
 344 SQMP
 345 send-key
 346 ----------
 347
 348 Send keys to VM.
 349
 350 Arguments:
 351
 352 keys array:
 353     - "key": key sequence (a json-array of key union values,
 354              union can be number or qcode enum)
 355
 356 - hold-time: time to delay key up events, milliseconds. Defaults to 100
 357              (json-int, optional)
 358
 359 Example:
 360
 361 -> { "execute": "send-key",
 362      "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
 363                               { "type": "qcode", "data": "alt" },
 364                               { "type": "qcode", "data": "delete" } ] } }
 365 <- { "return": {} }
 366
 367 EQMP
 368
 369     {
 370         .name       = "cpu",
 371         .args_type  = "index:i",
 372         .mhandler.cmd_new = qmp_marshal_cpu,
 373     },
 374
 375 SQMP
 376 cpu
 377 ---
 378
 379 Set the default CPU.
 380
 381 Arguments:
 382
 383 - "index": the CPU's index (json-int)
 384
 385 Example:
 386
 387 -> { "execute": "cpu", "arguments": { "index": 0 } }
 388 <- { "return": {} }
 389
 390 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 391
 392 EQMP
 393
 394     {
 395         .name       = "cpu-add",
 396         .args_type  = "id:i",
 397         .mhandler.cmd_new = qmp_marshal_cpu_add,
 398     },
 399
 400 SQMP
 401 cpu-add
 402 -------
 403
 404 Adds virtual cpu
 405
 406 Arguments:
 407
 408 - "id": cpu id (json-int)
 409
 410 Example:
 411
 412 -> { "execute": "cpu-add", "arguments": { "id": 2 } }
 413 <- { "return": {} }
 414
 415 EQMP
 416
 417     {
 418         .name       = "memsave",
 419         .args_type  = "val:l,size:i,filename:s,cpu:i?",
 420         .mhandler.cmd_new = qmp_marshal_memsave,
 421     },
 422
 423 SQMP
 424 memsave
 425 -------
 426
 427 Save to disk virtual memory dump starting at 'val' of size 'size'.
 428
 429 Arguments:
 430
 431 - "val": the starting address (json-int)
 432 - "size": the memory size, in bytes (json-int)
 433 - "filename": file path (json-string)
 434 - "cpu": virtual CPU index (json-int, optional)
 435
 436 Example:
 437
 438 -> { "execute": "memsave",
 439              "arguments": { "val": 10,
 440                             "size": 100,
 441                             "filename": "/tmp/virtual-mem-dump" } }
 442 <- { "return": {} }
 443
 444 EQMP
 445
 446     {
 447         .name       = "pmemsave",
 448         .args_type  = "val:l,size:i,filename:s",
 449         .mhandler.cmd_new = qmp_marshal_pmemsave,
 450     },
 451
 452 SQMP
 453 pmemsave
 454 --------
 455
 456 Save to disk physical memory dump starting at 'val' of size 'size'.
 457
 458 Arguments:
 459
 460 - "val": the starting address (json-int)
 461 - "size": the memory size, in bytes (json-int)
 462 - "filename": file path (json-string)
 463
 464 Example:
 465
 466 -> { "execute": "pmemsave",
 467              "arguments": { "val": 10,
 468                             "size": 100,
 469                             "filename": "/tmp/physical-mem-dump" } }
 470 <- { "return": {} }
 471
 472 EQMP
 473
 474     {
 475         .name       = "inject-nmi",
 476         .args_type  = "",
 477         .mhandler.cmd_new = qmp_marshal_inject_nmi,
 478     },
 479
 480 SQMP
 481 inject-nmi
 482 ----------
 483
 484 Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64).
 485
 486 Arguments: None.
 487
 488 Example:
 489
 490 -> { "execute": "inject-nmi" }
 491 <- { "return": {} }
 492
 493 Note: inject-nmi fails when the guest doesn't support injecting.
 494
 495 EQMP
 496
 497     {
 498         .name       = "ringbuf-write",
 499         .args_type  = "device:s,data:s,format:s?",
 500         .mhandler.cmd_new = qmp_marshal_ringbuf_write,
 501     },
 502
 503 SQMP
 504 ringbuf-write
 505 -------------
 506
 507 Write to a ring buffer character device.
 508
 509 Arguments:
 510
 511 - "device": ring buffer character device name (json-string)
 512 - "data": data to write (json-string)
 513 - "format": data format (json-string, optional)
 514           - Possible values: "utf8" (default), "base64"
 515
 516 Example:
 517
 518 -> { "execute": "ringbuf-write",
 519                 "arguments": { "device": "foo",
 520                                "data": "abcdefgh",
 521                                "format": "utf8" } }
 522 <- { "return": {} }
 523
 524 EQMP
 525
 526     {
 527         .name       = "ringbuf-read",
 528         .args_type  = "device:s,size:i,format:s?",
 529         .mhandler.cmd_new = qmp_marshal_ringbuf_read,
 530     },
 531
 532 SQMP
 533 ringbuf-read
 534 -------------
 535
 536 Read from a ring buffer character device.
 537
 538 Arguments:
 539
 540 - "device": ring buffer character device name (json-string)
 541 - "size": how many bytes to read at most (json-int)
 542           - Number of data bytes, not number of characters in encoded data
 543 - "format": data format (json-string, optional)
 544           - Possible values: "utf8" (default), "base64"
 545           - Naturally, format "utf8" works only when the ring buffer
 546             contains valid UTF-8 text.  Invalid UTF-8 sequences get
 547             replaced.  Bug: replacement doesn't work.  Bug: can screw
 548             up on encountering NUL characters, after the ring buffer
 549             lost data, and when reading stops because the size limit
 550             is reached.
 551
 552 Example:
 553
 554 -> { "execute": "ringbuf-read",
 555                 "arguments": { "device": "foo",
 556                                "size": 1000,
 557                                "format": "utf8" } }
 558 <- {"return": "abcdefgh"}
 559
 560 EQMP
 561
 562     {
 563         .name       = "xen-save-devices-state",
 564         .args_type  = "filename:F",
 565     .mhandler.cmd_new = qmp_marshal_xen_save_devices_state,
 566     },
 567
 568 SQMP
 569 xen-save-devices-state
 570 -------
 571
 572 Save the state of all devices to file. The RAM and the block devices
 573 of the VM are not saved by this command.
 574
 575 Arguments:
 576
 577 - "filename": the file to save the state of the devices to as binary
 578 data. See xen-save-devices-state.txt for a description of the binary
 579 format.
 580
 581 Example:
 582
 583 -> { "execute": "xen-save-devices-state",
 584      "arguments": { "filename": "/tmp/save" } }
 585 <- { "return": {} }
 586
 587 EQMP
 588
 589     {
 590         .name       = "xen-set-global-dirty-log",
 591         .args_type  = "enable:b",
 592         .mhandler.cmd_new = qmp_marshal_xen_set_global_dirty_log,
 593     },
 594
 595 SQMP
 596 xen-set-global-dirty-log
 597 -------
 598
 599 Enable or disable the global dirty log mode.
 600
 601 Arguments:
 602
 603 - "enable": Enable it or disable it.
 604
 605 Example:
 606
 607 -> { "execute": "xen-set-global-dirty-log",
 608      "arguments": { "enable": true } }
 609 <- { "return": {} }
 610
 611 EQMP
 612
 613     {
 614         .name       = "migrate",
 615         .args_type  = "detach:-d,blk:-b,inc:-i,uri:s",
 616         .mhandler.cmd_new = qmp_marshal_migrate,
 617     },
 618
 619 SQMP
 620 migrate
 621 -------
 622
 623 Migrate to URI.
 624
 625 Arguments:
 626
 627 - "blk": block migration, full disk copy (json-bool, optional)
 628 - "inc": incremental disk copy (json-bool, optional)
 629 - "uri": Destination URI (json-string)
 630
 631 Example:
 632
 633 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
 634 <- { "return": {} }
 635
 636 Notes:
 637
 638 (1) The 'query-migrate' command should be used to check migration's progress
 639     and final result (this information is provided by the 'status' member)
 640 (2) All boolean arguments default to false
 641 (3) The user Monitor's "detach" argument is invalid in QMP and should not
 642     be used
 643
 644 EQMP
 645
 646     {
 647         .name       = "migrate_cancel",
 648         .args_type  = "",
 649         .mhandler.cmd_new = qmp_marshal_migrate_cancel,
 650     },
 651
 652 SQMP
 653 migrate_cancel
 654 --------------
 655
 656 Cancel the current migration.
 657
 658 Arguments: None.
 659
 660 Example:
 661
 662 -> { "execute": "migrate_cancel" }
 663 <- { "return": {} }
 664
 665 EQMP
 666
 667     {
 668         .name       = "migrate-incoming",
 669         .args_type  = "uri:s",
 670         .mhandler.cmd_new = qmp_marshal_migrate_incoming,
 671     },
 672
 673 SQMP
 674 migrate-incoming
 675 ----------------
 676
 677 Continue an incoming migration
 678
 679 Arguments:
 680
 681 - "uri": Source/listening URI (json-string)
 682
 683 Example:
 684
 685 -> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } }
 686 <- { "return": {} }
 687
 688 Notes:
 689
 690 (1) QEMU must be started with -incoming defer to allow migrate-incoming to
 691     be used
 692 (2) The uri format is the same as for -incoming
 693
 694 EQMP
 695     {
 696         .name       = "migrate-set-cache-size",
 697         .args_type  = "value:o",
 698         .mhandler.cmd_new = qmp_marshal_migrate_set_cache_size,
 699     },
 700
 701 SQMP
 702 migrate-set-cache-size
 703 ----------------------
 704
 705 Set cache size to be used by XBZRLE migration, the cache size will be rounded
 706 down to the nearest power of 2
 707
 708 Arguments:
 709
 710 - "value": cache size in bytes (json-int)
 711
 712 Example:
 713
 714 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 715 <- { "return": {} }
 716
 717 EQMP
 718     {
 719         .name       = "migrate-start-postcopy",
 720         .args_type  = "",
 721         .mhandler.cmd_new = qmp_marshal_migrate_start_postcopy,
 722     },
 723
 724 SQMP
 725 migrate-start-postcopy
 726 ----------------------
 727
 728 Switch an in-progress migration to postcopy mode. Ignored after the end of
 729 migration (or once already in postcopy).
 730
 731 Example:
 732 -> { "execute": "migrate-start-postcopy" }
 733 <- { "return": {} }
 734
 735 EQMP
 736
 737     {
 738         .name       = "query-migrate-cache-size",
 739         .args_type  = "",
 740         .mhandler.cmd_new = qmp_marshal_query_migrate_cache_size,
 741     },
 742
 743 SQMP
 744 query-migrate-cache-size
 745 ------------------------
 746
 747 Show cache size to be used by XBZRLE migration
 748
 749 returns a json-object with the following information:
 750 - "size" : json-int
 751
 752 Example:
 753
 754 -> { "execute": "query-migrate-cache-size" }
 755 <- { "return": 67108864 }
 756
 757 EQMP
 758
 759     {
 760         .name       = "migrate_set_speed",
 761         .args_type  = "value:o",
 762         .mhandler.cmd_new = qmp_marshal_migrate_set_speed,
 763     },
 764
 765 SQMP
 766 migrate_set_speed
 767 -----------------
 768
 769 Set maximum speed for migrations.
 770
 771 Arguments:
 772
 773 - "value": maximum speed, in bytes per second (json-int)
 774
 775 Example:
 776
 777 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
 778 <- { "return": {} }
 779
 780 EQMP
 781
 782     {
 783         .name       = "migrate_set_downtime",
 784         .args_type  = "value:T",
 785         .mhandler.cmd_new = qmp_marshal_migrate_set_downtime,
 786     },
 787
 788 SQMP
 789 migrate_set_downtime
 790 --------------------
 791
 792 Set maximum tolerated downtime (in seconds) for migrations.
 793
 794 Arguments:
 795
 796 - "value": maximum downtime (json-number)
 797
 798 Example:
 799
 800 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
 801 <- { "return": {} }
 802
 803 EQMP
 804
 805     {
 806         .name       = "client_migrate_info",
 807         .args_type  = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
 808         .params     = "protocol hostname port tls-port cert-subject",
 809         .help       = "set migration information for remote display",
 810         .mhandler.cmd_new = qmp_marshal_client_migrate_info,
 811     },
 812
 813 SQMP
 814 client_migrate_info
 815 -------------------
 816
 817 Set migration information for remote display.  This makes the server
 818 ask the client to automatically reconnect using the new parameters
 819 once migration finished successfully.  Only implemented for SPICE.
 820
 821 Arguments:
 822
 823 - "protocol":     must be "spice" (json-string)
 824 - "hostname":     migration target hostname (json-string)
 825 - "port":         spice tcp port for plaintext channels (json-int, optional)
 826 - "tls-port":     spice tcp port for tls-secured channels (json-int, optional)
 827 - "cert-subject": server certificate subject (json-string, optional)
 828
 829 Example:
 830
 831 -> { "execute": "client_migrate_info",
 832      "arguments": { "protocol": "spice",
 833                     "hostname": "virt42.lab.kraxel.org",
 834                     "port": 1234 } }
 835 <- { "return": {} }
 836
 837 EQMP
 838
 839     {
 840         .name       = "dump-guest-memory",
 841         .args_type  = "paging:b,protocol:s,begin:i?,end:i?,format:s?",
 842         .params     = "-p protocol [begin] [length] [format]",
 843         .help       = "dump guest memory to file",
 844         .mhandler.cmd_new = qmp_marshal_dump_guest_memory,
 845     },
 846
 847 SQMP
 848 dump
 849
 850
 851 Dump guest memory to file. The file can be processed with crash or gdb.
 852
 853 Arguments:
 854
 855 - "paging": do paging to get guest's memory mapping (json-bool)
 856 - "protocol": destination file(started with "file:") or destination file
 857               descriptor (started with "fd:") (json-string)
 858 - "begin": the starting physical address. It's optional, and should be specified
 859            with length together (json-int)
 860 - "length": the memory size, in bytes. It's optional, and should be specified
 861             with begin together (json-int)
 862 - "format": the format of guest memory dump. It's optional, and can be
 863             elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will
 864             conflict with paging and filter, ie. begin and length (json-string)
 865
 866 Example:
 867
 868 -> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
 869 <- { "return": {} }
 870
 871 Notes:
 872
 873 (1) All boolean arguments default to false
 874
 875 EQMP
 876
 877     {
 878         .name       = "query-dump-guest-memory-capability",
 879         .args_type  = "",
 880     .mhandler.cmd_new = qmp_marshal_query_dump_guest_memory_capability,
 881     },
 882
 883 SQMP
 884 query-dump-guest-memory-capability
 885 ----------
 886
 887 Show available formats for 'dump-guest-memory'
 888
 889 Example:
 890
 891 -> { "execute": "query-dump-guest-memory-capability" }
 892 <- { "return": { "formats":
 893                     ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
 894
 895 EQMP
 896
 897 #if defined TARGET_S390X
 898     {
 899         .name       = "dump-skeys",
 900         .args_type  = "filename:F",
 901         .mhandler.cmd_new = qmp_marshal_dump_skeys,
 902     },
 903 #endif
 904
 905 SQMP
 906 dump-skeys
 907 ----------
 908
 909 Save guest storage keys to file.
 910
 911 Arguments:
 912
 913 - "filename": file path (json-string)
 914
 915 Example:
 916
 917 -> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } }
 918 <- { "return": {} }
 919
 920 EQMP
 921
 922     {
 923         .name       = "netdev_add",
 924         .args_type  = "netdev:O",
 925         .mhandler.cmd_new = qmp_netdev_add,
 926     },
 927
 928 SQMP
 929 netdev_add
 930 ----------
 931
 932 Add host network device.
 933
 934 Arguments:
 935
 936 - "type": the device type, "tap", "user", ... (json-string)
 937 - "id": the device's ID, must be unique (json-string)
 938 - device options
 939
 940 Example:
 941
 942 -> { "execute": "netdev_add",
 943      "arguments": { "type": "user", "id": "netdev1",
 944                     "dnssearch": "example.org" } }
 945 <- { "return": {} }
 946
 947 Note: The supported device options are the same ones supported by the '-netdev'
 948       command-line argument, which are listed in the '-help' output or QEMU's
 949       manual
 950
 951 EQMP
 952
 953     {
 954         .name       = "netdev_del",
 955         .args_type  = "id:s",
 956         .mhandler.cmd_new = qmp_marshal_netdev_del,
 957     },
 958
 959 SQMP
 960 netdev_del
 961 ----------
 962
 963 Remove host network device.
 964
 965 Arguments:
 966
 967 - "id": the device's ID, must be unique (json-string)
 968
 969 Example:
 970
 971 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
 972 <- { "return": {} }
 973
 974
 975 EQMP
 976
 977     {
 978         .name       = "object-add",
 979         .args_type  = "qom-type:s,id:s,props:q?",
 980         .mhandler.cmd_new = qmp_marshal_object_add,
 981     },
 982
 983 SQMP
 984 object-add
 985 ----------
 986
 987 Create QOM object.
 988
 989 Arguments:
 990
 991 - "qom-type": the object's QOM type, i.e. the class name (json-string)
 992 - "id": the object's ID, must be unique (json-string)
 993 - "props": a dictionary of object property values (optional, json-dict)
 994
 995 Example:
 996
 997 -> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1",
 998      "props": { "filename": "/dev/hwrng" } } }
 999 <- { "return": {} }
1000
1001 EQMP
1002
1003     {
1004         .name       = "object-del",
1005         .args_type  = "id:s",
1006         .mhandler.cmd_new = qmp_marshal_object_del,
1007     },
1008
1009 SQMP
1010 object-del
1011 ----------
1012
1013 Remove QOM object.
1014
1015 Arguments:
1016
1017 - "id": the object's ID (json-string)
1018
1019 Example:
1020
1021 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
1022 <- { "return": {} }
1023
1024
1025 EQMP
1026
1027
1028     {
1029         .name       = "block_resize",
1030         .args_type  = "device:s?,node-name:s?,size:o",
1031         .mhandler.cmd_new = qmp_marshal_block_resize,
1032     },
1033
1034 SQMP
1035 block_resize
1036 ------------
1037
1038 Resize a block image while a guest is running.
1039
1040 Arguments:
1041
1042 - "device": the device's ID, must be unique (json-string)
1043 - "node-name": the node name in the block driver state graph (json-string)
1044 - "size": new size
1045
1046 Example:
1047
1048 -> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
1049 <- { "return": {} }
1050
1051 EQMP
1052
1053     {
1054         .name       = "block-stream",
1055         .args_type  = "device:B,base:s?,speed:o?,backing-file:s?,on-error:s?",
1056         .mhandler.cmd_new = qmp_marshal_block_stream,
1057     },
1058
1059 SQMP
1060 block-stream
1061 ------------
1062
1063 Copy data from a backing file into a block device.
1064
1065 Arguments:
1066
1067 - "device": The device's ID, must be unique (json-string)
1068 - "base": The file name of the backing image above which copying starts
1069           (json-string, optional)
1070 - "backing-file": The backing file string to write into the active layer. This
1071                   filename is not validated.
1072
1073                   If a pathname string is such that it cannot be resolved by
1074                   QEMU, that means that subsequent QMP or HMP commands must use
1075                   node-names for the image in question, as filename lookup
1076                   methods will fail.
1077
1078                   If not specified, QEMU will automatically determine the
1079                   backing file string to use, or error out if there is no
1080                   obvious choice.  Care should be taken when specifying the
1081                   string, to specify a valid filename or protocol.
1082                   (json-string, optional) (Since 2.1)
1083 - "speed":  the maximum speed, in bytes per second (json-int, optional)
1084 - "on-error": the action to take on an error (default 'report').  'stop' and
1085               'enospc' can only be used if the block device supports io-status.
1086               (json-string, optional) (Since 2.1)
1087
1088 Example:
1089
1090 -> { "execute": "block-stream", "arguments": { "device": "virtio0",
1091                                                "base": "/tmp/master.qcow2" } }
1092 <- { "return": {} }
1093
1094 EQMP
1095
1096     {
1097         .name       = "block-commit",
1098         .args_type  = "device:B,base:s?,top:s?,backing-file:s?,speed:o?",
1099         .mhandler.cmd_new = qmp_marshal_block_commit,
1100     },
1101
1102 SQMP
1103 block-commit
1104 ------------
1105
1106 Live commit of data from overlay image nodes into backing nodes - i.e., writes
1107 data between 'top' and 'base' into 'base'.
1108
1109 Arguments:
1110
1111 - "device": The device's ID, must be unique (json-string)
1112 - "base": The file name of the backing image to write data into.
1113           If not specified, this is the deepest backing image
1114           (json-string, optional)
1115 - "top":  The file name of the backing image within the image chain,
1116           which contains the topmost data to be committed down. If
1117           not specified, this is the active layer. (json-string, optional)
1118
1119 - backing-file:     The backing file string to write into the overlay
1120                     image of 'top'.  If 'top' is the active layer,
1121                     specifying a backing file string is an error. This
1122                     filename is not validated.
1123
1124                     If a pathname string is such that it cannot be
1125                     resolved by QEMU, that means that subsequent QMP or
1126                     HMP commands must use node-names for the image in
1127                     question, as filename lookup methods will fail.
1128
1129                     If not specified, QEMU will automatically determine
1130                     the backing file string to use, or error out if
1131                     there is no obvious choice. Care should be taken
1132                     when specifying the string, to specify a valid
1133                     filename or protocol.
1134                     (json-string, optional) (Since 2.1)
1135
1136           If top == base, that is an error.
1137           If top == active, the job will not be completed by itself,
1138           user needs to complete the job with the block-job-complete
1139           command after getting the ready event. (Since 2.0)
1140
1141           If the base image is smaller than top, then the base image
1142           will be resized to be the same size as top.  If top is
1143           smaller than the base image, the base will not be
1144           truncated.  If you want the base image size to match the
1145           size of the smaller top, you can safely truncate it
1146           yourself once the commit operation successfully completes.
1147           (json-string)
1148 - "speed":  the maximum speed, in bytes per second (json-int, optional)
1149
1150
1151 Example:
1152
1153 -> { "execute": "block-commit", "arguments": { "device": "virtio0",
1154                                               "top": "/tmp/snap1.qcow2" } }
1155 <- { "return": {} }
1156
1157 EQMP
1158
1159     {
1160         .name       = "drive-backup",
1161         .args_type  = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
1162                       "bitmap:s?,on-source-error:s?,on-target-error:s?",
1163         .mhandler.cmd_new = qmp_marshal_drive_backup,
1164     },
1165
1166 SQMP
1167 drive-backup
1168 ------------
1169
1170 Start a point-in-time copy of a block device to a new destination.  The
1171 status of ongoing drive-backup operations can be checked with
1172 query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
1173 The operation can be stopped before it has completed using the
1174 block-job-cancel command.
1175
1176 Arguments:
1177
1178 - "device": the name of the device which should be copied.
1179             (json-string)
1180 - "target": the target of the new image. If the file exists, or if it is a
1181             device, the existing file/device will be used as the new
1182             destination.  If it does not exist, a new file will be created.
1183             (json-string)
1184 - "format": the format of the new destination, default is to probe if 'mode' is
1185             'existing', else the format of the source
1186             (json-string, optional)
1187 - "sync": what parts of the disk image should be copied to the destination;
1188   possibilities include "full" for all the disk, "top" for only the sectors
1189   allocated in the topmost image, "incremental" for only the dirty sectors in
1190   the bitmap, or "none" to only replicate new I/O (MirrorSyncMode).
1191 - "bitmap": dirty bitmap name for sync==incremental. Must be present if sync
1192             is "incremental", must NOT be present otherwise.
1193 - "mode": whether and how QEMU should create a new image
1194           (NewImageMode, optional, default 'absolute-paths')
1195 - "speed": the maximum speed, in bytes per second (json-int, optional)
1196 - "on-source-error": the action to take on an error on the source, default
1197                      'report'.  'stop' and 'enospc' can only be used
1198                      if the block device supports io-status.
1199                      (BlockdevOnError, optional)
1200 - "on-target-error": the action to take on an error on the target, default
1201                      'report' (no limitations, since this applies to
1202                      a different block device than device).
1203                      (BlockdevOnError, optional)
1204
1205 Example:
1206 -> { "execute": "drive-backup", "arguments": { "device": "drive0",
1207                                                "sync": "full",
1208                                                "target": "backup.img" } }
1209 <- { "return": {} }
1210
1211 EQMP
1212
1213     {
1214         .name       = "blockdev-backup",
1215         .args_type  = "sync:s,device:B,target:B,speed:i?,"
1216                       "on-source-error:s?,on-target-error:s?",
1217         .mhandler.cmd_new = qmp_marshal_blockdev_backup,
1218     },
1219
1220 SQMP
1221 blockdev-backup
1222 ---------------
1223
1224 The device version of drive-backup: this command takes an existing named device
1225 as backup target.
1226
1227 Arguments:
1228
1229 - "device": the name of the device which should be copied.
1230             (json-string)
1231 - "target": the name of the backup target device. (json-string)
1232 - "sync": what parts of the disk image should be copied to the destination;
1233           possibilities include "full" for all the disk, "top" for only the
1234           sectors allocated in the topmost image, or "none" to only replicate
1235           new I/O (MirrorSyncMode).
1236 - "speed": the maximum speed, in bytes per second (json-int, optional)
1237 - "on-source-error": the action to take on an error on the source, default
1238                      'report'.  'stop' and 'enospc' can only be used
1239                      if the block device supports io-status.
1240                      (BlockdevOnError, optional)
1241 - "on-target-error": the action to take on an error on the target, default
1242                      'report' (no limitations, since this applies to
1243                      a different block device than device).
1244                      (BlockdevOnError, optional)
1245
1246 Example:
1247 -> { "execute": "blockdev-backup", "arguments": { "device": "src-id",
1248                                                   "sync": "full",
1249                                                   "target": "tgt-id" } }
1250 <- { "return": {} }
1251
1252 EQMP
1253
1254     {
1255         .name       = "block-job-set-speed",
1256         .args_type  = "device:B,speed:o",
1257         .mhandler.cmd_new = qmp_marshal_block_job_set_speed,
1258     },
1259
1260     {
1261         .name       = "block-job-cancel",
1262         .args_type  = "device:B,force:b?",
1263         .mhandler.cmd_new = qmp_marshal_block_job_cancel,
1264     },
1265     {
1266         .name       = "block-job-pause",
1267         .args_type  = "device:B",
1268         .mhandler.cmd_new = qmp_marshal_block_job_pause,
1269     },
1270     {
1271         .name       = "block-job-resume",
1272         .args_type  = "device:B",
1273         .mhandler.cmd_new = qmp_marshal_block_job_resume,
1274     },
1275     {
1276         .name       = "block-job-complete",
1277         .args_type  = "device:B",
1278         .mhandler.cmd_new = qmp_marshal_block_job_complete,
1279     },
1280     {
1281         .name       = "transaction",
1282         .args_type  = "actions:q,properties:q?",
1283         .mhandler.cmd_new = qmp_marshal_transaction,
1284     },
1285
1286 SQMP
1287 transaction
1288 -----------
1289
1290 Atomically operate on one or more block devices.  Operations that are
1291 currently supported:
1292
1293     - drive-backup
1294     - blockdev-backup
1295     - blockdev-snapshot-sync
1296     - blockdev-snapshot-internal-sync
1297     - abort
1298     - block-dirty-bitmap-add
1299     - block-dirty-bitmap-clear
1300
1301 Refer to the qemu/qapi-schema.json file for minimum required QEMU
1302 versions for these operations.  A list of dictionaries is accepted,
1303 that contains the actions to be performed.  If there is any failure
1304 performing any of the operations, all operations for the group are
1305 abandoned.
1306
1307 For external snapshots, the dictionary contains the device, the file to use for
1308 the new snapshot, and the format.  The default format, if not specified, is
1309 qcow2.
1310
1311 Each new snapshot defaults to being created by QEMU (wiping any
1312 contents if the file already exists), but it is also possible to reuse
1313 an externally-created file.  In the latter case, you should ensure that
1314 the new image file has the same contents as the current one; QEMU cannot
1315 perform any meaningful check.  Typically this is achieved by using the
1316 current image file as the backing file for the new image.
1317
1318 On failure, the original disks pre-snapshot attempt will be used.
1319
1320 For internal snapshots, the dictionary contains the device and the snapshot's
1321 name.  If an internal snapshot matching name already exists, the request will
1322 be rejected.  Only some image formats support it, for example, qcow2, rbd,
1323 and sheepdog.
1324
1325 On failure, qemu will try delete the newly created internal snapshot in the
1326 transaction.  When an I/O error occurs during deletion, the user needs to fix
1327 it later with qemu-img or other command.
1328
1329 Arguments:
1330
1331 actions array:
1332     - "type": the operation to perform (json-string).  Possible
1333               values: "drive-backup", "blockdev-backup",
1334                       "blockdev-snapshot-sync",
1335                       "blockdev-snapshot-internal-sync",
1336                       "abort", "block-dirty-bitmap-add",
1337                       "block-dirty-bitmap-clear"
1338     - "data": a dictionary.  The contents depend on the value
1339       of "type".  When "type" is "blockdev-snapshot-sync":
1340       - "device": device name to snapshot (json-string)
1341       - "node-name": graph node name to snapshot (json-string)
1342       - "snapshot-file": name of new image file (json-string)
1343       - "snapshot-node-name": graph node name of the new snapshot (json-string)
1344       - "format": format of new image (json-string, optional)
1345       - "mode": whether and how QEMU should create the snapshot file
1346         (NewImageMode, optional, default "absolute-paths")
1347       When "type" is "blockdev-snapshot-internal-sync":
1348       - "device": device name to snapshot (json-string)
1349       - "name": name of the new snapshot (json-string)
1350
1351 Example:
1352
1353 -> { "execute": "transaction",
1354      "arguments": { "actions": [
1355          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
1356                                          "snapshot-file": "/some/place/my-image",
1357                                          "format": "qcow2" } },
1358          { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
1359                                          "snapshot-file": "/some/place/my-image2",
1360                                          "snapshot-node-name": "node3432",
1361                                          "mode": "existing",
1362                                          "format": "qcow2" } },
1363          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
1364                                          "snapshot-file": "/some/place/my-image2",
1365                                          "mode": "existing",
1366                                          "format": "qcow2" } },
1367          { "type": "blockdev-snapshot-internal-sync", "data" : {
1368                                          "device": "ide-hd2",
1369                                          "name": "snapshot0" } } ] } }
1370 <- { "return": {} }
1371
1372 EQMP
1373
1374     {
1375         .name       = "block-dirty-bitmap-add",
1376         .args_type  = "node:B,name:s,granularity:i?",
1377         .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_add,
1378     },
1379
1380 SQMP
1381
1382 block-dirty-bitmap-add
1383 ----------------------
1384 Since 2.4
1385
1386 Create a dirty bitmap with a name on the device, and start tracking the writes.
1387
1388 Arguments:
1389
1390 - "node": device/node on which to create dirty bitmap (json-string)
1391 - "name": name of the new dirty bitmap (json-string)
1392 - "granularity": granularity to track writes with (int, optional)
1393
1394 Example:
1395
1396 -> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0",
1397                                                    "name": "bitmap0" } }
1398 <- { "return": {} }
1399
1400 EQMP
1401
1402     {
1403         .name       = "block-dirty-bitmap-remove",
1404         .args_type  = "node:B,name:s",
1405         .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_remove,
1406     },
1407
1408 SQMP
1409
1410 block-dirty-bitmap-remove
1411 -------------------------
1412 Since 2.4
1413
1414 Stop write tracking and remove the dirty bitmap that was created with
1415 block-dirty-bitmap-add.
1416
1417 Arguments:
1418
1419 - "node": device/node on which to remove dirty bitmap (json-string)
1420 - "name": name of the dirty bitmap to remove (json-string)
1421
1422 Example:
1423
1424 -> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0",
1425                                                       "name": "bitmap0" } }
1426 <- { "return": {} }
1427
1428 EQMP
1429
1430     {
1431         .name       = "block-dirty-bitmap-clear",
1432         .args_type  = "node:B,name:s",
1433         .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_clear,
1434     },
1435
1436 SQMP
1437
1438 block-dirty-bitmap-clear
1439 ------------------------
1440 Since 2.4
1441
1442 Reset the dirty bitmap associated with a node so that an incremental backup
1443 from this point in time forward will only backup clusters modified after this
1444 clear operation.
1445
1446 Arguments:
1447
1448 - "node": device/node on which to remove dirty bitmap (json-string)
1449 - "name": name of the dirty bitmap to remove (json-string)
1450
1451 Example:
1452
1453 -> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0",
1454                                                            "name": "bitmap0" } }
1455 <- { "return": {} }
1456
1457 EQMP
1458
1459     {
1460         .name       = "blockdev-snapshot-sync",
1461         .args_type  = "device:s?,node-name:s?,snapshot-file:s,snapshot-node-name:s?,format:s?,mode:s?",
1462         .mhandler.cmd_new = qmp_marshal_blockdev_snapshot_sync,
1463     },
1464
1465 SQMP
1466 blockdev-snapshot-sync
1467 ----------------------
1468
1469 Synchronous snapshot of a block device. snapshot-file specifies the
1470 target of the new image. If the file exists, or if it is a device, the
1471 snapshot will be created in the existing file/device. If does not
1472 exist, a new file will be created. format specifies the format of the
1473 snapshot image, default is qcow2.
1474
1475 Arguments:
1476
1477 - "device": device name to snapshot (json-string)
1478 - "node-name": graph node name to snapshot (json-string)
1479 - "snapshot-file": name of new image file (json-string)
1480 - "snapshot-node-name": graph node name of the new snapshot (json-string)
1481 - "mode": whether and how QEMU should create the snapshot file
1482   (NewImageMode, optional, default "absolute-paths")
1483 - "format": format of new image (json-string, optional)
1484
1485 Example:
1486
1487 -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
1488                                                          "snapshot-file":
1489                                                         "/some/place/my-image",
1490                                                         "format": "qcow2" } }
1491 <- { "return": {} }
1492
1493 EQMP
1494
1495     {
1496         .name       = "blockdev-snapshot",
1497         .args_type  = "node:s,overlay:s",
1498         .mhandler.cmd_new = qmp_marshal_blockdev_snapshot,
1499     },
1500
1501 SQMP
1502 blockdev-snapshot
1503 -----------------
1504 Since 2.5
1505
1506 Create a snapshot, by installing 'node' as the backing image of
1507 'overlay'. Additionally, if 'node' is associated with a block
1508 device, the block device changes to using 'overlay' as its new active
1509 image.
1510
1511 Arguments:
1512
1513 - "node": device that will have a snapshot created (json-string)
1514 - "overlay": device that will have 'node' as its backing image (json-string)
1515
1516 Example:
1517
1518 -> { "execute": "blockdev-add",
1519                 "arguments": { "options": { "driver": "qcow2",
1520                                             "node-name": "node1534",
1521                                             "file": { "driver": "file",
1522                                                       "filename": "hd1.qcow2" },
1523                                             "backing": "" } } }
1524
1525 <- { "return": {} }
1526
1527 -> { "execute": "blockdev-snapshot", "arguments": { "node": "ide-hd0",
1528                                                     "overlay": "node1534" } }
1529 <- { "return": {} }
1530
1531 EQMP
1532
1533     {
1534         .name       = "blockdev-snapshot-internal-sync",
1535         .args_type  = "device:B,name:s",
1536         .mhandler.cmd_new = qmp_marshal_blockdev_snapshot_internal_sync,
1537     },
1538
1539 SQMP
1540 blockdev-snapshot-internal-sync
1541 -------------------------------
1542
1543 Synchronously take an internal snapshot of a block device when the format of
1544 image used supports it.  If the name is an empty string, or a snapshot with
1545 name already exists, the operation will fail.
1546
1547 Arguments:
1548
1549 - "device": device name to snapshot (json-string)
1550 - "name": name of the new snapshot (json-string)
1551
1552 Example:
1553
1554 -> { "execute": "blockdev-snapshot-internal-sync",
1555                 "arguments": { "device": "ide-hd0",
1556                                "name": "snapshot0" }
1557    }
1558 <- { "return": {} }
1559
1560 EQMP
1561
1562     {
1563         .name       = "blockdev-snapshot-delete-internal-sync",
1564         .args_type  = "device:B,id:s?,name:s?",
1565         .mhandler.cmd_new =
1566                       qmp_marshal_blockdev_snapshot_delete_internal_sync,
1567     },
1568
1569 SQMP
1570 blockdev-snapshot-delete-internal-sync
1571 --------------------------------------
1572
1573 Synchronously delete an internal snapshot of a block device when the format of
1574 image used supports it.  The snapshot is identified by name or id or both.  One
1575 of name or id is required.  If the snapshot is not found, the operation will
1576 fail.
1577
1578 Arguments:
1579
1580 - "device": device name (json-string)
1581 - "id": ID of the snapshot (json-string, optional)
1582 - "name": name of the snapshot (json-string, optional)
1583
1584 Example:
1585
1586 -> { "execute": "blockdev-snapshot-delete-internal-sync",
1587                 "arguments": { "device": "ide-hd0",
1588                                "name": "snapshot0" }
1589    }
1590 <- { "return": {
1591                    "id": "1",
1592                    "name": "snapshot0",
1593                    "vm-state-size": 0,
1594                    "date-sec": 1000012,
1595                    "date-nsec": 10,
1596                    "vm-clock-sec": 100,
1597                    "vm-clock-nsec": 20
1598      }
1599    }
1600
1601 EQMP
1602
1603     {
1604         .name       = "drive-mirror",
1605         .args_type  = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
1606                       "node-name:s?,replaces:s?,"
1607                       "on-source-error:s?,on-target-error:s?,"
1608                       "unmap:b?,"
1609                       "granularity:i?,buf-size:i?",
1610         .mhandler.cmd_new = qmp_marshal_drive_mirror,
1611     },
1612
1613 SQMP
1614 drive-mirror
1615 ------------
1616
1617 Start mirroring a block device's writes to a new destination. target
1618 specifies the target of the new image. If the file exists, or if it is
1619 a device, it will be used as the new destination for writes. If it does not
1620 exist, a new file will be created. format specifies the format of the
1621 mirror image, default is to probe if mode='existing', else the format
1622 of the source.
1623
1624 Arguments:
1625
1626 - "device": device name to operate on (json-string)
1627 - "target": name of new image file (json-string)
1628 - "format": format of new image (json-string, optional)
1629 - "node-name": the name of the new block driver state in the node graph
1630                (json-string, optional)
1631 - "replaces": the block driver node name to replace when finished
1632               (json-string, optional)
1633 - "mode": how an image file should be created into the target
1634   file/device (NewImageMode, optional, default 'absolute-paths')
1635 - "speed": maximum speed of the streaming job, in bytes per second
1636   (json-int)
1637 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1638 - "buf-size": maximum amount of data in flight from source to target, in bytes
1639   (json-int, default 10M)
1640 - "sync": what parts of the disk image should be copied to the destination;
1641   possibilities include "full" for all the disk, "top" for only the sectors
1642   allocated in the topmost image, or "none" to only replicate new I/O
1643   (MirrorSyncMode).
1644 - "on-source-error": the action to take on an error on the source
1645   (BlockdevOnError, default 'report')
1646 - "on-target-error": the action to take on an error on the target
1647   (BlockdevOnError, default 'report')
1648 - "unmap": whether the target sectors should be discarded where source has only
1649   zeroes. (json-bool, optional, default true)
1650
1651 The default value of the granularity is the image cluster size clamped
1652 between 4096 and 65536, if the image format defines one.  If the format
1653 does not define a cluster size, the default value of the granularity
1654 is 65536.
1655
1656
1657 Example:
1658
1659 -> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
1660                                                "target": "/some/place/my-image",
1661                                                "sync": "full",
1662                                                "format": "qcow2" } }
1663 <- { "return": {} }
1664
1665 EQMP
1666
1667     {
1668         .name       = "blockdev-mirror",
1669         .args_type  = "sync:s,device:B,target:B,replaces:s?,speed:i?,"
1670                       "on-source-error:s?,on-target-error:s?,"
1671                       "granularity:i?,buf-size:i?",
1672         .mhandler.cmd_new = qmp_marshal_blockdev_mirror,
1673     },
1674
1675 SQMP
1676 blockdev-mirror
1677 ------------
1678
1679 Start mirroring a block device's writes to another block device. target
1680 specifies the target of mirror operation.
1681
1682 Arguments:
1683
1684 - "device": device name to operate on (json-string)
1685 - "target": device name to mirror to (json-string)
1686 - "replaces": the block driver node name to replace when finished
1687               (json-string, optional)
1688 - "speed": maximum speed of the streaming job, in bytes per second
1689   (json-int)
1690 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1691 - "buf_size": maximum amount of data in flight from source to target, in bytes
1692   (json-int, default 10M)
1693 - "sync": what parts of the disk image should be copied to the destination;
1694   possibilities include "full" for all the disk, "top" for only the sectors
1695   allocated in the topmost image, or "none" to only replicate new I/O
1696   (MirrorSyncMode).
1697 - "on-source-error": the action to take on an error on the source
1698   (BlockdevOnError, default 'report')
1699 - "on-target-error": the action to take on an error on the target
1700   (BlockdevOnError, default 'report')
1701
1702 The default value of the granularity is the image cluster size clamped
1703 between 4096 and 65536, if the image format defines one.  If the format
1704 does not define a cluster size, the default value of the granularity
1705 is 65536.
1706
1707 Example:
1708
1709 -> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
1710                                                   "target": "target0",
1711                                                   "sync": "full" } }
1712 <- { "return": {} }
1713
1714 EQMP
1715     {
1716         .name       = "change-backing-file",
1717         .args_type  = "device:s,image-node-name:s,backing-file:s",
1718         .mhandler.cmd_new = qmp_marshal_change_backing_file,
1719     },
1720
1721 SQMP
1722 change-backing-file
1723 -------------------
1724 Since: 2.1
1725
1726 Change the backing file in the image file metadata.  This does not cause
1727 QEMU to reopen the image file to reparse the backing filename (it may,
1728 however, perform a reopen to change permissions from r/o -> r/w -> r/o,
1729 if needed). The new backing file string is written into the image file
1730 metadata, and the QEMU internal strings are updated.
1731
1732 Arguments:
1733
1734 - "image-node-name":    The name of the block driver state node of the
1735                         image to modify.  The "device" is argument is used to
1736                         verify "image-node-name" is in the chain described by
1737                         "device".
1738                         (json-string, optional)
1739
1740 - "device":             The name of the device.
1741                         (json-string)
1742
1743 - "backing-file":       The string to write as the backing file.  This string is
1744                         not validated, so care should be taken when specifying
1745                         the string or the image chain may not be able to be
1746                         reopened again.
1747                         (json-string)
1748
1749 Returns: Nothing on success
1750          If "device" does not exist or cannot be determined, DeviceNotFound
1751
1752 EQMP
1753
1754     {
1755         .name       = "balloon",
1756         .args_type  = "value:M",
1757         .mhandler.cmd_new = qmp_marshal_balloon,
1758     },
1759
1760 SQMP
1761 balloon
1762 -------
1763
1764 Request VM to change its memory allocation (in bytes).
1765
1766 Arguments:
1767
1768 - "value": New memory allocation (json-int)
1769
1770 Example:
1771
1772 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1773 <- { "return": {} }
1774
1775 EQMP
1776
1777     {
1778         .name       = "set_link",
1779         .args_type  = "name:s,up:b",
1780         .mhandler.cmd_new = qmp_marshal_set_link,
1781     },
1782
1783 SQMP
1784 set_link
1785 --------
1786
1787 Change the link status of a network adapter.
1788
1789 Arguments:
1790
1791 - "name": network device name (json-string)
1792 - "up": status is up (json-bool)
1793
1794 Example:
1795
1796 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1797 <- { "return": {} }
1798
1799 EQMP
1800
1801     {
1802         .name       = "getfd",
1803         .args_type  = "fdname:s",
1804         .params     = "getfd name",
1805         .help       = "receive a file descriptor via SCM rights and assign it a name",
1806         .mhandler.cmd_new = qmp_marshal_getfd,
1807     },
1808
1809 SQMP
1810 getfd
1811 -----
1812
1813 Receive a file descriptor via SCM rights and assign it a name.
1814
1815 Arguments:
1816
1817 - "fdname": file descriptor name (json-string)
1818
1819 Example:
1820
1821 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1822 <- { "return": {} }
1823
1824 Notes:
1825
1826 (1) If the name specified by the "fdname" argument already exists,
1827     the file descriptor assigned to it will be closed and replaced
1828     by the received file descriptor.
1829 (2) The 'closefd' command can be used to explicitly close the file
1830     descriptor when it is no longer needed.
1831
1832 EQMP
1833
1834     {
1835         .name       = "closefd",
1836         .args_type  = "fdname:s",
1837         .params     = "closefd name",
1838         .help       = "close a file descriptor previously passed via SCM rights",
1839         .mhandler.cmd_new = qmp_marshal_closefd,
1840     },
1841
1842 SQMP
1843 closefd
1844 -------
1845
1846 Close a file descriptor previously passed via SCM rights.
1847
1848 Arguments:
1849
1850 - "fdname": file descriptor name (json-string)
1851
1852 Example:
1853
1854 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1855 <- { "return": {} }
1856
1857 EQMP
1858
1859      {
1860         .name       = "add-fd",
1861         .args_type  = "fdset-id:i?,opaque:s?",
1862         .params     = "add-fd fdset-id opaque",
1863         .help       = "Add a file descriptor, that was passed via SCM rights, to an fd set",
1864         .mhandler.cmd_new = qmp_marshal_add_fd,
1865     },
1866
1867 SQMP
1868 add-fd
1869 -------
1870
1871 Add a file descriptor, that was passed via SCM rights, to an fd set.
1872
1873 Arguments:
1874
1875 - "fdset-id": The ID of the fd set to add the file descriptor to.
1876               (json-int, optional)
1877 - "opaque": A free-form string that can be used to describe the fd.
1878             (json-string, optional)
1879
1880 Return a json-object with the following information:
1881
1882 - "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1883 - "fd": The file descriptor that was received via SCM rights and added to the
1884         fd set. (json-int)
1885
1886 Example:
1887
1888 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1889 <- { "return": { "fdset-id": 1, "fd": 3 } }
1890
1891 Notes:
1892
1893 (1) The list of fd sets is shared by all monitor connections.
1894 (2) If "fdset-id" is not specified, a new fd set will be created.
1895
1896 EQMP
1897
1898      {
1899         .name       = "remove-fd",
1900         .args_type  = "fdset-id:i,fd:i?",
1901         .params     = "remove-fd fdset-id fd",
1902         .help       = "Remove a file descriptor from an fd set",
1903         .mhandler.cmd_new = qmp_marshal_remove_fd,
1904     },
1905
1906 SQMP
1907 remove-fd
1908 ---------
1909
1910 Remove a file descriptor from an fd set.
1911
1912 Arguments:
1913
1914 - "fdset-id": The ID of the fd set that the file descriptor belongs to.
1915               (json-int)
1916 - "fd": The file descriptor that is to be removed. (json-int, optional)
1917
1918 Example:
1919
1920 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1921 <- { "return": {} }
1922
1923 Notes:
1924
1925 (1) The list of fd sets is shared by all monitor connections.
1926 (2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1927     removed.
1928
1929 EQMP
1930
1931     {
1932         .name       = "query-fdsets",
1933         .args_type  = "",
1934         .help       = "Return information describing all fd sets",
1935         .mhandler.cmd_new = qmp_marshal_query_fdsets,
1936     },
1937
1938 SQMP
1939 query-fdsets
1940 -------------
1941
1942 Return information describing all fd sets.
1943
1944 Arguments: None
1945
1946 Example:
1947
1948 -> { "execute": "query-fdsets" }
1949 <- { "return": [
1950        {
1951          "fds": [
1952            {
1953              "fd": 30,
1954              "opaque": "rdonly:/path/to/file"
1955            },
1956            {
1957              "fd": 24,
1958              "opaque": "rdwr:/path/to/file"
1959            }
1960          ],
1961          "fdset-id": 1
1962        },
1963        {
1964          "fds": [
1965            {
1966              "fd": 28
1967            },
1968            {
1969              "fd": 29
1970            }
1971          ],
1972          "fdset-id": 0
1973        }
1974      ]
1975    }
1976
1977 Note: The list of fd sets is shared by all monitor connections.
1978
1979 EQMP
1980
1981     {
1982         .name       = "block_passwd",
1983         .args_type  = "device:s?,node-name:s?,password:s",
1984         .mhandler.cmd_new = qmp_marshal_block_passwd,
1985     },
1986
1987 SQMP
1988 block_passwd
1989 ------------
1990
1991 Set the password of encrypted block devices.
1992
1993 Arguments:
1994
1995 - "device": device name (json-string)
1996 - "node-name": name in the block driver state graph (json-string)
1997 - "password": password (json-string)
1998
1999 Example:
2000
2001 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
2002                                                "password": "12345" } }
2003 <- { "return": {} }
2004
2005 EQMP
2006
2007     {
2008         .name       = "block_set_io_throttle",
2009         .args_type  = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l,bps_max:l?,bps_rd_max:l?,bps_wr_max:l?,iops_max:l?,iops_rd_max:l?,iops_wr_max:l?,iops_size:l?,group:s?",
2010         .mhandler.cmd_new = qmp_marshal_block_set_io_throttle,
2011     },
2012
2013 SQMP
2014 block_set_io_throttle
2015 ------------
2016
2017 Change I/O throttle limits for a block drive.
2018
2019 Arguments:
2020
2021 - "device": device name (json-string)
2022 - "bps": total throughput limit in bytes per second (json-int)
2023 - "bps_rd": read throughput limit in bytes per second (json-int)
2024 - "bps_wr": write throughput limit in bytes per second (json-int)
2025 - "iops": total I/O operations per second (json-int)
2026 - "iops_rd": read I/O operations per second (json-int)
2027 - "iops_wr": write I/O operations per second (json-int)
2028 - "bps_max":  total max in bytes (json-int)
2029 - "bps_rd_max":  read max in bytes (json-int)
2030 - "bps_wr_max":  write max in bytes (json-int)
2031 - "iops_max":  total I/O operations max (json-int)
2032 - "iops_rd_max":  read I/O operations max (json-int)
2033 - "iops_wr_max":  write I/O operations max (json-int)
2034 - "iops_size":  I/O size in bytes when limiting (json-int)
2035 - "group": throttle group name (json-string)
2036
2037 Example:
2038
2039 -> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
2040                                                "bps": 1000000,
2041                                                "bps_rd": 0,
2042                                                "bps_wr": 0,
2043                                                "iops": 0,
2044                                                "iops_rd": 0,
2045                                                "iops_wr": 0,
2046                                                "bps_max": 8000000,
2047                                                "bps_rd_max": 0,
2048                                                "bps_wr_max": 0,
2049                                                "iops_max": 0,
2050                                                "iops_rd_max": 0,
2051                                                "iops_wr_max": 0,
2052                                                "iops_size": 0 } }
2053 <- { "return": {} }
2054
2055 EQMP
2056
2057     {
2058         .name       = "set_password",
2059         .args_type  = "protocol:s,password:s,connected:s?",
2060         .mhandler.cmd_new = qmp_marshal_set_password,
2061     },
2062
2063 SQMP
2064 set_password
2065 ------------
2066
2067 Set the password for vnc/spice protocols.
2068
2069 Arguments:
2070
2071 - "protocol": protocol name (json-string)
2072 - "password": password (json-string)
2073 - "connected": [ keep | disconnect | fail ] (json-string, optional)
2074
2075 Example:
2076
2077 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
2078                                                "password": "secret" } }
2079 <- { "return": {} }
2080
2081 EQMP
2082
2083     {
2084         .name       = "expire_password",
2085         .args_type  = "protocol:s,time:s",
2086         .mhandler.cmd_new = qmp_marshal_expire_password,
2087     },
2088
2089 SQMP
2090 expire_password
2091 ---------------
2092
2093 Set the password expire time for vnc/spice protocols.
2094
2095 Arguments:
2096
2097 - "protocol": protocol name (json-string)
2098 - "time": [ now | never | +secs | secs ] (json-string)
2099
2100 Example:
2101
2102 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
2103                                                   "time": "+60" } }
2104 <- { "return": {} }
2105
2106 EQMP
2107
2108     {
2109         .name       = "add_client",
2110         .args_type  = "protocol:s,fdname:s,skipauth:b?,tls:b?",
2111         .mhandler.cmd_new = qmp_marshal_add_client,
2112     },
2113
2114 SQMP
2115 add_client
2116 ----------
2117
2118 Add a graphics client
2119
2120 Arguments:
2121
2122 - "protocol": protocol name (json-string)
2123 - "fdname": file descriptor name (json-string)
2124 - "skipauth": whether to skip authentication (json-bool, optional)
2125 - "tls": whether to perform TLS (json-bool, optional)
2126
2127 Example:
2128
2129 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
2130                                              "fdname": "myclient" } }
2131 <- { "return": {} }
2132
2133 EQMP
2134     {
2135         .name       = "qmp_capabilities",
2136         .args_type  = "",
2137         .params     = "",
2138         .help       = "enable QMP capabilities",
2139         .mhandler.cmd_new = qmp_capabilities,
2140     },
2141
2142 SQMP
2143 qmp_capabilities
2144 ----------------
2145
2146 Enable QMP capabilities.
2147
2148 Arguments: None.
2149
2150 Example:
2151
2152 -> { "execute": "qmp_capabilities" }
2153 <- { "return": {} }
2154
2155 Note: This command must be issued before issuing any other command.
2156
2157 EQMP
2158
2159     {
2160         .name       = "human-monitor-command",
2161         .args_type  = "command-line:s,cpu-index:i?",
2162         .mhandler.cmd_new = qmp_marshal_human_monitor_command,
2163     },
2164
2165 SQMP
2166 human-monitor-command
2167 ---------------------
2168
2169 Execute a Human Monitor command.
2170
2171 Arguments:
2172
2173 - command-line: the command name and its arguments, just like the
2174                 Human Monitor's shell (json-string)
2175 - cpu-index: select the CPU number to be used by commands which access CPU
2176              data, like 'info registers'. The Monitor selects CPU 0 if this
2177              argument is not provided (json-int, optional)
2178
2179 Example:
2180
2181 -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
2182 <- { "return": "kvm support: enabled\r\n" }
2183
2184 Notes:
2185
2186 (1) The Human Monitor is NOT an stable interface, this means that command
2187     names, arguments and responses can change or be removed at ANY time.
2188     Applications that rely on long term stability guarantees should NOT
2189     use this command
2190
2191 (2) Limitations:
2192
2193     o This command is stateless, this means that commands that depend
2194       on state information (such as getfd) might not work
2195
2196     o Commands that prompt the user for data (eg. 'cont' when the block
2197       device is encrypted) don't currently work
2198
2199 3. Query Commands
2200 =================
2201
2202 HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
2203 HXCOMM this! We will possibly move query commands definitions inside those
2204 HXCOMM sections, just like regular commands.
2205
2206 EQMP
2207
2208 SQMP
2209 query-version
2210 -------------
2211
2212 Show QEMU version.
2213
2214 Return a json-object with the following information:
2215
2216 - "qemu": A json-object containing three integer values:
2217     - "major": QEMU's major version (json-int)
2218     - "minor": QEMU's minor version (json-int)
2219     - "micro": QEMU's micro version (json-int)
2220 - "package": package's version (json-string)
2221
2222 Example:
2223
2224 -> { "execute": "query-version" }
2225 <- {
2226       "return":{
2227          "qemu":{
2228             "major":0,
2229             "minor":11,
2230             "micro":5
2231          },
2232          "package":""
2233       }
2234    }
2235
2236 EQMP
2237
2238     {
2239         .name       = "query-version",
2240         .args_type  = "",
2241         .mhandler.cmd_new = qmp_marshal_query_version,
2242     },
2243
2244 SQMP
2245 query-commands
2246 --------------
2247
2248 List QMP available commands.
2249
2250 Each command is represented by a json-object, the returned value is a json-array
2251 of all commands.
2252
2253 Each json-object contain:
2254
2255 - "name": command's name (json-string)
2256
2257 Example:
2258
2259 -> { "execute": "query-commands" }
2260 <- {
2261       "return":[
2262          {
2263             "name":"query-balloon"
2264          },
2265          {
2266             "name":"system_powerdown"
2267          }
2268       ]
2269    }
2270
2271 Note: This example has been shortened as the real response is too long.
2272
2273 EQMP
2274
2275     {
2276         .name       = "query-commands",
2277         .args_type  = "",
2278         .mhandler.cmd_new = qmp_marshal_query_commands,
2279     },
2280
2281 SQMP
2282 query-events
2283 --------------
2284
2285 List QMP available events.
2286
2287 Each event is represented by a json-object, the returned value is a json-array
2288 of all events.
2289
2290 Each json-object contains:
2291
2292 - "name": event's name (json-string)
2293
2294 Example:
2295
2296 -> { "execute": "query-events" }
2297 <- {
2298       "return":[
2299          {
2300             "name":"SHUTDOWN"
2301          },
2302          {
2303             "name":"RESET"
2304          }
2305       ]
2306    }
2307
2308 Note: This example has been shortened as the real response is too long.
2309
2310 EQMP
2311
2312     {
2313         .name       = "query-events",
2314         .args_type  = "",
2315         .mhandler.cmd_new = qmp_marshal_query_events,
2316     },
2317
2318 SQMP
2319 query-qmp-schema
2320 ----------------
2321
2322 Return the QMP wire schema.  The returned value is a json-array of
2323 named schema entities.  Entities are commands, events and various
2324 types.  See docs/qapi-code-gen.txt for information on their structure
2325 and intended use.
2326
2327 EQMP
2328
2329     {
2330         .name       = "query-qmp-schema",
2331         .args_type  = "",
2332         .mhandler.cmd_new = qmp_query_qmp_schema,
2333     },
2334
2335 SQMP
2336 query-chardev
2337 -------------
2338
2339 Each device is represented by a json-object. The returned value is a json-array
2340 of all devices.
2341
2342 Each json-object contain the following:
2343
2344 - "label": device's label (json-string)
2345 - "filename": device's file (json-string)
2346 - "frontend-open": open/closed state of the frontend device attached to this
2347                    backend (json-bool)
2348
2349 Example:
2350
2351 -> { "execute": "query-chardev" }
2352 <- {
2353       "return": [
2354          {
2355             "label": "charchannel0",
2356             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
2357             "frontend-open": false
2358          },
2359          {
2360             "label": "charmonitor",
2361             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
2362             "frontend-open": true
2363          },
2364          {
2365             "label": "charserial0",
2366             "filename": "pty:/dev/pts/2",
2367             "frontend-open": true
2368          }
2369       ]
2370    }
2371
2372 EQMP
2373
2374     {
2375         .name       = "query-chardev",
2376         .args_type  = "",
2377         .mhandler.cmd_new = qmp_marshal_query_chardev,
2378     },
2379
2380 SQMP
2381 query-chardev-backends
2382 -------------
2383
2384 List available character device backends.
2385
2386 Each backend is represented by a json-object, the returned value is a json-array
2387 of all backends.
2388
2389 Each json-object contains:
2390
2391 - "name": backend name (json-string)
2392
2393 Example:
2394
2395 -> { "execute": "query-chardev-backends" }
2396 <- {
2397       "return":[
2398          {
2399             "name":"udp"
2400          },
2401          {
2402             "name":"tcp"
2403          },
2404          {
2405             "name":"unix"
2406          },
2407          {
2408             "name":"spiceport"
2409          }
2410       ]
2411    }
2412
2413 EQMP
2414
2415     {
2416         .name       = "query-chardev-backends",
2417         .args_type  = "",
2418         .mhandler.cmd_new = qmp_marshal_query_chardev_backends,
2419     },
2420
2421 SQMP
2422 query-block
2423 -----------
2424
2425 Show the block devices.
2426
2427 Each block device information is stored in a json-object and the returned value
2428 is a json-array of all devices.
2429
2430 Each json-object contain the following:
2431
2432 - "device": device name (json-string)
2433 - "type": device type (json-string)
2434          - deprecated, retained for backward compatibility
2435          - Possible values: "unknown"
2436 - "removable": true if the device is removable, false otherwise (json-bool)
2437 - "locked": true if the device is locked, false otherwise (json-bool)
2438 - "tray_open": only present if removable, true if the device has a tray,
2439                and it is open (json-bool)
2440 - "inserted": only present if the device is inserted, it is a json-object
2441    containing the following:
2442          - "file": device file name (json-string)
2443          - "ro": true if read-only, false otherwise (json-bool)
2444          - "drv": driver format name (json-string)
2445              - Possible values: "blkdebug", "bochs", "cloop", "dmg",
2446                                 "file", "file", "ftp", "ftps", "host_cdrom",
2447                                 "host_device", "http", "https",
2448                                 "nbd", "parallels", "qcow", "qcow2", "raw",
2449                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
2450          - "backing_file": backing file name (json-string, optional)
2451          - "backing_file_depth": number of files in the backing file chain (json-int)
2452          - "encrypted": true if encrypted, false otherwise (json-bool)
2453          - "bps": limit total bytes per second (json-int)
2454          - "bps_rd": limit read bytes per second (json-int)
2455          - "bps_wr": limit write bytes per second (json-int)
2456          - "iops": limit total I/O operations per second (json-int)
2457          - "iops_rd": limit read operations per second (json-int)
2458          - "iops_wr": limit write operations per second (json-int)
2459          - "bps_max":  total max in bytes (json-int)
2460          - "bps_rd_max":  read max in bytes (json-int)
2461          - "bps_wr_max":  write max in bytes (json-int)
2462          - "iops_max":  total I/O operations max (json-int)
2463          - "iops_rd_max":  read I/O operations max (json-int)
2464          - "iops_wr_max":  write I/O operations max (json-int)
2465          - "iops_size": I/O size when limiting by iops (json-int)
2466          - "detect_zeroes": detect and optimize zero writing (json-string)
2467              - Possible values: "off", "on", "unmap"
2468          - "write_threshold": write offset threshold in bytes, a event will be
2469                               emitted if crossed. Zero if disabled (json-int)
2470          - "image": the detail of the image, it is a json-object containing
2471             the following:
2472              - "filename": image file name (json-string)
2473              - "format": image format (json-string)
2474              - "virtual-size": image capacity in bytes (json-int)
2475              - "dirty-flag": true if image is not cleanly closed, not present
2476                              means clean (json-bool, optional)
2477              - "actual-size": actual size on disk in bytes of the image, not
2478                               present when image does not support thin
2479                               provision (json-int, optional)
2480              - "cluster-size": size of a cluster in bytes, not present if image
2481                                format does not support it (json-int, optional)
2482              - "encrypted": true if the image is encrypted, not present means
2483                             false or the image format does not support
2484                             encryption (json-bool, optional)
2485              - "backing_file": backing file name, not present means no backing
2486                                file is used or the image format does not
2487                                support backing file chain
2488                                (json-string, optional)
2489              - "full-backing-filename": full path of the backing file, not
2490                                         present if it equals backing_file or no
2491                                         backing file is used
2492                                         (json-string, optional)
2493              - "backing-filename-format": the format of the backing file, not
2494                                           present means unknown or no backing
2495                                           file (json-string, optional)
2496              - "snapshots": the internal snapshot info, it is an optional list
2497                 of json-object containing the following:
2498                  - "id": unique snapshot id (json-string)
2499                  - "name": snapshot name (json-string)
2500                  - "vm-state-size": size of the VM state in bytes (json-int)
2501                  - "date-sec": UTC date of the snapshot in seconds (json-int)
2502                  - "date-nsec": fractional part in nanoseconds to be used with
2503                                 date-sec (json-int)
2504                  - "vm-clock-sec": VM clock relative to boot in seconds
2505                                    (json-int)
2506                  - "vm-clock-nsec": fractional part in nanoseconds to be used
2507                                     with vm-clock-sec (json-int)
2508              - "backing-image": the detail of the backing image, it is an
2509                                 optional json-object only present when a
2510                                 backing image present for this image
2511
2512 - "io-status": I/O operation status, only present if the device supports it
2513                and the VM is configured to stop on errors. It's always reset
2514                to "ok" when the "cont" command is issued (json_string, optional)
2515              - Possible values: "ok", "failed", "nospace"
2516
2517 Example:
2518
2519 -> { "execute": "query-block" }
2520 <- {
2521       "return":[
2522          {
2523             "io-status": "ok",
2524             "device":"ide0-hd0",
2525             "locked":false,
2526             "removable":false,
2527             "inserted":{
2528                "ro":false,
2529                "drv":"qcow2",
2530                "encrypted":false,
2531                "file":"disks/test.qcow2",
2532                "backing_file_depth":1,
2533                "bps":1000000,
2534                "bps_rd":0,
2535                "bps_wr":0,
2536                "iops":1000000,
2537                "iops_rd":0,
2538                "iops_wr":0,
2539                "bps_max": 8000000,
2540                "bps_rd_max": 0,
2541                "bps_wr_max": 0,
2542                "iops_max": 0,
2543                "iops_rd_max": 0,
2544                "iops_wr_max": 0,
2545                "iops_size": 0,
2546                "detect_zeroes": "on",
2547                "write_threshold": 0,
2548                "image":{
2549                   "filename":"disks/test.qcow2",
2550                   "format":"qcow2",
2551                   "virtual-size":2048000,
2552                   "backing_file":"base.qcow2",
2553                   "full-backing-filename":"disks/base.qcow2",
2554                   "backing-filename-format":"qcow2",
2555                   "snapshots":[
2556                      {
2557                         "id": "1",
2558                         "name": "snapshot1",
2559                         "vm-state-size": 0,
2560                         "date-sec": 10000200,
2561                         "date-nsec": 12,
2562                         "vm-clock-sec": 206,
2563                         "vm-clock-nsec": 30
2564                      }
2565                   ],
2566                   "backing-image":{
2567                       "filename":"disks/base.qcow2",
2568                       "format":"qcow2",
2569                       "virtual-size":2048000
2570                   }
2571                }
2572             },
2573             "type":"unknown"
2574          },
2575          {
2576             "io-status": "ok",
2577             "device":"ide1-cd0",
2578             "locked":false,
2579             "removable":true,
2580             "type":"unknown"
2581          },
2582          {
2583             "device":"floppy0",
2584             "locked":false,
2585             "removable":true,
2586             "type":"unknown"
2587          },
2588          {
2589             "device":"sd0",
2590             "locked":false,
2591             "removable":true,
2592             "type":"unknown"
2593          }
2594       ]
2595    }
2596
2597 EQMP
2598
2599     {
2600         .name       = "query-block",
2601         .args_type  = "",
2602         .mhandler.cmd_new = qmp_marshal_query_block,
2603     },
2604
2605 SQMP
2606 query-blockstats
2607 ----------------
2608
2609 Show block device statistics.
2610
2611 Each device statistic information is stored in a json-object and the returned
2612 value is a json-array of all devices.
2613
2614 Each json-object contain the following:
2615
2616 - "device": device name (json-string)
2617 - "stats": A json-object with the statistics information, it contains:
2618     - "rd_bytes": bytes read (json-int)
2619     - "wr_bytes": bytes written (json-int)
2620     - "rd_operations": read operations (json-int)
2621     - "wr_operations": write operations (json-int)
2622     - "flush_operations": cache flush operations (json-int)
2623     - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
2624     - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
2625     - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
2626     - "wr_highest_offset": The offset after the greatest byte written to the
2627                            BlockDriverState since it has been opened (json-int)
2628     - "rd_merged": number of read requests that have been merged into
2629                    another request (json-int)
2630     - "wr_merged": number of write requests that have been merged into
2631                    another request (json-int)
2632     - "idle_time_ns": time since the last I/O operation, in
2633                       nanoseconds. If the field is absent it means
2634                       that there haven't been any operations yet
2635                       (json-int, optional)
2636     - "failed_rd_operations": number of failed read operations
2637                               (json-int)
2638     - "failed_wr_operations": number of failed write operations
2639                               (json-int)
2640     - "failed_flush_operations": number of failed flush operations
2641                                (json-int)
2642     - "invalid_rd_operations": number of invalid read operations
2643                                (json-int)
2644     - "invalid_wr_operations": number of invalid write operations
2645                                (json-int)
2646     - "invalid_flush_operations": number of invalid flush operations
2647                                   (json-int)
2648     - "account_invalid": whether invalid operations are included in
2649                          the last access statistics (json-bool)
2650     - "account_failed": whether failed operations are included in the
2651                          latency and last access statistics
2652                          (json-bool)
2653     - "timed_stats": A json-array containing statistics collected in
2654                      specific intervals, with the following members:
2655         - "interval_length": interval used for calculating the
2656                              statistics, in seconds (json-int)
2657         - "min_rd_latency_ns": minimum latency of read operations in
2658                                the defined interval, in nanoseconds
2659                                (json-int)
2660         - "min_wr_latency_ns": minimum latency of write operations in
2661                                the defined interval, in nanoseconds
2662                                (json-int)
2663         - "min_flush_latency_ns": minimum latency of flush operations
2664                                   in the defined interval, in
2665                                   nanoseconds (json-int)
2666         - "max_rd_latency_ns": maximum latency of read operations in
2667                                the defined interval, in nanoseconds
2668                                (json-int)
2669         - "max_wr_latency_ns": maximum latency of write operations in
2670                                the defined interval, in nanoseconds
2671                                (json-int)
2672         - "max_flush_latency_ns": maximum latency of flush operations
2673                                   in the defined interval, in
2674                                   nanoseconds (json-int)
2675         - "avg_rd_latency_ns": average latency of read operations in
2676                                the defined interval, in nanoseconds
2677                                (json-int)
2678         - "avg_wr_latency_ns": average latency of write operations in
2679                                the defined interval, in nanoseconds
2680                                (json-int)
2681         - "avg_flush_latency_ns": average latency of flush operations
2682                                   in the defined interval, in
2683                                   nanoseconds (json-int)
2684         - "avg_rd_queue_depth": average number of pending read
2685                                 operations in the defined interval
2686                                 (json-number)
2687         - "avg_wr_queue_depth": average number of pending write
2688                                 operations in the defined interval
2689                                 (json-number).
2690 - "parent": Contains recursively the statistics of the underlying
2691             protocol (e.g. the host file for a qcow2 image). If there is
2692             no underlying protocol, this field is omitted
2693             (json-object, optional)
2694
2695 Example:
2696
2697 -> { "execute": "query-blockstats" }
2698 <- {
2699       "return":[
2700          {
2701             "device":"ide0-hd0",
2702             "parent":{
2703                "stats":{
2704                   "wr_highest_offset":3686448128,
2705                   "wr_bytes":9786368,
2706                   "wr_operations":751,
2707                   "rd_bytes":122567168,
2708                   "rd_operations":36772
2709                   "wr_total_times_ns":313253456
2710                   "rd_total_times_ns":3465673657
2711                   "flush_total_times_ns":49653
2712                   "flush_operations":61,
2713                   "rd_merged":0,
2714                   "wr_merged":0,
2715                   "idle_time_ns":2953431879,
2716                   "account_invalid":true,
2717                   "account_failed":false
2718                }
2719             },
2720             "stats":{
2721                "wr_highest_offset":2821110784,
2722                "wr_bytes":9786368,
2723                "wr_operations":692,
2724                "rd_bytes":122739200,
2725                "rd_operations":36604
2726                "flush_operations":51,
2727                "wr_total_times_ns":313253456
2728                "rd_total_times_ns":3465673657
2729                "flush_total_times_ns":49653,
2730                "rd_merged":0,
2731                "wr_merged":0,
2732                "idle_time_ns":2953431879,
2733                "account_invalid":true,
2734                "account_failed":false
2735             }
2736          },
2737          {
2738             "device":"ide1-cd0",
2739             "stats":{
2740                "wr_highest_offset":0,
2741                "wr_bytes":0,
2742                "wr_operations":0,
2743                "rd_bytes":0,
2744                "rd_operations":0
2745                "flush_operations":0,
2746                "wr_total_times_ns":0
2747                "rd_total_times_ns":0
2748                "flush_total_times_ns":0,
2749                "rd_merged":0,
2750                "wr_merged":0,
2751                "account_invalid":false,
2752                "account_failed":false
2753             }
2754          },
2755          {
2756             "device":"floppy0",
2757             "stats":{
2758                "wr_highest_offset":0,
2759                "wr_bytes":0,
2760                "wr_operations":0,
2761                "rd_bytes":0,
2762                "rd_operations":0
2763                "flush_operations":0,
2764                "wr_total_times_ns":0
2765                "rd_total_times_ns":0
2766                "flush_total_times_ns":0,
2767                "rd_merged":0,
2768                "wr_merged":0,
2769                "account_invalid":false,
2770                "account_failed":false
2771             }
2772          },
2773          {
2774             "device":"sd0",
2775             "stats":{
2776                "wr_highest_offset":0,
2777                "wr_bytes":0,
2778                "wr_operations":0,
2779                "rd_bytes":0,
2780                "rd_operations":0
2781                "flush_operations":0,
2782                "wr_total_times_ns":0
2783                "rd_total_times_ns":0
2784                "flush_total_times_ns":0,
2785                "rd_merged":0,
2786                "wr_merged":0,
2787                "account_invalid":false,
2788                "account_failed":false
2789             }
2790          }
2791       ]
2792    }
2793
2794 EQMP
2795
2796     {
2797         .name       = "query-blockstats",
2798         .args_type  = "query-nodes:b?",
2799         .mhandler.cmd_new = qmp_marshal_query_blockstats,
2800     },
2801
2802 SQMP
2803 query-cpus
2804 ----------
2805
2806 Show CPU information.
2807
2808 Return a json-array. Each CPU is represented by a json-object, which contains:
2809
2810 - "CPU": CPU index (json-int)
2811 - "current": true if this is the current CPU, false otherwise (json-bool)
2812 - "halted": true if the cpu is halted, false otherwise (json-bool)
2813 - "qom_path": path to the CPU object in the QOM tree (json-str)
2814 - "arch": architecture of the cpu, which determines what additional
2815           keys will be present (json-str)
2816 - Current program counter. The key's name depends on the architecture:
2817      "pc": i386/x86_64 (json-int)
2818      "nip": PPC (json-int)
2819      "pc" and "npc": sparc (json-int)
2820      "PC": mips (json-int)
2821 - "thread_id": ID of the underlying host thread (json-int)
2822
2823 Example:
2824
2825 -> { "execute": "query-cpus" }
2826 <- {
2827       "return":[
2828          {
2829             "CPU":0,
2830             "current":true,
2831             "halted":false,
2832             "qom_path":"/machine/unattached/device[0]",
2833             "arch":"x86",
2834             "pc":3227107138,
2835             "thread_id":3134
2836          },
2837          {
2838             "CPU":1,
2839             "current":false,
2840             "halted":true,
2841             "qom_path":"/machine/unattached/device[2]",
2842             "arch":"x86",
2843             "pc":7108165,
2844             "thread_id":3135
2845          }
2846       ]
2847    }
2848
2849 EQMP
2850
2851     {
2852         .name       = "query-cpus",
2853         .args_type  = "",
2854         .mhandler.cmd_new = qmp_marshal_query_cpus,
2855     },
2856
2857 SQMP
2858 query-iothreads
2859 ---------------
2860
2861 Returns a list of information about each iothread.
2862
2863 Note this list excludes the QEMU main loop thread, which is not declared
2864 using the -object iothread command-line option.  It is always the main thread
2865 of the process.
2866
2867 Return a json-array. Each iothread is represented by a json-object, which contains:
2868
2869 - "id": name of iothread (json-str)
2870 - "thread-id": ID of the underlying host thread (json-int)
2871
2872 Example:
2873
2874 -> { "execute": "query-iothreads" }
2875 <- {
2876       "return":[
2877          {
2878             "id":"iothread0",
2879             "thread-id":3134
2880          },
2881          {
2882             "id":"iothread1",
2883             "thread-id":3135
2884          }
2885       ]
2886    }
2887
2888 EQMP
2889
2890     {
2891         .name       = "query-iothreads",
2892         .args_type  = "",
2893         .mhandler.cmd_new = qmp_marshal_query_iothreads,
2894     },
2895
2896 SQMP
2897 query-pci
2898 ---------
2899
2900 PCI buses and devices information.
2901
2902 The returned value is a json-array of all buses. Each bus is represented by
2903 a json-object, which has a key with a json-array of all PCI devices attached
2904 to it. Each device is represented by a json-object.
2905
2906 The bus json-object contains the following:
2907
2908 - "bus": bus number (json-int)
2909 - "devices": a json-array of json-objects, each json-object represents a
2910              PCI device
2911
2912 The PCI device json-object contains the following:
2913
2914 - "bus": identical to the parent's bus number (json-int)
2915 - "slot": slot number (json-int)
2916 - "function": function number (json-int)
2917 - "class_info": a json-object containing:
2918      - "desc": device class description (json-string, optional)
2919      - "class": device class number (json-int)
2920 - "id": a json-object containing:
2921      - "device": device ID (json-int)
2922      - "vendor": vendor ID (json-int)
2923 - "irq": device's IRQ if assigned (json-int, optional)
2924 - "qdev_id": qdev id string (json-string)
2925 - "pci_bridge": It's a json-object, only present if this device is a
2926                 PCI bridge, contains:
2927      - "bus": bus number (json-int)
2928      - "secondary": secondary bus number (json-int)
2929      - "subordinate": subordinate bus number (json-int)
2930      - "io_range": I/O memory range information, a json-object with the
2931                    following members:
2932                  - "base": base address, in bytes (json-int)
2933                  - "limit": limit address, in bytes (json-int)
2934      - "memory_range": memory range information, a json-object with the
2935                        following members:
2936                  - "base": base address, in bytes (json-int)
2937                  - "limit": limit address, in bytes (json-int)
2938      - "prefetchable_range": Prefetchable memory range information, a
2939                              json-object with the following members:
2940                  - "base": base address, in bytes (json-int)
2941                  - "limit": limit address, in bytes (json-int)
2942      - "devices": a json-array of PCI devices if there's any attached, each
2943                   each element is represented by a json-object, which contains
2944                   the same members of the 'PCI device json-object' described
2945                   above (optional)
2946 - "regions": a json-array of json-objects, each json-object represents a
2947              memory region of this device
2948
2949 The memory range json-object contains the following:
2950
2951 - "base": base memory address (json-int)
2952 - "limit": limit value (json-int)
2953
2954 The region json-object can be an I/O region or a memory region, an I/O region
2955 json-object contains the following:
2956
2957 - "type": "io" (json-string, fixed)
2958 - "bar": BAR number (json-int)
2959 - "address": memory address (json-int)
2960 - "size": memory size (json-int)
2961
2962 A memory region json-object contains the following:
2963
2964 - "type": "memory" (json-string, fixed)
2965 - "bar": BAR number (json-int)
2966 - "address": memory address (json-int)
2967 - "size": memory size (json-int)
2968 - "mem_type_64": true or false (json-bool)
2969 - "prefetch": true or false (json-bool)
2970
2971 Example:
2972
2973 -> { "execute": "query-pci" }
2974 <- {
2975       "return":[
2976          {
2977             "bus":0,
2978             "devices":[
2979                {
2980                   "bus":0,
2981                   "qdev_id":"",
2982                   "slot":0,
2983                   "class_info":{
2984                      "class":1536,
2985                      "desc":"Host bridge"
2986                   },
2987                   "id":{
2988                      "device":32902,
2989                      "vendor":4663
2990                   },
2991                   "function":0,
2992                   "regions":[
2993
2994                   ]
2995                },
2996                {
2997                   "bus":0,
2998                   "qdev_id":"",
2999                   "slot":1,
3000                   "class_info":{
3001                      "class":1537,
3002                      "desc":"ISA bridge"
3003                   },
3004                   "id":{
3005                      "device":32902,
3006                      "vendor":28672
3007                   },
3008                   "function":0,
3009                   "regions":[
3010
3011                   ]
3012                },
3013                {
3014                   "bus":0,
3015                   "qdev_id":"",
3016                   "slot":1,
3017                   "class_info":{
3018                      "class":257,
3019                      "desc":"IDE controller"
3020                   },
3021                   "id":{
3022                      "device":32902,
3023                      "vendor":28688
3024                   },
3025                   "function":1,
3026                   "regions":[
3027                      {
3028                         "bar":4,
3029                         "size":16,
3030                         "address":49152,
3031                         "type":"io"
3032                      }
3033                   ]
3034                },
3035                {
3036                   "bus":0,
3037                   "qdev_id":"",
3038                   "slot":2,
3039                   "class_info":{
3040                      "class":768,
3041                      "desc":"VGA controller"
3042                   },
3043                   "id":{
3044                      "device":4115,
3045                      "vendor":184
3046                   },
3047                   "function":0,
3048                   "regions":[
3049                      {
3050                         "prefetch":true,
3051                         "mem_type_64":false,
3052                         "bar":0,
3053                         "size":33554432,
3054                         "address":4026531840,
3055                         "type":"memory"
3056                      },
3057                      {
3058                         "prefetch":false,
3059                         "mem_type_64":false,
3060                         "bar":1,
3061                         "size":4096,
3062                         "address":4060086272,
3063                         "type":"memory"
3064                      },
3065                      {
3066                         "prefetch":false,
3067                         "mem_type_64":false,
3068                         "bar":6,
3069                         "size":65536,
3070                         "address":-1,
3071                         "type":"memory"
3072                      }
3073                   ]
3074                },
3075                {
3076                   "bus":0,
3077                   "qdev_id":"",
3078                   "irq":11,
3079                   "slot":4,
3080                   "class_info":{
3081                      "class":1280,
3082                      "desc":"RAM controller"
3083                   },
3084                   "id":{
3085                      "device":6900,
3086                      "vendor":4098
3087                   },
3088                   "function":0,
3089                   "regions":[
3090                      {
3091                         "bar":0,
3092                         "size":32,
3093                         "address":49280,
3094                         "type":"io"
3095                      }
3096                   ]
3097                }
3098             ]
3099          }
3100       ]
3101    }
3102
3103 Note: This example has been shortened as the real response is too long.
3104
3105 EQMP
3106
3107     {
3108         .name       = "query-pci",
3109         .args_type  = "",
3110         .mhandler.cmd_new = qmp_marshal_query_pci,
3111     },
3112
3113 SQMP
3114 query-kvm
3115 ---------
3116
3117 Show KVM information.
3118
3119 Return a json-object with the following information:
3120
3121 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
3122 - "present": true if QEMU has KVM support, false otherwise (json-bool)
3123
3124 Example:
3125
3126 -> { "execute": "query-kvm" }
3127 <- { "return": { "enabled": true, "present": true } }
3128
3129 EQMP
3130
3131     {
3132         .name       = "query-kvm",
3133         .args_type  = "",
3134         .mhandler.cmd_new = qmp_marshal_query_kvm,
3135     },
3136
3137 SQMP
3138 query-status
3139 ------------
3140
3141 Return a json-object with the following information:
3142
3143 - "running": true if the VM is running, or false if it is paused (json-bool)
3144 - "singlestep": true if the VM is in single step mode,
3145                 false otherwise (json-bool)
3146 - "status": one of the following values (json-string)
3147     "debug" - QEMU is running on a debugger
3148     "inmigrate" - guest is paused waiting for an incoming migration
3149     "internal-error" - An internal error that prevents further guest
3150     execution has occurred
3151     "io-error" - the last IOP has failed and the device is configured
3152     to pause on I/O errors
3153     "paused" - guest has been paused via the 'stop' command
3154     "postmigrate" - guest is paused following a successful 'migrate'
3155     "prelaunch" - QEMU was started with -S and guest has not started
3156     "finish-migrate" - guest is paused to finish the migration process
3157     "restore-vm" - guest is paused to restore VM state
3158     "running" - guest is actively running
3159     "save-vm" - guest is paused to save the VM state
3160     "shutdown" - guest is shut down (and -no-shutdown is in use)
3161     "watchdog" - the watchdog action is configured to pause and
3162      has been triggered
3163
3164 Example:
3165
3166 -> { "execute": "query-status" }
3167 <- { "return": { "running": true, "singlestep": false, "status": "running" } }
3168
3169 EQMP
3170
3171     {
3172         .name       = "query-status",
3173         .args_type  = "",
3174         .mhandler.cmd_new = qmp_marshal_query_status,
3175     },
3176
3177 SQMP
3178 query-mice
3179 ----------
3180
3181 Show VM mice information.
3182
3183 Each mouse is represented by a json-object, the returned value is a json-array
3184 of all mice.
3185
3186 The mouse json-object contains the following:
3187
3188 - "name": mouse's name (json-string)
3189 - "index": mouse's index (json-int)
3190 - "current": true if this mouse is receiving events, false otherwise (json-bool)
3191 - "absolute": true if the mouse generates absolute input events (json-bool)
3192
3193 Example:
3194
3195 -> { "execute": "query-mice" }
3196 <- {
3197       "return":[
3198          {
3199             "name":"QEMU Microsoft Mouse",
3200             "index":0,
3201             "current":false,
3202             "absolute":false
3203          },
3204          {
3205             "name":"QEMU PS/2 Mouse",
3206             "index":1,
3207             "current":true,
3208             "absolute":true
3209          }
3210       ]
3211    }
3212
3213 EQMP
3214
3215     {
3216         .name       = "query-mice",
3217         .args_type  = "",
3218         .mhandler.cmd_new = qmp_marshal_query_mice,
3219     },
3220
3221 SQMP
3222 query-vnc
3223 ---------
3224
3225 Show VNC server information.
3226
3227 Return a json-object with server information. Connected clients are returned
3228 as a json-array of json-objects.
3229
3230 The main json-object contains the following:
3231
3232 - "enabled": true or false (json-bool)
3233 - "host": server's IP address (json-string)
3234 - "family": address family (json-string)
3235          - Possible values: "ipv4", "ipv6", "unix", "unknown"
3236 - "service": server's port number (json-string)
3237 - "auth": authentication method (json-string)
3238          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
3239                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
3240                             "vencrypt+plain", "vencrypt+tls+none",
3241                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
3242                             "vencrypt+tls+vnc", "vencrypt+x509+none",
3243                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
3244                             "vencrypt+x509+vnc", "vnc"
3245 - "clients": a json-array of all connected clients
3246
3247 Clients are described by a json-object, each one contain the following:
3248
3249 - "host": client's IP address (json-string)
3250 - "family": address family (json-string)
3251          - Possible values: "ipv4", "ipv6", "unix", "unknown"
3252 - "service": client's port number (json-string)
3253 - "x509_dname": TLS dname (json-string, optional)
3254 - "sasl_username": SASL username (json-string, optional)
3255
3256 Example:
3257
3258 -> { "execute": "query-vnc" }
3259 <- {
3260       "return":{
3261          "enabled":true,
3262          "host":"0.0.0.0",
3263          "service":"50402",
3264          "auth":"vnc",
3265          "family":"ipv4",
3266          "clients":[
3267             {
3268                "host":"127.0.0.1",
3269                "service":"50401",
3270                "family":"ipv4"
3271             }
3272          ]
3273       }
3274    }
3275
3276 EQMP
3277
3278     {
3279         .name       = "query-vnc",
3280         .args_type  = "",
3281         .mhandler.cmd_new = qmp_marshal_query_vnc,
3282     },
3283     {
3284         .name       = "query-vnc-servers",
3285         .args_type  = "",
3286         .mhandler.cmd_new = qmp_marshal_query_vnc_servers,
3287     },
3288
3289 SQMP
3290 query-spice
3291 -----------
3292
3293 Show SPICE server information.
3294
3295 Return a json-object with server information. Connected clients are returned
3296 as a json-array of json-objects.
3297
3298 The main json-object contains the following:
3299
3300 - "enabled": true or false (json-bool)
3301 - "host": server's IP address (json-string)
3302 - "port": server's port number (json-int, optional)
3303 - "tls-port": server's port number (json-int, optional)
3304 - "auth": authentication method (json-string)
3305          - Possible values: "none", "spice"
3306 - "channels": a json-array of all active channels clients
3307
3308 Channels are described by a json-object, each one contain the following:
3309
3310 - "host": client's IP address (json-string)
3311 - "family": address family (json-string)
3312          - Possible values: "ipv4", "ipv6", "unix", "unknown"
3313 - "port": client's port number (json-string)
3314 - "connection-id": spice connection id.  All channels with the same id
3315                    belong to the same spice session (json-int)
3316 - "channel-type": channel type.  "1" is the main control channel, filter for
3317                   this one if you want track spice sessions only (json-int)
3318 - "channel-id": channel id.  Usually "0", might be different needed when
3319                 multiple channels of the same type exist, such as multiple
3320                 display channels in a multihead setup (json-int)
3321 - "tls": whether the channel is encrypted (json-bool)
3322
3323 Example:
3324
3325 -> { "execute": "query-spice" }
3326 <- {
3327       "return": {
3328          "enabled": true,
3329          "auth": "spice",
3330          "port": 5920,
3331          "tls-port": 5921,
3332          "host": "0.0.0.0",
3333          "channels": [
3334             {
3335                "port": "54924",
3336                "family": "ipv4",
3337                "channel-type": 1,
3338                "connection-id": 1804289383,
3339                "host": "127.0.0.1",
3340                "channel-id": 0,
3341                "tls": true
3342             },
3343             {
3344                "port": "36710",
3345                "family": "ipv4",
3346                "channel-type": 4,
3347                "connection-id": 1804289383,
3348                "host": "127.0.0.1",
3349                "channel-id": 0,
3350                "tls": false
3351             },
3352             [ ... more channels follow ... ]
3353          ]
3354       }
3355    }
3356
3357 EQMP
3358
3359 #if defined(CONFIG_SPICE)
3360     {
3361         .name       = "query-spice",
3362         .args_type  = "",
3363         .mhandler.cmd_new = qmp_marshal_query_spice,
3364     },
3365 #endif
3366
3367 SQMP
3368 query-name
3369 ----------
3370
3371 Show VM name.
3372
3373 Return a json-object with the following information:
3374
3375 - "name": VM's name (json-string, optional)
3376
3377 Example:
3378
3379 -> { "execute": "query-name" }
3380 <- { "return": { "name": "qemu-name" } }
3381
3382 EQMP
3383
3384     {
3385         .name       = "query-name",
3386         .args_type  = "",
3387         .mhandler.cmd_new = qmp_marshal_query_name,
3388     },
3389
3390 SQMP
3391 query-uuid
3392 ----------
3393
3394 Show VM UUID.
3395
3396 Return a json-object with the following information:
3397
3398 - "UUID": Universally Unique Identifier (json-string)
3399
3400 Example:
3401
3402 -> { "execute": "query-uuid" }
3403 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
3404
3405 EQMP
3406
3407     {
3408         .name       = "query-uuid",
3409         .args_type  = "",
3410         .mhandler.cmd_new = qmp_marshal_query_uuid,
3411     },
3412
3413 SQMP
3414 query-command-line-options
3415 --------------------------
3416
3417 Show command line option schema.
3418
3419 Return a json-array of command line option schema for all options (or for
3420 the given option), returning an error if the given option doesn't exist.
3421
3422 Each array entry contains the following:
3423
3424 - "option": option name (json-string)
3425 - "parameters": a json-array describes all parameters of the option:
3426     - "name": parameter name (json-string)
3427     - "type": parameter type (one of 'string', 'boolean', 'number',
3428               or 'size')
3429     - "help": human readable description of the parameter
3430               (json-string, optional)
3431     - "default": default value string for the parameter
3432                  (json-string, optional)
3433
3434 Example:
3435
3436 -> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } }
3437 <- { "return": [
3438         {
3439             "parameters": [
3440                 {
3441                     "name": "romfile",
3442                     "type": "string"
3443                 },
3444                 {
3445                     "name": "bootindex",
3446                     "type": "number"
3447                 }
3448             ],
3449             "option": "option-rom"
3450         }
3451      ]
3452    }
3453
3454 EQMP
3455
3456     {
3457         .name       = "query-command-line-options",
3458         .args_type  = "option:s?",
3459         .mhandler.cmd_new = qmp_marshal_query_command_line_options,
3460     },
3461
3462 SQMP
3463 query-migrate
3464 -------------
3465
3466 Migration status.
3467
3468 Return a json-object. If migration is active there will be another json-object
3469 with RAM migration status and if block migration is active another one with
3470 block migration status.
3471
3472 The main json-object contains the following:
3473
3474 - "status": migration status (json-string)
3475      - Possible values: "setup", "active", "completed", "failed", "cancelled"
3476 - "total-time": total amount of ms since migration started.  If
3477                 migration has ended, it returns the total migration
3478                 time (json-int)
3479 - "setup-time" amount of setup time in milliseconds _before_ the
3480                iterations begin but _after_ the QMP command is issued.
3481                This is designed to provide an accounting of any activities
3482                (such as RDMA pinning) which may be expensive, but do not
3483                actually occur during the iterative migration rounds
3484                themselves. (json-int)
3485 - "downtime": only present when migration has finished correctly
3486               total amount in ms for downtime that happened (json-int)
3487 - "expected-downtime": only present while migration is active
3488                 total amount in ms for downtime that was calculated on
3489                 the last bitmap round (json-int)
3490 - "ram": only present if "status" is "active", it is a json-object with the
3491   following RAM information:
3492          - "transferred": amount transferred in bytes (json-int)
3493          - "remaining": amount remaining to transfer in bytes (json-int)
3494          - "total": total amount of memory in bytes (json-int)
3495          - "duplicate": number of pages filled entirely with the same
3496             byte (json-int)
3497             These are sent over the wire much more efficiently.
3498          - "skipped": number of skipped zero pages (json-int)
3499          - "normal" : number of whole pages transferred.  I.e. they
3500             were not sent as duplicate or xbzrle pages (json-int)
3501          - "normal-bytes" : number of bytes transferred in whole
3502             pages. This is just normal pages times size of one page,
3503             but this way upper levels don't need to care about page
3504             size (json-int)
3505          - "dirty-sync-count": times that dirty ram was synchronized (json-int)
3506 - "disk": only present if "status" is "active" and it is a block migration,
3507   it is a json-object with the following disk information:
3508          - "transferred": amount transferred in bytes (json-int)
3509          - "remaining": amount remaining to transfer in bytes json-int)
3510          - "total": total disk size in bytes (json-int)
3511 - "xbzrle-cache": only present if XBZRLE is active.
3512   It is a json-object with the following XBZRLE information:
3513          - "cache-size": XBZRLE cache size in bytes
3514          - "bytes": number of bytes transferred for XBZRLE compressed pages
3515          - "pages": number of XBZRLE compressed pages
3516          - "cache-miss": number of XBRZRLE page cache misses
3517          - "cache-miss-rate": rate of XBRZRLE page cache misses
3518          - "overflow": number of times XBZRLE overflows.  This means
3519            that the XBZRLE encoding was bigger than just sent the
3520            whole page, and then we sent the whole page instead (as as
3521            normal page).
3522
3523 Examples:
3524
3525 1. Before the first migration
3526
3527 -> { "execute": "query-migrate" }
3528 <- { "return": {} }
3529
3530 2. Migration is done and has succeeded
3531
3532 -> { "execute": "query-migrate" }
3533 <- { "return": {
3534         "status": "completed",
3535         "ram":{
3536           "transferred":123,
3537           "remaining":123,
3538           "total":246,
3539           "total-time":12345,
3540           "setup-time":12345,
3541           "downtime":12345,
3542           "duplicate":123,
3543           "normal":123,
3544           "normal-bytes":123456,
3545           "dirty-sync-count":15
3546         }
3547      }
3548    }
3549
3550 3. Migration is done and has failed
3551
3552 -> { "execute": "query-migrate" }
3553 <- { "return": { "status": "failed" } }
3554
3555 4. Migration is being performed and is not a block migration:
3556
3557 -> { "execute": "query-migrate" }
3558 <- {
3559       "return":{
3560          "status":"active",
3561          "ram":{
3562             "transferred":123,
3563             "remaining":123,
3564             "total":246,
3565             "total-time":12345,
3566             "setup-time":12345,
3567             "expected-downtime":12345,
3568             "duplicate":123,
3569             "normal":123,
3570             "normal-bytes":123456,
3571             "dirty-sync-count":15
3572          }
3573       }
3574    }
3575
3576 5. Migration is being performed and is a block migration:
3577
3578 -> { "execute": "query-migrate" }
3579 <- {
3580       "return":{
3581          "status":"active",
3582          "ram":{
3583             "total":1057024,
3584             "remaining":1053304,
3585             "transferred":3720,
3586             "total-time":12345,
3587             "setup-time":12345,
3588             "expected-downtime":12345,
3589             "duplicate":123,
3590             "normal":123,
3591             "normal-bytes":123456,
3592             "dirty-sync-count":15
3593          },
3594          "disk":{
3595             "total":20971520,
3596             "remaining":20880384,
3597             "transferred":91136
3598          }
3599       }
3600    }
3601
3602 6. Migration is being performed and XBZRLE is active:
3603
3604 -> { "execute": "query-migrate" }
3605 <- {
3606       "return":{
3607          "status":"active",
3608          "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
3609          "ram":{
3610             "total":1057024,
3611             "remaining":1053304,
3612             "transferred":3720,
3613             "total-time":12345,
3614             "setup-time":12345,
3615             "expected-downtime":12345,
3616             "duplicate":10,
3617             "normal":3333,
3618             "normal-bytes":3412992,
3619             "dirty-sync-count":15
3620          },
3621          "xbzrle-cache":{
3622             "cache-size":67108864,
3623             "bytes":20971520,
3624             "pages":2444343,
3625             "cache-miss":2244,
3626             "cache-miss-rate":0.123,
3627             "overflow":34434
3628          }
3629       }
3630    }
3631
3632 EQMP
3633
3634     {
3635         .name       = "query-migrate",
3636         .args_type  = "",
3637         .mhandler.cmd_new = qmp_marshal_query_migrate,
3638     },
3639
3640 SQMP
3641 migrate-set-capabilities
3642 ------------------------
3643
3644 Enable/Disable migration capabilities
3645
3646 - "xbzrle": XBZRLE support
3647 - "rdma-pin-all": pin all pages when using RDMA during migration
3648 - "auto-converge": throttle down guest to help convergence of migration
3649 - "zero-blocks": compress zero blocks during block migration
3650 - "compress": use multiple compression threads to accelerate live migration
3651 - "events": generate events for each migration state change
3652 - "x-postcopy-ram": postcopy mode for live migration
3653
3654 Arguments:
3655
3656 Example:
3657
3658 -> { "execute": "migrate-set-capabilities" , "arguments":
3659      { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
3660
3661 EQMP
3662
3663     {
3664         .name       = "migrate-set-capabilities",
3665         .args_type  = "capabilities:q",
3666         .params     = "capability:s,state:b",
3667         .mhandler.cmd_new = qmp_marshal_migrate_set_capabilities,
3668     },
3669 SQMP
3670 query-migrate-capabilities
3671 --------------------------
3672
3673 Query current migration capabilities
3674
3675 - "capabilities": migration capabilities state
3676          - "xbzrle" : XBZRLE state (json-bool)
3677          - "rdma-pin-all" : RDMA Pin Page state (json-bool)
3678          - "auto-converge" : Auto Converge state (json-bool)
3679          - "zero-blocks" : Zero Blocks state (json-bool)
3680          - "compress": Multiple compression threads state (json-bool)
3681          - "events": Migration state change event state (json-bool)
3682          - "x-postcopy-ram": postcopy ram state (json-bool)
3683
3684 Arguments:
3685
3686 Example:
3687
3688 -> { "execute": "query-migrate-capabilities" }
3689 <- {"return": [
3690      {"state": false, "capability": "xbzrle"},
3691      {"state": false, "capability": "rdma-pin-all"},
3692      {"state": false, "capability": "auto-converge"},
3693      {"state": false, "capability": "zero-blocks"},
3694      {"state": false, "capability": "compress"},
3695      {"state": true, "capability": "events"},
3696      {"state": false, "capability": "x-postcopy-ram"}
3697    ]}
3698
3699 EQMP
3700
3701     {
3702         .name       = "query-migrate-capabilities",
3703         .args_type  = "",
3704         .mhandler.cmd_new = qmp_marshal_query_migrate_capabilities,
3705     },
3706
3707 SQMP
3708 migrate-set-parameters
3709 ----------------------
3710
3711 Set migration parameters
3712
3713 - "compress-level": set compression level during migration (json-int)
3714 - "compress-threads": set compression thread count for migration (json-int)
3715 - "decompress-threads": set decompression thread count for migration (json-int)
3716 - "x-cpu-throttle-initial": set initial percentage of time guest cpus are
3717                            throttled for auto-converge (json-int)
3718 - "x-cpu-throttle-increment": set throttle increasing percentage for
3719                              auto-converge (json-int)
3720
3721 Arguments:
3722
3723 Example:
3724
3725 -> { "execute": "migrate-set-parameters" , "arguments":
3726       { "compress-level": 1 } }
3727
3728 EQMP
3729
3730     {
3731         .name       = "migrate-set-parameters",
3732         .args_type  =
3733             "compress-level:i?,compress-threads:i?,decompress-threads:i?,x-cpu-throttle-initial:i?,x-cpu-throttle-increment:i?",
3734         .mhandler.cmd_new = qmp_marshal_migrate_set_parameters,
3735     },
3736 SQMP
3737 query-migrate-parameters
3738 ------------------------
3739
3740 Query current migration parameters
3741
3742 - "parameters": migration parameters value
3743          - "compress-level" : compression level value (json-int)
3744          - "compress-threads" : compression thread count value (json-int)
3745          - "decompress-threads" : decompression thread count value (json-int)
3746          - "x-cpu-throttle-initial" : initial percentage of time guest cpus are
3747                                       throttled (json-int)
3748          - "x-cpu-throttle-increment" : throttle increasing percentage for
3749                                         auto-converge (json-int)
3750
3751 Arguments:
3752
3753 Example:
3754
3755 -> { "execute": "query-migrate-parameters" }
3756 <- {
3757       "return": {
3758          "decompress-threads": 2,
3759          "x-cpu-throttle-increment": 10,
3760          "compress-threads": 8,
3761          "compress-level": 1,
3762          "x-cpu-throttle-initial": 20
3763       }
3764    }
3765
3766 EQMP
3767
3768     {
3769         .name       = "query-migrate-parameters",
3770         .args_type  = "",
3771         .mhandler.cmd_new = qmp_marshal_query_migrate_parameters,
3772     },
3773
3774 SQMP
3775 query-balloon
3776 -------------
3777
3778 Show balloon information.
3779
3780 Make an asynchronous request for balloon info. When the request completes a
3781 json-object will be returned containing the following data:
3782
3783 - "actual": current balloon value in bytes (json-int)
3784
3785 Example:
3786
3787 -> { "execute": "query-balloon" }
3788 <- {
3789       "return":{
3790          "actual":1073741824,
3791       }
3792    }
3793
3794 EQMP
3795
3796     {
3797         .name       = "query-balloon",
3798         .args_type  = "",
3799         .mhandler.cmd_new = qmp_marshal_query_balloon,
3800     },
3801
3802     {
3803         .name       = "query-block-jobs",
3804         .args_type  = "",
3805         .mhandler.cmd_new = qmp_marshal_query_block_jobs,
3806     },
3807
3808     {
3809         .name       = "qom-list",
3810         .args_type  = "path:s",
3811         .mhandler.cmd_new = qmp_marshal_qom_list,
3812     },
3813
3814     {
3815         .name       = "qom-set",
3816         .args_type  = "path:s,property:s,value:q",
3817         .mhandler.cmd_new = qmp_marshal_qom_set,
3818     },
3819
3820     {
3821         .name       = "qom-get",
3822         .args_type  = "path:s,property:s",
3823         .mhandler.cmd_new = qmp_marshal_qom_get,
3824     },
3825
3826     {
3827         .name       = "nbd-server-start",
3828         .args_type  = "addr:q,tls-creds:s?",
3829         .mhandler.cmd_new = qmp_marshal_nbd_server_start,
3830     },
3831     {
3832         .name       = "nbd-server-add",
3833         .args_type  = "device:B,writable:b?",
3834         .mhandler.cmd_new = qmp_marshal_nbd_server_add,
3835     },
3836     {
3837         .name       = "nbd-server-stop",
3838         .args_type  = "",
3839         .mhandler.cmd_new = qmp_marshal_nbd_server_stop,
3840     },
3841
3842     {
3843         .name       = "change-vnc-password",
3844         .args_type  = "password:s",
3845         .mhandler.cmd_new = qmp_marshal_change_vnc_password,
3846     },
3847     {
3848         .name       = "qom-list-types",
3849         .args_type  = "implements:s?,abstract:b?",
3850         .mhandler.cmd_new = qmp_marshal_qom_list_types,
3851     },
3852
3853     {
3854         .name       = "device-list-properties",
3855         .args_type  = "typename:s",
3856         .mhandler.cmd_new = qmp_marshal_device_list_properties,
3857     },
3858
3859     {
3860         .name       = "query-machines",
3861         .args_type  = "",
3862         .mhandler.cmd_new = qmp_marshal_query_machines,
3863     },
3864
3865     {
3866         .name       = "query-cpu-definitions",
3867         .args_type  = "",
3868         .mhandler.cmd_new = qmp_marshal_query_cpu_definitions,
3869     },
3870
3871     {
3872         .name       = "query-target",
3873         .args_type  = "",
3874         .mhandler.cmd_new = qmp_marshal_query_target,
3875     },
3876
3877     {
3878         .name       = "query-tpm",
3879         .args_type  = "",
3880         .mhandler.cmd_new = qmp_marshal_query_tpm,
3881     },
3882
3883 SQMP
3884 query-tpm
3885 ---------
3886
3887 Return information about the TPM device.
3888
3889 Arguments: None
3890
3891 Example:
3892
3893 -> { "execute": "query-tpm" }
3894 <- { "return":
3895      [
3896        { "model": "tpm-tis",
3897          "options":
3898            { "type": "passthrough",
3899              "data":
3900                { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
3901                  "path": "/dev/tpm0"
3902                }
3903            },
3904          "id": "tpm0"
3905        }
3906      ]
3907    }
3908
3909 EQMP
3910
3911     {
3912         .name       = "query-tpm-models",
3913         .args_type  = "",
3914         .mhandler.cmd_new = qmp_marshal_query_tpm_models,
3915     },
3916
3917 SQMP
3918 query-tpm-models
3919 ----------------
3920
3921 Return a list of supported TPM models.
3922
3923 Arguments: None
3924
3925 Example:
3926
3927 -> { "execute": "query-tpm-models" }
3928 <- { "return": [ "tpm-tis" ] }
3929
3930 EQMP
3931
3932     {
3933         .name       = "query-tpm-types",
3934         .args_type  = "",
3935         .mhandler.cmd_new = qmp_marshal_query_tpm_types,
3936     },
3937
3938 SQMP
3939 query-tpm-types
3940 ---------------
3941
3942 Return a list of supported TPM types.
3943
3944 Arguments: None
3945
3946 Example:
3947
3948 -> { "execute": "query-tpm-types" }
3949 <- { "return": [ "passthrough" ] }
3950
3951 EQMP
3952
3953     {
3954         .name       = "chardev-add",
3955         .args_type  = "id:s,backend:q",
3956         .mhandler.cmd_new = qmp_marshal_chardev_add,
3957     },
3958
3959 SQMP
3960 chardev-add
3961 ----------------
3962
3963 Add a chardev.
3964
3965 Arguments:
3966
3967 - "id": the chardev's ID, must be unique (json-string)
3968 - "backend": chardev backend type + parameters
3969
3970 Examples:
3971
3972 -> { "execute" : "chardev-add",
3973      "arguments" : { "id" : "foo",
3974                      "backend" : { "type" : "null", "data" : {} } } }
3975 <- { "return": {} }
3976
3977 -> { "execute" : "chardev-add",
3978      "arguments" : { "id" : "bar",
3979                      "backend" : { "type" : "file",
3980                                    "data" : { "out" : "/tmp/bar.log" } } } }
3981 <- { "return": {} }
3982
3983 -> { "execute" : "chardev-add",
3984      "arguments" : { "id" : "baz",
3985                      "backend" : { "type" : "pty", "data" : {} } } }
3986 <- { "return": { "pty" : "/dev/pty/42" } }
3987
3988 EQMP
3989
3990     {
3991         .name       = "chardev-remove",
3992         .args_type  = "id:s",
3993         .mhandler.cmd_new = qmp_marshal_chardev_remove,
3994     },
3995
3996
3997 SQMP
3998 chardev-remove
3999 --------------
4000
4001 Remove a chardev.
4002
4003 Arguments:
4004
4005 - "id": the chardev's ID, must exist and not be in use (json-string)
4006
4007 Example:
4008
4009 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
4010 <- { "return": {} }
4011
4012 EQMP
4013     {
4014         .name       = "query-rx-filter",
4015         .args_type  = "name:s?",
4016         .mhandler.cmd_new = qmp_marshal_query_rx_filter,
4017     },
4018
4019 SQMP
4020 query-rx-filter
4021 ---------------
4022
4023 Show rx-filter information.
4024
4025 Returns a json-array of rx-filter information for all NICs (or for the
4026 given NIC), returning an error if the given NIC doesn't exist, or
4027 given NIC doesn't support rx-filter querying, or given net client
4028 isn't a NIC.
4029
4030 The query will clear the event notification flag of each NIC, then qemu
4031 will start to emit event to QMP monitor.
4032
4033 Each array entry contains the following:
4034
4035 - "name": net client name (json-string)
4036 - "promiscuous": promiscuous mode is enabled (json-bool)
4037 - "multicast": multicast receive state (one of 'normal', 'none', 'all')
4038 - "unicast": unicast receive state  (one of 'normal', 'none', 'all')
4039 - "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0)
4040 - "broadcast-allowed": allow to receive broadcast (json-bool)
4041 - "multicast-overflow": multicast table is overflowed (json-bool)
4042 - "unicast-overflow": unicast table is overflowed (json-bool)
4043 - "main-mac": main macaddr string (json-string)
4044 - "vlan-table": a json-array of active vlan id
4045 - "unicast-table": a json-array of unicast macaddr string
4046 - "multicast-table": a json-array of multicast macaddr string
4047
4048 Example:
4049
4050 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
4051 <- { "return": [
4052         {
4053             "promiscuous": true,
4054             "name": "vnet0",
4055             "main-mac": "52:54:00:12:34:56",
4056             "unicast": "normal",
4057             "vlan": "normal",
4058             "vlan-table": [
4059                 4,
4060                 0
4061             ],
4062             "unicast-table": [
4063             ],
4064             "multicast": "normal",
4065             "multicast-overflow": false,
4066             "unicast-overflow": false,
4067             "multicast-table": [
4068                 "01:00:5e:00:00:01",
4069                 "33:33:00:00:00:01",
4070                 "33:33:ff:12:34:56"
4071             ],
4072             "broadcast-allowed": false
4073         }
4074       ]
4075    }
4076
4077 EQMP
4078
4079     {
4080         .name       = "blockdev-add",
4081         .args_type  = "options:q",
4082         .mhandler.cmd_new = qmp_marshal_blockdev_add,
4083     },
4084
4085 SQMP
4086 blockdev-add
4087 ------------
4088
4089 Add a block device.
4090
4091 This command is still a work in progress.  It doesn't support all
4092 block drivers among other things.  Stay away from it unless you want
4093 to help with its development.
4094
4095 Arguments:
4096
4097 - "options": block driver options
4098
4099 Example (1):
4100
4101 -> { "execute": "blockdev-add",
4102     "arguments": { "options" : { "driver": "qcow2",
4103                                  "file": { "driver": "file",
4104                                            "filename": "test.qcow2" } } } }
4105 <- { "return": {} }
4106
4107 Example (2):
4108
4109 -> { "execute": "blockdev-add",
4110      "arguments": {
4111          "options": {
4112            "driver": "qcow2",
4113            "id": "my_disk",
4114            "discard": "unmap",
4115            "cache": {
4116                "direct": true,
4117                "writeback": true
4118            },
4119            "file": {
4120                "driver": "file",
4121                "filename": "/tmp/test.qcow2"
4122            },
4123            "backing": {
4124                "driver": "raw",
4125                "file": {
4126                    "driver": "file",
4127                    "filename": "/dev/fdset/4"
4128                }
4129            }
4130          }
4131        }
4132      }
4133
4134 <- { "return": {} }
4135
4136 EQMP
4137
4138     {
4139         .name       = "x-blockdev-del",
4140         .args_type  = "id:s?,node-name:s?",
4141         .mhandler.cmd_new = qmp_marshal_x_blockdev_del,
4142     },
4143
4144 SQMP
4145 x-blockdev-del
4146 ------------
4147 Since 2.5
4148
4149 Deletes a block device thas has been added using blockdev-add.
4150 The selected device can be either a block backend or a graph node.
4151
4152 In the former case the backend will be destroyed, along with its
4153 inserted medium if there's any. The command will fail if the backend
4154 or its medium are in use.
4155
4156 In the latter case the node will be destroyed. The command will fail
4157 if the node is attached to a block backend or is otherwise being
4158 used.
4159
4160 One of "id" or "node-name" must be specified, but not both.
4161
4162 This command is still a work in progress and is considered
4163 experimental. Stay away from it unless you want to help with its
4164 development.
4165
4166 Arguments:
4167
4168 - "id": Name of the block backend device to delete (json-string, optional)
4169 - "node-name": Name of the graph node to delete (json-string, optional)
4170
4171 Example:
4172
4173 -> { "execute": "blockdev-add",
4174      "arguments": {
4175          "options": {
4176              "driver": "qcow2",
4177              "id": "drive0",
4178              "file": {
4179                  "driver": "file",
4180                  "filename": "test.qcow2"
4181              }
4182          }
4183      }
4184    }
4185
4186 <- { "return": {} }
4187
4188 -> { "execute": "x-blockdev-del",
4189      "arguments": { "id": "drive0" }
4190    }
4191 <- { "return": {} }
4192
4193 EQMP
4194
4195     {
4196         .name       = "blockdev-open-tray",
4197         .args_type  = "device:s,force:b?",
4198         .mhandler.cmd_new = qmp_marshal_blockdev_open_tray,
4199     },
4200
4201 SQMP
4202 blockdev-open-tray
4203 ------------------
4204
4205 Opens a block device's tray. If there is a block driver state tree inserted as a
4206 medium, it will become inaccessible to the guest (but it will remain associated
4207 to the block device, so closing the tray will make it accessible again).
4208
4209 If the tray was already open before, this will be a no-op.
4210
4211 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
4212 which no such event will be generated, these include:
4213 - if the guest has locked the tray, @force is false and the guest does not
4214   respond to the eject request
4215 - if the BlockBackend denoted by @device does not have a guest device attached
4216   to it
4217 - if the guest device does not have an actual tray and is empty, for instance
4218   for floppy disk drives
4219
4220 Arguments:
4221
4222 - "device": block device name (json-string)
4223 - "force": if false (the default), an eject request will be sent to the guest if
4224            it has locked the tray (and the tray will not be opened immediately);
4225            if true, the tray will be opened regardless of whether it is locked
4226            (json-bool, optional)
4227
4228 Example:
4229
4230 -> { "execute": "blockdev-open-tray",
4231      "arguments": { "device": "ide1-cd0" } }
4232
4233 <- { "timestamp": { "seconds": 1418751016,
4234                     "microseconds": 716996 },
4235      "event": "DEVICE_TRAY_MOVED",
4236      "data": { "device": "ide1-cd0",
4237                "tray-open": true } }
4238
4239 <- { "return": {} }
4240
4241 EQMP
4242
4243     {
4244         .name       = "blockdev-close-tray",
4245         .args_type  = "device:s",
4246         .mhandler.cmd_new = qmp_marshal_blockdev_close_tray,
4247     },
4248
4249 SQMP
4250 blockdev-close-tray
4251 -------------------
4252
4253 Closes a block device's tray. If there is a block driver state tree associated
4254 with the block device (which is currently ejected), that tree will be loaded as
4255 the medium.
4256
4257 If the tray was already closed before, this will be a no-op.
4258
4259 Arguments:
4260
4261 - "device": block device name (json-string)
4262
4263 Example:
4264
4265 -> { "execute": "blockdev-close-tray",
4266      "arguments": { "device": "ide1-cd0" } }
4267
4268 <- { "timestamp": { "seconds": 1418751345,
4269                     "microseconds": 272147 },
4270      "event": "DEVICE_TRAY_MOVED",
4271      "data": { "device": "ide1-cd0",
4272                "tray-open": false } }
4273
4274 <- { "return": {} }
4275
4276 EQMP
4277
4278     {
4279         .name       = "x-blockdev-remove-medium",
4280         .args_type  = "device:s",
4281         .mhandler.cmd_new = qmp_marshal_x_blockdev_remove_medium,
4282     },
4283
4284 SQMP
4285 x-blockdev-remove-medium
4286 ------------------------
4287
4288 Removes a medium (a block driver state tree) from a block device. That block
4289 device's tray must currently be open (unless there is no attached guest device).
4290
4291 If the tray is open and there is no medium inserted, this will be a no-op.
4292
4293 This command is still a work in progress and is considered experimental.
4294 Stay away from it unless you want to help with its development.
4295
4296 Arguments:
4297
4298 - "device": block device name (json-string)
4299
4300 Example:
4301
4302 -> { "execute": "x-blockdev-remove-medium",
4303      "arguments": { "device": "ide1-cd0" } }
4304
4305 <- { "error": { "class": "GenericError",
4306                 "desc": "Tray of device 'ide1-cd0' is not open" } }
4307
4308 -> { "execute": "blockdev-open-tray",
4309      "arguments": { "device": "ide1-cd0" } }
4310
4311 <- { "timestamp": { "seconds": 1418751627,
4312                     "microseconds": 549958 },
4313      "event": "DEVICE_TRAY_MOVED",
4314      "data": { "device": "ide1-cd0",
4315                "tray-open": true } }
4316
4317 <- { "return": {} }
4318
4319 -> { "execute": "x-blockdev-remove-medium",
4320      "arguments": { "device": "ide1-cd0" } }
4321
4322 <- { "return": {} }
4323
4324 EQMP
4325
4326     {
4327         .name       = "x-blockdev-insert-medium",
4328         .args_type  = "device:s,node-name:s",
4329         .mhandler.cmd_new = qmp_marshal_x_blockdev_insert_medium,
4330     },
4331
4332 SQMP
4333 x-blockdev-insert-medium
4334 ------------------------
4335
4336 Inserts a medium (a block driver state tree) into a block device. That block
4337 device's tray must currently be open (unless there is no attached guest device)
4338 and there must be no medium inserted already.
4339
4340 This command is still a work in progress and is considered experimental.
4341 Stay away from it unless you want to help with its development.
4342
4343 Arguments:
4344
4345 - "device": block device name (json-string)
4346 - "node-name": root node of the BDS tree to insert into the block device
4347
4348 Example:
4349
4350 -> { "execute": "blockdev-add",
4351      "arguments": { "options": { "node-name": "node0",
4352                                  "driver": "raw",
4353                                  "file": { "driver": "file",
4354                                            "filename": "fedora.iso" } } } }
4355
4356 <- { "return": {} }
4357
4358 -> { "execute": "x-blockdev-insert-medium",
4359      "arguments": { "device": "ide1-cd0",
4360                     "node-name": "node0" } }
4361
4362 <- { "return": {} }
4363
4364 EQMP
4365
4366     {
4367         .name       = "query-named-block-nodes",
4368         .args_type  = "",
4369         .mhandler.cmd_new = qmp_marshal_query_named_block_nodes,
4370     },
4371
4372 SQMP
4373 @query-named-block-nodes
4374 ------------------------
4375
4376 Return a list of BlockDeviceInfo for all the named block driver nodes
4377
4378 Example:
4379
4380 -> { "execute": "query-named-block-nodes" }
4381 <- { "return": [ { "ro":false,
4382                    "drv":"qcow2",
4383                    "encrypted":false,
4384                    "file":"disks/test.qcow2",
4385                    "node-name": "my-node",
4386                    "backing_file_depth":1,
4387                    "bps":1000000,
4388                    "bps_rd":0,
4389                    "bps_wr":0,
4390                    "iops":1000000,
4391                    "iops_rd":0,
4392                    "iops_wr":0,
4393                    "bps_max": 8000000,
4394                    "bps_rd_max": 0,
4395                    "bps_wr_max": 0,
4396                    "iops_max": 0,
4397                    "iops_rd_max": 0,
4398                    "iops_wr_max": 0,
4399                    "iops_size": 0,
4400                    "write_threshold": 0,
4401                    "image":{
4402                       "filename":"disks/test.qcow2",
4403                       "format":"qcow2",
4404                       "virtual-size":2048000,
4405                       "backing_file":"base.qcow2",
4406                       "full-backing-filename":"disks/base.qcow2",
4407                       "backing-filename-format":"qcow2",
4408                       "snapshots":[
4409                          {
4410                             "id": "1",
4411                             "name": "snapshot1",
4412                             "vm-state-size": 0,
4413                             "date-sec": 10000200,
4414                             "date-nsec": 12,
4415                             "vm-clock-sec": 206,
4416                             "vm-clock-nsec": 30
4417                          }
4418                       ],
4419                       "backing-image":{
4420                           "filename":"disks/base.qcow2",
4421                           "format":"qcow2",
4422                           "virtual-size":2048000
4423                       }
4424                    } } ] }
4425
4426 EQMP
4427
4428     {
4429         .name       = "blockdev-change-medium",
4430         .args_type  = "device:B,filename:F,format:s?,read-only-mode:s?",
4431         .mhandler.cmd_new = qmp_marshal_blockdev_change_medium,
4432     },
4433
4434 SQMP
4435 blockdev-change-medium
4436 ----------------------
4437
4438 Changes the medium inserted into a block device by ejecting the current medium
4439 and loading a new image file which is inserted as the new medium.
4440
4441 Arguments:
4442
4443 - "device": device name (json-string)
4444 - "filename": filename of the new image (json-string)
4445 - "format": format of the new image (json-string, optional)
4446 - "read-only-mode": new read-only mode (json-string, optional)
4447           - Possible values: "retain" (default), "read-only", "read-write"
4448
4449 Examples:
4450
4451 1. Change a removable medium
4452
4453 -> { "execute": "blockdev-change-medium",
4454              "arguments": { "device": "ide1-cd0",
4455                             "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
4456                             "format": "raw" } }
4457 <- { "return": {} }
4458
4459 2. Load a read-only medium into a writable drive
4460
4461 -> { "execute": "blockdev-change-medium",
4462              "arguments": { "device": "isa-fd0",
4463                             "filename": "/srv/images/ro.img",
4464                             "format": "raw",
4465                             "read-only-mode": "retain" } }
4466
4467 <- { "error":
4468      { "class": "GenericError",
4469        "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
4470
4471 -> { "execute": "blockdev-change-medium",
4472              "arguments": { "device": "isa-fd0",
4473                             "filename": "/srv/images/ro.img",
4474                             "format": "raw",
4475                             "read-only-mode": "read-only" } }
4476
4477 <- { "return": {} }
4478
4479 EQMP
4480
4481     {
4482         .name       = "query-memdev",
4483         .args_type  = "",
4484         .mhandler.cmd_new = qmp_marshal_query_memdev,
4485     },
4486
4487 SQMP
4488 query-memdev
4489 ------------
4490
4491 Show memory devices information.
4492
4493
4494 Example (1):
4495
4496 -> { "execute": "query-memdev" }
4497 <- { "return": [
4498        {
4499          "size": 536870912,
4500          "merge": false,
4501          "dump": true,
4502          "prealloc": false,
4503          "host-nodes": [0, 1],
4504          "policy": "bind"
4505        },
4506        {
4507          "size": 536870912,
4508          "merge": false,
4509          "dump": true,
4510          "prealloc": true,
4511          "host-nodes": [2, 3],
4512          "policy": "preferred"
4513        }
4514      ]
4515    }
4516
4517 EQMP
4518
4519     {
4520         .name       = "query-memory-devices",
4521         .args_type  = "",
4522         .mhandler.cmd_new = qmp_marshal_query_memory_devices,
4523     },
4524
4525 SQMP
4526 @query-memory-devices
4527 --------------------
4528
4529 Return a list of memory devices.
4530
4531 Example:
4532 -> { "execute": "query-memory-devices" }
4533 <- { "return": [ { "data":
4534                       { "addr": 5368709120,
4535                         "hotpluggable": true,
4536                         "hotplugged": true,
4537                         "id": "d1",
4538                         "memdev": "/objects/memX",
4539                         "node": 0,
4540                         "size": 1073741824,
4541                         "slot": 0},
4542                    "type": "dimm"
4543                  } ] }
4544 EQMP
4545
4546     {
4547         .name       = "query-acpi-ospm-status",
4548         .args_type  = "",
4549         .mhandler.cmd_new = qmp_marshal_query_acpi_ospm_status,
4550     },
4551
4552 SQMP
4553 @query-acpi-ospm-status
4554 --------------------
4555
4556 Return list of ACPIOSTInfo for devices that support status reporting
4557 via ACPI _OST method.
4558
4559 Example:
4560 -> { "execute": "query-acpi-ospm-status" }
4561 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
4562                  { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
4563                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
4564                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
4565    ]}
4566 EQMP
4567
4568 #if defined TARGET_I386
4569     {
4570         .name       = "rtc-reset-reinjection",
4571         .args_type  = "",
4572         .mhandler.cmd_new = qmp_marshal_rtc_reset_reinjection,
4573     },
4574 #endif
4575
4576 SQMP
4577 rtc-reset-reinjection
4578 ---------------------
4579
4580 Reset the RTC interrupt reinjection backlog.
4581
4582 Arguments: None.
4583
4584 Example:
4585
4586 -> { "execute": "rtc-reset-reinjection" }
4587 <- { "return": {} }
4588 EQMP
4589
4590     {
4591         .name       = "trace-event-get-state",
4592         .args_type  = "name:s",
4593         .mhandler.cmd_new = qmp_marshal_trace_event_get_state,
4594     },
4595
4596 SQMP
4597 trace-event-get-state
4598 ---------------------
4599
4600 Query the state of events.
4601
4602 Example:
4603
4604 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
4605 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
4606 EQMP
4607
4608     {
4609         .name       = "trace-event-set-state",
4610         .args_type  = "name:s,enable:b,ignore-unavailable:b?",
4611         .mhandler.cmd_new = qmp_marshal_trace_event_set_state,
4612     },
4613
4614 SQMP
4615 trace-event-set-state
4616 ---------------------
4617
4618 Set the state of events.
4619
4620 Example:
4621
4622 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
4623 <- { "return": {} }
4624 EQMP
4625
4626     {
4627         .name       = "x-input-send-event",
4628         .args_type  = "console:i?,events:q",
4629         .mhandler.cmd_new = qmp_marshal_x_input_send_event,
4630     },
4631
4632 SQMP
4633 @x-input-send-event
4634 -----------------
4635
4636 Send input event to guest.
4637
4638 Arguments:
4639
4640 - "console": console index. (json-int, optional)
4641 - "events": list of input events.
4642
4643 The consoles are visible in the qom tree, under
4644 /backend/console[$index]. They have a device link and head property, so
4645 it is possible to map which console belongs to which device and display.
4646
4647 Note: this command is experimental, and not a stable API.
4648
4649 Example (1):
4650
4651 Press left mouse button.
4652
4653 -> { "execute": "x-input-send-event",
4654     "arguments": { "console": 0,
4655                    "events": [ { "type": "btn",
4656                     "data" : { "down": true, "button": "Left" } } ] } }
4657 <- { "return": {} }
4658
4659 -> { "execute": "x-input-send-event",
4660     "arguments": { "console": 0,
4661                    "events": [ { "type": "btn",
4662                     "data" : { "down": false, "button": "Left" } } ] } }
4663 <- { "return": {} }
4664
4665 Example (2):
4666
4667 Press ctrl-alt-del.
4668
4669 -> { "execute": "x-input-send-event",
4670      "arguments": { "console": 0, "events": [
4671         { "type": "key", "data" : { "down": true,
4672           "key": {"type": "qcode", "data": "ctrl" } } },
4673         { "type": "key", "data" : { "down": true,
4674           "key": {"type": "qcode", "data": "alt" } } },
4675         { "type": "key", "data" : { "down": true,
4676           "key": {"type": "qcode", "data": "delete" } } } ] } }
4677 <- { "return": {} }
4678
4679 Example (3):
4680
4681 Move mouse pointer to absolute coordinates (20000, 400).
4682
4683 -> { "execute": "x-input-send-event" ,
4684   "arguments": { "console": 0, "events": [
4685                { "type": "abs", "data" : { "axis": "X", "value" : 20000 } },
4686                { "type": "abs", "data" : { "axis": "Y", "value" : 400 } } ] } }
4687 <- { "return": {} }
4688
4689 EQMP
4690
4691     {
4692         .name       = "block-set-write-threshold",
4693         .args_type  = "node-name:s,write-threshold:l",
4694         .mhandler.cmd_new = qmp_marshal_block_set_write_threshold,
4695     },
4696
4697 SQMP
4698 block-set-write-threshold
4699 ------------
4700
4701 Change the write threshold for a block drive. The threshold is an offset,
4702 thus must be non-negative. Default is no write threshold.
4703 Setting the threshold to zero disables it.
4704
4705 Arguments:
4706
4707 - "node-name": the node name in the block driver state graph (json-string)
4708 - "write-threshold": the write threshold in bytes (json-int)
4709
4710 Example:
4711
4712 -> { "execute": "block-set-write-threshold",
4713   "arguments": { "node-name": "mydev",
4714                  "write-threshold": 17179869184 } }
4715 <- { "return": {} }
4716
4717 EQMP
4718
4719     {
4720         .name       = "query-rocker",
4721         .args_type  = "name:s",
4722         .mhandler.cmd_new = qmp_marshal_query_rocker,
4723     },
4724
4725 SQMP
4726 Show rocker switch
4727 ------------------
4728
4729 Arguments:
4730
4731 - "name": switch name
4732
4733 Example:
4734
4735 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
4736 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
4737
4738 EQMP
4739
4740     {
4741         .name       = "query-rocker-ports",
4742         .args_type  = "name:s",
4743         .mhandler.cmd_new = qmp_marshal_query_rocker_ports,
4744     },
4745
4746 SQMP
4747 Show rocker switch ports
4748 ------------------------
4749
4750 Arguments:
4751
4752 - "name": switch name
4753
4754 Example:
4755
4756 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
4757 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
4758                   "autoneg": "off", "link-up": true, "speed": 10000},
4759                  {"duplex": "full", "enabled": true, "name": "sw1.2",
4760                   "autoneg": "off", "link-up": true, "speed": 10000}
4761    ]}
4762
4763 EQMP
4764
4765     {
4766         .name       = "query-rocker-of-dpa-flows",
4767         .args_type  = "name:s,tbl-id:i?",
4768         .mhandler.cmd_new = qmp_marshal_query_rocker_of_dpa_flows,
4769     },
4770
4771 SQMP
4772 Show rocker switch OF-DPA flow tables
4773 -------------------------------------
4774
4775 Arguments:
4776
4777 - "name": switch name
4778 - "tbl-id": (optional) flow table ID
4779
4780 Example:
4781
4782 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
4783 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
4784                   "hits": 138,
4785                   "cookie": 0,
4786                   "action": {"goto-tbl": 10},
4787                   "mask": {"in-pport": 4294901760}
4788                  },
4789                  {...more...},
4790    ]}
4791
4792 EQMP
4793
4794     {
4795         .name       = "query-rocker-of-dpa-groups",
4796         .args_type  = "name:s,type:i?",
4797         .mhandler.cmd_new = qmp_marshal_query_rocker_of_dpa_groups,
4798     },
4799
4800 SQMP
4801 Show rocker OF-DPA group tables
4802 -------------------------------
4803
4804 Arguments:
4805
4806 - "name": switch name
4807 - "type": (optional) group type
4808
4809 Example:
4810
4811 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
4812 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
4813                   "pop-vlan": 1, "id": 251723778},
4814                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
4815                   "pop-vlan": 1, "id": 251723776},
4816                  {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
4817                   "pop-vlan": 1, "id": 251658241},
4818                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
4819                   "pop-vlan": 1, "id": 251658240}
4820    ]}