docs/qmp-commands.txt

   1                         QMP Supported Commands
   2                         ----------------------
   3
   4 This document describes all commands currently supported by QMP.
   5
   6 Most of the time their usage is exactly the same as in the user Monitor, this
   7 means that any other document which also describe commands (the manpage,
   8 QEMU's manual, etc) can and should be consulted.
   9
  10 QMP has two types of commands: regular and query commands. Regular commands
  11 usually change the Virtual Machine's state someway, while query commands just
  12 return information. The sections below are divided accordingly.
  13
  14 It's important to observe that all communication examples are formatted in
  15 a reader-friendly way, so that they're easier to understand. However, in real
  16 protocol usage, they're emitted as a single line.
  17
  18 Also, the following notation is used to denote data flow:
  19
  20 -> data issued by the Client
  21 <- Server data response
  22
  23 Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
  24 information on the Server command and response formats.
  25
  26 NOTE: This document is temporary and will be replaced soon.
  27
  28 1. Stability Considerations
  29 ===========================
  30
  31 The current QMP command set (described in this file) may be useful for a
  32 number of use cases, however it's limited and several commands have bad
  33 defined semantics, specially with regard to command completion.
  34
  35 These problems are going to be solved incrementally in the next QEMU releases
  36 and we're going to establish a deprecation policy for badly defined commands.
  37
  38 If you're planning to adopt QMP, please observe the following:
  39
  40     1. The deprecation policy will take effect and be documented soon, please
  41        check the documentation of each used command as soon as a new release of
  42        QEMU is available
  43
  44     2. DO NOT rely on anything which is not explicit documented
  45
  46     3. Errors, in special, are not documented. Applications should NOT check
  47        for specific errors classes or data (it's strongly recommended to only
  48        check for the "error" key)
  49
  50 2. Regular Commands
  51 ===================
  52
  53 Server's responses in the examples below are always a success response, please
  54 refer to the QMP specification for more details on error responses.
  55
  56 quit
  57 ----
  58
  59 Quit the emulator.
  60
  61 Arguments: None.
  62
  63 Example:
  64
  65 -> { "execute": "quit" }
  66 <- { "return": {} }
  67
  68 eject
  69 -----
  70
  71 Eject a removable medium.
  72
  73 Arguments:
  74
  75 - "force": force ejection (json-bool, optional)
  76 - "device": block device name (deprecated, use @id instead)
  77             (json-string, optional)
  78 - "id": the name or QOM path of the guest device (json-string, optional)
  79
  80 Example:
  81
  82 -> { "execute": "eject", "arguments": { "id": "ide0-1-0" } }
  83 <- { "return": {} }
  84
  85 Note: The "force" argument defaults to false.
  86
  87 change
  88 ------
  89
  90 Change a removable medium or VNC configuration.
  91
  92 Arguments:
  93
  94 - "device": device name (json-string)
  95 - "target": filename or item (json-string)
  96 - "arg": additional argument (json-string, optional)
  97
  98 Examples:
  99
 100 1. Change a removable medium
 101
 102 -> { "execute": "change",
 103              "arguments": { "device": "ide1-cd0",
 104                             "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
 105 <- { "return": {} }
 106
 107 2. Change VNC password
 108
 109 -> { "execute": "change",
 110              "arguments": { "device": "vnc", "target": "password",
 111                             "arg": "foobar1" } }
 112 <- { "return": {} }
 113
 114 screendump
 115 ----------
 116
 117 Save screen into PPM image.
 118
 119 Arguments:
 120
 121 - "filename": file path (json-string)
 122
 123 Example:
 124
 125 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 126 <- { "return": {} }
 127
 128 stop
 129 ----
 130
 131 Stop the emulator.
 132
 133 Arguments: None.
 134
 135 Example:
 136
 137 -> { "execute": "stop" }
 138 <- { "return": {} }
 139
 140 cont
 141 ----
 142
 143 Resume emulation.
 144
 145 Arguments: None.
 146
 147 Example:
 148
 149 -> { "execute": "cont" }
 150 <- { "return": {} }
 151
 152 system_wakeup
 153 -------------
 154
 155 Wakeup guest from suspend.
 156
 157 Arguments: None.
 158
 159 Example:
 160
 161 -> { "execute": "system_wakeup" }
 162 <- { "return": {} }
 163
 164 system_reset
 165 ------------
 166
 167 Reset the system.
 168
 169 Arguments: None.
 170
 171 Example:
 172
 173 -> { "execute": "system_reset" }
 174 <- { "return": {} }
 175
 176 system_powerdown
 177 ----------------
 178
 179 Send system power down event.
 180
 181 Arguments: None.
 182
 183 Example:
 184
 185 -> { "execute": "system_powerdown" }
 186 <- { "return": {} }
 187
 188 device_add
 189 ----------
 190
 191 Add a device.
 192
 193 Arguments:
 194
 195 - "driver": the name of the new device's driver (json-string)
 196 - "bus": the device's parent bus (device tree path, json-string, optional)
 197 - "id": the device's ID, must be unique (json-string)
 198 - device properties
 199
 200 Example:
 201
 202 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
 203 <- { "return": {} }
 204
 205 Notes:
 206
 207 (1) For detailed information about this command, please refer to the
 208     'docs/qdev-device-use.txt' file.
 209
 210 (2) It's possible to list device properties by running QEMU with the
 211     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
 212
 213 device_del
 214 ----------
 215
 216 Remove a device.
 217
 218 Arguments:
 219
 220 - "id": the device's ID or QOM path (json-string)
 221
 222 Example:
 223
 224 -> { "execute": "device_del", "arguments": { "id": "net1" } }
 225 <- { "return": {} }
 226
 227 Example:
 228
 229 -> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
 230 <- { "return": {} }
 231
 232 send-key
 233 ----------
 234
 235 Send keys to VM.
 236
 237 Arguments:
 238
 239 keys array:
 240     - "key": key sequence (a json-array of key union values,
 241              union can be number or qcode enum)
 242
 243 - hold-time: time to delay key up events, milliseconds. Defaults to 100
 244              (json-int, optional)
 245
 246 Example:
 247
 248 -> { "execute": "send-key",
 249      "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
 250                               { "type": "qcode", "data": "alt" },
 251                               { "type": "qcode", "data": "delete" } ] } }
 252 <- { "return": {} }
 253
 254 cpu
 255 ---
 256
 257 Set the default CPU.
 258
 259 Arguments:
 260
 261 - "index": the CPU's index (json-int)
 262
 263 Example:
 264
 265 -> { "execute": "cpu", "arguments": { "index": 0 } }
 266 <- { "return": {} }
 267
 268 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 269
 270 cpu-add
 271 -------
 272
 273 Adds virtual cpu
 274
 275 Arguments:
 276
 277 - "id": cpu id (json-int)
 278
 279 Example:
 280
 281 -> { "execute": "cpu-add", "arguments": { "id": 2 } }
 282 <- { "return": {} }
 283
 284 memsave
 285 -------
 286
 287 Save to disk virtual memory dump starting at 'val' of size 'size'.
 288
 289 Arguments:
 290
 291 - "val": the starting address (json-int)
 292 - "size": the memory size, in bytes (json-int)
 293 - "filename": file path (json-string)
 294 - "cpu": virtual CPU index (json-int, optional)
 295
 296 Example:
 297
 298 -> { "execute": "memsave",
 299              "arguments": { "val": 10,
 300                             "size": 100,
 301                             "filename": "/tmp/virtual-mem-dump" } }
 302 <- { "return": {} }
 303
 304 pmemsave
 305 --------
 306
 307 Save to disk physical memory dump starting at 'val' of size 'size'.
 308
 309 Arguments:
 310
 311 - "val": the starting address (json-int)
 312 - "size": the memory size, in bytes (json-int)
 313 - "filename": file path (json-string)
 314
 315 Example:
 316
 317 -> { "execute": "pmemsave",
 318              "arguments": { "val": 10,
 319                             "size": 100,
 320                             "filename": "/tmp/physical-mem-dump" } }
 321 <- { "return": {} }
 322
 323 inject-nmi
 324 ----------
 325
 326 Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64).
 327
 328 Arguments: None.
 329
 330 Example:
 331
 332 -> { "execute": "inject-nmi" }
 333 <- { "return": {} }
 334
 335 Note: inject-nmi fails when the guest doesn't support injecting.
 336
 337 ringbuf-write
 338 -------------
 339
 340 Write to a ring buffer character device.
 341
 342 Arguments:
 343
 344 - "device": ring buffer character device name (json-string)
 345 - "data": data to write (json-string)
 346 - "format": data format (json-string, optional)
 347           - Possible values: "utf8" (default), "base64"
 348
 349 Example:
 350
 351 -> { "execute": "ringbuf-write",
 352                 "arguments": { "device": "foo",
 353                                "data": "abcdefgh",
 354                                "format": "utf8" } }
 355 <- { "return": {} }
 356
 357 ringbuf-read
 358 -------------
 359
 360 Read from a ring buffer character device.
 361
 362 Arguments:
 363
 364 - "device": ring buffer character device name (json-string)
 365 - "size": how many bytes to read at most (json-int)
 366           - Number of data bytes, not number of characters in encoded data
 367 - "format": data format (json-string, optional)
 368           - Possible values: "utf8" (default), "base64"
 369           - Naturally, format "utf8" works only when the ring buffer
 370             contains valid UTF-8 text.  Invalid UTF-8 sequences get
 371             replaced.  Bug: replacement doesn't work.  Bug: can screw
 372             up on encountering NUL characters, after the ring buffer
 373             lost data, and when reading stops because the size limit
 374             is reached.
 375
 376 Example:
 377
 378 -> { "execute": "ringbuf-read",
 379                 "arguments": { "device": "foo",
 380                                "size": 1000,
 381                                "format": "utf8" } }
 382 <- {"return": "abcdefgh"}
 383
 384 xen-save-devices-state
 385 -------
 386
 387 Save the state of all devices to file. The RAM and the block devices
 388 of the VM are not saved by this command.
 389
 390 Arguments:
 391
 392 - "filename": the file to save the state of the devices to as binary
 393 data. See xen-save-devices-state.txt for a description of the binary
 394 format.
 395
 396 Example:
 397
 398 -> { "execute": "xen-save-devices-state",
 399      "arguments": { "filename": "/tmp/save" } }
 400 <- { "return": {} }
 401
 402 xen-load-devices-state
 403 ----------------------
 404
 405 Load the state of all devices from file. The RAM and the block devices
 406 of the VM are not loaded by this command.
 407
 408 Arguments:
 409
 410 - "filename": the file to load the state of the devices from as binary
 411 data. See xen-save-devices-state.txt for a description of the binary
 412 format.
 413
 414 Example:
 415
 416 -> { "execute": "xen-load-devices-state",
 417      "arguments": { "filename": "/tmp/resume" } }
 418 <- { "return": {} }
 419
 420 xen-set-global-dirty-log
 421 -------
 422
 423 Enable or disable the global dirty log mode.
 424
 425 Arguments:
 426
 427 - "enable": Enable it or disable it.
 428
 429 Example:
 430
 431 -> { "execute": "xen-set-global-dirty-log",
 432      "arguments": { "enable": true } }
 433 <- { "return": {} }
 434
 435 migrate
 436 -------
 437
 438 Migrate to URI.
 439
 440 Arguments:
 441
 442 - "blk": block migration, full disk copy (json-bool, optional)
 443 - "inc": incremental disk copy (json-bool, optional)
 444 - "uri": Destination URI (json-string)
 445
 446 Example:
 447
 448 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
 449 <- { "return": {} }
 450
 451 Notes:
 452
 453 (1) The 'query-migrate' command should be used to check migration's progress
 454     and final result (this information is provided by the 'status' member)
 455 (2) All boolean arguments default to false
 456 (3) The user Monitor's "detach" argument is invalid in QMP and should not
 457     be used
 458
 459 migrate_cancel
 460 --------------
 461
 462 Cancel the current migration.
 463
 464 Arguments: None.
 465
 466 Example:
 467
 468 -> { "execute": "migrate_cancel" }
 469 <- { "return": {} }
 470
 471 migrate-incoming
 472 ----------------
 473
 474 Continue an incoming migration
 475
 476 Arguments:
 477
 478 - "uri": Source/listening URI (json-string)
 479
 480 Example:
 481
 482 -> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } }
 483 <- { "return": {} }
 484
 485 Notes:
 486
 487 (1) QEMU must be started with -incoming defer to allow migrate-incoming to
 488     be used
 489 (2) The uri format is the same as for -incoming
 490
 491 migrate-set-cache-size
 492 ----------------------
 493
 494 Set cache size to be used by XBZRLE migration, the cache size will be rounded
 495 down to the nearest power of 2
 496
 497 Arguments:
 498
 499 - "value": cache size in bytes (json-int)
 500
 501 Example:
 502
 503 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 504 <- { "return": {} }
 505
 506 migrate-start-postcopy
 507 ----------------------
 508
 509 Switch an in-progress migration to postcopy mode. Ignored after the end of
 510 migration (or once already in postcopy).
 511
 512 Example:
 513 -> { "execute": "migrate-start-postcopy" }
 514 <- { "return": {} }
 515
 516 query-migrate-cache-size
 517 ------------------------
 518
 519 Show cache size to be used by XBZRLE migration
 520
 521 returns a json-object with the following information:
 522 - "size" : json-int
 523
 524 Example:
 525
 526 -> { "execute": "query-migrate-cache-size" }
 527 <- { "return": 67108864 }
 528
 529 migrate_set_speed
 530 -----------------
 531
 532 Set maximum speed for migrations.
 533
 534 Arguments:
 535
 536 - "value": maximum speed, in bytes per second (json-int)
 537
 538 Example:
 539
 540 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
 541 <- { "return": {} }
 542
 543 migrate_set_downtime
 544 --------------------
 545
 546 Set maximum tolerated downtime (in seconds) for migrations.
 547
 548 Arguments:
 549
 550 - "value": maximum downtime (json-number)
 551
 552 Example:
 553
 554 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
 555 <- { "return": {} }
 556
 557 client_migrate_info
 558 -------------------
 559
 560 Set migration information for remote display.  This makes the server
 561 ask the client to automatically reconnect using the new parameters
 562 once migration finished successfully.  Only implemented for SPICE.
 563
 564 Arguments:
 565
 566 - "protocol":     must be "spice" (json-string)
 567 - "hostname":     migration target hostname (json-string)
 568 - "port":         spice tcp port for plaintext channels (json-int, optional)
 569 - "tls-port":     spice tcp port for tls-secured channels (json-int, optional)
 570 - "cert-subject": server certificate subject (json-string, optional)
 571
 572 Example:
 573
 574 -> { "execute": "client_migrate_info",
 575      "arguments": { "protocol": "spice",
 576                     "hostname": "virt42.lab.kraxel.org",
 577                     "port": 1234 } }
 578 <- { "return": {} }
 579
 580 dump
 581
 582
 583 Dump guest memory to file. The file can be processed with crash or gdb.
 584
 585 Arguments:
 586
 587 - "paging": do paging to get guest's memory mapping (json-bool)
 588 - "protocol": destination file(started with "file:") or destination file
 589               descriptor (started with "fd:") (json-string)
 590 - "detach": if specified, command will return immediately, without waiting
 591             for the dump to finish. The user can track progress using
 592             "query-dump". (json-bool)
 593 - "begin": the starting physical address. It's optional, and should be specified
 594            with length together (json-int)
 595 - "length": the memory size, in bytes. It's optional, and should be specified
 596             with begin together (json-int)
 597 - "format": the format of guest memory dump. It's optional, and can be
 598             elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will
 599             conflict with paging and filter, ie. begin and length (json-string)
 600
 601 Example:
 602
 603 -> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
 604 <- { "return": {} }
 605
 606 Notes:
 607
 608 (1) All boolean arguments default to false
 609
 610 query-dump-guest-memory-capability
 611 ----------
 612
 613 Show available formats for 'dump-guest-memory'
 614
 615 Example:
 616
 617 -> { "execute": "query-dump-guest-memory-capability" }
 618 <- { "return": { "formats":
 619                     ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
 620
 621 query-dump
 622 ----------
 623
 624 Query background dump status.
 625
 626 Arguments: None.
 627
 628 Example:
 629
 630 -> { "execute": "query-dump" }
 631 <- { "return": { "status": "active", "completed": 1024000,
 632                  "total": 2048000 } }
 633
 634 dump-skeys
 635 ----------
 636
 637 Save guest storage keys to file.
 638
 639 Arguments:
 640
 641 - "filename": file path (json-string)
 642
 643 Example:
 644
 645 -> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } }
 646 <- { "return": {} }
 647
 648 netdev_add
 649 ----------
 650
 651 Add host network device.
 652
 653 Arguments:
 654
 655 - "type": the device type, "tap", "user", ... (json-string)
 656 - "id": the device's ID, must be unique (json-string)
 657 - device options
 658
 659 Example:
 660
 661 -> { "execute": "netdev_add",
 662      "arguments": { "type": "user", "id": "netdev1",
 663                     "dnssearch": "example.org" } }
 664 <- { "return": {} }
 665
 666 Note: The supported device options are the same ones supported by the '-netdev'
 667       command-line argument, which are listed in the '-help' output or QEMU's
 668       manual
 669
 670 netdev_del
 671 ----------
 672
 673 Remove host network device.
 674
 675 Arguments:
 676
 677 - "id": the device's ID, must be unique (json-string)
 678
 679 Example:
 680
 681 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
 682 <- { "return": {} }
 683
 684
 685 object-add
 686 ----------
 687
 688 Create QOM object.
 689
 690 Arguments:
 691
 692 - "qom-type": the object's QOM type, i.e. the class name (json-string)
 693 - "id": the object's ID, must be unique (json-string)
 694 - "props": a dictionary of object property values (optional, json-dict)
 695
 696 Example:
 697
 698 -> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1",
 699      "props": { "filename": "/dev/hwrng" } } }
 700 <- { "return": {} }
 701
 702 object-del
 703 ----------
 704
 705 Remove QOM object.
 706
 707 Arguments:
 708
 709 - "id": the object's ID (json-string)
 710
 711 Example:
 712
 713 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
 714 <- { "return": {} }
 715
 716
 717 block_resize
 718 ------------
 719
 720 Resize a block image while a guest is running.
 721
 722 Arguments:
 723
 724 - "device": the device's ID, must be unique (json-string)
 725 - "node-name": the node name in the block driver state graph (json-string)
 726 - "size": new size
 727
 728 Example:
 729
 730 -> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
 731 <- { "return": {} }
 732
 733 block-stream
 734 ------------
 735
 736 Copy data from a backing file into a block device.
 737
 738 Arguments:
 739
 740 - "job-id": Identifier for the newly-created block job. If omitted,
 741             the device name will be used. (json-string, optional)
 742 - "device": The device name or node-name of a root node (json-string)
 743 - "base": The file name of the backing image above which copying starts
 744           (json-string, optional)
 745 - "backing-file": The backing file string to write into the active layer. This
 746                   filename is not validated.
 747
 748                   If a pathname string is such that it cannot be resolved by
 749                   QEMU, that means that subsequent QMP or HMP commands must use
 750                   node-names for the image in question, as filename lookup
 751                   methods will fail.
 752
 753                   If not specified, QEMU will automatically determine the
 754                   backing file string to use, or error out if there is no
 755                   obvious choice.  Care should be taken when specifying the
 756                   string, to specify a valid filename or protocol.
 757                   (json-string, optional) (Since 2.1)
 758 - "speed":  the maximum speed, in bytes per second (json-int, optional)
 759 - "on-error": the action to take on an error (default 'report').  'stop' and
 760               'enospc' can only be used if the block device supports io-status.
 761               (json-string, optional) (Since 2.1)
 762
 763 Example:
 764
 765 -> { "execute": "block-stream", "arguments": { "device": "virtio0",
 766                                                "base": "/tmp/master.qcow2" } }
 767 <- { "return": {} }
 768
 769 block-commit
 770 ------------
 771
 772 Live commit of data from overlay image nodes into backing nodes - i.e., writes
 773 data between 'top' and 'base' into 'base'.
 774
 775 Arguments:
 776
 777 - "job-id": Identifier for the newly-created block job. If omitted,
 778             the device name will be used. (json-string, optional)
 779 - "device": The device name or node-name of a root node (json-string)
 780 - "base": The file name of the backing image to write data into.
 781           If not specified, this is the deepest backing image
 782           (json-string, optional)
 783 - "top":  The file name of the backing image within the image chain,
 784           which contains the topmost data to be committed down. If
 785           not specified, this is the active layer. (json-string, optional)
 786
 787 - backing-file:     The backing file string to write into the overlay
 788                     image of 'top'.  If 'top' is the active layer,
 789                     specifying a backing file string is an error. This
 790                     filename is not validated.
 791
 792                     If a pathname string is such that it cannot be
 793                     resolved by QEMU, that means that subsequent QMP or
 794                     HMP commands must use node-names for the image in
 795                     question, as filename lookup methods will fail.
 796
 797                     If not specified, QEMU will automatically determine
 798                     the backing file string to use, or error out if
 799                     there is no obvious choice. Care should be taken
 800                     when specifying the string, to specify a valid
 801                     filename or protocol.
 802                     (json-string, optional) (Since 2.1)
 803
 804           If top == base, that is an error.
 805           If top == active, the job will not be completed by itself,
 806           user needs to complete the job with the block-job-complete
 807           command after getting the ready event. (Since 2.0)
 808
 809           If the base image is smaller than top, then the base image
 810           will be resized to be the same size as top.  If top is
 811           smaller than the base image, the base will not be
 812           truncated.  If you want the base image size to match the
 813           size of the smaller top, you can safely truncate it
 814           yourself once the commit operation successfully completes.
 815           (json-string)
 816 - "speed":  the maximum speed, in bytes per second (json-int, optional)
 817
 818
 819 Example:
 820
 821 -> { "execute": "block-commit", "arguments": { "device": "virtio0",
 822                                               "top": "/tmp/snap1.qcow2" } }
 823 <- { "return": {} }
 824
 825 drive-backup
 826 ------------
 827
 828 Start a point-in-time copy of a block device to a new destination.  The
 829 status of ongoing drive-backup operations can be checked with
 830 query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
 831 The operation can be stopped before it has completed using the
 832 block-job-cancel command.
 833
 834 Arguments:
 835
 836 - "job-id": Identifier for the newly-created block job. If omitted,
 837             the device name will be used. (json-string, optional)
 838 - "device": the device name or node-name of a root node which should be copied.
 839             (json-string)
 840 - "target": the target of the new image. If the file exists, or if it is a
 841             device, the existing file/device will be used as the new
 842             destination.  If it does not exist, a new file will be created.
 843             (json-string)
 844 - "format": the format of the new destination, default is to probe if 'mode' is
 845             'existing', else the format of the source
 846             (json-string, optional)
 847 - "sync": what parts of the disk image should be copied to the destination;
 848   possibilities include "full" for all the disk, "top" for only the sectors
 849   allocated in the topmost image, "incremental" for only the dirty sectors in
 850   the bitmap, or "none" to only replicate new I/O (MirrorSyncMode).
 851 - "bitmap": dirty bitmap name for sync==incremental. Must be present if sync
 852             is "incremental", must NOT be present otherwise.
 853 - "mode": whether and how QEMU should create a new image
 854           (NewImageMode, optional, default 'absolute-paths')
 855 - "speed": the maximum speed, in bytes per second (json-int, optional)
 856 - "compress": true to compress data, if the target format supports it.
 857               (json-bool, optional, default false)
 858 - "on-source-error": the action to take on an error on the source, default
 859                      'report'.  'stop' and 'enospc' can only be used
 860                      if the block device supports io-status.
 861                      (BlockdevOnError, optional)
 862 - "on-target-error": the action to take on an error on the target, default
 863                      'report' (no limitations, since this applies to
 864                      a different block device than device).
 865                      (BlockdevOnError, optional)
 866
 867 Example:
 868 -> { "execute": "drive-backup", "arguments": { "device": "drive0",
 869                                                "sync": "full",
 870                                                "target": "backup.img" } }
 871 <- { "return": {} }
 872
 873 blockdev-backup
 874 ---------------
 875
 876 The device version of drive-backup: this command takes an existing named device
 877 as backup target.
 878
 879 Arguments:
 880
 881 - "job-id": Identifier for the newly-created block job. If omitted,
 882             the device name will be used. (json-string, optional)
 883 - "device": the device name or node-name of a root node which should be copied.
 884             (json-string)
 885 - "target": the name of the backup target device. (json-string)
 886 - "sync": what parts of the disk image should be copied to the destination;
 887           possibilities include "full" for all the disk, "top" for only the
 888           sectors allocated in the topmost image, or "none" to only replicate
 889           new I/O (MirrorSyncMode).
 890 - "speed": the maximum speed, in bytes per second (json-int, optional)
 891 - "compress": true to compress data, if the target format supports it.
 892               (json-bool, optional, default false)
 893 - "on-source-error": the action to take on an error on the source, default
 894                      'report'.  'stop' and 'enospc' can only be used
 895                      if the block device supports io-status.
 896                      (BlockdevOnError, optional)
 897 - "on-target-error": the action to take on an error on the target, default
 898                      'report' (no limitations, since this applies to
 899                      a different block device than device).
 900                      (BlockdevOnError, optional)
 901
 902 Example:
 903 -> { "execute": "blockdev-backup", "arguments": { "device": "src-id",
 904                                                   "sync": "full",
 905                                                   "target": "tgt-id" } }
 906 <- { "return": {} }
 907
 908 transaction
 909 -----------
 910
 911 Atomically operate on one or more block devices.  Operations that are
 912 currently supported:
 913
 914     - drive-backup
 915     - blockdev-backup
 916     - blockdev-snapshot-sync
 917     - blockdev-snapshot-internal-sync
 918     - abort
 919     - block-dirty-bitmap-add
 920     - block-dirty-bitmap-clear
 921
 922 Refer to the qemu/qapi-schema.json file for minimum required QEMU
 923 versions for these operations.  A list of dictionaries is accepted,
 924 that contains the actions to be performed.  If there is any failure
 925 performing any of the operations, all operations for the group are
 926 abandoned.
 927
 928 For external snapshots, the dictionary contains the device, the file to use for
 929 the new snapshot, and the format.  The default format, if not specified, is
 930 qcow2.
 931
 932 Each new snapshot defaults to being created by QEMU (wiping any
 933 contents if the file already exists), but it is also possible to reuse
 934 an externally-created file.  In the latter case, you should ensure that
 935 the new image file has the same contents as the current one; QEMU cannot
 936 perform any meaningful check.  Typically this is achieved by using the
 937 current image file as the backing file for the new image.
 938
 939 On failure, the original disks pre-snapshot attempt will be used.
 940
 941 For internal snapshots, the dictionary contains the device and the snapshot's
 942 name.  If an internal snapshot matching name already exists, the request will
 943 be rejected.  Only some image formats support it, for example, qcow2, rbd,
 944 and sheepdog.
 945
 946 On failure, qemu will try delete the newly created internal snapshot in the
 947 transaction.  When an I/O error occurs during deletion, the user needs to fix
 948 it later with qemu-img or other command.
 949
 950 Arguments:
 951
 952 actions array:
 953     - "type": the operation to perform (json-string).  Possible
 954               values: "drive-backup", "blockdev-backup",
 955                       "blockdev-snapshot-sync",
 956                       "blockdev-snapshot-internal-sync",
 957                       "abort", "block-dirty-bitmap-add",
 958                       "block-dirty-bitmap-clear"
 959     - "data": a dictionary.  The contents depend on the value
 960       of "type".  When "type" is "blockdev-snapshot-sync":
 961       - "device": device name to snapshot (json-string)
 962       - "node-name": graph node name to snapshot (json-string)
 963       - "snapshot-file": name of new image file (json-string)
 964       - "snapshot-node-name": graph node name of the new snapshot (json-string)
 965       - "format": format of new image (json-string, optional)
 966       - "mode": whether and how QEMU should create the snapshot file
 967         (NewImageMode, optional, default "absolute-paths")
 968       When "type" is "blockdev-snapshot-internal-sync":
 969       - "device": the device name or node-name of a root node to snapshot
 970                   (json-string)
 971       - "name": name of the new snapshot (json-string)
 972
 973 Example:
 974
 975 -> { "execute": "transaction",
 976      "arguments": { "actions": [
 977          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
 978                                          "snapshot-file": "/some/place/my-image",
 979                                          "format": "qcow2" } },
 980          { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
 981                                          "snapshot-file": "/some/place/my-image2",
 982                                          "snapshot-node-name": "node3432",
 983                                          "mode": "existing",
 984                                          "format": "qcow2" } },
 985          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
 986                                          "snapshot-file": "/some/place/my-image2",
 987                                          "mode": "existing",
 988                                          "format": "qcow2" } },
 989          { "type": "blockdev-snapshot-internal-sync", "data" : {
 990                                          "device": "ide-hd2",
 991                                          "name": "snapshot0" } } ] } }
 992 <- { "return": {} }
 993
 994 block-dirty-bitmap-add
 995 ----------------------
 996 Since 2.4
 997
 998 Create a dirty bitmap with a name on the device, and start tracking the writes.
 999
