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       = "change-backing-file",
1669         .args_type  = "device:s,image-node-name:s,backing-file:s",
1670         .mhandler.cmd_new = qmp_marshal_change_backing_file,
1671     },
1672
1673 SQMP
1674 change-backing-file
1675 -------------------
1676 Since: 2.1
1677
1678 Change the backing file in the image file metadata.  This does not cause
1679 QEMU to reopen the image file to reparse the backing filename (it may,
1680 however, perform a reopen to change permissions from r/o -> r/w -> r/o,
1681 if needed). The new backing file string is written into the image file
1682 metadata, and the QEMU internal strings are updated.
1683
1684 Arguments:
1685
1686 - "image-node-name":    The name of the block driver state node of the
1687                         image to modify.  The "device" is argument is used to
1688                         verify "image-node-name" is in the chain described by
1689                         "device".
1690                         (json-string, optional)
1691
1692 - "device":             The name of the device.
1693                         (json-string)
1694
1695 - "backing-file":       The string to write as the backing file.  This string is
1696                         not validated, so care should be taken when specifying
1697                         the string or the image chain may not be able to be
1698                         reopened again.
1699                         (json-string)
1700
1701 Returns: Nothing on success
1702          If "device" does not exist or cannot be determined, DeviceNotFound
1703
1704 EQMP
1705
1706     {
1707         .name       = "balloon",
1708         .args_type  = "value:M",
1709         .mhandler.cmd_new = qmp_marshal_balloon,
1710     },
1711
1712 SQMP
1713 balloon
1714 -------
1715
1716 Request VM to change its memory allocation (in bytes).
1717
1718 Arguments:
1719
1720 - "value": New memory allocation (json-int)
1721
1722 Example:
1723
1724 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1725 <- { "return": {} }
1726
1727 EQMP
1728
1729     {
1730         .name       = "set_link",
1731         .args_type  = "name:s,up:b",
1732         .mhandler.cmd_new = qmp_marshal_set_link,
1733     },
1734
1735 SQMP
1736 set_link
1737 --------
1738
1739 Change the link status of a network adapter.
1740
1741 Arguments:
1742
1743 - "name": network device name (json-string)
1744 - "up": status is up (json-bool)
1745
1746 Example:
1747
1748 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1749 <- { "return": {} }
1750
1751 EQMP
1752
1753     {
1754         .name       = "getfd",
1755         .args_type  = "fdname:s",
1756         .params     = "getfd name",
1757         .help       = "receive a file descriptor via SCM rights and assign it a name",
1758         .mhandler.cmd_new = qmp_marshal_getfd,
1759     },
1760
1761 SQMP
1762 getfd
1763 -----
1764
1765 Receive a file descriptor via SCM rights and assign it a name.
1766
1767 Arguments:
1768
1769 - "fdname": file descriptor name (json-string)
1770
1771 Example:
1772
1773 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1774 <- { "return": {} }
1775
1776 Notes:
1777
1778 (1) If the name specified by the "fdname" argument already exists,
1779     the file descriptor assigned to it will be closed and replaced
1780     by the received file descriptor.
1781 (2) The 'closefd' command can be used to explicitly close the file
1782     descriptor when it is no longer needed.
1783
1784 EQMP
1785
1786     {
1787         .name       = "closefd",
1788         .args_type  = "fdname:s",
1789         .params     = "closefd name",
1790         .help       = "close a file descriptor previously passed via SCM rights",
1791         .mhandler.cmd_new = qmp_marshal_closefd,
1792     },
1793
1794 SQMP
1795 closefd
1796 -------
1797
1798 Close a file descriptor previously passed via SCM rights.
1799
1800 Arguments:
1801
1802 - "fdname": file descriptor name (json-string)
1803
1804 Example:
1805
1806 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1807 <- { "return": {} }
1808
1809 EQMP
1810
1811      {
1812         .name       = "add-fd",
1813         .args_type  = "fdset-id:i?,opaque:s?",
1814         .params     = "add-fd fdset-id opaque",
1815         .help       = "Add a file descriptor, that was passed via SCM rights, to an fd set",
1816         .mhandler.cmd_new = qmp_marshal_add_fd,
1817     },
1818
1819 SQMP
1820 add-fd
1821 -------
1822
1823 Add a file descriptor, that was passed via SCM rights, to an fd set.
1824
1825 Arguments:
1826
1827 - "fdset-id": The ID of the fd set to add the file descriptor to.
1828               (json-int, optional)
1829 - "opaque": A free-form string that can be used to describe the fd.
1830             (json-string, optional)
1831
1832 Return a json-object with the following information:
1833
1834 - "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1835 - "fd": The file descriptor that was received via SCM rights and added to the
1836         fd set. (json-int)
1837
1838 Example:
1839
1840 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1841 <- { "return": { "fdset-id": 1, "fd": 3 } }
1842
1843 Notes:
1844
1845 (1) The list of fd sets is shared by all monitor connections.
1846 (2) If "fdset-id" is not specified, a new fd set will be created.
1847
1848 EQMP
1849
1850      {
1851         .name       = "remove-fd",
1852         .args_type  = "fdset-id:i,fd:i?",
1853         .params     = "remove-fd fdset-id fd",
1854         .help       = "Remove a file descriptor from an fd set",
1855         .mhandler.cmd_new = qmp_marshal_remove_fd,
1856     },
1857
1858 SQMP
1859 remove-fd
1860 ---------
1861
1862 Remove a file descriptor from an fd set.
1863
1864 Arguments:
1865
1866 - "fdset-id": The ID of the fd set that the file descriptor belongs to.
1867               (json-int)
1868 - "fd": The file descriptor that is to be removed. (json-int, optional)
1869
1870 Example:
1871
1872 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1873 <- { "return": {} }
1874
1875 Notes:
1876
1877 (1) The list of fd sets is shared by all monitor connections.
1878 (2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1879     removed.
1880
1881 EQMP
1882
1883     {
1884         .name       = "query-fdsets",
1885         .args_type  = "",
1886         .help       = "Return information describing all fd sets",
1887         .mhandler.cmd_new = qmp_marshal_query_fdsets,
1888     },
1889
1890 SQMP
1891 query-fdsets
1892 -------------
1893
1894 Return information describing all fd sets.
1895
1896 Arguments: None
1897
1898 Example:
1899
1900 -> { "execute": "query-fdsets" }
1901 <- { "return": [
1902        {
1903          "fds": [
1904            {
1905              "fd": 30,
1906              "opaque": "rdonly:/path/to/file"
1907            },
1908            {
1909              "fd": 24,
1910              "opaque": "rdwr:/path/to/file"
1911            }
1912          ],
1913          "fdset-id": 1
1914        },
1915        {
1916          "fds": [
1917            {
1918              "fd": 28
1919            },
1920            {
1921              "fd": 29
1922            }
1923          ],
1924          "fdset-id": 0
1925        }
1926      ]
1927    }
1928
1929 Note: The list of fd sets is shared by all monitor connections.
1930
1931 EQMP
1932
1933     {
1934         .name       = "block_passwd",
1935         .args_type  = "device:s?,node-name:s?,password:s",
1936         .mhandler.cmd_new = qmp_marshal_block_passwd,
1937     },
1938
1939 SQMP
1940 block_passwd
1941 ------------
1942
1943 Set the password of encrypted block devices.
1944
1945 Arguments:
1946
1947 - "device": device name (json-string)
1948 - "node-name": name in the block driver state graph (json-string)
1949 - "password": password (json-string)
1950
1951 Example:
1952
1953 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1954                                                "password": "12345" } }
1955 <- { "return": {} }
1956
1957 EQMP
1958
1959     {
1960         .name       = "block_set_io_throttle",
1961         .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?",
1962         .mhandler.cmd_new = qmp_marshal_block_set_io_throttle,
1963     },
1964
1965 SQMP
1966 block_set_io_throttle
1967 ------------
1968
1969 Change I/O throttle limits for a block drive.
1970
1971 Arguments:
1972
1973 - "device": device name (json-string)
1974 - "bps": total throughput limit in bytes per second (json-int)
1975 - "bps_rd": read throughput limit in bytes per second (json-int)
1976 - "bps_wr": write throughput limit in bytes per second (json-int)
1977 - "iops": total I/O operations per second (json-int)
1978 - "iops_rd": read I/O operations per second (json-int)
1979 - "iops_wr": write I/O operations per second (json-int)
1980 - "bps_max":  total max in bytes (json-int)
1981 - "bps_rd_max":  read max in bytes (json-int)
1982 - "bps_wr_max":  write max in bytes (json-int)
1983 - "iops_max":  total I/O operations max (json-int)
1984 - "iops_rd_max":  read I/O operations max (json-int)
1985 - "iops_wr_max":  write I/O operations max (json-int)
1986 - "iops_size":  I/O size in bytes when limiting (json-int)
1987 - "group": throttle group name (json-string)
1988
1989 Example:
1990
1991 -> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
1992                                                "bps": 1000000,
1993                                                "bps_rd": 0,
1994                                                "bps_wr": 0,
1995                                                "iops": 0,
1996                                                "iops_rd": 0,
1997                                                "iops_wr": 0,
1998                                                "bps_max": 8000000,
1999                                                "bps_rd_max": 0,
2000                                                "bps_wr_max": 0,
2001                                                "iops_max": 0,
2002                                                "iops_rd_max": 0,
2003                                                "iops_wr_max": 0,
2004                                                "iops_size": 0 } }
2005 <- { "return": {} }
2006
2007 EQMP
2008
2009     {
2010         .name       = "set_password",
2011         .args_type  = "protocol:s,password:s,connected:s?",
2012         .mhandler.cmd_new = qmp_marshal_set_password,
2013     },
2014
2015 SQMP
2016 set_password
2017 ------------
2018
2019 Set the password for vnc/spice protocols.
2020
2021 Arguments:
2022
2023 - "protocol": protocol name (json-string)
2024 - "password": password (json-string)
2025 - "connected": [ keep | disconnect | fail ] (json-string, optional)
2026
2027 Example:
2028
2029 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
2030                                                "password": "secret" } }
2031 <- { "return": {} }
2032
2033 EQMP
2034
2035     {
2036         .name       = "expire_password",
2037         .args_type  = "protocol:s,time:s",
2038         .mhandler.cmd_new = qmp_marshal_expire_password,
2039     },
2040
2041 SQMP
2042 expire_password
2043 ---------------
2044
2045 Set the password expire time for vnc/spice protocols.
2046
2047 Arguments:
2048
2049 - "protocol": protocol name (json-string)
2050 - "time": [ now | never | +secs | secs ] (json-string)
2051
2052 Example:
2053
2054 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
2055                                                   "time": "+60" } }
2056 <- { "return": {} }
2057
2058 EQMP
2059
2060     {
2061         .name       = "add_client",
2062         .args_type  = "protocol:s,fdname:s,skipauth:b?,tls:b?",
2063         .mhandler.cmd_new = qmp_marshal_add_client,
2064     },
2065
2066 SQMP
2067 add_client
2068 ----------
2069
2070 Add a graphics client
2071
2072 Arguments:
2073
2074 - "protocol": protocol name (json-string)
2075 - "fdname": file descriptor name (json-string)
2076 - "skipauth": whether to skip authentication (json-bool, optional)
2077 - "tls": whether to perform TLS (json-bool, optional)
2078
2079 Example:
2080
2081 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
2082                                              "fdname": "myclient" } }
2083 <- { "return": {} }
2084
2085 EQMP
2086     {
2087         .name       = "qmp_capabilities",
2088         .args_type  = "",
2089         .params     = "",
2090         .help       = "enable QMP capabilities",
2091         .mhandler.cmd_new = qmp_capabilities,
2092     },
2093
2094 SQMP
2095 qmp_capabilities
2096 ----------------
2097
2098 Enable QMP capabilities.
2099
2100 Arguments: None.
2101
2102 Example:
2103
2104 -> { "execute": "qmp_capabilities" }
2105 <- { "return": {} }
2106
2107 Note: This command must be issued before issuing any other command.
2108
2109 EQMP
2110
2111     {
2112         .name       = "human-monitor-command",
2113         .args_type  = "command-line:s,cpu-index:i?",
2114         .mhandler.cmd_new = qmp_marshal_human_monitor_command,
2115     },
2116
2117 SQMP
2118 human-monitor-command
2119 ---------------------
2120
2121 Execute a Human Monitor command.
2122
2123 Arguments:
2124
2125 - command-line: the command name and its arguments, just like the
2126                 Human Monitor's shell (json-string)
2127 - cpu-index: select the CPU number to be used by commands which access CPU
2128              data, like 'info registers'. The Monitor selects CPU 0 if this
2129              argument is not provided (json-int, optional)
2130
2131 Example:
2132
2133 -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
2134 <- { "return": "kvm support: enabled\r\n" }
2135
2136 Notes:
2137
2138 (1) The Human Monitor is NOT an stable interface, this means that command
2139     names, arguments and responses can change or be removed at ANY time.
2140     Applications that rely on long term stability guarantees should NOT
2141     use this command
2142
2143 (2) Limitations:
2144
2145     o This command is stateless, this means that commands that depend
2146       on state information (such as getfd) might not work
2147
2148     o Commands that prompt the user for data (eg. 'cont' when the block
2149       device is encrypted) don't currently work
2150
2151 3. Query Commands
2152 =================
2153
2154 HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
2155 HXCOMM this! We will possibly move query commands definitions inside those
2156 HXCOMM sections, just like regular commands.
2157
2158 EQMP
2159
2160 SQMP
2161 query-version
2162 -------------
2163
2164 Show QEMU version.
2165
2166 Return a json-object with the following information:
2167
2168 - "qemu": A json-object containing three integer values:
2169     - "major": QEMU's major version (json-int)
2170     - "minor": QEMU's minor version (json-int)
2171     - "micro": QEMU's micro version (json-int)
2172 - "package": package's version (json-string)
2173
2174 Example:
2175
2176 -> { "execute": "query-version" }
2177 <- {
2178       "return":{
2179          "qemu":{
2180             "major":0,
2181             "minor":11,
2182             "micro":5
2183          },
2184          "package":""
2185       }
2186    }
2187
2188 EQMP
2189
2190     {
2191         .name       = "query-version",
2192         .args_type  = "",
2193         .mhandler.cmd_new = qmp_marshal_query_version,
2194     },
2195
2196 SQMP
2197 query-commands
2198 --------------
2199
2200 List QMP available commands.
2201
2202 Each command is represented by a json-object, the returned value is a json-array
2203 of all commands.
2204
2205 Each json-object contain:
2206
2207 - "name": command's name (json-string)
2208
2209 Example:
2210
2211 -> { "execute": "query-commands" }
2212 <- {
2213       "return":[
2214          {
2215             "name":"query-balloon"
2216          },
2217          {
2218             "name":"system_powerdown"
2219          }
2220       ]
2221    }
2222
2223 Note: This example has been shortened as the real response is too long.
2224
2225 EQMP
2226
2227     {
2228         .name       = "query-commands",
2229         .args_type  = "",
2230         .mhandler.cmd_new = qmp_marshal_query_commands,
2231     },
2232
2233 SQMP
2234 query-events
2235 --------------
2236
2237 List QMP available events.
2238
2239 Each event is represented by a json-object, the returned value is a json-array
2240 of all events.
2241
2242 Each json-object contains:
2243
2244 - "name": event's name (json-string)
2245
2246 Example:
2247
2248 -> { "execute": "query-events" }
2249 <- {
2250       "return":[
2251          {
2252             "name":"SHUTDOWN"
2253          },
2254          {
2255             "name":"RESET"
2256          }
2257       ]
2258    }
2259
2260 Note: This example has been shortened as the real response is too long.
2261
2262 EQMP
2263
2264     {
2265         .name       = "query-events",
2266         .args_type  = "",
2267         .mhandler.cmd_new = qmp_marshal_query_events,
2268     },
2269
2270 SQMP
2271 query-qmp-schema
2272 ----------------
2273
2274 Return the QMP wire schema.  The returned value is a json-array of
2275 named schema entities.  Entities are commands, events and various
2276 types.  See docs/qapi-code-gen.txt for information on their structure
2277 and intended use.
2278
2279 EQMP
2280
2281     {
2282         .name       = "query-qmp-schema",
2283         .args_type  = "",
2284         .mhandler.cmd_new = qmp_query_qmp_schema,
2285     },
2286
2287 SQMP
2288 query-chardev
2289 -------------
2290
2291 Each device is represented by a json-object. The returned value is a json-array
2292 of all devices.
2293
2294 Each json-object contain the following:
2295
2296 - "label": device's label (json-string)
2297 - "filename": device's file (json-string)
2298 - "frontend-open": open/closed state of the frontend device attached to this
2299                    backend (json-bool)
2300
2301 Example:
2302
2303 -> { "execute": "query-chardev" }
2304 <- {
2305       "return": [
2306          {
2307             "label": "charchannel0",
2308             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
2309             "frontend-open": false
2310          },
2311          {
2312             "label": "charmonitor",
2313             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
2314             "frontend-open": true
2315          },
2316          {
2317             "label": "charserial0",
2318             "filename": "pty:/dev/pts/2",
2319             "frontend-open": true
2320          }
2321       ]
2322    }
2323
2324 EQMP
2325
2326     {
2327         .name       = "query-chardev",
2328         .args_type  = "",
2329         .mhandler.cmd_new = qmp_marshal_query_chardev,
2330     },
2331
2332 SQMP
2333 query-chardev-backends
2334 -------------
2335
2336 List available character device backends.
2337
2338 Each backend is represented by a json-object, the returned value is a json-array
2339 of all backends.
2340
2341 Each json-object contains:
2342
2343 - "name": backend name (json-string)
2344
2345 Example:
2346
2347 -> { "execute": "query-chardev-backends" }
2348 <- {
2349       "return":[
2350          {
2351             "name":"udp"
2352          },
2353          {
2354             "name":"tcp"
2355          },
2356          {
2357             "name":"unix"
2358          },
2359          {
2360             "name":"spiceport"
2361          }
2362       ]
2363    }
2364
2365 EQMP
2366
2367     {
2368         .name       = "query-chardev-backends",
2369         .args_type  = "",
2370         .mhandler.cmd_new = qmp_marshal_query_chardev_backends,
2371     },
2372
2373 SQMP
2374 query-block
2375 -----------
2376
2377 Show the block devices.
2378
2379 Each block device information is stored in a json-object and the returned value
2380 is a json-array of all devices.
2381
2382 Each json-object contain the following:
2383
2384 - "device": device name (json-string)
2385 - "type": device type (json-string)
2386          - deprecated, retained for backward compatibility
2387          - Possible values: "unknown"
2388 - "removable": true if the device is removable, false otherwise (json-bool)
2389 - "locked": true if the device is locked, false otherwise (json-bool)
2390 - "tray_open": only present if removable, true if the device has a tray,
2391                and it is open (json-bool)
2392 - "inserted": only present if the device is inserted, it is a json-object
2393    containing the following:
2394          - "file": device file name (json-string)
2395          - "ro": true if read-only, false otherwise (json-bool)
2396          - "drv": driver format name (json-string)
2397              - Possible values: "blkdebug", "bochs", "cloop", "dmg",
2398                                 "file", "file", "ftp", "ftps", "host_cdrom",
2399                                 "host_device", "http", "https",
2400                                 "nbd", "parallels", "qcow", "qcow2", "raw",
2401                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
2402          - "backing_file": backing file name (json-string, optional)
2403          - "backing_file_depth": number of files in the backing file chain (json-int)
2404          - "encrypted": true if encrypted, false otherwise (json-bool)
2405          - "bps": limit total bytes per second (json-int)
2406          - "bps_rd": limit read bytes per second (json-int)
2407          - "bps_wr": limit write bytes per second (json-int)
2408          - "iops": limit total I/O operations per second (json-int)
2409          - "iops_rd": limit read operations per second (json-int)
2410          - "iops_wr": limit write operations per second (json-int)
2411          - "bps_max":  total max in bytes (json-int)
2412          - "bps_rd_max":  read max in bytes (json-int)
2413          - "bps_wr_max":  write max in bytes (json-int)
2414          - "iops_max":  total I/O operations max (json-int)
2415          - "iops_rd_max":  read I/O operations max (json-int)
2416          - "iops_wr_max":  write I/O operations max (json-int)
2417          - "iops_size": I/O size when limiting by iops (json-int)
2418          - "detect_zeroes": detect and optimize zero writing (json-string)
2419              - Possible values: "off", "on", "unmap"
2420          - "write_threshold": write offset threshold in bytes, a event will be
2421                               emitted if crossed. Zero if disabled (json-int)
2422          - "image": the detail of the image, it is a json-object containing
2423             the following:
2424              - "filename": image file name (json-string)
2425              - "format": image format (json-string)
2426              - "virtual-size": image capacity in bytes (json-int)
2427              - "dirty-flag": true if image is not cleanly closed, not present
2428                              means clean (json-bool, optional)
2429              - "actual-size": actual size on disk in bytes of the image, not
2430                               present when image does not support thin
2431                               provision (json-int, optional)
2432              - "cluster-size": size of a cluster in bytes, not present if image
2433                                format does not support it (json-int, optional)
2434              - "encrypted": true if the image is encrypted, not present means
2435                             false or the image format does not support
2436                             encryption (json-bool, optional)
2437              - "backing_file": backing file name, not present means no backing
2438                                file is used or the image format does not
2439                                support backing file chain
2440                                (json-string, optional)
2441              - "full-backing-filename": full path of the backing file, not
2442                                         present if it equals backing_file or no
2443                                         backing file is used
2444                                         (json-string, optional)
2445              - "backing-filename-format": the format of the backing file, not
2446                                           present means unknown or no backing
2447                                           file (json-string, optional)
2448              - "snapshots": the internal snapshot info, it is an optional list
2449                 of json-object containing the following:
2450                  - "id": unique snapshot id (json-string)
2451                  - "name": snapshot name (json-string)
2452                  - "vm-state-size": size of the VM state in bytes (json-int)
2453                  - "date-sec": UTC date of the snapshot in seconds (json-int)
2454                  - "date-nsec": fractional part in nanoseconds to be used with
2455                                 date-sec (json-int)
2456                  - "vm-clock-sec": VM clock relative to boot in seconds
2457                                    (json-int)
2458                  - "vm-clock-nsec": fractional part in nanoseconds to be used
2459                                     with vm-clock-sec (json-int)
2460              - "backing-image": the detail of the backing image, it is an
2461                                 optional json-object only present when a
2462                                 backing image present for this image
2463
2464 - "io-status": I/O operation status, only present if the device supports it
2465                and the VM is configured to stop on errors. It's always reset
2466                to "ok" when the "cont" command is issued (json_string, optional)
2467              - Possible values: "ok", "failed", "nospace"
2468
2469 Example:
2470
2471 -> { "execute": "query-block" }
2472 <- {
2473       "return":[
2474          {
2475             "io-status": "ok",
2476             "device":"ide0-hd0",
2477             "locked":false,
2478             "removable":false,
2479             "inserted":{
2480                "ro":false,
2481                "drv":"qcow2",
2482                "encrypted":false,
2483                "file":"disks/test.qcow2",
2484                "backing_file_depth":1,
2485                "bps":1000000,
2486                "bps_rd":0,
2487                "bps_wr":0,
2488                "iops":1000000,
2489                "iops_rd":0,
2490                "iops_wr":0,
2491                "bps_max": 8000000,
2492                "bps_rd_max": 0,
2493                "bps_wr_max": 0,
2494                "iops_max": 0,
2495                "iops_rd_max": 0,
2496                "iops_wr_max": 0,
2497                "iops_size": 0,
2498                "detect_zeroes": "on",
2499                "write_threshold": 0,
2500                "image":{
2501                   "filename":"disks/test.qcow2",
2502                   "format":"qcow2",
2503                   "virtual-size":2048000,
2504                   "backing_file":"base.qcow2",
2505                   "full-backing-filename":"disks/base.qcow2",
2506                   "backing-filename-format":"qcow2",
2507                   "snapshots":[
2508                      {
2509                         "id": "1",
2510                         "name": "snapshot1",
2511                         "vm-state-size": 0,
2512                         "date-sec": 10000200,
2513                         "date-nsec": 12,
2514                         "vm-clock-sec": 206,
2515                         "vm-clock-nsec": 30
2516                      }
2517                   ],
2518                   "backing-image":{
2519                       "filename":"disks/base.qcow2",
2520                       "format":"qcow2",
2521                       "virtual-size":2048000
2522                   }
2523                }
2524             },
2525             "type":"unknown"
2526          },
2527          {
2528             "io-status": "ok",
2529             "device":"ide1-cd0",
2530             "locked":false,
2531             "removable":true,
2532             "type":"unknown"
2533          },
2534          {
2535             "device":"floppy0",
2536             "locked":false,
2537             "removable":true,
2538             "type":"unknown"
2539          },
2540          {
2541             "device":"sd0",
2542             "locked":false,
2543             "removable":true,
2544             "type":"unknown"
2545          }
2546       ]
2547    }
2548
2549 EQMP
2550
2551     {
2552         .name       = "query-block",
2553         .args_type  = "",
2554         .mhandler.cmd_new = qmp_marshal_query_block,
2555     },
2556
2557 SQMP
2558 query-blockstats
2559 ----------------
2560
2561 Show block device statistics.
2562
2563 Each device statistic information is stored in a json-object and the returned
2564 value is a json-array of all devices.
2565
2566 Each json-object contain the following:
2567
2568 - "device": device name (json-string)
2569 - "stats": A json-object with the statistics information, it contains:
2570     - "rd_bytes": bytes read (json-int)
2571     - "wr_bytes": bytes written (json-int)
2572     - "rd_operations": read operations (json-int)
2573     - "wr_operations": write operations (json-int)
2574     - "flush_operations": cache flush operations (json-int)
2575     - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
2576     - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
2577     - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
2578     - "wr_highest_offset": The offset after the greatest byte written to the
2579                            BlockDriverState since it has been opened (json-int)
2580     - "rd_merged": number of read requests that have been merged into
2581                    another request (json-int)
2582     - "wr_merged": number of write requests that have been merged into
2583                    another request (json-int)
2584     - "idle_time_ns": time since the last I/O operation, in
2585                       nanoseconds. If the field is absent it means
2586                       that there haven't been any operations yet
2587                       (json-int, optional)
2588     - "failed_rd_operations": number of failed read operations
2589                               (json-int)
2590     - "failed_wr_operations": number of failed write operations
2591                               (json-int)
2592     - "failed_flush_operations": number of failed flush operations
2593                                (json-int)
2594     - "invalid_rd_operations": number of invalid read operations
2595                                (json-int)
2596     - "invalid_wr_operations": number of invalid write operations
2597                                (json-int)
2598     - "invalid_flush_operations": number of invalid flush operations
2599                                   (json-int)
2600     - "account_invalid": whether invalid operations are included in
2601                          the last access statistics (json-bool)
2602     - "account_failed": whether failed operations are included in the
2603                          latency and last access statistics
2604                          (json-bool)
2605     - "timed_stats": A json-array containing statistics collected in
2606                      specific intervals, with the following members:
2607         - "interval_length": interval used for calculating the
2608                              statistics, in seconds (json-int)
2609         - "min_rd_latency_ns": minimum latency of read operations in
2610                                the defined interval, in nanoseconds
2611                                (json-int)
2612         - "min_wr_latency_ns": minimum latency of write operations in
2613                                the defined interval, in nanoseconds
2614                                (json-int)
2615         - "min_flush_latency_ns": minimum latency of flush operations
2616                                   in the defined interval, in
2617                                   nanoseconds (json-int)
2618         - "max_rd_latency_ns": maximum latency of read operations in
2619                                the defined interval, in nanoseconds
2620                                (json-int)
2621         - "max_wr_latency_ns": maximum latency of write operations in
2622                                the defined interval, in nanoseconds
2623                                (json-int)
2624         - "max_flush_latency_ns": maximum latency of flush operations
2625                                   in the defined interval, in
2626                                   nanoseconds (json-int)
2627         - "avg_rd_latency_ns": average latency of read operations in
2628                                the defined interval, in nanoseconds
2629                                (json-int)
2630         - "avg_wr_latency_ns": average latency of write operations in
2631                                the defined interval, in nanoseconds
2632                                (json-int)
2633         - "avg_flush_latency_ns": average latency of flush operations
2634                                   in the defined interval, in
2635                                   nanoseconds (json-int)
2636         - "avg_rd_queue_depth": average number of pending read
2637                                 operations in the defined interval
2638                                 (json-number)
2639         - "avg_wr_queue_depth": average number of pending write
2640                                 operations in the defined interval
2641                                 (json-number).
2642 - "parent": Contains recursively the statistics of the underlying
2643             protocol (e.g. the host file for a qcow2 image). If there is
2644             no underlying protocol, this field is omitted
2645             (json-object, optional)
2646
2647 Example:
2648
2649 -> { "execute": "query-blockstats" }
2650 <- {
2651       "return":[
2652          {
2653             "device":"ide0-hd0",
2654             "parent":{
2655                "stats":{
2656                   "wr_highest_offset":3686448128,
2657                   "wr_bytes":9786368,
2658                   "wr_operations":751,
2659                   "rd_bytes":122567168,
2660                   "rd_operations":36772
2661                   "wr_total_times_ns":313253456
2662                   "rd_total_times_ns":3465673657
2663                   "flush_total_times_ns":49653
2664                   "flush_operations":61,
2665                   "rd_merged":0,
2666                   "wr_merged":0,
2667                   "idle_time_ns":2953431879,
2668                   "account_invalid":true,
2669                   "account_failed":false
2670                }
2671             },
2672             "stats":{
2673                "wr_highest_offset":2821110784,
2674                "wr_bytes":9786368,
2675                "wr_operations":692,
2676                "rd_bytes":122739200,
2677                "rd_operations":36604
2678                "flush_operations":51,
2679                "wr_total_times_ns":313253456
2680                "rd_total_times_ns":3465673657
2681                "flush_total_times_ns":49653,
2682                "rd_merged":0,
2683                "wr_merged":0,
2684                "idle_time_ns":2953431879,
2685                "account_invalid":true,
2686                "account_failed":false
2687             }
2688          },
2689          {
2690             "device":"ide1-cd0",
2691             "stats":{
2692                "wr_highest_offset":0,
2693                "wr_bytes":0,
2694                "wr_operations":0,
2695                "rd_bytes":0,
2696                "rd_operations":0
2697                "flush_operations":0,
2698                "wr_total_times_ns":0
2699                "rd_total_times_ns":0
2700                "flush_total_times_ns":0,
2701                "rd_merged":0,
2702                "wr_merged":0,
2703                "account_invalid":false,
2704                "account_failed":false
2705             }
2706          },
2707          {
2708             "device":"floppy0",
2709             "stats":{
2710                "wr_highest_offset":0,
2711                "wr_bytes":0,
2712                "wr_operations":0,
2713                "rd_bytes":0,
2714                "rd_operations":0
2715                "flush_operations":0,
2716                "wr_total_times_ns":0
2717                "rd_total_times_ns":0
2718                "flush_total_times_ns":0,
2719                "rd_merged":0,
2720                "wr_merged":0,
2721                "account_invalid":false,
2722                "account_failed":false
2723             }
2724          },
2725          {
2726             "device":"sd0",
2727             "stats":{
2728                "wr_highest_offset":0,
2729                "wr_bytes":0,
2730                "wr_operations":0,
2731                "rd_bytes":0,
2732                "rd_operations":0
2733                "flush_operations":0,
2734                "wr_total_times_ns":0
2735                "rd_total_times_ns":0
2736                "flush_total_times_ns":0,
2737                "rd_merged":0,
2738                "wr_merged":0,
2739                "account_invalid":false,
2740                "account_failed":false
2741             }
2742          }
2743       ]
2744    }
2745
2746 EQMP
2747
2748     {
2749         .name       = "query-blockstats",
2750         .args_type  = "query-nodes:b?",
2751         .mhandler.cmd_new = qmp_marshal_query_blockstats,
2752     },
2753
2754 SQMP
2755 query-cpus
2756 ----------
2757
2758 Show CPU information.
2759
2760 Return a json-array. Each CPU is represented by a json-object, which contains:
2761
2762 - "CPU": CPU index (json-int)
2763 - "current": true if this is the current CPU, false otherwise (json-bool)
2764 - "halted": true if the cpu is halted, false otherwise (json-bool)
2765 - "qom_path": path to the CPU object in the QOM tree (json-str)
2766 - "arch": architecture of the cpu, which determines what additional
2767           keys will be present (json-str)
2768 - Current program counter. The key's name depends on the architecture:
2769      "pc": i386/x86_64 (json-int)
2770      "nip": PPC (json-int)
2771      "pc" and "npc": sparc (json-int)
2772      "PC": mips (json-int)
2773 - "thread_id": ID of the underlying host thread (json-int)
2774
2775 Example:
2776
2777 -> { "execute": "query-cpus" }
2778 <- {
2779       "return":[
2780          {
2781             "CPU":0,
2782             "current":true,
2783             "halted":false,
2784             "qom_path":"/machine/unattached/device[0]",
2785             "arch":"x86",
2786             "pc":3227107138,
2787             "thread_id":3134
2788          },
2789          {
2790             "CPU":1,
2791             "current":false,
2792             "halted":true,
2793             "qom_path":"/machine/unattached/device[2]",
2794             "arch":"x86",
2795             "pc":7108165,
2796             "thread_id":3135
2797          }
2798       ]
2799    }
2800
2801 EQMP
2802
2803     {
2804         .name       = "query-cpus",
2805         .args_type  = "",
2806         .mhandler.cmd_new = qmp_marshal_query_cpus,
2807     },
2808
2809 SQMP
2810 query-iothreads
2811 ---------------
2812
2813 Returns a list of information about each iothread.
2814
2815 Note this list excludes the QEMU main loop thread, which is not declared
2816 using the -object iothread command-line option.  It is always the main thread
2817 of the process.
2818
2819 Return a json-array. Each iothread is represented by a json-object, which contains:
2820
2821 - "id": name of iothread (json-str)
2822 - "thread-id": ID of the underlying host thread (json-int)
2823
2824 Example:
2825
2826 -> { "execute": "query-iothreads" }
2827 <- {
2828       "return":[
2829          {
2830             "id":"iothread0",
2831             "thread-id":3134
2832          },
2833          {
2834             "id":"iothread1",
2835             "thread-id":3135
2836          }
2837       ]
2838    }
2839
2840 EQMP
2841
2842     {
2843         .name       = "query-iothreads",
2844         .args_type  = "",
2845         .mhandler.cmd_new = qmp_marshal_query_iothreads,
2846     },
2847
2848 SQMP
2849 query-pci
2850 ---------
2851
2852 PCI buses and devices information.
2853
2854 The returned value is a json-array of all buses. Each bus is represented by
2855 a json-object, which has a key with a json-array of all PCI devices attached
2856 to it. Each device is represented by a json-object.
2857
2858 The bus json-object contains the following:
2859
2860 - "bus": bus number (json-int)
2861 - "devices": a json-array of json-objects, each json-object represents a
2862              PCI device
2863
2864 The PCI device json-object contains the following:
2865
2866 - "bus": identical to the parent's bus number (json-int)
2867 - "slot": slot number (json-int)
2868 - "function": function number (json-int)
2869 - "class_info": a json-object containing:
2870      - "desc": device class description (json-string, optional)
2871      - "class": device class number (json-int)
2872 - "id": a json-object containing:
2873      - "device": device ID (json-int)
2874      - "vendor": vendor ID (json-int)
2875 - "irq": device's IRQ if assigned (json-int, optional)
2876 - "qdev_id": qdev id string (json-string)
2877 - "pci_bridge": It's a json-object, only present if this device is a
2878                 PCI bridge, contains:
2879      - "bus": bus number (json-int)
2880      - "secondary": secondary bus number (json-int)
2881      - "subordinate": subordinate bus number (json-int)
2882      - "io_range": I/O memory range information, a json-object with the
2883                    following members:
2884                  - "base": base address, in bytes (json-int)
2885                  - "limit": limit address, in bytes (json-int)
2886      - "memory_range": memory range information, a json-object with the
2887                        following members:
2888                  - "base": base address, in bytes (json-int)
2889                  - "limit": limit address, in bytes (json-int)
2890      - "prefetchable_range": Prefetchable memory range information, a
2891                              json-object with the following members:
2892                  - "base": base address, in bytes (json-int)
2893                  - "limit": limit address, in bytes (json-int)
2894      - "devices": a json-array of PCI devices if there's any attached, each
2895                   each element is represented by a json-object, which contains
2896                   the same members of the 'PCI device json-object' described
2897                   above (optional)
2898 - "regions": a json-array of json-objects, each json-object represents a
2899              memory region of this device
2900
2901 The memory range json-object contains the following:
2902
2903 - "base": base memory address (json-int)
2904 - "limit": limit value (json-int)
2905
2906 The region json-object can be an I/O region or a memory region, an I/O region
2907 json-object contains the following:
2908
2909 - "type": "io" (json-string, fixed)
2910 - "bar": BAR number (json-int)
2911 - "address": memory address (json-int)
2912 - "size": memory size (json-int)
2913
2914 A memory region json-object contains the following:
2915
2916 - "type": "memory" (json-string, fixed)
2917 - "bar": BAR number (json-int)
2918 - "address": memory address (json-int)
2919 - "size": memory size (json-int)
2920 - "mem_type_64": true or false (json-bool)
2921 - "prefetch": true or false (json-bool)
2922
2923 Example:
2924
2925 -> { "execute": "query-pci" }
2926 <- {
2927       "return":[
2928          {
2929             "bus":0,
2930             "devices":[
2931                {
2932                   "bus":0,
2933                   "qdev_id":"",
2934                   "slot":0,
2935                   "class_info":{
2936                      "class":1536,
2937                      "desc":"Host bridge"
2938                   },
2939                   "id":{
2940                      "device":32902,
2941                      "vendor":4663
2942                   },
2943                   "function":0,
2944                   "regions":[
2945
2946                   ]
2947                },
2948                {
2949                   "bus":0,
2950                   "qdev_id":"",
2951                   "slot":1,
2952                   "class_info":{
2953                      "class":1537,
2954                      "desc":"ISA bridge"
2955                   },
2956                   "id":{
2957                      "device":32902,
2958                      "vendor":28672
2959                   },
2960                   "function":0,
2961                   "regions":[
2962
2963                   ]
2964                },
2965                {
2966                   "bus":0,
2967                   "qdev_id":"",
2968                   "slot":1,
2969                   "class_info":{
2970                      "class":257,
2971                      "desc":"IDE controller"
2972                   },
2973                   "id":{
2974                      "device":32902,
2975                      "vendor":28688
2976                   },
2977                   "function":1,
2978                   "regions":[
2979                      {
2980                         "bar":4,
2981                         "size":16,
2982                         "address":49152,
2983                         "type":"io"
2984                      }
2985                   ]
2986                },
2987                {
2988                   "bus":0,
2989                   "qdev_id":"",
2990                   "slot":2,
2991                   "class_info":{
2992                      "class":768,
2993                      "desc":"VGA controller"
2994                   },
2995                   "id":{
2996                      "device":4115,
2997                      "vendor":184
2998                   },
2999                   "function":0,
3000                   "regions":[
3001                      {
3002                         "prefetch":true,
3003                         "mem_type_64":false,
3004                         "bar":0,
3005                         "size":33554432,
3006                         "address":4026531840,
3007                         "type":"memory"
3008                      },
3009                      {
3010                         "prefetch":false,
3011                         "mem_type_64":false,
3012                         "bar":1,
3013                         "size":4096,
3014                         "address":4060086272,
3015                         "type":"memory"
3016                      },
3017                      {
3018                         "prefetch":false,
3019                         "mem_type_64":false,
3020                         "bar":6,
3021                         "size":65536,
3022                         "address":-1,
3023                         "type":"memory"
3024                      }
3025                   ]
3026                },
3027                {
3028                   "bus":0,
3029                   "qdev_id":"",
3030                   "irq":11,
3031                   "slot":4,
3032                   "class_info":{
3033                      "class":1280,
3034                      "desc":"RAM controller"
3035                   },
3036                   "id":{
3037                      "device":6900,
3038                      "vendor":4098
3039                   },
3040                   "function":0,
3041                   "regions":[
3042                      {
3043                         "bar":0,
3044                         "size":32,
3045                         "address":49280,
3046                         "type":"io"
3047                      }
3048                   ]
3049                }
3050             ]
3051          }
3052       ]
3053    }
3054
3055 Note: This example has been shortened as the real response is too long.
3056
3057 EQMP
3058
3059     {
3060         .name       = "query-pci",
3061         .args_type  = "",
3062         .mhandler.cmd_new = qmp_marshal_query_pci,
3063     },
3064
3065 SQMP
3066 query-kvm
3067 ---------
3068
3069 Show KVM information.
3070
3071 Return a json-object with the following information:
3072
3073 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
3074 - "present": true if QEMU has KVM support, false otherwise (json-bool)
3075
3076 Example:
3077
3078 -> { "execute": "query-kvm" }
3079 <- { "return": { "enabled": true, "present": true } }
3080
3081 EQMP
3082
3083     {
3084         .name       = "query-kvm",
3085         .args_type  = "",
3086         .mhandler.cmd_new = qmp_marshal_query_kvm,
3087     },
3088
3089 SQMP
3090 query-status
3091 ------------
3092
3093 Return a json-object with the following information:
3094
3095 - "running": true if the VM is running, or false if it is paused (json-bool)
3096 - "singlestep": true if the VM is in single step mode,
3097                 false otherwise (json-bool)
3098 - "status": one of the following values (json-string)
3099     "debug" - QEMU is running on a debugger
3100     "inmigrate" - guest is paused waiting for an incoming migration
3101     "internal-error" - An internal error that prevents further guest
3102     execution has occurred
3103     "io-error" - the last IOP has failed and the device is configured
3104     to pause on I/O errors
3105     "paused" - guest has been paused via the 'stop' command
3106     "postmigrate" - guest is paused following a successful 'migrate'
3107     "prelaunch" - QEMU was started with -S and guest has not started
3108     "finish-migrate" - guest is paused to finish the migration process
3109     "restore-vm" - guest is paused to restore VM state
3110     "running" - guest is actively running
3111     "save-vm" - guest is paused to save the VM state
3112     "shutdown" - guest is shut down (and -no-shutdown is in use)
3113     "watchdog" - the watchdog action is configured to pause and
3114      has been triggered
3115
3116 Example:
3117
3118 -> { "execute": "query-status" }
3119 <- { "return": { "running": true, "singlestep": false, "status": "running" } }
3120
3121 EQMP
3122
3123     {
3124         .name       = "query-status",
3125         .args_type  = "",
3126         .mhandler.cmd_new = qmp_marshal_query_status,
3127     },
3128
3129 SQMP
3130 query-mice
3131 ----------
3132
3133 Show VM mice information.
3134
3135 Each mouse is represented by a json-object, the returned value is a json-array
3136 of all mice.
3137
3138 The mouse json-object contains the following:
3139
3140 - "name": mouse's name (json-string)
3141 - "index": mouse's index (json-int)
3142 - "current": true if this mouse is receiving events, false otherwise (json-bool)
3143 - "absolute": true if the mouse generates absolute input events (json-bool)
3144
3145 Example:
3146
3147 -> { "execute": "query-mice" }
3148 <- {
3149       "return":[
3150          {
3151             "name":"QEMU Microsoft Mouse",
3152             "index":0,
3153             "current":false,
3154             "absolute":false
3155          },
3156          {
3157             "name":"QEMU PS/2 Mouse",
3158             "index":1,
3159             "current":true,
3160             "absolute":true
3161          }
3162       ]
3163    }
3164
3165 EQMP
3166
3167     {
3168         .name       = "query-mice",
3169         .args_type  = "",
3170         .mhandler.cmd_new = qmp_marshal_query_mice,
3171     },
3172
3173 SQMP
3174 query-vnc
3175 ---------
3176
3177 Show VNC server information.
3178
3179 Return a json-object with server information. Connected clients are returned
3180 as a json-array of json-objects.
3181
3182 The main json-object contains the following:
3183
3184 - "enabled": true or false (json-bool)
3185 - "host": server's IP address (json-string)
3186 - "family": address family (json-string)
3187          - Possible values: "ipv4", "ipv6", "unix", "unknown"
3188 - "service": server's port number (json-string)
3189 - "auth": authentication method (json-string)
3190          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
3191                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
3192                             "vencrypt+plain", "vencrypt+tls+none",
3193                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
3194                             "vencrypt+tls+vnc", "vencrypt+x509+none",
3195                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
3196                             "vencrypt+x509+vnc", "vnc"
3197 - "clients": a json-array of all connected clients
3198
3199 Clients are described by a json-object, each one contain the following:
3200
3201 - "host": client's IP address (json-string)
3202 - "family": address family (json-string)
3203          - Possible values: "ipv4", "ipv6", "unix", "unknown"
3204 - "service": client's port number (json-string)
3205 - "x509_dname": TLS dname (json-string, optional)
3206 - "sasl_username": SASL username (json-string, optional)
3207
3208 Example:
3209
3210 -> { "execute": "query-vnc" }
3211 <- {
3212       "return":{
3213          "enabled":true,
3214          "host":"0.0.0.0",
3215          "service":"50402",
3216          "auth":"vnc",
3217          "family":"ipv4",
3218          "clients":[
3219             {
3220                "host":"127.0.0.1",
3221                "service":"50401",
3222                "family":"ipv4"
3223             }
3224          ]
3225       }
3226    }
3227
3228 EQMP
3229
3230     {
3231         .name       = "query-vnc",
3232         .args_type  = "",
3233         .mhandler.cmd_new = qmp_marshal_query_vnc,
3234     },
3235     {
3236         .name       = "query-vnc-servers",
3237         .args_type  = "",
3238         .mhandler.cmd_new = qmp_marshal_query_vnc_servers,
3239     },
3240
3241 SQMP
3242 query-spice
3243 -----------
3244
3245 Show SPICE server information.
3246
3247 Return a json-object with server information. Connected clients are returned
3248 as a json-array of json-objects.
3249
3250 The main json-object contains the following:
3251
3252 - "enabled": true or false (json-bool)
3253 - "host": server's IP address (json-string)
3254 - "port": server's port number (json-int, optional)
3255 - "tls-port": server's port number (json-int, optional)
3256 - "auth": authentication method (json-string)
3257          - Possible values: "none", "spice"
3258 - "channels": a json-array of all active channels clients
3259
3260 Channels are described by a json-object, each one contain the following:
3261
3262 - "host": client's IP address (json-string)
3263 - "family": address family (json-string)
3264          - Possible values: "ipv4", "ipv6", "unix", "unknown"
3265 - "port": client's port number (json-string)
3266 - "connection-id": spice connection id.  All channels with the same id
3267                    belong to the same spice session (json-int)
3268 - "channel-type": channel type.  "1" is the main control channel, filter for
3269                   this one if you want track spice sessions only (json-int)
3270 - "channel-id": channel id.  Usually "0", might be different needed when
3271                 multiple channels of the same type exist, such as multiple
3272                 display channels in a multihead setup (json-int)
3273 - "tls": whether the channel is encrypted (json-bool)
3274
3275 Example:
3276
3277 -> { "execute": "query-spice" }
3278 <- {
3279       "return": {
3280          "enabled": true,
3281          "auth": "spice",
3282          "port": 5920,
3283          "tls-port": 5921,
3284          "host": "0.0.0.0",
3285          "channels": [
3286             {
3287                "port": "54924",
3288                "family": "ipv4",
3289                "channel-type": 1,
3290                "connection-id": 1804289383,
3291                "host": "127.0.0.1",
3292                "channel-id": 0,
3293                "tls": true
3294             },
3295             {
3296                "port": "36710",
3297                "family": "ipv4",
3298                "channel-type": 4,
3299                "connection-id": 1804289383,
3300                "host": "127.0.0.1",
3301                "channel-id": 0,
3302                "tls": false
3303             },
3304             [ ... more channels follow ... ]
3305          ]
3306       }
3307    }
3308
3309 EQMP
3310
3311 #if defined(CONFIG_SPICE)
3312     {
3313         .name       = "query-spice",
3314         .args_type  = "",
3315         .mhandler.cmd_new = qmp_marshal_query_spice,
3316     },
3317 #endif
3318
3319 SQMP
3320 query-name
3321 ----------
3322
3323 Show VM name.
3324
3325 Return a json-object with the following information:
3326
3327 - "name": VM's name (json-string, optional)
3328
3329 Example:
3330
3331 -> { "execute": "query-name" }
3332 <- { "return": { "name": "qemu-name" } }
3333
3334 EQMP
3335
3336     {
3337         .name       = "query-name",
3338         .args_type  = "",
3339         .mhandler.cmd_new = qmp_marshal_query_name,
3340     },
3341
3342 SQMP
3343 query-uuid
3344 ----------
3345
3346 Show VM UUID.
3347
3348 Return a json-object with the following information:
3349
3350 - "UUID": Universally Unique Identifier (json-string)
3351
3352 Example:
3353
3354 -> { "execute": "query-uuid" }
3355 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
3356
3357 EQMP
3358
3359     {
3360         .name       = "query-uuid",
3361         .args_type  = "",
3362         .mhandler.cmd_new = qmp_marshal_query_uuid,
3363     },
3364
3365 SQMP
3366 query-command-line-options
3367 --------------------------
3368
3369 Show command line option schema.
3370
3371 Return a json-array of command line option schema for all options (or for
3372 the given option), returning an error if the given option doesn't exist.
3373
3374 Each array entry contains the following:
3375
3376 - "option": option name (json-string)
3377 - "parameters": a json-array describes all parameters of the option:
3378     - "name": parameter name (json-string)
3379     - "type": parameter type (one of 'string', 'boolean', 'number',
3380               or 'size')
3381     - "help": human readable description of the parameter
3382               (json-string, optional)
3383     - "default": default value string for the parameter
3384                  (json-string, optional)
3385
3386 Example:
3387
3388 -> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } }
3389 <- { "return": [
3390         {
3391             "parameters": [
3392                 {
3393                     "name": "romfile",
3394                     "type": "string"
3395                 },
3396                 {
3397                     "name": "bootindex",
3398                     "type": "number"
3399                 }
3400             ],
3401             "option": "option-rom"
3402         }
3403      ]
3404    }
3405
3406 EQMP
3407
3408     {
3409         .name       = "query-command-line-options",
3410         .args_type  = "option:s?",
3411         .mhandler.cmd_new = qmp_marshal_query_command_line_options,
3412     },
3413
3414 SQMP
3415 query-migrate
3416 -------------
3417
3418 Migration status.
3419
3420 Return a json-object. If migration is active there will be another json-object
3421 with RAM migration status and if block migration is active another one with
3422 block migration status.
3423
3424 The main json-object contains the following:
3425
3426 - "status": migration status (json-string)
3427      - Possible values: "setup", "active", "completed", "failed", "cancelled"
3428 - "total-time": total amount of ms since migration started.  If
3429                 migration has ended, it returns the total migration
3430                 time (json-int)
3431 - "setup-time" amount of setup time in milliseconds _before_ the
3432                iterations begin but _after_ the QMP command is issued.
3433                This is designed to provide an accounting of any activities
3434                (such as RDMA pinning) which may be expensive, but do not
3435                actually occur during the iterative migration rounds
3436                themselves. (json-int)
3437 - "downtime": only present when migration has finished correctly
3438               total amount in ms for downtime that happened (json-int)
3439 - "expected-downtime": only present while migration is active
3440                 total amount in ms for downtime that was calculated on
3441                 the last bitmap round (json-int)
3442 - "ram": only present if "status" is "active", it is a json-object with the
3443   following RAM information:
3444          - "transferred": amount transferred in bytes (json-int)
3445          - "remaining": amount remaining to transfer in bytes (json-int)
3446          - "total": total amount of memory in bytes (json-int)
3447          - "duplicate": number of pages filled entirely with the same
3448             byte (json-int)
3449             These are sent over the wire much more efficiently.
3450          - "skipped": number of skipped zero pages (json-int)
3451          - "normal" : number of whole pages transferred.  I.e. they
3452             were not sent as duplicate or xbzrle pages (json-int)
3453          - "normal-bytes" : number of bytes transferred in whole
3454             pages. This is just normal pages times size of one page,
3455             but this way upper levels don't need to care about page
3456             size (json-int)
3457          - "dirty-sync-count": times that dirty ram was synchronized (json-int)
3458 - "disk": only present if "status" is "active" and it is a block migration,
3459   it is a json-object with the following disk information:
3460          - "transferred": amount transferred in bytes (json-int)
3461          - "remaining": amount remaining to transfer in bytes json-int)
3462          - "total": total disk size in bytes (json-int)
3463 - "xbzrle-cache": only present if XBZRLE is active.
3464   It is a json-object with the following XBZRLE information:
3465          - "cache-size": XBZRLE cache size in bytes
3466          - "bytes": number of bytes transferred for XBZRLE compressed pages
3467          - "pages": number of XBZRLE compressed pages
3468          - "cache-miss": number of XBRZRLE page cache misses
3469          - "cache-miss-rate": rate of XBRZRLE page cache misses
3470          - "overflow": number of times XBZRLE overflows.  This means
3471            that the XBZRLE encoding was bigger than just sent the
3472            whole page, and then we sent the whole page instead (as as
3473            normal page).
3474
3475 Examples:
3476
3477 1. Before the first migration
3478
3479 -> { "execute": "query-migrate" }
3480 <- { "return": {} }
3481
3482 2. Migration is done and has succeeded
3483
3484 -> { "execute": "query-migrate" }
3485 <- { "return": {
3486         "status": "completed",
3487         "ram":{
3488           "transferred":123,
3489           "remaining":123,
3490           "total":246,
3491           "total-time":12345,
3492           "setup-time":12345,
3493           "downtime":12345,
3494           "duplicate":123,
3495           "normal":123,
3496           "normal-bytes":123456,
3497           "dirty-sync-count":15
3498         }
3499      }
3500    }
3501
3502 3. Migration is done and has failed
3503
3504 -> { "execute": "query-migrate" }
3505 <- { "return": { "status": "failed" } }
3506
3507 4. Migration is being performed and is not a block migration:
3508
3509 -> { "execute": "query-migrate" }
3510 <- {
3511       "return":{
3512          "status":"active",
3513          "ram":{
3514             "transferred":123,
3515             "remaining":123,
3516             "total":246,
3517             "total-time":12345,
3518             "setup-time":12345,
3519             "expected-downtime":12345,
3520             "duplicate":123,
3521             "normal":123,
3522             "normal-bytes":123456,
3523             "dirty-sync-count":15
3524          }
3525       }
3526    }
3527
3528 5. Migration is being performed and is a block migration:
3529
3530 -> { "execute": "query-migrate" }
3531 <- {
3532       "return":{
3533          "status":"active",
3534          "ram":{
3535             "total":1057024,
3536             "remaining":1053304,
3537             "transferred":3720,
3538             "total-time":12345,
3539             "setup-time":12345,
3540             "expected-downtime":12345,
3541             "duplicate":123,
3542             "normal":123,
3543             "normal-bytes":123456,
3544             "dirty-sync-count":15
3545          },
3546          "disk":{
3547             "total":20971520,
3548             "remaining":20880384,
3549             "transferred":91136
3550          }
3551       }
3552    }
3553
3554 6. Migration is being performed and XBZRLE is active:
3555
3556 -> { "execute": "query-migrate" }
3557 <- {
3558       "return":{
3559          "status":"active",
3560          "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
3561          "ram":{
3562             "total":1057024,
3563             "remaining":1053304,
3564             "transferred":3720,
3565             "total-time":12345,
3566             "setup-time":12345,
3567             "expected-downtime":12345,
3568             "duplicate":10,
3569             "normal":3333,
3570             "normal-bytes":3412992,
3571             "dirty-sync-count":15
3572          },
3573          "xbzrle-cache":{
3574             "cache-size":67108864,
3575             "bytes":20971520,
3576             "pages":2444343,
3577             "cache-miss":2244,
3578             "cache-miss-rate":0.123,
3579             "overflow":34434
3580          }
3581       }
3582    }
3583
3584 EQMP
3585
3586     {
3587         .name       = "query-migrate",
3588         .args_type  = "",
3589         .mhandler.cmd_new = qmp_marshal_query_migrate,
3590     },
3591
3592 SQMP
3593 migrate-set-capabilities
3594 ------------------------
3595
3596 Enable/Disable migration capabilities
3597
3598 - "xbzrle": XBZRLE support
3599 - "rdma-pin-all": pin all pages when using RDMA during migration
3600 - "auto-converge": throttle down guest to help convergence of migration
3601 - "zero-blocks": compress zero blocks during block migration
3602 - "events": generate events for each migration state change
3603
3604 Arguments:
3605
3606 Example:
3607
3608 -> { "execute": "migrate-set-capabilities" , "arguments":
3609      { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
3610
3611 EQMP
3612
3613     {
3614         .name       = "migrate-set-capabilities",
3615         .args_type  = "capabilities:q",
3616         .params     = "capability:s,state:b",
3617         .mhandler.cmd_new = qmp_marshal_migrate_set_capabilities,
3618     },
3619 SQMP
3620 query-migrate-capabilities
3621 --------------------------
3622
3623 Query current migration capabilities
3624
3625 - "capabilities": migration capabilities state
3626          - "xbzrle" : XBZRLE state (json-bool)
3627          - "rdma-pin-all" : RDMA Pin Page state (json-bool)
3628          - "auto-converge" : Auto Converge state (json-bool)
3629          - "zero-blocks" : Zero Blocks state (json-bool)
3630
3631 Arguments:
3632
3633 Example:
3634
3635 -> { "execute": "query-migrate-capabilities" }
3636 <- { "return": [ { "state": false, "capability": "xbzrle" } ] }
3637
3638 EQMP
3639
3640     {
3641         .name       = "query-migrate-capabilities",
3642         .args_type  = "",
3643         .mhandler.cmd_new = qmp_marshal_query_migrate_capabilities,
3644     },
3645
3646 SQMP
3647 migrate-set-parameters
3648 ----------------------
3649
3650 Set migration parameters
3651
3652 - "compress-level": set compression level during migration (json-int)
3653 - "compress-threads": set compression thread count for migration (json-int)
3654 - "decompress-threads": set decompression thread count for migration (json-int)
3655
3656 Arguments:
3657
3658 Example:
3659
3660 -> { "execute": "migrate-set-parameters" , "arguments":
3661       { "compress-level": 1 } }
3662
3663 EQMP
3664
3665     {
3666         .name       = "migrate-set-parameters",
3667         .args_type  =
3668             "compress-level:i?,compress-threads:i?,decompress-threads:i?",
3669         .mhandler.cmd_new = qmp_marshal_migrate_set_parameters,
3670     },
3671 SQMP
3672 query-migrate-parameters
3673 ------------------------
3674
3675 Query current migration parameters
3676
3677 - "parameters": migration parameters value
3678          - "compress-level" : compression level value (json-int)
3679          - "compress-threads" : compression thread count value (json-int)
3680          - "decompress-threads" : decompression thread count value (json-int)
3681
3682 Arguments:
3683
3684 Example:
3685
3686 -> { "execute": "query-migrate-parameters" }
3687 <- {
3688       "return": {
3689          "decompress-threads", 2,
3690          "compress-threads", 8,
3691          "compress-level", 1
3692       }
3693    }
3694
3695 EQMP
3696
3697     {
3698         .name       = "query-migrate-parameters",
3699         .args_type  = "",
3700         .mhandler.cmd_new = qmp_marshal_query_migrate_parameters,
3701     },
3702
3703 SQMP
3704 query-balloon
3705 -------------
3706
3707 Show balloon information.
3708
3709 Make an asynchronous request for balloon info. When the request completes a
3710 json-object will be returned containing the following data:
3711
3712 - "actual": current balloon value in bytes (json-int)
3713
3714 Example:
3715
3716 -> { "execute": "query-balloon" }
3717 <- {
3718       "return":{
3719          "actual":1073741824,
3720       }
3721    }
3722
3723 EQMP
3724
3725     {
3726         .name       = "query-balloon",
3727         .args_type  = "",
3728         .mhandler.cmd_new = qmp_marshal_query_balloon,
3729     },
3730
3731     {
3732         .name       = "query-block-jobs",
3733         .args_type  = "",
3734         .mhandler.cmd_new = qmp_marshal_query_block_jobs,
3735     },
3736
3737     {
3738         .name       = "qom-list",
3739         .args_type  = "path:s",
3740         .mhandler.cmd_new = qmp_marshal_qom_list,
3741     },
3742
3743     {
3744         .name       = "qom-set",
3745         .args_type  = "path:s,property:s,value:q",
3746         .mhandler.cmd_new = qmp_marshal_qom_set,
3747     },
3748
3749     {
3750         .name       = "qom-get",
3751         .args_type  = "path:s,property:s",
3752         .mhandler.cmd_new = qmp_marshal_qom_get,
3753     },
3754
3755     {
3756         .name       = "nbd-server-start",
3757         .args_type  = "addr:q",
3758         .mhandler.cmd_new = qmp_marshal_nbd_server_start,
3759     },
3760     {
3761         .name       = "nbd-server-add",
3762         .args_type  = "device:B,writable:b?",
3763         .mhandler.cmd_new = qmp_marshal_nbd_server_add,
3764     },
3765     {
3766         .name       = "nbd-server-stop",
3767         .args_type  = "",
3768         .mhandler.cmd_new = qmp_marshal_nbd_server_stop,
3769     },
3770
3771     {
3772         .name       = "change-vnc-password",
3773         .args_type  = "password:s",
3774         .mhandler.cmd_new = qmp_marshal_change_vnc_password,
3775     },
3776     {
3777         .name       = "qom-list-types",
3778         .args_type  = "implements:s?,abstract:b?",
3779         .mhandler.cmd_new = qmp_marshal_qom_list_types,
3780     },
3781
3782     {
3783         .name       = "device-list-properties",
3784         .args_type  = "typename:s",
3785         .mhandler.cmd_new = qmp_marshal_device_list_properties,
3786     },
3787
3788     {
3789         .name       = "query-machines",
3790         .args_type  = "",
3791         .mhandler.cmd_new = qmp_marshal_query_machines,
3792     },
3793
3794     {
3795         .name       = "query-cpu-definitions",
3796         .args_type  = "",
3797         .mhandler.cmd_new = qmp_marshal_query_cpu_definitions,
3798     },
3799
3800     {
3801         .name       = "query-target",
3802         .args_type  = "",
3803         .mhandler.cmd_new = qmp_marshal_query_target,
3804     },
3805
3806     {
3807         .name       = "query-tpm",
3808         .args_type  = "",
3809         .mhandler.cmd_new = qmp_marshal_query_tpm,
3810     },
3811
3812 SQMP
3813 query-tpm
3814 ---------
3815
3816 Return information about the TPM device.
3817
3818 Arguments: None
3819
3820 Example:
3821
3822 -> { "execute": "query-tpm" }
3823 <- { "return":
3824      [
3825        { "model": "tpm-tis",
3826          "options":
3827            { "type": "passthrough",
3828              "data":
3829                { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
3830                  "path": "/dev/tpm0"
3831                }
3832            },
3833          "id": "tpm0"
3834        }
3835      ]
3836    }
3837
3838 EQMP
3839
3840     {
3841         .name       = "query-tpm-models",
3842         .args_type  = "",
3843         .mhandler.cmd_new = qmp_marshal_query_tpm_models,
3844     },
3845
3846 SQMP
3847 query-tpm-models
3848 ----------------
3849
3850 Return a list of supported TPM models.
3851
3852 Arguments: None
3853
3854 Example:
3855
3856 -> { "execute": "query-tpm-models" }
3857 <- { "return": [ "tpm-tis" ] }
3858
3859 EQMP
3860
3861     {
3862         .name       = "query-tpm-types",
3863         .args_type  = "",
3864         .mhandler.cmd_new = qmp_marshal_query_tpm_types,
3865     },
3866
3867 SQMP
3868 query-tpm-types
3869 ---------------
3870
3871 Return a list of supported TPM types.
3872
3873 Arguments: None
3874
3875 Example:
3876
3877 -> { "execute": "query-tpm-types" }
3878 <- { "return": [ "passthrough" ] }
3879
3880 EQMP
3881
3882     {
3883         .name       = "chardev-add",
3884         .args_type  = "id:s,backend:q",
3885         .mhandler.cmd_new = qmp_marshal_chardev_add,
3886     },
3887
3888 SQMP
3889 chardev-add
3890 ----------------
3891
3892 Add a chardev.
3893
3894 Arguments:
3895
3896 - "id": the chardev's ID, must be unique (json-string)
3897 - "backend": chardev backend type + parameters
3898
3899 Examples:
3900
3901 -> { "execute" : "chardev-add",
3902      "arguments" : { "id" : "foo",
3903                      "backend" : { "type" : "null", "data" : {} } } }
3904 <- { "return": {} }
3905
3906 -> { "execute" : "chardev-add",
3907      "arguments" : { "id" : "bar",
3908                      "backend" : { "type" : "file",
3909                                    "data" : { "out" : "/tmp/bar.log" } } } }
3910 <- { "return": {} }
3911
3912 -> { "execute" : "chardev-add",
3913      "arguments" : { "id" : "baz",
3914                      "backend" : { "type" : "pty", "data" : {} } } }
3915 <- { "return": { "pty" : "/dev/pty/42" } }
3916
3917 EQMP
3918
3919     {
3920         .name       = "chardev-remove",
3921         .args_type  = "id:s",
3922         .mhandler.cmd_new = qmp_marshal_chardev_remove,
3923     },
3924
3925
3926 SQMP
3927 chardev-remove
3928 --------------
3929
3930 Remove a chardev.
3931
3932 Arguments:
3933
3934 - "id": the chardev's ID, must exist and not be in use (json-string)
3935
3936 Example:
3937
3938 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
3939 <- { "return": {} }
3940
3941 EQMP
3942     {
3943         .name       = "query-rx-filter",
3944         .args_type  = "name:s?",
3945         .mhandler.cmd_new = qmp_marshal_query_rx_filter,
3946     },
3947
3948 SQMP
3949 query-rx-filter
3950 ---------------
3951
3952 Show rx-filter information.
3953
3954 Returns a json-array of rx-filter information for all NICs (or for the
3955 given NIC), returning an error if the given NIC doesn't exist, or
3956 given NIC doesn't support rx-filter querying, or given net client
3957 isn't a NIC.
3958
3959 The query will clear the event notification flag of each NIC, then qemu
3960 will start to emit event to QMP monitor.
3961
3962 Each array entry contains the following:
3963
3964 - "name": net client name (json-string)
3965 - "promiscuous": promiscuous mode is enabled (json-bool)
3966 - "multicast": multicast receive state (one of 'normal', 'none', 'all')
3967 - "unicast": unicast receive state  (one of 'normal', 'none', 'all')
3968 - "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0)
3969 - "broadcast-allowed": allow to receive broadcast (json-bool)
3970 - "multicast-overflow": multicast table is overflowed (json-bool)
3971 - "unicast-overflow": unicast table is overflowed (json-bool)
3972 - "main-mac": main macaddr string (json-string)
3973 - "vlan-table": a json-array of active vlan id
3974 - "unicast-table": a json-array of unicast macaddr string
3975 - "multicast-table": a json-array of multicast macaddr string
3976
3977 Example:
3978
3979 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
3980 <- { "return": [
3981         {
3982             "promiscuous": true,
3983             "name": "vnet0",
3984             "main-mac": "52:54:00:12:34:56",
3985             "unicast": "normal",
3986             "vlan": "normal",
3987             "vlan-table": [
3988                 4,
3989                 0
3990             ],
3991             "unicast-table": [
3992             ],
3993             "multicast": "normal",
3994             "multicast-overflow": false,
3995             "unicast-overflow": false,
3996             "multicast-table": [
3997                 "01:00:5e:00:00:01",
3998                 "33:33:00:00:00:01",
3999                 "33:33:ff:12:34:56"
4000             ],
4001             "broadcast-allowed": false
4002         }
4003       ]
4004    }
4005
4006 EQMP
4007
4008     {
4009         .name       = "blockdev-add",
4010         .args_type  = "options:q",
4011         .mhandler.cmd_new = qmp_marshal_blockdev_add,
4012     },
4013
4014 SQMP
4015 blockdev-add
4016 ------------
4017
4018 Add a block device.
4019
4020 This command is still a work in progress.  It doesn't support all
4021 block drivers among other things.  Stay away from it unless you want
4022 to help with its development.
4023
4024 Arguments:
4025
4026 - "options": block driver options
4027
4028 Example (1):
4029
4030 -> { "execute": "blockdev-add",
4031     "arguments": { "options" : { "driver": "qcow2",
4032                                  "file": { "driver": "file",
4033                                            "filename": "test.qcow2" } } } }
4034 <- { "return": {} }
4035
4036 Example (2):
4037
4038 -> { "execute": "blockdev-add",
4039      "arguments": {
4040          "options": {
4041            "driver": "qcow2",
4042            "id": "my_disk",
4043            "discard": "unmap",
4044            "cache": {
4045                "direct": true,
4046                "writeback": true
4047            },
4048            "file": {
4049                "driver": "file",
4050                "filename": "/tmp/test.qcow2"
4051            },
4052            "backing": {
4053                "driver": "raw",
4054                "file": {
4055                    "driver": "file",
4056                    "filename": "/dev/fdset/4"
4057                }
4058            }
4059          }
4060        }
4061      }
4062
4063 <- { "return": {} }
4064
4065 EQMP
4066
4067     {
4068         .name       = "x-blockdev-del",
4069         .args_type  = "id:s?,node-name:s?",
4070         .mhandler.cmd_new = qmp_marshal_x_blockdev_del,
4071     },
4072
4073 SQMP
4074 x-blockdev-del
4075 ------------
4076 Since 2.5
4077
4078 Deletes a block device thas has been added using blockdev-add.
4079 The selected device can be either a block backend or a graph node.
4080
4081 In the former case the backend will be destroyed, along with its
4082 inserted medium if there's any. The command will fail if the backend
4083 or its medium are in use.
4084
4085 In the latter case the node will be destroyed. The command will fail
4086 if the node is attached to a block backend or is otherwise being
4087 used.
4088
4089 One of "id" or "node-name" must be specified, but not both.
4090
4091 This command is still a work in progress and is considered
4092 experimental. Stay away from it unless you want to help with its
4093 development.
4094
4095 Arguments:
4096
4097 - "id": Name of the block backend device to delete (json-string, optional)
4098 - "node-name": Name of the graph node to delete (json-string, optional)
4099
4100 Example:
4101
4102 -> { "execute": "blockdev-add",
4103      "arguments": {
4104          "options": {
4105              "driver": "qcow2",
4106              "id": "drive0",
4107              "file": {
4108                  "driver": "file",
4109                  "filename": "test.qcow2"
4110              }
4111          }
4112      }
4113    }
4114
4115 <- { "return": {} }
4116
4117 -> { "execute": "x-blockdev-del",
4118      "arguments": { "id": "drive0" }
4119    }
4120 <- { "return": {} }
4121
4122 EQMP
4123
4124     {
4125         .name       = "blockdev-open-tray",
4126         .args_type  = "device:s,force:b?",
4127         .mhandler.cmd_new = qmp_marshal_blockdev_open_tray,
4128     },
4129
4130 SQMP
4131 blockdev-open-tray
4132 ------------------
4133
4134 Opens a block device's tray. If there is a block driver state tree inserted as a
4135 medium, it will become inaccessible to the guest (but it will remain associated
4136 to the block device, so closing the tray will make it accessible again).
4137
4138 If the tray was already open before, this will be a no-op.
4139
4140 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
4141 which no such event will be generated, these include:
4142 - if the guest has locked the tray, @force is false and the guest does not
4143   respond to the eject request
4144 - if the BlockBackend denoted by @device does not have a guest device attached
4145   to it
4146 - if the guest device does not have an actual tray and is empty, for instance
4147   for floppy disk drives
4148
4149 Arguments:
4150
4151 - "device": block device name (json-string)
4152 - "force": if false (the default), an eject request will be sent to the guest if
4153            it has locked the tray (and the tray will not be opened immediately);
4154            if true, the tray will be opened regardless of whether it is locked
4155            (json-bool, optional)
4156
4157 Example:
4158
4159 -> { "execute": "blockdev-open-tray",
4160      "arguments": { "device": "ide1-cd0" } }
4161
4162 <- { "timestamp": { "seconds": 1418751016,
4163                     "microseconds": 716996 },
4164      "event": "DEVICE_TRAY_MOVED",
4165      "data": { "device": "ide1-cd0",
4166                "tray-open": true } }
4167
4168 <- { "return": {} }
4169
4170 EQMP
4171
4172     {
4173         .name       = "blockdev-close-tray",
4174         .args_type  = "device:s",
4175         .mhandler.cmd_new = qmp_marshal_blockdev_close_tray,
4176     },
4177
4178 SQMP
4179 blockdev-close-tray
4180 -------------------
4181
4182 Closes a block device's tray. If there is a block driver state tree associated
4183 with the block device (which is currently ejected), that tree will be loaded as
4184 the medium.
4185
4186 If the tray was already closed before, this will be a no-op.
4187
4188 Arguments:
4189
4190 - "device": block device name (json-string)
4191
4192 Example:
4193
4194 -> { "execute": "blockdev-close-tray",
4195      "arguments": { "device": "ide1-cd0" } }
4196
4197 <- { "timestamp": { "seconds": 1418751345,
4198                     "microseconds": 272147 },
4199      "event": "DEVICE_TRAY_MOVED",
4200      "data": { "device": "ide1-cd0",
4201                "tray-open": false } }
4202
4203 <- { "return": {} }
4204
4205 EQMP
4206
4207     {
4208         .name       = "x-blockdev-remove-medium",
4209         .args_type  = "device:s",
4210         .mhandler.cmd_new = qmp_marshal_x_blockdev_remove_medium,
4211     },
4212
4213 SQMP
4214 x-blockdev-remove-medium
4215 ------------------------
4216
4217 Removes a medium (a block driver state tree) from a block device. That block
4218 device's tray must currently be open (unless there is no attached guest device).
4219
4220 If the tray is open and there is no medium inserted, this will be a no-op.
4221
4222 This command is still a work in progress and is considered experimental.
4223 Stay away from it unless you want to help with its development.
4224
4225 Arguments:
4226
4227 - "device": block device name (json-string)
4228
4229 Example:
4230
4231 -> { "execute": "x-blockdev-remove-medium",
4232      "arguments": { "device": "ide1-cd0" } }
4233
4234 <- { "error": { "class": "GenericError",
4235                 "desc": "Tray of device 'ide1-cd0' is not open" } }
4236
4237 -> { "execute": "blockdev-open-tray",
4238      "arguments": { "device": "ide1-cd0" } }
4239
4240 <- { "timestamp": { "seconds": 1418751627,
4241                     "microseconds": 549958 },
4242      "event": "DEVICE_TRAY_MOVED",
4243      "data": { "device": "ide1-cd0",
4244                "tray-open": true } }
4245
4246 <- { "return": {} }
4247
4248 -> { "execute": "x-blockdev-remove-medium",
4249      "arguments": { "device": "ide1-cd0" } }
4250
4251 <- { "return": {} }
4252
4253 EQMP
4254
4255     {
4256         .name       = "x-blockdev-insert-medium",
4257         .args_type  = "device:s,node-name:s",
4258         .mhandler.cmd_new = qmp_marshal_x_blockdev_insert_medium,
4259     },
4260
4261 SQMP
4262 x-blockdev-insert-medium
4263 ------------------------
4264
4265 Inserts a medium (a block driver state tree) into a block device. That block
4266 device's tray must currently be open (unless there is no attached guest device)
4267 and there must be no medium inserted already.
4268
4269 This command is still a work in progress and is considered experimental.
4270 Stay away from it unless you want to help with its development.
4271
4272 Arguments:
4273
4274 - "device": block device name (json-string)
4275 - "node-name": root node of the BDS tree to insert into the block device
4276
4277 Example:
4278
4279 -> { "execute": "blockdev-add",
4280      "arguments": { "options": { "node-name": "node0",
4281                                  "driver": "raw",
4282                                  "file": { "driver": "file",
4283                                            "filename": "fedora.iso" } } } }
4284
4285 <- { "return": {} }
4286
4287 -> { "execute": "x-blockdev-insert-medium",
4288      "arguments": { "device": "ide1-cd0",
4289                     "node-name": "node0" } }
4290
4291 <- { "return": {} }
4292
4293 EQMP
4294
4295     {
4296         .name       = "query-named-block-nodes",
4297         .args_type  = "",
4298         .mhandler.cmd_new = qmp_marshal_query_named_block_nodes,
4299     },
4300
4301 SQMP
4302 @query-named-block-nodes
4303 ------------------------
4304
4305 Return a list of BlockDeviceInfo for all the named block driver nodes
4306
4307 Example:
4308
4309 -> { "execute": "query-named-block-nodes" }
4310 <- { "return": [ { "ro":false,
4311                    "drv":"qcow2",
4312                    "encrypted":false,
4313                    "file":"disks/test.qcow2",
4314                    "node-name": "my-node",
4315                    "backing_file_depth":1,
4316                    "bps":1000000,
4317                    "bps_rd":0,
4318                    "bps_wr":0,
4319                    "iops":1000000,
4320                    "iops_rd":0,
4321                    "iops_wr":0,
4322                    "bps_max": 8000000,
4323                    "bps_rd_max": 0,
4324                    "bps_wr_max": 0,
4325                    "iops_max": 0,
4326                    "iops_rd_max": 0,
4327                    "iops_wr_max": 0,
4328                    "iops_size": 0,
4329                    "write_threshold": 0,
4330                    "image":{
4331                       "filename":"disks/test.qcow2",
4332                       "format":"qcow2",
4333                       "virtual-size":2048000,
4334                       "backing_file":"base.qcow2",
4335                       "full-backing-filename":"disks/base.qcow2",
4336                       "backing-filename-format":"qcow2",
4337                       "snapshots":[
4338                          {
4339                             "id": "1",
4340                             "name": "snapshot1",
4341                             "vm-state-size": 0,
4342                             "date-sec": 10000200,
4343                             "date-nsec": 12,
4344                             "vm-clock-sec": 206,
4345                             "vm-clock-nsec": 30
4346                          }
4347                       ],
4348                       "backing-image":{
4349                           "filename":"disks/base.qcow2",
4350                           "format":"qcow2",
4351                           "virtual-size":2048000
4352                       }
4353                    } } ] }
4354
4355 EQMP
4356
4357     {
4358         .name       = "blockdev-change-medium",
4359         .args_type  = "device:B,filename:F,format:s?,read-only-mode:s?",
4360         .mhandler.cmd_new = qmp_marshal_blockdev_change_medium,
4361     },
4362
4363 SQMP
4364 blockdev-change-medium
4365 ----------------------
4366
4367 Changes the medium inserted into a block device by ejecting the current medium
4368 and loading a new image file which is inserted as the new medium.
4369
4370 Arguments:
4371
4372 - "device": device name (json-string)
4373 - "filename": filename of the new image (json-string)
4374 - "format": format of the new image (json-string, optional)
4375 - "read-only-mode": new read-only mode (json-string, optional)
4376           - Possible values: "retain" (default), "read-only", "read-write"
4377
4378 Examples:
4379
4380 1. Change a removable medium
4381
4382 -> { "execute": "blockdev-change-medium",
4383              "arguments": { "device": "ide1-cd0",
4384                             "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
4385                             "format": "raw" } }
4386 <- { "return": {} }
4387
4388 2. Load a read-only medium into a writable drive
4389
4390 -> { "execute": "blockdev-change-medium",
4391              "arguments": { "device": "isa-fd0",
4392                             "filename": "/srv/images/ro.img",
4393                             "format": "raw",
4394                             "read-only-mode": "retain" } }
4395
4396 <- { "error":
4397      { "class": "GenericError",
4398        "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
4399
4400 -> { "execute": "blockdev-change-medium",
4401              "arguments": { "device": "isa-fd0",
4402                             "filename": "/srv/images/ro.img",
4403                             "format": "raw",
4404                             "read-only-mode": "read-only" } }
4405
4406 <- { "return": {} }
4407
4408 EQMP
4409
4410     {
4411         .name       = "query-memdev",
4412         .args_type  = "",
4413         .mhandler.cmd_new = qmp_marshal_query_memdev,
4414     },
4415
4416 SQMP
4417 query-memdev
4418 ------------
4419
4420 Show memory devices information.
4421
4422
4423 Example (1):
4424
4425 -> { "execute": "query-memdev" }
4426 <- { "return": [
4427        {
4428          "size": 536870912,
4429          "merge": false,
4430          "dump": true,
4431          "prealloc": false,
4432          "host-nodes": [0, 1],
4433          "policy": "bind"
4434        },
4435        {
4436          "size": 536870912,
4437          "merge": false,
4438          "dump": true,
4439          "prealloc": true,
4440          "host-nodes": [2, 3],
4441          "policy": "preferred"
4442        }
4443      ]
4444    }
4445
4446 EQMP
4447
4448     {
4449         .name       = "query-memory-devices",
4450         .args_type  = "",
4451         .mhandler.cmd_new = qmp_marshal_query_memory_devices,
4452     },
4453
4454 SQMP
4455 @query-memory-devices
4456 --------------------
4457
4458 Return a list of memory devices.
4459
4460 Example:
4461 -> { "execute": "query-memory-devices" }
4462 <- { "return": [ { "data":
4463                       { "addr": 5368709120,
4464                         "hotpluggable": true,
4465                         "hotplugged": true,
4466                         "id": "d1",
4467                         "memdev": "/objects/memX",
4468                         "node": 0,
4469                         "size": 1073741824,
4470                         "slot": 0},
4471                    "type": "dimm"
4472                  } ] }
4473 EQMP
4474
4475     {
4476         .name       = "query-acpi-ospm-status",
4477         .args_type  = "",
4478         .mhandler.cmd_new = qmp_marshal_query_acpi_ospm_status,
4479     },
4480
4481 SQMP
4482 @query-acpi-ospm-status
4483 --------------------
4484
4485 Return list of ACPIOSTInfo for devices that support status reporting
4486 via ACPI _OST method.
4487
4488 Example:
4489 -> { "execute": "query-acpi-ospm-status" }
4490 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
4491                  { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
4492                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
4493                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
4494    ]}
4495 EQMP
4496
4497 #if defined TARGET_I386
4498     {
4499         .name       = "rtc-reset-reinjection",
4500         .args_type  = "",
4501         .mhandler.cmd_new = qmp_marshal_rtc_reset_reinjection,
4502     },
4503 #endif
4504
4505 SQMP
4506 rtc-reset-reinjection
4507 ---------------------
4508
4509 Reset the RTC interrupt reinjection backlog.
4510
4511 Arguments: None.
4512
4513 Example:
4514
4515 -> { "execute": "rtc-reset-reinjection" }
4516 <- { "return": {} }
4517 EQMP
4518
4519     {
4520         .name       = "trace-event-get-state",
4521         .args_type  = "name:s",
4522         .mhandler.cmd_new = qmp_marshal_trace_event_get_state,
4523     },
4524
4525 SQMP
4526 trace-event-get-state
4527 ---------------------
4528
4529 Query the state of events.
4530
4531 Example:
4532
4533 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
4534 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
4535 EQMP
4536
4537     {
4538         .name       = "trace-event-set-state",
4539         .args_type  = "name:s,enable:b,ignore-unavailable:b?",
4540         .mhandler.cmd_new = qmp_marshal_trace_event_set_state,
4541     },
4542
4543 SQMP
4544 trace-event-set-state
4545 ---------------------
4546
4547 Set the state of events.
4548
4549 Example:
4550
4551 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
4552 <- { "return": {} }
4553 EQMP
4554
4555     {
4556         .name       = "x-input-send-event",
4557         .args_type  = "console:i?,events:q",
4558         .mhandler.cmd_new = qmp_marshal_x_input_send_event,
4559     },
4560
4561 SQMP
4562 @x-input-send-event
4563 -----------------
4564
4565 Send input event to guest.
4566
4567 Arguments:
4568
4569 - "console": console index. (json-int, optional)
4570 - "events": list of input events.
4571
4572 The consoles are visible in the qom tree, under
4573 /backend/console[$index]. They have a device link and head property, so
4574 it is possible to map which console belongs to which device and display.
4575
4576 Note: this command is experimental, and not a stable API.
4577
4578 Example (1):
4579
4580 Press left mouse button.
4581
4582 -> { "execute": "x-input-send-event",
4583     "arguments": { "console": 0,
4584                    "events": [ { "type": "btn",
4585                     "data" : { "down": true, "button": "Left" } } ] } }
4586 <- { "return": {} }
4587
4588 -> { "execute": "x-input-send-event",
4589     "arguments": { "console": 0,
4590                    "events": [ { "type": "btn",
4591                     "data" : { "down": false, "button": "Left" } } ] } }
4592 <- { "return": {} }
4593
4594 Example (2):
4595
4596 Press ctrl-alt-del.
4597
4598 -> { "execute": "x-input-send-event",
4599      "arguments": { "console": 0, "events": [
4600         { "type": "key", "data" : { "down": true,
4601           "key": {"type": "qcode", "data": "ctrl" } } },
4602         { "type": "key", "data" : { "down": true,
4603           "key": {"type": "qcode", "data": "alt" } } },
4604         { "type": "key", "data" : { "down": true,
4605           "key": {"type": "qcode", "data": "delete" } } } ] } }
4606 <- { "return": {} }
4607
4608 Example (3):
4609
4610 Move mouse pointer to absolute coordinates (20000, 400).
4611
4612 -> { "execute": "x-input-send-event" ,
4613   "arguments": { "console": 0, "events": [
4614                { "type": "abs", "data" : { "axis": "X", "value" : 20000 } },
4615                { "type": "abs", "data" : { "axis": "Y", "value" : 400 } } ] } }
4616 <- { "return": {} }
4617
4618 EQMP
4619
4620     {
4621         .name       = "block-set-write-threshold",
4622         .args_type  = "node-name:s,write-threshold:l",
4623         .mhandler.cmd_new = qmp_marshal_block_set_write_threshold,
4624     },
4625
4626 SQMP
4627 block-set-write-threshold
4628 ------------
4629
4630 Change the write threshold for a block drive. The threshold is an offset,
4631 thus must be non-negative. Default is no write threshold.
4632 Setting the threshold to zero disables it.
4633
4634 Arguments:
4635
4636 - "node-name": the node name in the block driver state graph (json-string)
4637 - "write-threshold": the write threshold in bytes (json-int)
4638
4639 Example:
4640
4641 -> { "execute": "block-set-write-threshold",
4642   "arguments": { "node-name": "mydev",
4643                  "write-threshold": 17179869184 } }
4644 <- { "return": {} }
4645
4646 EQMP
4647
4648     {
4649         .name       = "query-rocker",
4650         .args_type  = "name:s",
4651         .mhandler.cmd_new = qmp_marshal_query_rocker,
4652     },
4653
4654 SQMP
4655 Show rocker switch
4656 ------------------
4657
4658 Arguments:
4659
4660 - "name": switch name
4661
4662 Example:
4663
4664 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
4665 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
4666
4667 EQMP
4668
4669     {
4670         .name       = "query-rocker-ports",
4671         .args_type  = "name:s",
4672         .mhandler.cmd_new = qmp_marshal_query_rocker_ports,
4673     },
4674
4675 SQMP
4676 Show rocker switch ports
4677 ------------------------
4678
4679 Arguments:
4680
4681 - "name": switch name
4682
4683 Example:
4684
4685 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
4686 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
4687                   "autoneg": "off", "link-up": true, "speed": 10000},
4688                  {"duplex": "full", "enabled": true, "name": "sw1.2",
4689                   "autoneg": "off", "link-up": true, "speed": 10000}
4690    ]}
4691
4692 EQMP
4693
4694     {
4695         .name       = "query-rocker-of-dpa-flows",
4696         .args_type  = "name:s,tbl-id:i?",
4697         .mhandler.cmd_new = qmp_marshal_query_rocker_of_dpa_flows,
4698     },
4699
4700 SQMP
4701 Show rocker switch OF-DPA flow tables
4702 -------------------------------------
4703
4704 Arguments:
4705
4706 - "name": switch name
4707 - "tbl-id": (optional) flow table ID
4708
4709 Example:
4710
4711 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
4712 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
4713                   "hits": 138,
4714                   "cookie": 0,
4715                   "action": {"goto-tbl": 10},
4716                   "mask": {"in-pport": 4294901760}
4717                  },
4718                  {...more...},
4719    ]}
4720
4721 EQMP
4722
4723     {
4724         .name       = "query-rocker-of-dpa-groups",
4725         .args_type  = "name:s,type:i?",
4726         .mhandler.cmd_new = qmp_marshal_query_rocker_of_dpa_groups,
4727     },
4728
4729 SQMP
4730 Show rocker OF-DPA group tables
4731 -------------------------------
4732
4733 Arguments:
4734
4735 - "name": switch name
4736 - "type": (optional) group type
4737
4738 Example:
4739
4740 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
4741 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
4742                   "pop-vlan": 1, "id": 251723778},
4743                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
4744                   "pop-vlan": 1, "id": 251723776},
4745                  {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
4746                   "pop-vlan": 1, "id": 251658241},
4747                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
4748                   "pop-vlan": 1, "id": 251658240}
4749    ]}