1000 Arguments:
1001
1002 - "node": device/node on which to create dirty bitmap (json-string)
1003 - "name": name of the new dirty bitmap (json-string)
1004 - "granularity": granularity to track writes with (int, optional)
1005
1006 Example:
1007
1008 -> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0",
1009                                                    "name": "bitmap0" } }
1010 <- { "return": {} }
1011
1012 block-dirty-bitmap-remove
1013 -------------------------
1014 Since 2.4
1015
1016 Stop write tracking and remove the dirty bitmap that was created with
1017 block-dirty-bitmap-add.
1018
1019 Arguments:
1020
1021 - "node": device/node on which to remove dirty bitmap (json-string)
1022 - "name": name of the dirty bitmap to remove (json-string)
1023
1024 Example:
1025
1026 -> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0",
1027                                                       "name": "bitmap0" } }
1028 <- { "return": {} }
1029
1030 block-dirty-bitmap-clear
1031 ------------------------
1032 Since 2.4
1033
1034 Reset the dirty bitmap associated with a node so that an incremental backup
1035 from this point in time forward will only backup clusters modified after this
1036 clear operation.
1037
1038 Arguments:
1039
1040 - "node": device/node on which to remove dirty bitmap (json-string)
1041 - "name": name of the dirty bitmap to remove (json-string)
1042
1043 Example:
1044
1045 -> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0",
1046                                                            "name": "bitmap0" } }
1047 <- { "return": {} }
1048
1049 blockdev-snapshot-sync
1050 ----------------------
1051
1052 Synchronous snapshot of a block device. snapshot-file specifies the
1053 target of the new image. If the file exists, or if it is a device, the
1054 snapshot will be created in the existing file/device. If does not
1055 exist, a new file will be created. format specifies the format of the
1056 snapshot image, default is qcow2.
1057
1058 Arguments:
1059
1060 - "device": device name to snapshot (json-string)
1061 - "node-name": graph node name to snapshot (json-string)
1062 - "snapshot-file": name of new image file (json-string)
1063 - "snapshot-node-name": graph node name of the new snapshot (json-string)
1064 - "mode": whether and how QEMU should create the snapshot file
1065   (NewImageMode, optional, default "absolute-paths")
1066 - "format": format of new image (json-string, optional)
1067
1068 Example:
1069
1070 -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
1071                                                          "snapshot-file":
1072                                                         "/some/place/my-image",
1073                                                         "format": "qcow2" } }
1074 <- { "return": {} }
1075
1076 blockdev-snapshot
1077 -----------------
1078 Since 2.5
1079
1080 Create a snapshot, by installing 'node' as the backing image of
1081 'overlay'. Additionally, if 'node' is associated with a block
1082 device, the block device changes to using 'overlay' as its new active
1083 image.
1084
1085 Arguments:
1086
1087 - "node": device that will have a snapshot created (json-string)
1088 - "overlay": device that will have 'node' as its backing image (json-string)
1089
1090 Example:
1091
1092 -> { "execute": "blockdev-add",
1093                 "arguments": { "options": { "driver": "qcow2",
1094                                             "node-name": "node1534",
1095                                             "file": { "driver": "file",
1096                                                       "filename": "hd1.qcow2" },
1097                                             "backing": "" } } }
1098
1099 <- { "return": {} }
1100
1101 -> { "execute": "blockdev-snapshot", "arguments": { "node": "ide-hd0",
1102                                                     "overlay": "node1534" } }
1103 <- { "return": {} }
1104
1105 blockdev-snapshot-internal-sync
1106 -------------------------------
1107
1108 Synchronously take an internal snapshot of a block device when the format of
1109 image used supports it.  If the name is an empty string, or a snapshot with
1110 name already exists, the operation will fail.
1111
1112 Arguments:
1113
1114 - "device": the device name or node-name of a root node to snapshot
1115             (json-string)
1116 - "name": name of the new snapshot (json-string)
1117
1118 Example:
1119
1120 -> { "execute": "blockdev-snapshot-internal-sync",
1121                 "arguments": { "device": "ide-hd0",
1122                                "name": "snapshot0" }
1123    }
1124 <- { "return": {} }
1125
1126 blockdev-snapshot-delete-internal-sync
1127 --------------------------------------
1128
1129 Synchronously delete an internal snapshot of a block device when the format of
1130 image used supports it.  The snapshot is identified by name or id or both.  One
1131 of name or id is required.  If the snapshot is not found, the operation will
1132 fail.
1133
1134 Arguments:
1135
1136 - "device": the device name or node-name of a root node (json-string)
1137 - "id": ID of the snapshot (json-string, optional)
1138 - "name": name of the snapshot (json-string, optional)
1139
1140 Example:
1141
1142 -> { "execute": "blockdev-snapshot-delete-internal-sync",
1143                 "arguments": { "device": "ide-hd0",
1144                                "name": "snapshot0" }
1145    }
1146 <- { "return": {
1147                    "id": "1",
1148                    "name": "snapshot0",
1149                    "vm-state-size": 0,
1150                    "date-sec": 1000012,
1151                    "date-nsec": 10,
1152                    "vm-clock-sec": 100,
1153                    "vm-clock-nsec": 20
1154      }
1155    }
1156
1157 drive-mirror
1158 ------------
1159
1160 Start mirroring a block device's writes to a new destination. target
1161 specifies the target of the new image. If the file exists, or if it is
1162 a device, it will be used as the new destination for writes. If it does not
1163 exist, a new file will be created. format specifies the format of the
1164 mirror image, default is to probe if mode='existing', else the format
1165 of the source.
1166
1167 Arguments:
1168
1169 - "job-id": Identifier for the newly-created block job. If omitted,
1170             the device name will be used. (json-string, optional)
1171 - "device": the device name or node-name of a root node whose writes should be
1172             mirrored. (json-string)
1173 - "target": name of new image file (json-string)
1174 - "format": format of new image (json-string, optional)
1175 - "node-name": the name of the new block driver state in the node graph
1176                (json-string, optional)
1177 - "replaces": the block driver node name to replace when finished
1178               (json-string, optional)
1179 - "mode": how an image file should be created into the target
1180   file/device (NewImageMode, optional, default 'absolute-paths')
1181 - "speed": maximum speed of the streaming job, in bytes per second
1182   (json-int)
1183 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1184 - "buf-size": maximum amount of data in flight from source to target, in bytes
1185   (json-int, default 10M)
1186 - "sync": what parts of the disk image should be copied to the destination;
1187   possibilities include "full" for all the disk, "top" for only the sectors
1188   allocated in the topmost image, or "none" to only replicate new I/O
1189   (MirrorSyncMode).
1190 - "on-source-error": the action to take on an error on the source
1191   (BlockdevOnError, default 'report')
1192 - "on-target-error": the action to take on an error on the target
1193   (BlockdevOnError, default 'report')
1194 - "unmap": whether the target sectors should be discarded where source has only
1195   zeroes. (json-bool, optional, default true)
1196
1197 The default value of the granularity is the image cluster size clamped
1198 between 4096 and 65536, if the image format defines one.  If the format
1199 does not define a cluster size, the default value of the granularity
1200 is 65536.
1201
1202
1203 Example:
1204
1205 -> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
1206                                                "target": "/some/place/my-image",
1207                                                "sync": "full",
1208                                                "format": "qcow2" } }
1209 <- { "return": {} }
1210
1211 blockdev-mirror
1212 ------------
1213
1214 Start mirroring a block device's writes to another block device. target
1215 specifies the target of mirror operation.
1216
1217 Arguments:
1218
1219 - "job-id": Identifier for the newly-created block job. If omitted,
1220             the device name will be used. (json-string, optional)
1221 - "device": The device name or node-name of a root node whose writes should be
1222             mirrored (json-string)
1223 - "target": device name to mirror to (json-string)
1224 - "replaces": the block driver node name to replace when finished
1225               (json-string, optional)
1226 - "speed": maximum speed of the streaming job, in bytes per second
1227   (json-int)
1228 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1229 - "buf_size": maximum amount of data in flight from source to target, in bytes
1230   (json-int, default 10M)
1231 - "sync": what parts of the disk image should be copied to the destination;
1232   possibilities include "full" for all the disk, "top" for only the sectors
1233   allocated in the topmost image, or "none" to only replicate new I/O
1234   (MirrorSyncMode).
1235 - "on-source-error": the action to take on an error on the source
1236   (BlockdevOnError, default 'report')
1237 - "on-target-error": the action to take on an error on the target
1238   (BlockdevOnError, default 'report')
1239
1240 The default value of the granularity is the image cluster size clamped
1241 between 4096 and 65536, if the image format defines one.  If the format
1242 does not define a cluster size, the default value of the granularity
1243 is 65536.
1244
1245 Example:
1246
1247 -> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
1248                                                   "target": "target0",
1249                                                   "sync": "full" } }
1250 <- { "return": {} }
1251
1252 change-backing-file
1253 -------------------
1254 Since: 2.1
1255
1256 Change the backing file in the image file metadata.  This does not cause
1257 QEMU to reopen the image file to reparse the backing filename (it may,
1258 however, perform a reopen to change permissions from r/o -> r/w -> r/o,
1259 if needed). The new backing file string is written into the image file
1260 metadata, and the QEMU internal strings are updated.
1261
1262 Arguments:
1263
1264 - "image-node-name":    The name of the block driver state node of the
1265                         image to modify.  The "device" is argument is used to
1266                         verify "image-node-name" is in the chain described by
1267                         "device".
1268                         (json-string, optional)
1269
1270 - "device":             The device name or node-name of the root node that owns
1271                         image-node-name.
1272                         (json-string)
1273
1274 - "backing-file":       The string to write as the backing file.  This string is
1275                         not validated, so care should be taken when specifying
1276                         the string or the image chain may not be able to be
1277                         reopened again.
1278                         (json-string)
1279
1280 Returns: Nothing on success
1281          If "device" does not exist or cannot be determined, DeviceNotFound
1282
1283 balloon
1284 -------
1285
1286 Request VM to change its memory allocation (in bytes).
1287
1288 Arguments:
1289
1290 - "value": New memory allocation (json-int)
1291
1292 Example:
1293
1294 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1295 <- { "return": {} }
1296
1297 set_link
1298 --------
1299
1300 Change the link status of a network adapter.
1301
1302 Arguments:
1303
1304 - "name": network device name (json-string)
1305 - "up": status is up (json-bool)
1306
1307 Example:
1308
1309 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1310 <- { "return": {} }
1311
1312 getfd
1313 -----
1314
1315 Receive a file descriptor via SCM rights and assign it a name.
1316
1317 Arguments:
1318
1319 - "fdname": file descriptor name (json-string)
1320
1321 Example:
1322
1323 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1324 <- { "return": {} }
1325
1326 Notes:
1327
1328 (1) If the name specified by the "fdname" argument already exists,
1329     the file descriptor assigned to it will be closed and replaced
1330     by the received file descriptor.
1331 (2) The 'closefd' command can be used to explicitly close the file
1332     descriptor when it is no longer needed.
1333
1334 closefd
1335 -------
1336
1337 Close a file descriptor previously passed via SCM rights.
1338
1339 Arguments:
1340
1341 - "fdname": file descriptor name (json-string)
1342
1343 Example:
1344
1345 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1346 <- { "return": {} }
1347
1348 add-fd
1349 -------
1350
1351 Add a file descriptor, that was passed via SCM rights, to an fd set.
1352
1353 Arguments:
1354
1355 - "fdset-id": The ID of the fd set to add the file descriptor to.
1356               (json-int, optional)
1357 - "opaque": A free-form string that can be used to describe the fd.
1358             (json-string, optional)
1359
1360 Return a json-object with the following information:
1361
1362 - "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1363 - "fd": The file descriptor that was received via SCM rights and added to the
1364         fd set. (json-int)
1365
1366 Example:
1367
1368 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1369 <- { "return": { "fdset-id": 1, "fd": 3 } }
1370
1371 Notes:
1372
1373 (1) The list of fd sets is shared by all monitor connections.
1374 (2) If "fdset-id" is not specified, a new fd set will be created.
1375
1376 remove-fd
1377 ---------
1378
1379 Remove a file descriptor from an fd set.
1380
1381 Arguments:
1382
1383 - "fdset-id": The ID of the fd set that the file descriptor belongs to.
1384               (json-int)
1385 - "fd": The file descriptor that is to be removed. (json-int, optional)
1386
1387 Example:
1388
1389 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1390 <- { "return": {} }
1391
1392 Notes:
1393
1394 (1) The list of fd sets is shared by all monitor connections.
1395 (2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1396     removed.
1397
1398 query-fdsets
1399 -------------
1400
1401 Return information describing all fd sets.
1402
1403 Arguments: None
1404
1405 Example:
1406
1407 -> { "execute": "query-fdsets" }
1408 <- { "return": [
1409        {
1410          "fds": [
1411            {
1412              "fd": 30,
1413              "opaque": "rdonly:/path/to/file"
1414            },
1415            {
1416              "fd": 24,
1417              "opaque": "rdwr:/path/to/file"
1418            }
1419          ],
1420          "fdset-id": 1
1421        },
1422        {
1423          "fds": [
1424            {
1425              "fd": 28
1426            },
1427            {
1428              "fd": 29
1429            }
1430          ],
1431          "fdset-id": 0
1432        }
1433      ]
1434    }
1435
1436 Note: The list of fd sets is shared by all monitor connections.
1437
1438 block_passwd
1439 ------------
1440
1441 Set the password of encrypted block devices.
1442
1443 Arguments:
1444
1445 - "device": device name (json-string)
1446 - "node-name": name in the block driver state graph (json-string)
1447 - "password": password (json-string)
1448
1449 Example:
1450
1451 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1452                                                "password": "12345" } }
1453 <- { "return": {} }
1454
1455 block_set_io_throttle
1456 ------------
1457
1458 Change I/O throttle limits for a block drive.
1459
1460 Arguments:
1461
1462 - "device": device name (json-string)
1463 - "bps": total throughput limit in bytes per second (json-int)
1464 - "bps_rd": read throughput limit in bytes per second (json-int)
1465 - "bps_wr": write throughput limit in bytes per second (json-int)
1466 - "iops": total I/O operations per second (json-int)
1467 - "iops_rd": read I/O operations per second (json-int)
1468 - "iops_wr": write I/O operations per second (json-int)
1469 - "bps_max": total throughput limit during bursts, in bytes (json-int, optional)
1470 - "bps_rd_max": read throughput limit during bursts, in bytes (json-int, optional)
1471 - "bps_wr_max": write throughput limit during bursts, in bytes (json-int, optional)
1472 - "iops_max": total I/O operations per second during bursts (json-int, optional)
1473 - "iops_rd_max": read I/O operations per second during bursts (json-int, optional)
1474 - "iops_wr_max": write I/O operations per second during bursts (json-int, optional)
1475 - "bps_max_length": maximum length of the @bps_max burst period, in seconds (json-int, optional)
1476 - "bps_rd_max_length": maximum length of the @bps_rd_max burst period, in seconds (json-int, optional)
1477 - "bps_wr_max_length": maximum length of the @bps_wr_max burst period, in seconds (json-int, optional)
1478 - "iops_max_length": maximum length of the @iops_max burst period, in seconds (json-int, optional)
1479 - "iops_rd_max_length": maximum length of the @iops_rd_max burst period, in seconds (json-int, optional)
1480 - "iops_wr_max_length": maximum length of the @iops_wr_max burst period, in seconds (json-int, optional)
1481 - "iops_size":  I/O size in bytes when limiting (json-int, optional)
1482 - "group": throttle group name (json-string, optional)
1483
1484 Example:
1485
1486 -> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
1487                                                "bps": 1000000,
1488                                                "bps_rd": 0,
1489                                                "bps_wr": 0,
1490                                                "iops": 0,
1491                                                "iops_rd": 0,
1492                                                "iops_wr": 0,
1493                                                "bps_max": 8000000,
1494                                                "bps_rd_max": 0,
1495                                                "bps_wr_max": 0,
1496                                                "iops_max": 0,
1497                                                "iops_rd_max": 0,
1498                                                "iops_wr_max": 0,
1499                                                "bps_max_length": 60,
1500                                                "iops_size": 0 } }
1501 <- { "return": {} }
1502
1503 set_password
1504 ------------
1505
1506 Set the password for vnc/spice protocols.
1507
1508 Arguments:
1509
1510 - "protocol": protocol name (json-string)
1511 - "password": password (json-string)
1512 - "connected": [ keep | disconnect | fail ] (json-string, optional)
1513
1514 Example:
1515
1516 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
1517                                                "password": "secret" } }
1518 <- { "return": {} }
1519
1520 expire_password
1521 ---------------
1522
1523 Set the password expire time for vnc/spice protocols.
1524
1525 Arguments:
1526
1527 - "protocol": protocol name (json-string)
1528 - "time": [ now | never | +secs | secs ] (json-string)
1529
1530 Example:
1531
1532 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
1533                                                   "time": "+60" } }
1534 <- { "return": {} }
1535
1536 add_client
1537 ----------
1538
1539 Add a graphics client
1540
1541 Arguments:
1542
1543 - "protocol": protocol name (json-string)
1544 - "fdname": file descriptor name (json-string)
1545 - "skipauth": whether to skip authentication (json-bool, optional)
1546 - "tls": whether to perform TLS (json-bool, optional)
1547
1548 Example:
1549
1550 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
1551                                              "fdname": "myclient" } }
1552 <- { "return": {} }
1553
1554 qmp_capabilities
1555 ----------------
1556
1557 Enable QMP capabilities.
1558
1559 Arguments: None.
1560
1561 Example:
1562
1563 -> { "execute": "qmp_capabilities" }
1564 <- { "return": {} }
1565
1566 Note: This command must be issued before issuing any other command.
1567
1568 human-monitor-command
1569 ---------------------
1570
1571 Execute a Human Monitor command.
1572
1573 Arguments:
1574
1575 - command-line: the command name and its arguments, just like the
1576                 Human Monitor's shell (json-string)
1577 - cpu-index: select the CPU number to be used by commands which access CPU
1578              data, like 'info registers'. The Monitor selects CPU 0 if this
1579              argument is not provided (json-int, optional)
1580
1581 Example:
1582
1583 -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
1584 <- { "return": "kvm support: enabled\r\n" }
1585
1586 Notes:
1587
1588 (1) The Human Monitor is NOT an stable interface, this means that command
1589     names, arguments and responses can change or be removed at ANY time.
1590     Applications that rely on long term stability guarantees should NOT
1591     use this command
1592
1593 (2) Limitations:
1594
1595     o This command is stateless, this means that commands that depend
1596       on state information (such as getfd) might not work
1597
1598     o Commands that prompt the user for data (eg. 'cont' when the block
1599       device is encrypted) don't currently work
1600
1601 3. Query Commands
1602 =================
1603
1604
1605 query-version
1606 -------------
1607
1608 Show QEMU version.
1609
1610 Return a json-object with the following information:
1611
1612 - "qemu": A json-object containing three integer values:
1613     - "major": QEMU's major version (json-int)
1614     - "minor": QEMU's minor version (json-int)
1615     - "micro": QEMU's micro version (json-int)
1616 - "package": package's version (json-string)
1617
1618 Example:
1619
1620 -> { "execute": "query-version" }
1621 <- {
1622       "return":{
1623          "qemu":{
1624             "major":0,
1625             "minor":11,
1626             "micro":5
1627          },
1628          "package":""
1629       }
1630    }
1631
1632 query-commands
1633 --------------
1634
1635 List QMP available commands.
1636
1637 Each command is represented by a json-object, the returned value is a json-array
1638 of all commands.
1639
1640 Each json-object contain:
1641
1642 - "name": command's name (json-string)
1643
1644 Example:
1645
1646 -> { "execute": "query-commands" }
1647 <- {
1648       "return":[
1649          {
1650             "name":"query-balloon"
1651          },
1652          {
1653             "name":"system_powerdown"
1654          }
1655       ]
1656    }
1657
1658 Note: This example has been shortened as the real response is too long.
1659
1660 query-events
1661 --------------
1662
1663 List QMP available events.
1664
1665 Each event is represented by a json-object, the returned value is a json-array
1666 of all events.
1667
1668 Each json-object contains:
1669
1670 - "name": event's name (json-string)
1671
1672 Example:
1673
1674 -> { "execute": "query-events" }
1675 <- {
1676       "return":[
1677          {
1678             "name":"SHUTDOWN"
1679          },
1680          {
1681             "name":"RESET"
1682          }
1683       ]
1684    }
1685
1686 Note: This example has been shortened as the real response is too long.
1687
1688 query-qmp-schema
1689 ----------------
1690
1691 Return the QMP wire schema.  The returned value is a json-array of
1692 named schema entities.  Entities are commands, events and various
1693 types.  See docs/qapi-code-gen.txt for information on their structure
1694 and intended use.
1695
1696 query-chardev
1697 -------------
1698
1699 Each device is represented by a json-object. The returned value is a json-array
1700 of all devices.
1701
1702 Each json-object contain the following:
1703
1704 - "label": device's label (json-string)
1705 - "filename": device's file (json-string)
1706 - "frontend-open": open/closed state of the frontend device attached to this
1707                    backend (json-bool)
1708
1709 Example:
1710
1711 -> { "execute": "query-chardev" }
1712 <- {
1713       "return": [
1714          {
1715             "label": "charchannel0",
1716             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
1717             "frontend-open": false
1718          },
1719          {
1720             "label": "charmonitor",
1721             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
1722             "frontend-open": true
1723          },
1724          {
1725             "label": "charserial0",
1726             "filename": "pty:/dev/pts/2",
1727             "frontend-open": true
1728          }
1729       ]
1730    }
1731
1732 query-chardev-backends
1733 -------------
1734
1735 List available character device backends.
1736
1737 Each backend is represented by a json-object, the returned value is a json-array
1738 of all backends.
1739
1740 Each json-object contains:
1741
1742 - "name": backend name (json-string)
1743
1744 Example:
1745
1746 -> { "execute": "query-chardev-backends" }
1747 <- {
1748       "return":[
1749          {
1750             "name":"udp"
1751          },
1752          {
1753             "name":"tcp"
1754          },
1755          {
1756             "name":"unix"
1757          },
1758          {
1759             "name":"spiceport"
1760          }
1761       ]
1762    }
1763
1764 query-block
1765 -----------
1766
1767 Show the block devices.
1768
1769 Each block device information is stored in a json-object and the returned value
1770 is a json-array of all devices.
1771
1772 Each json-object contain the following:
1773
1774 - "device": device name (json-string)
1775 - "type": device type (json-string)
1776          - deprecated, retained for backward compatibility
1777          - Possible values: "unknown"
1778 - "removable": true if the device is removable, false otherwise (json-bool)
1779 - "locked": true if the device is locked, false otherwise (json-bool)
1780 - "tray_open": only present if removable, true if the device has a tray,
1781                and it is open (json-bool)
1782 - "inserted": only present if the device is inserted, it is a json-object
1783    containing the following:
1784          - "file": device file name (json-string)
1785          - "ro": true if read-only, false otherwise (json-bool)
1786          - "drv": driver format name (json-string)
1787              - Possible values: "blkdebug", "bochs", "cloop", "dmg",
1788                                 "file", "file", "ftp", "ftps", "host_cdrom",
1789                                 "host_device", "http", "https",
1790                                 "nbd", "parallels", "qcow", "qcow2", "raw",
1791                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1792          - "backing_file": backing file name (json-string, optional)
1793          - "backing_file_depth": number of files in the backing file chain (json-int)
1794          - "encrypted": true if encrypted, false otherwise (json-bool)
1795          - "bps": limit total bytes per second (json-int)
1796          - "bps_rd": limit read bytes per second (json-int)
1797          - "bps_wr": limit write bytes per second (json-int)
1798          - "iops": limit total I/O operations per second (json-int)
1799          - "iops_rd": limit read operations per second (json-int)
1800          - "iops_wr": limit write operations per second (json-int)
1801          - "bps_max":  total max in bytes (json-int)
1802          - "bps_rd_max":  read max in bytes (json-int)
1803          - "bps_wr_max":  write max in bytes (json-int)
1804          - "iops_max":  total I/O operations max (json-int)
1805          - "iops_rd_max":  read I/O operations max (json-int)
1806          - "iops_wr_max":  write I/O operations max (json-int)
1807          - "iops_size": I/O size when limiting by iops (json-int)
1808          - "detect_zeroes": detect and optimize zero writing (json-string)
1809              - Possible values: "off", "on", "unmap"
1810          - "write_threshold": write offset threshold in bytes, a event will be
1811                               emitted if crossed. Zero if disabled (json-int)
1812          - "image": the detail of the image, it is a json-object containing
1813             the following:
1814              - "filename": image file name (json-string)
1815              - "format": image format (json-string)
1816              - "virtual-size": image capacity in bytes (json-int)
1817              - "dirty-flag": true if image is not cleanly closed, not present
1818                              means clean (json-bool, optional)
1819              - "actual-size": actual size on disk in bytes of the image, not
1820                               present when image does not support thin
1821                               provision (json-int, optional)
1822              - "cluster-size": size of a cluster in bytes, not present if image
1823                                format does not support it (json-int, optional)
1824              - "encrypted": true if the image is encrypted, not present means
1825                             false or the image format does not support
1826                             encryption (json-bool, optional)
1827              - "backing_file": backing file name, not present means no backing
1828                                file is used or the image format does not
1829                                support backing file chain
1830                                (json-string, optional)
1831              - "full-backing-filename": full path of the backing file, not
1832                                         present if it equals backing_file or no
1833                                         backing file is used
1834                                         (json-string, optional)
1835              - "backing-filename-format": the format of the backing file, not
1836                                           present means unknown or no backing
1837                                           file (json-string, optional)
1838              - "snapshots": the internal snapshot info, it is an optional list
1839                 of json-object containing the following:
1840                  - "id": unique snapshot id (json-string)
1841                  - "name": snapshot name (json-string)
1842                  - "vm-state-size": size of the VM state in bytes (json-int)
1843                  - "date-sec": UTC date of the snapshot in seconds (json-int)
1844                  - "date-nsec": fractional part in nanoseconds to be used with
1845                                 date-sec (json-int)
1846                  - "vm-clock-sec": VM clock relative to boot in seconds
1847                                    (json-int)
1848                  - "vm-clock-nsec": fractional part in nanoseconds to be used
1849                                     with vm-clock-sec (json-int)
1850              - "backing-image": the detail of the backing image, it is an
1851                                 optional json-object only present when a
1852                                 backing image present for this image
1853
1854 - "io-status": I/O operation status, only present if the device supports it
1855                and the VM is configured to stop on errors. It's always reset
1856                to "ok" when the "cont" command is issued (json_string, optional)
1857              - Possible values: "ok", "failed", "nospace"
1858
1859 Example:
1860
1861 -> { "execute": "query-block" }
1862 <- {
1863       "return":[
1864          {
1865             "io-status": "ok",
1866             "device":"ide0-hd0",
1867             "locked":false,
1868             "removable":false,
1869             "inserted":{
1870                "ro":false,
1871                "drv":"qcow2",
1872                "encrypted":false,
1873                "file":"disks/test.qcow2",
1874                "backing_file_depth":1,
1875                "bps":1000000,
1876                "bps_rd":0,
1877                "bps_wr":0,
1878                "iops":1000000,
1879                "iops_rd":0,
1880                "iops_wr":0,
1881                "bps_max": 8000000,
1882                "bps_rd_max": 0,
1883                "bps_wr_max": 0,
1884                "iops_max": 0,
1885                "iops_rd_max": 0,
1886                "iops_wr_max": 0,
1887                "iops_size": 0,
1888                "detect_zeroes": "on",
1889                "write_threshold": 0,
1890                "image":{
1891                   "filename":"disks/test.qcow2",
1892                   "format":"qcow2",
1893                   "virtual-size":2048000,
1894                   "backing_file":"base.qcow2",
1895                   "full-backing-filename":"disks/base.qcow2",
1896                   "backing-filename-format":"qcow2",
1897                   "snapshots":[
1898                      {
1899                         "id": "1",
1900                         "name": "snapshot1",
1901                         "vm-state-size": 0,
1902                         "date-sec": 10000200,
1903                         "date-nsec": 12,
1904                         "vm-clock-sec": 206,
1905                         "vm-clock-nsec": 30
1906                      }
1907                   ],
1908                   "backing-image":{
1909                       "filename":"disks/base.qcow2",
1910                       "format":"qcow2",
1911                       "virtual-size":2048000
1912                   }
1913                }
1914             },
1915             "type":"unknown"
1916          },
1917          {
1918             "io-status": "ok",
1919             "device":"ide1-cd0",
1920             "locked":false,
1921             "removable":true,
1922             "type":"unknown"
1923          },
1924          {
1925             "device":"floppy0",
1926             "locked":false,
1927             "removable":true,
1928             "type":"unknown"
1929          },
1930          {
1931             "device":"sd0",
1932             "locked":false,
1933             "removable":true,
1934             "type":"unknown"
1935          }
1936       ]
1937    }
1938
1939 query-blockstats
1940 ----------------
1941
1942 Show block device statistics.
1943
1944 Each device statistic information is stored in a json-object and the returned
1945 value is a json-array of all devices.
1946
1947 Each json-object contain the following:
1948
1949 - "device": device name (json-string)
1950 - "stats": A json-object with the statistics information, it contains:
1951     - "rd_bytes": bytes read (json-int)
1952     - "wr_bytes": bytes written (json-int)
1953     - "rd_operations": read operations (json-int)
1954     - "wr_operations": write operations (json-int)
1955     - "flush_operations": cache flush operations (json-int)
1956     - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
1957     - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
1958     - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
1959     - "wr_highest_offset": The offset after the greatest byte written to the
1960                            BlockDriverState since it has been opened (json-int)
1961     - "rd_merged": number of read requests that have been merged into
1962                    another request (json-int)
1963     - "wr_merged": number of write requests that have been merged into
1964                    another request (json-int)
1965     - "idle_time_ns": time since the last I/O operation, in
1966                       nanoseconds. If the field is absent it means
1967                       that there haven't been any operations yet
1968                       (json-int, optional)
1969     - "failed_rd_operations": number of failed read operations
1970                               (json-int)
1971     - "failed_wr_operations": number of failed write operations
1972                               (json-int)
1973     - "failed_flush_operations": number of failed flush operations
1974                                (json-int)
1975     - "invalid_rd_operations": number of invalid read operations
1976                                (json-int)
1977     - "invalid_wr_operations": number of invalid write operations
1978                                (json-int)
1979     - "invalid_flush_operations": number of invalid flush operations
1980                                   (json-int)
1981     - "account_invalid": whether invalid operations are included in
1982                          the last access statistics (json-bool)
1983     - "account_failed": whether failed operations are included in the
1984                          latency and last access statistics
1985                          (json-bool)
1986     - "timed_stats": A json-array containing statistics collected in
1987                      specific intervals, with the following members:
1988         - "interval_length": interval used for calculating the
1989                              statistics, in seconds (json-int)
1990         - "min_rd_latency_ns": minimum latency of read operations in
1991                                the defined interval, in nanoseconds
1992                                (json-int)
1993         - "min_wr_latency_ns": minimum latency of write operations in
1994                                the defined interval, in nanoseconds
1995                                (json-int)
1996         - "min_flush_latency_ns": minimum latency of flush operations
1997                                   in the defined interval, in
1998                                   nanoseconds (json-int)
1999         - "max_rd_latency_ns": maximum latency of read operations in
2000                                the defined interval, in nanoseconds
2001                                (json-int)
2002         - "max_wr_latency_ns": maximum latency of write operations in
2003                                the defined interval, in nanoseconds
2004                                (json-int)
2005         - "max_flush_latency_ns": maximum latency of flush operations
2006                                   in the defined interval, in
2007                                   nanoseconds (json-int)
2008         - "avg_rd_latency_ns": average latency of read operations in
2009                                the defined interval, in nanoseconds
2010                                (json-int)
2011         - "avg_wr_latency_ns": average latency of write operations in
2012                                the defined interval, in nanoseconds
2013                                (json-int)
2014         - "avg_flush_latency_ns": average latency of flush operations
2015                                   in the defined interval, in
2016                                   nanoseconds (json-int)
2017         - "avg_rd_queue_depth": average number of pending read
2018                                 operations in the defined interval
2019                                 (json-number)
2020         - "avg_wr_queue_depth": average number of pending write
2021                                 operations in the defined interval
2022                                 (json-number).
2023 - "parent": Contains recursively the statistics of the underlying
2024             protocol (e.g. the host file for a qcow2 image). If there is
2025             no underlying protocol, this field is omitted
2026             (json-object, optional)
2027
2028 Example:
2029
2030 -> { "execute": "query-blockstats" }
2031 <- {
2032       "return":[
2033          {
2034             "device":"ide0-hd0",
2035             "parent":{
2036                "stats":{
2037                   "wr_highest_offset":3686448128,
2038                   "wr_bytes":9786368,
2039                   "wr_operations":751,
2040                   "rd_bytes":122567168,
2041                   "rd_operations":36772
2042                   "wr_total_times_ns":313253456
2043                   "rd_total_times_ns":3465673657
2044                   "flush_total_times_ns":49653
2045                   "flush_operations":61,
2046                   "rd_merged":0,
2047                   "wr_merged":0,
2048                   "idle_time_ns":2953431879,
2049                   "account_invalid":true,
2050                   "account_failed":false
2051                }
2052             },
2053             "stats":{
2054                "wr_highest_offset":2821110784,
2055                "wr_bytes":9786368,
2056                "wr_operations":692,
2057                "rd_bytes":122739200,
2058                "rd_operations":36604
2059                "flush_operations":51,
2060                "wr_total_times_ns":313253456
2061                "rd_total_times_ns":3465673657
2062                "flush_total_times_ns":49653,
2063                "rd_merged":0,
2064                "wr_merged":0,
2065                "idle_time_ns":2953431879,
2066                "account_invalid":true,
2067                "account_failed":false
2068             }
2069          },
2070          {
2071             "device":"ide1-cd0",
2072             "stats":{
2073                "wr_highest_offset":0,
2074                "wr_bytes":0,
2075                "wr_operations":0,
2076                "rd_bytes":0,
2077                "rd_operations":0
2078                "flush_operations":0,
2079                "wr_total_times_ns":0
2080                "rd_total_times_ns":0
2081                "flush_total_times_ns":0,
2082                "rd_merged":0,
2083                "wr_merged":0,
2084                "account_invalid":false,
2085                "account_failed":false
2086             }
2087          },
2088          {
2089             "device":"floppy0",
2090             "stats":{
2091                "wr_highest_offset":0,
2092                "wr_bytes":0,
2093                "wr_operations":0,
2094                "rd_bytes":0,
2095                "rd_operations":0
2096                "flush_operations":0,
2097                "wr_total_times_ns":0
2098                "rd_total_times_ns":0
2099                "flush_total_times_ns":0,
2100                "rd_merged":0,
2101                "wr_merged":0,
2102                "account_invalid":false,
2103                "account_failed":false
2104             }
2105          },
2106          {
2107             "device":"sd0",
2108             "stats":{
2109                "wr_highest_offset":0,
2110                "wr_bytes":0,
2111                "wr_operations":0,
2112                "rd_bytes":0,
2113                "rd_operations":0
2114                "flush_operations":0,
2115                "wr_total_times_ns":0
2116                "rd_total_times_ns":0
2117                "flush_total_times_ns":0,
2118                "rd_merged":0,
2119                "wr_merged":0,
2120                "account_invalid":false,
2121                "account_failed":false
2122             }
2123          }
2124       ]
2125    }
2126
2127 query-cpus
2128 ----------
2129
2130 Show CPU information.
2131
2132 Return a json-array. Each CPU is represented by a json-object, which contains:
2133
2134 - "CPU": CPU index (json-int)
2135 - "current": true if this is the current CPU, false otherwise (json-bool)
2136 - "halted": true if the cpu is halted, false otherwise (json-bool)
2137 - "qom_path": path to the CPU object in the QOM tree (json-str)
2138 - "arch": architecture of the cpu, which determines what additional
2139           keys will be present (json-str)
2140 - Current program counter. The key's name depends on the architecture:
2141      "pc": i386/x86_64 (json-int)
2142      "nip": PPC (json-int)
2143      "pc" and "npc": sparc (json-int)
2144      "PC": mips (json-int)
2145 - "thread_id": ID of the underlying host thread (json-int)
2146
2147 Example:
2148
2149 -> { "execute": "query-cpus" }
2150 <- {
2151       "return":[
2152          {
2153             "CPU":0,
2154             "current":true,
2155             "halted":false,
2156             "qom_path":"/machine/unattached/device[0]",
2157             "arch":"x86",
2158             "pc":3227107138,
2159             "thread_id":3134
2160          },
2161          {
2162             "CPU":1,
2163             "current":false,
2164             "halted":true,
2165             "qom_path":"/machine/unattached/device[2]",
2166             "arch":"x86",
2167             "pc":7108165,
2168             "thread_id":3135
2169          }
2170       ]
2171    }
2172
2173 query-iothreads
2174 ---------------
2175
2176 Returns a list of information about each iothread.
2177
2178 Note this list excludes the QEMU main loop thread, which is not declared
2179 using the -object iothread command-line option.  It is always the main thread
2180 of the process.
2181
2182 Return a json-array. Each iothread is represented by a json-object, which contains:
2183
2184 - "id": name of iothread (json-str)
2185 - "thread-id": ID of the underlying host thread (json-int)
2186
2187 Example:
2188
2189 -> { "execute": "query-iothreads" }
2190 <- {
2191       "return":[
2192          {
2193             "id":"iothread0",
2194             "thread-id":3134
2195          },
2196          {
2197             "id":"iothread1",
2198             "thread-id":3135
2199          }
2200       ]
2201    }
2202
2203 query-pci
2204 ---------
2205
2206 PCI buses and devices information.
2207
2208 The returned value is a json-array of all buses. Each bus is represented by
2209 a json-object, which has a key with a json-array of all PCI devices attached
2210 to it. Each device is represented by a json-object.
2211
2212 The bus json-object contains the following:
2213
2214 - "bus": bus number (json-int)
2215 - "devices": a json-array of json-objects, each json-object represents a
2216              PCI device
2217
2218 The PCI device json-object contains the following:
2219
2220 - "bus": identical to the parent's bus number (json-int)
2221 - "slot": slot number (json-int)
2222 - "function": function number (json-int)
2223 - "class_info": a json-object containing:
2224      - "desc": device class description (json-string, optional)
2225      - "class": device class number (json-int)
2226 - "id": a json-object containing:
2227      - "device": device ID (json-int)
2228      - "vendor": vendor ID (json-int)
2229 - "irq": device's IRQ if assigned (json-int, optional)
2230 - "qdev_id": qdev id string (json-string)
2231 - "pci_bridge": It's a json-object, only present if this device is a
2232                 PCI bridge, contains:
2233      - "bus": bus number (json-int)
2234      - "secondary": secondary bus number (json-int)
2235      - "subordinate": subordinate bus number (json-int)
2236      - "io_range": I/O memory range information, a json-object with the
2237                    following members:
2238                  - "base": base address, in bytes (json-int)
2239                  - "limit": limit address, in bytes (json-int)
2240      - "memory_range": memory range information, a json-object with the
2241                        following members:
2242                  - "base": base address, in bytes (json-int)
2243                  - "limit": limit address, in bytes (json-int)
2244      - "prefetchable_range": Prefetchable memory range information, a
2245                              json-object with the following members:
2246                  - "base": base address, in bytes (json-int)
2247                  - "limit": limit address, in bytes (json-int)
2248      - "devices": a json-array of PCI devices if there's any attached, each
2249                   each element is represented by a json-object, which contains
2250                   the same members of the 'PCI device json-object' described
2251                   above (optional)
2252 - "regions": a json-array of json-objects, each json-object represents a
2253              memory region of this device
2254
2255 The memory range json-object contains the following:
2256
2257 - "base": base memory address (json-int)
2258 - "limit": limit value (json-int)
2259
2260 The region json-object can be an I/O region or a memory region, an I/O region
2261 json-object contains the following:
2262
2263 - "type": "io" (json-string, fixed)
2264 - "bar": BAR number (json-int)
2265 - "address": memory address (json-int)
2266 - "size": memory size (json-int)
2267
2268 A memory region json-object contains the following:
2269
2270 - "type": "memory" (json-string, fixed)
2271 - "bar": BAR number (json-int)
2272 - "address": memory address (json-int)
2273 - "size": memory size (json-int)
2274 - "mem_type_64": true or false (json-bool)
2275 - "prefetch": true or false (json-bool)
2276
2277 Example:
2278
2279 -> { "execute": "query-pci" }
2280 <- {
2281       "return":[
2282          {
2283             "bus":0,
2284             "devices":[
2285                {
2286                   "bus":0,
2287                   "qdev_id":"",
2288                   "slot":0,
2289                   "class_info":{
2290                      "class":1536,
2291                      "desc":"Host bridge"
2292                   },
2293                   "id":{
2294                      "device":32902,
2295                      "vendor":4663
2296                   },
2297                   "function":0,
2298                   "regions":[
2299
2300                   ]
2301                },
2302                {
2303                   "bus":0,
2304                   "qdev_id":"",
2305                   "slot":1,
2306                   "class_info":{
2307                      "class":1537,
2308                      "desc":"ISA bridge"
2309                   },
2310                   "id":{
2311                      "device":32902,
2312                      "vendor":28672
2313                   },
2314                   "function":0,
2315                   "regions":[
2316
2317                   ]
2318                },
2319                {
2320                   "bus":0,
2321                   "qdev_id":"",
2322                   "slot":1,
2323                   "class_info":{
2324                      "class":257,
2325                      "desc":"IDE controller"
2326                   },
2327                   "id":{
2328                      "device":32902,
2329                      "vendor":28688
2330                   },
2331                   "function":1,
2332                   "regions":[
2333                      {
2334                         "bar":4,
2335                         "size":16,
2336                         "address":49152,
2337                         "type":"io"
2338                      }
2339                   ]
2340                },
2341                {
2342                   "bus":0,
2343                   "qdev_id":"",
2344                   "slot":2,
2345                   "class_info":{
2346                      "class":768,
2347                      "desc":"VGA controller"
2348                   },
2349                   "id":{
2350                      "device":4115,
2351                      "vendor":184
2352                   },
2353                   "function":0,
2354                   "regions":[
2355                      {
2356                         "prefetch":true,
2357                         "mem_type_64":false,
2358                         "bar":0,
2359                         "size":33554432,
2360                         "address":4026531840,
2361                         "type":"memory"
2362                      },
2363                      {
2364                         "prefetch":false,
2365                         "mem_type_64":false,
2366                         "bar":1,
2367                         "size":4096,
2368                         "address":4060086272,
2369                         "type":"memory"
2370                      },
2371                      {
2372                         "prefetch":false,
2373                         "mem_type_64":false,
2374                         "bar":6,
2375                         "size":65536,
2376                         "address":-1,
2377                         "type":"memory"
2378                      }
2379                   ]
2380                },
2381                {
2382                   "bus":0,
2383                   "qdev_id":"",
2384                   "irq":11,
2385                   "slot":4,
2386                   "class_info":{
2387                      "class":1280,
2388                      "desc":"RAM controller"
2389                   },
2390                   "id":{
2391                      "device":6900,
2392                      "vendor":4098
2393                   },
2394                   "function":0,
2395                   "regions":[
2396                      {
2397                         "bar":0,
2398                         "size":32,
2399                         "address":49280,
2400                         "type":"io"
2401                      }
2402                   ]
2403                }
2404             ]
2405          }
2406       ]
2407    }
2408
2409 Note: This example has been shortened as the real response is too long.
2410
2411 query-kvm
2412 ---------
2413
2414 Show KVM information.
2415
2416 Return a json-object with the following information:
2417
2418 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
2419 - "present": true if QEMU has KVM support, false otherwise (json-bool)
2420
2421 Example:
2422
2423 -> { "execute": "query-kvm" }
2424 <- { "return": { "enabled": true, "present": true } }
2425
2426 query-status
2427 ------------
2428
2429 Return a json-object with the following information:
2430
2431 - "running": true if the VM is running, or false if it is paused (json-bool)
2432 - "singlestep": true if the VM is in single step mode,
2433                 false otherwise (json-bool)
2434 - "status": one of the following values (json-string)
2435     "debug" - QEMU is running on a debugger
2436     "inmigrate" - guest is paused waiting for an incoming migration
2437     "internal-error" - An internal error that prevents further guest
2438     execution has occurred
2439     "io-error" - the last IOP has failed and the device is configured
2440     to pause on I/O errors
2441     "paused" - guest has been paused via the 'stop' command
2442     "postmigrate" - guest is paused following a successful 'migrate'
2443     "prelaunch" - QEMU was started with -S and guest has not started
2444     "finish-migrate" - guest is paused to finish the migration process
2445     "restore-vm" - guest is paused to restore VM state
2446     "running" - guest is actively running
2447     "save-vm" - guest is paused to save the VM state
2448     "shutdown" - guest is shut down (and -no-shutdown is in use)
2449     "watchdog" - the watchdog action is configured to pause and
2450      has been triggered
2451
2452 Example:
2453
2454 -> { "execute": "query-status" }
2455 <- { "return": { "running": true, "singlestep": false, "status": "running" } }
2456
2457 query-mice
2458 ----------
2459
2460 Show VM mice information.
2461
2462 Each mouse is represented by a json-object, the returned value is a json-array
2463 of all mice.
2464
2465 The mouse json-object contains the following:
2466
2467 - "name": mouse's name (json-string)
2468 - "index": mouse's index (json-int)
2469 - "current": true if this mouse is receiving events, false otherwise (json-bool)
2470 - "absolute": true if the mouse generates absolute input events (json-bool)
2471
2472 Example:
2473
2474 -> { "execute": "query-mice" }
2475 <- {
2476       "return":[
2477          {
2478             "name":"QEMU Microsoft Mouse",
2479             "index":0,
2480             "current":false,
2481             "absolute":false
2482          },
2483          {
2484             "name":"QEMU PS/2 Mouse",
2485             "index":1,
2486             "current":true,
2487             "absolute":true
2488          }
2489       ]
2490    }
2491
2492 query-vnc
2493 ---------
2494
2495 Show VNC server information.
2496
2497 Return a json-object with server information. Connected clients are returned
2498 as a json-array of json-objects.
2499
2500 The main json-object contains the following:
2501
2502 - "enabled": true or false (json-bool)
2503 - "host": server's IP address (json-string)
2504 - "family": address family (json-string)
2505          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2506 - "service": server's port number (json-string)
2507 - "auth": authentication method (json-string)
2508          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2509                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2510                             "vencrypt+plain", "vencrypt+tls+none",
2511                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
2512                             "vencrypt+tls+vnc", "vencrypt+x509+none",
2513                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
2514                             "vencrypt+x509+vnc", "vnc"
2515 - "clients": a json-array of all connected clients
2516
2517 Clients are described by a json-object, each one contain the following:
2518
2519 - "host": client's IP address (json-string)
2520 - "family": address family (json-string)
2521          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2522 - "service": client's port number (json-string)
2523 - "x509_dname": TLS dname (json-string, optional)
2524 - "sasl_username": SASL username (json-string, optional)
2525
2526 Example:
2527
2528 -> { "execute": "query-vnc" }
2529 <- {
2530       "return":{
2531          "enabled":true,
2532          "host":"0.0.0.0",
2533          "service":"50402",
2534          "auth":"vnc",
2535          "family":"ipv4",
2536          "clients":[
2537             {
2538                "host":"127.0.0.1",
2539                "service":"50401",
2540                "family":"ipv4"
2541             }
2542          ]
2543       }
2544    }
2545
2546 query-spice
2547 -----------
2548
2549 Show SPICE server information.
2550
2551 Return a json-object with server information. Connected clients are returned
2552 as a json-array of json-objects.
2553
2554 The main json-object contains the following:
2555
2556 - "enabled": true or false (json-bool)
2557 - "host": server's IP address (json-string)
2558 - "port": server's port number (json-int, optional)
2559 - "tls-port": server's port number (json-int, optional)
2560 - "auth": authentication method (json-string)
2561          - Possible values: "none", "spice"
2562 - "channels": a json-array of all active channels clients
2563
2564 Channels are described by a json-object, each one contain the following:
2565
2566 - "host": client's IP address (json-string)
2567 - "family": address family (json-string)
2568          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2569 - "port": client's port number (json-string)
2570 - "connection-id": spice connection id.  All channels with the same id
2571                    belong to the same spice session (json-int)
2572 - "channel-type": channel type.  "1" is the main control channel, filter for
2573                   this one if you want track spice sessions only (json-int)
2574 - "channel-id": channel id.  Usually "0", might be different needed when
2575                 multiple channels of the same type exist, such as multiple
2576                 display channels in a multihead setup (json-int)
2577 - "tls": whether the channel is encrypted (json-bool)
2578
2579 Example:
2580
2581 -> { "execute": "query-spice" }
2582 <- {
2583       "return": {
2584          "enabled": true,
2585          "auth": "spice",
2586          "port": 5920,
2587          "tls-port": 5921,
2588          "host": "0.0.0.0",
2589          "channels": [
2590             {
2591                "port": "54924",
2592                "family": "ipv4",
2593                "channel-type": 1,
2594                "connection-id": 1804289383,
2595                "host": "127.0.0.1",
2596                "channel-id": 0,
2597                "tls": true
2598             },
2599             {
2600                "port": "36710",
2601                "family": "ipv4",
2602                "channel-type": 4,
2603                "connection-id": 1804289383,
2604                "host": "127.0.0.1",
2605                "channel-id": 0,
2606                "tls": false
2607             },
2608             [ ... more channels follow ... ]
2609          ]
2610       }
2611    }
2612
2613 query-name
2614 ----------
2615
2616 Show VM name.
2617
2618 Return a json-object with the following information:
2619
2620 - "name": VM's name (json-string, optional)
2621
2622 Example:
2623
2624 -> { "execute": "query-name" }
2625 <- { "return": { "name": "qemu-name" } }
2626
2627 query-uuid
2628 ----------
2629
2630 Show VM UUID.
2631
2632 Return a json-object with the following information:
2633
2634 - "UUID": Universally Unique Identifier (json-string)
2635
2636 Example:
2637
2638 -> { "execute": "query-uuid" }
2639 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2640
2641 query-command-line-options
2642 --------------------------
2643
2644 Show command line option schema.
2645
2646 Return a json-array of command line option schema for all options (or for
2647 the given option), returning an error if the given option doesn't exist.
2648
2649 Each array entry contains the following:
2650
2651 - "option": option name (json-string)
2652 - "parameters": a json-array describes all parameters of the option:
2653     - "name": parameter name (json-string)
2654     - "type": parameter type (one of 'string', 'boolean', 'number',
2655               or 'size')
2656     - "help": human readable description of the parameter
2657               (json-string, optional)
2658     - "default": default value string for the parameter
2659                  (json-string, optional)
2660
2661 Example:
2662
2663 -> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } }
2664 <- { "return": [
2665         {
2666             "parameters": [
2667                 {
2668                     "name": "romfile",
2669                     "type": "string"
2670                 },
2671                 {
2672                     "name": "bootindex",
2673                     "type": "number"
2674                 }
2675             ],
2676             "option": "option-rom"
2677         }
2678      ]
2679    }
2680
2681 query-migrate
2682 -------------
2683
2684 Migration status.
2685
2686 Return a json-object. If migration is active there will be another json-object
2687 with RAM migration status and if block migration is active another one with
2688 block migration status.
2689
2690 The main json-object contains the following:
2691
2692 - "status": migration status (json-string)
2693      - Possible values: "setup", "active", "completed", "failed", "cancelled"
2694 - "total-time": total amount of ms since migration started.  If
2695                 migration has ended, it returns the total migration
2696                 time (json-int)
2697 - "setup-time" amount of setup time in milliseconds _before_ the
2698                iterations begin but _after_ the QMP command is issued.
2699                This is designed to provide an accounting of any activities
2700                (such as RDMA pinning) which may be expensive, but do not
2701                actually occur during the iterative migration rounds
2702                themselves. (json-int)
2703 - "downtime": only present when migration has finished correctly
2704               total amount in ms for downtime that happened (json-int)
2705 - "expected-downtime": only present while migration is active
2706                 total amount in ms for downtime that was calculated on
2707                 the last bitmap round (json-int)
2708 - "ram": only present if "status" is "active", it is a json-object with the
2709   following RAM information:
2710          - "transferred": amount transferred in bytes (json-int)
2711          - "remaining": amount remaining to transfer in bytes (json-int)
2712          - "total": total amount of memory in bytes (json-int)
2713          - "duplicate": number of pages filled entirely with the same
2714             byte (json-int)
2715             These are sent over the wire much more efficiently.
2716          - "skipped": number of skipped zero pages (json-int)
2717          - "normal" : number of whole pages transferred.  I.e. they
2718             were not sent as duplicate or xbzrle pages (json-int)
2719          - "normal-bytes" : number of bytes transferred in whole
2720             pages. This is just normal pages times size of one page,
2721             but this way upper levels don't need to care about page
2722             size (json-int)
2723          - "dirty-sync-count": times that dirty ram was synchronized (json-int)
2724 - "disk": only present if "status" is "active" and it is a block migration,
2725   it is a json-object with the following disk information:
2726          - "transferred": amount transferred in bytes (json-int)
2727          - "remaining": amount remaining to transfer in bytes json-int)
2728          - "total": total disk size in bytes (json-int)
2729 - "xbzrle-cache": only present if XBZRLE is active.
2730   It is a json-object with the following XBZRLE information:
2731          - "cache-size": XBZRLE cache size in bytes
2732          - "bytes": number of bytes transferred for XBZRLE compressed pages
2733          - "pages": number of XBZRLE compressed pages
2734          - "cache-miss": number of XBRZRLE page cache misses
2735          - "cache-miss-rate": rate of XBRZRLE page cache misses
2736          - "overflow": number of times XBZRLE overflows.  This means
2737            that the XBZRLE encoding was bigger than just sent the
2738            whole page, and then we sent the whole page instead (as as
2739            normal page).
2740
2741 Examples:
2742
2743 1. Before the first migration
2744
2745 -> { "execute": "query-migrate" }
2746 <- { "return": {} }
2747
2748 2. Migration is done and has succeeded
2749
2750 -> { "execute": "query-migrate" }
2751 <- { "return": {
2752         "status": "completed",
2753         "ram":{
2754           "transferred":123,
2755           "remaining":123,
2756           "total":246,
2757           "total-time":12345,
2758           "setup-time":12345,
2759           "downtime":12345,
2760           "duplicate":123,
2761           "normal":123,
2762           "normal-bytes":123456,
2763           "dirty-sync-count":15
2764         }
2765      }
2766    }
2767
2768 3. Migration is done and has failed
2769
2770 -> { "execute": "query-migrate" }
2771 <- { "return": { "status": "failed" } }
2772
2773 4. Migration is being performed and is not a block migration:
2774
2775 -> { "execute": "query-migrate" }
2776 <- {
2777       "return":{
2778          "status":"active",
2779          "ram":{
2780             "transferred":123,
2781             "remaining":123,
2782             "total":246,
2783             "total-time":12345,
2784             "setup-time":12345,
2785             "expected-downtime":12345,
2786             "duplicate":123,
2787             "normal":123,
2788             "normal-bytes":123456,
2789             "dirty-sync-count":15
2790          }
2791       }
2792    }
2793
2794 5. Migration is being performed and is a block migration:
2795
2796 -> { "execute": "query-migrate" }
2797 <- {
2798       "return":{
2799          "status":"active",
2800          "ram":{
2801             "total":1057024,
2802             "remaining":1053304,
2803             "transferred":3720,
2804             "total-time":12345,
2805             "setup-time":12345,
2806             "expected-downtime":12345,
2807             "duplicate":123,
2808             "normal":123,
2809             "normal-bytes":123456,
2810             "dirty-sync-count":15
2811          },
2812          "disk":{
2813             "total":20971520,
2814             "remaining":20880384,
2815             "transferred":91136
2816          }
2817       }
2818    }
2819
2820 6. Migration is being performed and XBZRLE is active:
2821
2822 -> { "execute": "query-migrate" }
2823 <- {
2824       "return":{
2825          "status":"active",
2826          "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
2827          "ram":{
2828             "total":1057024,
2829             "remaining":1053304,
2830             "transferred":3720,
2831             "total-time":12345,
2832             "setup-time":12345,
2833             "expected-downtime":12345,
2834             "duplicate":10,
2835             "normal":3333,
2836             "normal-bytes":3412992,
2837             "dirty-sync-count":15
2838          },
2839          "xbzrle-cache":{
2840             "cache-size":67108864,
2841             "bytes":20971520,
2842             "pages":2444343,
2843             "cache-miss":2244,
2844             "cache-miss-rate":0.123,
2845             "overflow":34434
2846          }
2847       }
2848    }
2849
2850 migrate-set-capabilities
2851 ------------------------
2852
2853 Enable/Disable migration capabilities
2854
2855 - "xbzrle": XBZRLE support
2856 - "rdma-pin-all": pin all pages when using RDMA during migration
2857 - "auto-converge": throttle down guest to help convergence of migration
2858 - "zero-blocks": compress zero blocks during block migration
2859 - "compress": use multiple compression threads to accelerate live migration
2860 - "events": generate events for each migration state change
2861 - "postcopy-ram": postcopy mode for live migration
2862
2863 Arguments:
2864
2865 Example:
2866
2867 -> { "execute": "migrate-set-capabilities" , "arguments":
2868      { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
2869
2870 query-migrate-capabilities
2871 --------------------------
2872
2873 Query current migration capabilities
2874
2875 - "capabilities": migration capabilities state
2876          - "xbzrle" : XBZRLE state (json-bool)
2877          - "rdma-pin-all" : RDMA Pin Page state (json-bool)
2878          - "auto-converge" : Auto Converge state (json-bool)
2879          - "zero-blocks" : Zero Blocks state (json-bool)
2880          - "compress": Multiple compression threads state (json-bool)
2881          - "events": Migration state change event state (json-bool)
2882          - "postcopy-ram": postcopy ram state (json-bool)
2883
2884 Arguments:
2885
2886 Example:
2887
2888 -> { "execute": "query-migrate-capabilities" }
2889 <- {"return": [
2890      {"state": false, "capability": "xbzrle"},
2891      {"state": false, "capability": "rdma-pin-all"},
2892      {"state": false, "capability": "auto-converge"},
2893      {"state": false, "capability": "zero-blocks"},
2894      {"state": false, "capability": "compress"},
2895      {"state": true, "capability": "events"},
2896      {"state": false, "capability": "postcopy-ram"}
2897    ]}
2898
2899 migrate-set-parameters
2900 ----------------------
2901
2902 Set migration parameters
2903
2904 - "compress-level": set compression level during migration (json-int)
2905 - "compress-threads": set compression thread count for migration (json-int)
2906 - "decompress-threads": set decompression thread count for migration (json-int)
2907 - "cpu-throttle-initial": set initial percentage of time guest cpus are
2908                           throttled for auto-converge (json-int)
2909 - "cpu-throttle-increment": set throttle increasing percentage for
2910                             auto-converge (json-int)
2911
2912 Arguments:
2913
2914 Example:
2915
2916 -> { "execute": "migrate-set-parameters" , "arguments":
2917       { "compress-level": 1 } }
2918
2919 query-migrate-parameters
2920 ------------------------
2921
2922 Query current migration parameters
2923
2924 - "parameters": migration parameters value
2925          - "compress-level" : compression level value (json-int)
2926          - "compress-threads" : compression thread count value (json-int)
2927          - "decompress-threads" : decompression thread count value (json-int)
2928          - "cpu-throttle-initial" : initial percentage of time guest cpus are
2929                                     throttled (json-int)
2930          - "cpu-throttle-increment" : throttle increasing percentage for
2931                                       auto-converge (json-int)
2932
2933 Arguments:
2934
2935 Example:
2936
2937 -> { "execute": "query-migrate-parameters" }
2938 <- {
2939       "return": {
2940          "decompress-threads": 2,
2941          "cpu-throttle-increment": 10,
2942          "compress-threads": 8,
2943          "compress-level": 1,
2944          "cpu-throttle-initial": 20
2945       }
2946    }
2947
2948 query-balloon
2949 -------------
2950
2951 Show balloon information.
2952
2953 Make an asynchronous request for balloon info. When the request completes a
2954 json-object will be returned containing the following data:
2955
2956 - "actual": current balloon value in bytes (json-int)
2957
2958 Example:
2959
2960 -> { "execute": "query-balloon" }
2961 <- {
2962       "return":{
2963          "actual":1073741824,
2964       }
2965    }
2966
2967 query-tpm
2968 ---------
2969
2970 Return information about the TPM device.
2971
2972 Arguments: None
2973
2974 Example:
2975
2976 -> { "execute": "query-tpm" }
2977 <- { "return":
2978      [
2979        { "model": "tpm-tis",
2980          "options":
2981            { "type": "passthrough",
2982              "data":
2983                { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
2984                  "path": "/dev/tpm0"
2985                }
2986            },
2987          "id": "tpm0"
2988        }
2989      ]
2990    }
2991
2992 query-tpm-models
2993 ----------------
2994
2995 Return a list of supported TPM models.
2996
2997 Arguments: None
2998
2999 Example:
3000
3001 -> { "execute": "query-tpm-models" }
3002 <- { "return": [ "tpm-tis" ] }
3003
3004 query-tpm-types
3005 ---------------
3006
3007 Return a list of supported TPM types.
3008
3009 Arguments: None
3010
3011 Example:
3012
3013 -> { "execute": "query-tpm-types" }
3014 <- { "return": [ "passthrough" ] }
3015
3016 chardev-add
3017 ----------------
3018
3019 Add a chardev.
3020
3021 Arguments:
3022
3023 - "id": the chardev's ID, must be unique (json-string)
3024 - "backend": chardev backend type + parameters
3025
3026 Examples:
3027
3028 -> { "execute" : "chardev-add",
3029      "arguments" : { "id" : "foo",
3030                      "backend" : { "type" : "null", "data" : {} } } }
3031 <- { "return": {} }
3032
3033 -> { "execute" : "chardev-add",
3034      "arguments" : { "id" : "bar",
3035                      "backend" : { "type" : "file",
3036                                    "data" : { "out" : "/tmp/bar.log" } } } }
3037 <- { "return": {} }
3038
3039 -> { "execute" : "chardev-add",
3040      "arguments" : { "id" : "baz",
3041                      "backend" : { "type" : "pty", "data" : {} } } }
3042 <- { "return": { "pty" : "/dev/pty/42" } }
3043
3044 chardev-remove
3045 --------------
3046
3047 Remove a chardev.
3048
3049 Arguments:
3050
3051 - "id": the chardev's ID, must exist and not be in use (json-string)
3052
3053 Example:
3054
3055 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
3056 <- { "return": {} }
3057
3058 query-rx-filter
3059 ---------------
3060
3061 Show rx-filter information.
3062
3063 Returns a json-array of rx-filter information for all NICs (or for the
3064 given NIC), returning an error if the given NIC doesn't exist, or
3065 given NIC doesn't support rx-filter querying, or given net client
3066 isn't a NIC.
3067
3068 The query will clear the event notification flag of each NIC, then qemu
3069 will start to emit event to QMP monitor.
3070
3071 Each array entry contains the following:
3072
3073 - "name": net client name (json-string)
3074 - "promiscuous": promiscuous mode is enabled (json-bool)
3075 - "multicast": multicast receive state (one of 'normal', 'none', 'all')
3076 - "unicast": unicast receive state  (one of 'normal', 'none', 'all')
3077 - "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0)
3078 - "broadcast-allowed": allow to receive broadcast (json-bool)
3079 - "multicast-overflow": multicast table is overflowed (json-bool)
3080 - "unicast-overflow": unicast table is overflowed (json-bool)
3081 - "main-mac": main macaddr string (json-string)
3082 - "vlan-table": a json-array of active vlan id
3083 - "unicast-table": a json-array of unicast macaddr string
3084 - "multicast-table": a json-array of multicast macaddr string
3085
3086 Example:
3087
3088 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
3089 <- { "return": [
3090         {
3091             "promiscuous": true,
3092             "name": "vnet0",
3093             "main-mac": "52:54:00:12:34:56",
3094             "unicast": "normal",
3095             "vlan": "normal",
3096             "vlan-table": [
3097                 4,
3098                 0
3099             ],
3100             "unicast-table": [
3101             ],
3102             "multicast": "normal",
3103             "multicast-overflow": false,
3104             "unicast-overflow": false,
3105             "multicast-table": [
3106                 "01:00:5e:00:00:01",
3107                 "33:33:00:00:00:01",
3108                 "33:33:ff:12:34:56"
3109             ],
3110             "broadcast-allowed": false
3111         }
3112       ]
3113    }
3114
3115 blockdev-add
3116 ------------
3117
3118 Add a block device.
3119
3120 This command is still a work in progress.  It doesn't support all
3121 block drivers among other things.  Stay away from it unless you want
3122 to help with its development.
3123
3124 Arguments:
3125
3126 - "options": block driver options
3127
3128 Example (1):
3129
3130 -> { "execute": "blockdev-add",
3131     "arguments": { "options" : { "driver": "qcow2",
3132                                  "file": { "driver": "file",
3133                                            "filename": "test.qcow2" } } } }
3134 <- { "return": {} }
3135
3136 Example (2):
3137
3138 -> { "execute": "blockdev-add",
3139      "arguments": {
3140          "options": {
3141            "driver": "qcow2",
3142            "id": "my_disk",
3143            "discard": "unmap",
3144            "cache": {
3145                "direct": true,
3146                "writeback": true
3147            },
3148            "file": {
3149                "driver": "file",
3150                "filename": "/tmp/test.qcow2"
3151            },
3152            "backing": {
3153                "driver": "raw",
3154                "file": {
3155                    "driver": "file",
3156                    "filename": "/dev/fdset/4"
3157                }
3158            }
3159          }
3160        }
3161      }
3162
3163 <- { "return": {} }
3164
3165 x-blockdev-del
3166 ------------
3167 Since 2.5
3168
3169 Deletes a block device thas has been added using blockdev-add.
3170 The selected device can be either a block backend or a graph node.
3171
3172 In the former case the backend will be destroyed, along with its
3173 inserted medium if there's any. The command will fail if the backend
3174 or its medium are in use.
3175
3176 In the latter case the node will be destroyed. The command will fail
3177 if the node is attached to a block backend or is otherwise being
3178 used.
3179
3180 One of "id" or "node-name" must be specified, but not both.
3181
3182 This command is still a work in progress and is considered
3183 experimental. Stay away from it unless you want to help with its
3184 development.
3185
3186 Arguments:
3187
3188 - "id": Name of the block backend device to delete (json-string, optional)
3189 - "node-name": Name of the graph node to delete (json-string, optional)
3190
3191 Example:
3192
3193 -> { "execute": "blockdev-add",
3194      "arguments": {
3195          "options": {
3196              "driver": "qcow2",
3197              "id": "drive0",
3198              "file": {
3199                  "driver": "file",
3200                  "filename": "test.qcow2"
3201              }
3202          }
3203      }
3204    }
3205
3206 <- { "return": {} }
3207
3208 -> { "execute": "x-blockdev-del",
3209      "arguments": { "id": "drive0" }
3210    }
3211 <- { "return": {} }
3212
3213 blockdev-open-tray
3214 ------------------
3215
3216 Opens a block device's tray. If there is a block driver state tree inserted as a
3217 medium, it will become inaccessible to the guest (but it will remain associated
3218 to the block device, so closing the tray will make it accessible again).
3219
3220 If the tray was already open before, this will be a no-op.
3221
3222 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
3223 which no such event will be generated, these include:
3224 - if the guest has locked the tray, @force is false and the guest does not
3225   respond to the eject request
3226 - if the BlockBackend denoted by @device does not have a guest device attached
3227   to it
3228 - if the guest device does not have an actual tray and is empty, for instance
3229   for floppy disk drives
3230
3231 Arguments:
3232
3233 - "device": block device name (deprecated, use @id instead)
3234             (json-string, optional)
3235 - "id": the name or QOM path of the guest device (json-string, optional)
3236 - "force": if false (the default), an eject request will be sent to the guest if
3237            it has locked the tray (and the tray will not be opened immediately);
3238            if true, the tray will be opened regardless of whether it is locked
3239            (json-bool, optional)
3240
3241 Example:
3242
3243 -> { "execute": "blockdev-open-tray",
3244      "arguments": { "id": "ide0-1-0" } }
3245
3246 <- { "timestamp": { "seconds": 1418751016,
3247                     "microseconds": 716996 },
3248      "event": "DEVICE_TRAY_MOVED",
3249      "data": { "device": "ide1-cd0",
3250                "tray-open": true } }
3251
3252 <- { "return": {} }
3253
3254 blockdev-close-tray
3255 -------------------
3256
3257 Closes a block device's tray. If there is a block driver state tree associated
3258 with the block device (which is currently ejected), that tree will be loaded as
3259 the medium.
3260
3261 If the tray was already closed before, this will be a no-op.
3262
3263 Arguments:
3264
3265 - "device": block device name (deprecated, use @id instead)
3266             (json-string, optional)
3267 - "id": the name or QOM path of the guest device (json-string, optional)
3268
3269 Example:
3270
3271 -> { "execute": "blockdev-close-tray",
3272      "arguments": { "id": "ide0-1-0" } }
3273
3274 <- { "timestamp": { "seconds": 1418751345,
3275                     "microseconds": 272147 },
3276      "event": "DEVICE_TRAY_MOVED",
3277      "data": { "device": "ide1-cd0",
3278                "tray-open": false } }
3279
3280 <- { "return": {} }
3281
3282 x-blockdev-remove-medium
3283 ------------------------
3284
3285 Removes a medium (a block driver state tree) from a block device. That block
3286 device's tray must currently be open (unless there is no attached guest device).
3287
3288 If the tray is open and there is no medium inserted, this will be a no-op.
3289
3290 This command is still a work in progress and is considered experimental.
3291 Stay away from it unless you want to help with its development.
3292
3293 Arguments:
3294
3295 - "device": block device name (deprecated, use @id instead)
3296             (json-string, optional)
3297 - "id": the name or QOM path of the guest device (json-string, optional)
3298
3299 Example:
3300
3301 -> { "execute": "x-blockdev-remove-medium",
3302      "arguments": { "id": "ide0-1-0" } }
3303
3304 <- { "error": { "class": "GenericError",
3305                 "desc": "Tray of device 'ide0-1-0' is not open" } }
3306
3307 -> { "execute": "blockdev-open-tray",
3308      "arguments": { "id": "ide0-1-0" } }
3309
3310 <- { "timestamp": { "seconds": 1418751627,
3311                     "microseconds": 549958 },
3312      "event": "DEVICE_TRAY_MOVED",
3313      "data": { "device": "ide1-cd0",
3314                "tray-open": true } }
3315
3316 <- { "return": {} }
3317
3318 -> { "execute": "x-blockdev-remove-medium",
3319      "arguments": { "device": "ide0-1-0" } }
3320
3321 <- { "return": {} }
3322
3323 x-blockdev-insert-medium
3324 ------------------------
3325
3326 Inserts a medium (a block driver state tree) into a block device. That block
3327 device's tray must currently be open (unless there is no attached guest device)
3328 and there must be no medium inserted already.
3329
3330 This command is still a work in progress and is considered experimental.
3331 Stay away from it unless you want to help with its development.
3332
3333 Arguments:
3334
3335 - "device": block device name (deprecated, use @id instead)
3336             (json-string, optional)
3337 - "id": the name or QOM path of the guest device (json-string, optional)
3338 - "node-name": root node of the BDS tree to insert into the block device
3339
3340 Example:
3341
3342 -> { "execute": "blockdev-add",
3343      "arguments": { "options": { "node-name": "node0",
3344                                  "driver": "raw",
3345                                  "file": { "driver": "file",
3346                                            "filename": "fedora.iso" } } } }
3347
3348 <- { "return": {} }
3349
3350 -> { "execute": "x-blockdev-insert-medium",
3351      "arguments": { "id": "ide0-1-0",
3352                     "node-name": "node0" } }
3353
3354 <- { "return": {} }
3355
3356 x-blockdev-change
3357 -----------------
3358
3359 Dynamically reconfigure the block driver state graph. It can be used
3360 to add, remove, insert or replace a graph node. Currently only the
3361 Quorum driver implements this feature to add or remove its child. This
3362 is useful to fix a broken quorum child.
3363
3364 If @node is specified, it will be inserted under @parent. @child
3365 may not be specified in this case. If both @parent and @child are
3366 specified but @node is not, @child will be detached from @parent.
3367
3368 Arguments:
3369 - "parent": the id or name of the parent node (json-string)
3370 - "child": the name of a child under the given parent node (json-string, optional)
3371 - "node": the name of the node that will be added (json-string, optional)
3372
3373 Note: this command is experimental, and not a stable API. It doesn't
3374 support all kinds of operations, all kinds of children, nor all block
3375 drivers.
3376
3377 Warning: The data in a new quorum child MUST be consistent with that of
3378 the rest of the array.
3379
3380 Example:
3381
3382 Add a new node to a quorum
3383 -> { "execute": "blockdev-add",
3384      "arguments": { "options": { "driver": "raw",
3385                                  "node-name": "new_node",
3386                                  "file": { "driver": "file",
3387                                            "filename": "test.raw" } } } }
3388 <- { "return": {} }
3389 -> { "execute": "x-blockdev-change",
3390      "arguments": { "parent": "disk1",
3391                     "node": "new_node" } }
3392 <- { "return": {} }
3393
3394 Delete a quorum's node
3395 -> { "execute": "x-blockdev-change",
3396      "arguments": { "parent": "disk1",
3397                     "child": "children.1" } }
3398 <- { "return": {} }
3399
3400 query-named-block-nodes
3401 -----------------------
3402
3403 Return a list of BlockDeviceInfo for all the named block driver nodes
3404
3405 Example:
3406
3407 -> { "execute": "query-named-block-nodes" }
3408 <- { "return": [ { "ro":false,
3409                    "drv":"qcow2",
3410                    "encrypted":false,
3411                    "file":"disks/test.qcow2",
3412                    "node-name": "my-node",
3413                    "backing_file_depth":1,
3414                    "bps":1000000,
3415                    "bps_rd":0,
3416                    "bps_wr":0,
3417                    "iops":1000000,
3418                    "iops_rd":0,
3419                    "iops_wr":0,
3420                    "bps_max": 8000000,
3421                    "bps_rd_max": 0,
3422                    "bps_wr_max": 0,
3423                    "iops_max": 0,
3424                    "iops_rd_max": 0,
3425                    "iops_wr_max": 0,
3426                    "iops_size": 0,
3427                    "write_threshold": 0,
3428                    "image":{
3429                       "filename":"disks/test.qcow2",
3430                       "format":"qcow2",
3431                       "virtual-size":2048000,
3432                       "backing_file":"base.qcow2",
3433                       "full-backing-filename":"disks/base.qcow2",
3434                       "backing-filename-format":"qcow2",
3435                       "snapshots":[
3436                          {
3437                             "id": "1",
3438                             "name": "snapshot1",
3439                             "vm-state-size": 0,
3440                             "date-sec": 10000200,
3441                             "date-nsec": 12,
3442                             "vm-clock-sec": 206,
3443                             "vm-clock-nsec": 30
3444                          }
3445                       ],
3446                       "backing-image":{
3447                           "filename":"disks/base.qcow2",
3448                           "format":"qcow2",
3449                           "virtual-size":2048000
3450                       }
3451                    } } ] }
3452
3453 blockdev-change-medium
3454 ----------------------
3455
3456 Changes the medium inserted into a block device by ejecting the current medium
3457 and loading a new image file which is inserted as the new medium.
3458
3459 Arguments:
3460
3461 - "device": block device name (deprecated, use @id instead)
3462             (json-string, optional)
3463 - "id": the name or QOM path of the guest device (json-string, optional)
3464 - "filename": filename of the new image (json-string)
3465 - "format": format of the new image (json-string, optional)
3466 - "read-only-mode": new read-only mode (json-string, optional)
3467           - Possible values: "retain" (default), "read-only", "read-write"
3468
3469 Examples:
3470
3471 1. Change a removable medium
3472
3473 -> { "execute": "blockdev-change-medium",
3474              "arguments": { "id": "ide0-1-0",
3475                             "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
3476                             "format": "raw" } }
3477 <- { "return": {} }
3478
3479 2. Load a read-only medium into a writable drive
3480
3481 -> { "execute": "blockdev-change-medium",
3482              "arguments": { "id": "floppyA",
3483                             "filename": "/srv/images/ro.img",
3484                             "format": "raw",
3485                             "read-only-mode": "retain" } }
3486
3487 <- { "error":
3488      { "class": "GenericError",
3489        "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
3490
3491 -> { "execute": "blockdev-change-medium",
3492              "arguments": { "id": "floppyA",
3493                             "filename": "/srv/images/ro.img",
3494                             "format": "raw",
3495                             "read-only-mode": "read-only" } }
3496
3497 <- { "return": {} }
3498
3499 query-memdev
3500 ------------
3501
3502 Show memory devices information.
3503
3504
3505 Example (1):
3506
3507 -> { "execute": "query-memdev" }
3508 <- { "return": [
3509        {
3510          "size": 536870912,
3511          "merge": false,
3512          "dump": true,
3513          "prealloc": false,
3514          "host-nodes": [0, 1],
3515          "policy": "bind"
3516        },
3517        {
3518          "size": 536870912,
3519          "merge": false,
3520          "dump": true,
3521          "prealloc": true,
3522          "host-nodes": [2, 3],
3523          "policy": "preferred"
3524        }
3525      ]
3526    }
3527
3528 query-memory-devices
3529 --------------------
3530
3531 Return a list of memory devices.
3532
3533 Example:
3534 -> { "execute": "query-memory-devices" }
3535 <- { "return": [ { "data":
3536                       { "addr": 5368709120,
3537                         "hotpluggable": true,
3538                         "hotplugged": true,
3539                         "id": "d1",
3540                         "memdev": "/objects/memX",
3541                         "node": 0,
3542                         "size": 1073741824,
3543                         "slot": 0},
3544                    "type": "dimm"
3545                  } ] }
3546
3547 query-acpi-ospm-status
3548 ----------------------
3549
3550 Return list of ACPIOSTInfo for devices that support status reporting
3551 via ACPI _OST method.
3552
3553 Example:
3554 -> { "execute": "query-acpi-ospm-status" }
3555 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
3556                  { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
3557                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
3558                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
3559    ]}
3560
3561 rtc-reset-reinjection
3562 ---------------------
3563
3564 Reset the RTC interrupt reinjection backlog.
3565
3566 Arguments: None.
3567
3568 Example:
3569
3570 -> { "execute": "rtc-reset-reinjection" }
3571 <- { "return": {} }
3572
3573 trace-event-get-state
3574 ---------------------
3575
3576 Query the state of events.
3577
3578 Arguments:
3579
3580 - "name": Event name pattern (json-string).
3581 - "vcpu": The vCPU to query, any vCPU by default (json-int, optional).
3582
3583 An event is returned if:
3584 - its name matches the "name" pattern, and
3585 - if "vcpu" is given, the event has the "vcpu" property.
3586
3587 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
3588 returning their state on the specified vCPU. Special case: if "name" is an exact
3589 match, "vcpu" is given and the event does not have the "vcpu" property, an error
3590 is returned.
3591
3592 Example:
3593
3594 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
3595 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
3596
3597 trace-event-set-state
3598 ---------------------
3599
3600 Set the state of events.
3601
3602 Arguments:
3603
3604 - "name": Event name pattern (json-string).
3605 - "enable": Whether to enable or disable the event (json-bool).
3606 - "ignore-unavailable": Whether to ignore errors for events that cannot be
3607   changed (json-bool, optional).
3608 - "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional).
3609
3610 An event's state is modified if:
3611 - its name matches the "name" pattern, and
3612 - if "vcpu" is given, the event has the "vcpu" property.
3613
3614 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
3615 setting their state on the specified vCPU. Special case: if "name" is an exact
3616 match, "vcpu" is given and the event does not have the "vcpu" property, an error
3617 is returned.
3618
3619 Example:
3620
3621 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
3622 <- { "return": {} }
3623
3624 input-send-event
3625 ----------------
3626
3627 Send input event to guest.
3628
3629 Arguments:
3630
3631 - "device": display device (json-string, optional)
3632 - "head": display head (json-int, optional)
3633 - "events": list of input events
3634
3635 The consoles are visible in the qom tree, under
3636 /backend/console[$index]. They have a device link and head property, so
3637 it is possible to map which console belongs to which device and display.
3638
3639 Example (1):
3640
3641 Press left mouse button.
3642
3643 -> { "execute": "input-send-event",
3644     "arguments": { "device": "video0",
3645                    "events": [ { "type": "btn",
3646                    "data" : { "down": true, "button": "left" } } ] } }
3647 <- { "return": {} }
3648
3649 -> { "execute": "input-send-event",
3650     "arguments": { "device": "video0",
3651                    "events": [ { "type": "btn",
3652                    "data" : { "down": false, "button": "left" } } ] } }
3653 <- { "return": {} }
3654
3655 Example (2):
3656
3657 Press ctrl-alt-del.
3658
3659 -> { "execute": "input-send-event",
3660      "arguments": { "events": [
3661         { "type": "key", "data" : { "down": true,
3662           "key": {"type": "qcode", "data": "ctrl" } } },
3663         { "type": "key", "data" : { "down": true,
3664           "key": {"type": "qcode", "data": "alt" } } },
3665         { "type": "key", "data" : { "down": true,
3666           "key": {"type": "qcode", "data": "delete" } } } ] } }
3667 <- { "return": {} }
3668
3669 Example (3):
3670
3671 Move mouse pointer to absolute coordinates (20000, 400).
3672
3673 -> { "execute": "input-send-event" ,
3674   "arguments": { "events": [
3675                { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
3676                { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
3677 <- { "return": {} }
3678
3679 block-set-write-threshold
3680 ------------
3681
3682 Change the write threshold for a block drive. The threshold is an offset,
3683 thus must be non-negative. Default is no write threshold.
3684 Setting the threshold to zero disables it.
3685
3686 Arguments:
3687
3688 - "node-name": the node name in the block driver state graph (json-string)
3689 - "write-threshold": the write threshold in bytes (json-int)
3690
3691 Example:
3692
3693 -> { "execute": "block-set-write-threshold",
3694   "arguments": { "node-name": "mydev",
3695                  "write-threshold": 17179869184 } }
3696 <- { "return": {} }
3697
3698 Show rocker switch
3699 ------------------
3700
3701 Arguments:
3702
3703 - "name": switch name
3704
3705 Example:
3706
3707 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
3708 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
3709
3710 Show rocker switch ports
3711 ------------------------
3712
3713 Arguments:
3714
3715 - "name": switch name
3716
3717 Example:
3718
3719 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
3720 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
3721                   "autoneg": "off", "link-up": true, "speed": 10000},
3722                  {"duplex": "full", "enabled": true, "name": "sw1.2",
3723                   "autoneg": "off", "link-up": true, "speed": 10000}
3724    ]}
3725
3726 Show rocker switch OF-DPA flow tables
3727 -------------------------------------
3728
3729 Arguments:
3730
3731 - "name": switch name
3732 - "tbl-id": (optional) flow table ID
3733
3734 Example:
3735
3736 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
3737 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
3738                   "hits": 138,
3739                   "cookie": 0,
3740                   "action": {"goto-tbl": 10},
3741                   "mask": {"in-pport": 4294901760}
3742                  },
3743                  {...more...},
3744    ]}
3745
3746 Show rocker OF-DPA group tables
3747 -------------------------------
3748
3749 Arguments:
3750
3751 - "name": switch name
3752 - "type": (optional) group type
3753
3754 Example:
3755
3756 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
3757 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
3758                   "pop-vlan": 1, "id": 251723778},
3759                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
3760                   "pop-vlan": 1, "id": 251723776},
3761                  {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
3762                   "pop-vlan": 1, "id": 251658241},
3763                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
3764                   "pop-vlan": 1, "id": 251658240}
3765    ]}
3766
3767 query-gic-capabilities
3768 ---------------
3769
3770 Return a list of GICCapability objects, describing supported GIC
3771 (Generic Interrupt Controller) versions.
3772
3773 Arguments: None
3774
3775 Example:
3776
3777 -> { "execute": "query-gic-capabilities" }
3778 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
3779                 { "version": 3, "emulated": false, "kernel": true } ] }
3780
3781 Show existing/possible CPUs
3782 ---------------------------
3783
3784 Arguments: None.
3785
3786 Example for pseries machine type started with
3787 -smp 2,cores=2,maxcpus=4 -cpu POWER8:
3788
3789 -> { "execute": "query-hotpluggable-cpus" }
3790 <- {"return": [
3791      { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
3792        "vcpus-count": 1 },
3793      { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
3794        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
3795    ]}'
3796
3797 Example for pc machine type started with
3798 -smp 1,maxcpus=2:
3799     -> { "execute": "query-hotpluggable-cpus" }
3800     <- {"return": [
3801          {
3802             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
3803             "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
3804          },
3805          {
3806             "qom-path": "/machine/unattached/device[0]",
3807             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
3808             "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
3809          }
3810        ]}