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 (docs/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 eject
  57 -----
  58
  59 Eject a removable medium.
  60
  61 Arguments:
  62
  63 - "force": force ejection (json-bool, optional)
  64 - "device": block device name (deprecated, use @id instead)
  65             (json-string, optional)
  66 - "id": the name or QOM path of the guest device (json-string, optional)
  67
  68 Example:
  69
  70 -> { "execute": "eject", "arguments": { "id": "ide0-1-0" } }
  71 <- { "return": {} }
  72
  73 Note: The "force" argument defaults to false.
  74
  75 change
  76 ------
  77
  78 Change a removable medium or VNC configuration.
  79
  80 Arguments:
  81
  82 - "device": device name (json-string)
  83 - "target": filename or item (json-string)
  84 - "arg": additional argument (json-string, optional)
  85
  86 Examples:
  87
  88 1. Change a removable medium
  89
  90 -> { "execute": "change",
  91              "arguments": { "device": "ide1-cd0",
  92                             "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
  93 <- { "return": {} }
  94
  95 2. Change VNC password
  96
  97 -> { "execute": "change",
  98              "arguments": { "device": "vnc", "target": "password",
  99                             "arg": "foobar1" } }
 100 <- { "return": {} }
 101
 102 screendump
 103 ----------
 104
 105 Save screen into PPM image.
 106
 107 Arguments:
 108
 109 - "filename": file path (json-string)
 110
 111 Example:
 112
 113 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 114 <- { "return": {} }
 115
 116 device_add
 117 ----------
 118
 119 Add a device.
 120
 121 Arguments:
 122
 123 - "driver": the name of the new device's driver (json-string)
 124 - "bus": the device's parent bus (device tree path, json-string, optional)
 125 - "id": the device's ID, must be unique (json-string)
 126 - device properties
 127
 128 Example:
 129
 130 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
 131 <- { "return": {} }
 132
 133 Notes:
 134
 135 (1) For detailed information about this command, please refer to the
 136     'docs/qdev-device-use.txt' file.
 137
 138 (2) It's possible to list device properties by running QEMU with the
 139     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
 140
 141 device_del
 142 ----------
 143
 144 Remove a device.
 145
 146 Arguments:
 147
 148 - "id": the device's ID or QOM path (json-string)
 149
 150 Example:
 151
 152 -> { "execute": "device_del", "arguments": { "id": "net1" } }
 153 <- { "return": {} }
 154
 155 Example:
 156
 157 -> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
 158 <- { "return": {} }
 159
 160 send-key
 161 ----------
 162
 163 Send keys to VM.
 164
 165 Arguments:
 166
 167 keys array:
 168     - "key": key sequence (a json-array of key union values,
 169              union can be number or qcode enum)
 170
 171 - hold-time: time to delay key up events, milliseconds. Defaults to 100
 172              (json-int, optional)
 173
 174 Example:
 175
 176 -> { "execute": "send-key",
 177      "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
 178                               { "type": "qcode", "data": "alt" },
 179                               { "type": "qcode", "data": "delete" } ] } }
 180 <- { "return": {} }
 181
 182 cpu
 183 ---
 184
 185 Set the default CPU.
 186
 187 Arguments:
 188
 189 - "index": the CPU's index (json-int)
 190
 191 Example:
 192
 193 -> { "execute": "cpu", "arguments": { "index": 0 } }
 194 <- { "return": {} }
 195
 196 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 197
 198 xen-save-devices-state
 199 -------
 200
 201 Save the state of all devices to file. The RAM and the block devices
 202 of the VM are not saved by this command.
 203
 204 Arguments:
 205
 206 - "filename": the file to save the state of the devices to as binary
 207 data. See xen-save-devices-state.txt for a description of the binary
 208 format.
 209
 210 Example:
 211
 212 -> { "execute": "xen-save-devices-state",
 213      "arguments": { "filename": "/tmp/save" } }
 214 <- { "return": {} }
 215
 216 xen-load-devices-state
 217 ----------------------
 218
 219 Load the state of all devices from file. The RAM and the block devices
 220 of the VM are not loaded by this command.
 221
 222 Arguments:
 223
 224 - "filename": the file to load the state of the devices from as binary
 225 data. See xen-save-devices-state.txt for a description of the binary
 226 format.
 227
 228 Example:
 229
 230 -> { "execute": "xen-load-devices-state",
 231      "arguments": { "filename": "/tmp/resume" } }
 232 <- { "return": {} }
 233
 234 xen-set-global-dirty-log
 235 -------
 236
 237 Enable or disable the global dirty log mode.
 238
 239 Arguments:
 240
 241 - "enable": Enable it or disable it.
 242
 243 Example:
 244
 245 -> { "execute": "xen-set-global-dirty-log",
 246      "arguments": { "enable": true } }
 247 <- { "return": {} }
 248
 249 migrate
 250 -------
 251
 252 Migrate to URI.
 253
 254 Arguments:
 255
 256 - "blk": block migration, full disk copy (json-bool, optional)
 257 - "inc": incremental disk copy (json-bool, optional)
 258 - "uri": Destination URI (json-string)
 259
 260 Example:
 261
 262 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
 263 <- { "return": {} }
 264
 265 Notes:
 266
 267 (1) The 'query-migrate' command should be used to check migration's progress
 268     and final result (this information is provided by the 'status' member)
 269 (2) All boolean arguments default to false
 270 (3) The user Monitor's "detach" argument is invalid in QMP and should not
 271     be used
 272
 273 migrate-incoming
 274 ----------------
 275
 276 Continue an incoming migration
 277
 278 Arguments:
 279
 280 - "uri": Source/listening URI (json-string)
 281
 282 Example:
 283
 284 -> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } }
 285 <- { "return": {} }
 286
 287 Notes:
 288
 289 (1) QEMU must be started with -incoming defer to allow migrate-incoming to
 290     be used
 291 (2) The uri format is the same as for -incoming
 292
 293 migrate-set-cache-size
 294 ----------------------
 295
 296 Set cache size to be used by XBZRLE migration, the cache size will be rounded
 297 down to the nearest power of 2
 298
 299 Arguments:
 300
 301 - "value": cache size in bytes (json-int)
 302
 303 Example:
 304
 305 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 306 <- { "return": {} }
 307
 308 x-colo-lost-heartbeat
 309 --------------------
 310
 311 Tell COLO that heartbeat is lost, a failover or takeover is needed.
 312
 313 Example:
 314
 315 -> { "execute": "x-colo-lost-heartbeat" }
 316 <- { "return": {} }
 317
 318 dump
 319
 320
 321 Dump guest memory to file. The file can be processed with crash or gdb.
 322
 323 Arguments:
 324
 325 - "paging": do paging to get guest's memory mapping (json-bool)
 326 - "protocol": destination file(started with "file:") or destination file
 327               descriptor (started with "fd:") (json-string)
 328 - "detach": if specified, command will return immediately, without waiting
 329             for the dump to finish. The user can track progress using
 330             "query-dump". (json-bool)
 331 - "begin": the starting physical address. It's optional, and should be specified
 332            with length together (json-int)
 333 - "length": the memory size, in bytes. It's optional, and should be specified
 334             with begin together (json-int)
 335 - "format": the format of guest memory dump. It's optional, and can be
 336             elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will
 337             conflict with paging and filter, ie. begin and length (json-string)
 338
 339 Example:
 340
 341 -> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
 342 <- { "return": {} }
 343
 344 Notes:
 345
 346 (1) All boolean arguments default to false
 347
 348 query-dump-guest-memory-capability
 349 ----------
 350
 351 Show available formats for 'dump-guest-memory'
 352
 353 Example:
 354
 355 -> { "execute": "query-dump-guest-memory-capability" }
 356 <- { "return": { "formats":
 357                     ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
 358
 359 query-dump
 360 ----------
 361
 362 Query background dump status.
 363
 364 Arguments: None.
 365
 366 Example:
 367
 368 -> { "execute": "query-dump" }
 369 <- { "return": { "status": "active", "completed": 1024000,
 370                  "total": 2048000 } }
 371
 372 dump-skeys
 373 ----------
 374
 375 Save guest storage keys to file.
 376
 377 Arguments:
 378
 379 - "filename": file path (json-string)
 380
 381 Example:
 382
 383 -> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } }
 384 <- { "return": {} }
 385
 386 netdev_add
 387 ----------
 388
 389 Add host network device.
 390
 391 Arguments:
 392
 393 - "type": the device type, "tap", "user", ... (json-string)
 394 - "id": the device's ID, must be unique (json-string)
 395 - device options
 396
 397 Example:
 398
 399 -> { "execute": "netdev_add",
 400      "arguments": { "type": "user", "id": "netdev1",
 401                     "dnssearch": "example.org" } }
 402 <- { "return": {} }
 403
 404 Note: The supported device options are the same ones supported by the '-netdev'
 405       command-line argument, which are listed in the '-help' output or QEMU's
 406       manual
 407
 408 netdev_del
 409 ----------
 410
 411 Remove host network device.
 412
 413 Arguments:
 414
 415 - "id": the device's ID, must be unique (json-string)
 416
 417 Example:
 418
 419 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
 420 <- { "return": {} }
 421
 422
 423 object-add
 424 ----------
 425
 426 Create QOM object.
 427
 428 Arguments:
 429
 430 - "qom-type": the object's QOM type, i.e. the class name (json-string)
 431 - "id": the object's ID, must be unique (json-string)
 432 - "props": a dictionary of object property values (optional, json-dict)
 433
 434 Example:
 435
 436 -> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1",
 437      "props": { "filename": "/dev/hwrng" } } }
 438 <- { "return": {} }
 439
 440 object-del
 441 ----------
 442
 443 Remove QOM object.
 444
 445 Arguments:
 446
 447 - "id": the object's ID (json-string)
 448
 449 Example:
 450
 451 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
 452 <- { "return": {} }
 453
 454
 455 block_resize
 456 ------------
 457
 458 Resize a block image while a guest is running.
 459
 460 Arguments:
 461
 462 - "device": the device's ID, must be unique (json-string)
 463 - "node-name": the node name in the block driver state graph (json-string)
 464 - "size": new size
 465
 466 Example:
 467
 468 -> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
 469 <- { "return": {} }
 470
 471 block-stream
 472 ------------
 473
 474 Copy data from a backing file into a block device.
 475
 476 Arguments:
 477
 478 - "job-id": Identifier for the newly-created block job. If omitted,
 479             the device name will be used. (json-string, optional)
 480 - "device": The device name or node-name of a root node (json-string)
 481 - "base": The file name of the backing image above which copying starts.
 482           It cannot be set if 'base-node' is also set (json-string, optional)
 483 - "base-node": the node name of the backing image above which copying starts.
 484                It cannot be set if 'base' is also set.
 485                (json-string, optional) (Since 2.8)
 486 - "backing-file": The backing file string to write into the active layer. This
 487                   filename is not validated.
 488
 489                   If a pathname string is such that it cannot be resolved by
 490                   QEMU, that means that subsequent QMP or HMP commands must use
 491                   node-names for the image in question, as filename lookup
 492                   methods will fail.
 493
 494                   If not specified, QEMU will automatically determine the
 495                   backing file string to use, or error out if there is no
 496                   obvious choice.  Care should be taken when specifying the
 497                   string, to specify a valid filename or protocol.
 498                   (json-string, optional) (Since 2.1)
 499 - "speed":  the maximum speed, in bytes per second (json-int, optional)
 500 - "on-error": the action to take on an error (default 'report').  'stop' and
 501               'enospc' can only be used if the block device supports io-status.
 502               (json-string, optional) (Since 2.1)
 503
 504 Example:
 505
 506 -> { "execute": "block-stream", "arguments": { "device": "virtio0",
 507                                                "base": "/tmp/master.qcow2" } }
 508 <- { "return": {} }
 509
 510 block-commit
 511 ------------
 512
 513 Live commit of data from overlay image nodes into backing nodes - i.e., writes
 514 data between 'top' and 'base' into 'base'.
 515
 516 Arguments:
 517
 518 - "job-id": Identifier for the newly-created block job. If omitted,
 519             the device name will be used. (json-string, optional)
 520 - "device": The device name or node-name of a root node (json-string)
 521 - "base": The file name of the backing image to write data into.
 522           If not specified, this is the deepest backing image
 523           (json-string, optional)
 524 - "top":  The file name of the backing image within the image chain,
 525           which contains the topmost data to be committed down. If
 526           not specified, this is the active layer. (json-string, optional)
 527
 528 - backing-file:     The backing file string to write into the overlay
 529                     image of 'top'.  If 'top' is the active layer,
 530                     specifying a backing file string is an error. This
 531                     filename is not validated.
 532
 533                     If a pathname string is such that it cannot be
 534                     resolved by QEMU, that means that subsequent QMP or
 535                     HMP commands must use node-names for the image in
 536                     question, as filename lookup methods will fail.
 537
 538                     If not specified, QEMU will automatically determine
 539                     the backing file string to use, or error out if
 540                     there is no obvious choice. Care should be taken
 541                     when specifying the string, to specify a valid
 542                     filename or protocol.
 543                     (json-string, optional) (Since 2.1)
 544
 545           If top == base, that is an error.
 546           If top == active, the job will not be completed by itself,
 547           user needs to complete the job with the block-job-complete
 548           command after getting the ready event. (Since 2.0)
 549
 550           If the base image is smaller than top, then the base image
 551           will be resized to be the same size as top.  If top is
 552           smaller than the base image, the base will not be
 553           truncated.  If you want the base image size to match the
 554           size of the smaller top, you can safely truncate it
 555           yourself once the commit operation successfully completes.
 556           (json-string)
 557 - "speed":  the maximum speed, in bytes per second (json-int, optional)
 558
 559
 560 Example:
 561
 562 -> { "execute": "block-commit", "arguments": { "device": "virtio0",
 563                                               "top": "/tmp/snap1.qcow2" } }
 564 <- { "return": {} }
 565
 566 drive-backup
 567 ------------
 568
 569 Start a point-in-time copy of a block device to a new destination.  The
 570 status of ongoing drive-backup operations can be checked with
 571 query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
 572 The operation can be stopped before it has completed using the
 573 block-job-cancel command.
 574
 575 Arguments:
 576
 577 - "job-id": Identifier for the newly-created block job. If omitted,
 578             the device name will be used. (json-string, optional)
 579 - "device": the device name or node-name of a root node which should be copied.
 580             (json-string)
 581 - "target": the target of the new image. If the file exists, or if it is a
 582             device, the existing file/device will be used as the new
 583             destination.  If it does not exist, a new file will be created.
 584             (json-string)
 585 - "format": the format of the new destination, default is to probe if 'mode' is
 586             'existing', else the format of the source
 587             (json-string, optional)
 588 - "sync": what parts of the disk image should be copied to the destination;
 589   possibilities include "full" for all the disk, "top" for only the sectors
 590   allocated in the topmost image, "incremental" for only the dirty sectors in
 591   the bitmap, or "none" to only replicate new I/O (MirrorSyncMode).
 592 - "bitmap": dirty bitmap name for sync==incremental. Must be present if sync
 593             is "incremental", must NOT be present otherwise.
 594 - "mode": whether and how QEMU should create a new image
 595           (NewImageMode, optional, default 'absolute-paths')
 596 - "speed": the maximum speed, in bytes per second (json-int, optional)
 597 - "compress": true to compress data, if the target format supports it.
 598               (json-bool, optional, default false)
 599 - "on-source-error": the action to take on an error on the source, default
 600                      'report'.  'stop' and 'enospc' can only be used
 601                      if the block device supports io-status.
 602                      (BlockdevOnError, optional)
 603 - "on-target-error": the action to take on an error on the target, default
 604                      'report' (no limitations, since this applies to
 605                      a different block device than device).
 606                      (BlockdevOnError, optional)
 607
 608 Example:
 609 -> { "execute": "drive-backup", "arguments": { "device": "drive0",
 610                                                "sync": "full",
 611                                                "target": "backup.img" } }
 612 <- { "return": {} }
 613
 614 blockdev-backup
 615 ---------------
 616
 617 The device version of drive-backup: this command takes an existing named device
 618 as backup target.
 619
 620 Arguments:
 621
 622 - "job-id": Identifier for the newly-created block job. If omitted,
 623             the device name will be used. (json-string, optional)
 624 - "device": the device name or node-name of a root node which should be copied.
 625             (json-string)
 626 - "target": the name of the backup target device. (json-string)
 627 - "sync": what parts of the disk image should be copied to the destination;
 628           possibilities include "full" for all the disk, "top" for only the
 629           sectors allocated in the topmost image, or "none" to only replicate
 630           new I/O (MirrorSyncMode).
 631 - "speed": the maximum speed, in bytes per second (json-int, optional)
 632 - "compress": true to compress data, if the target format supports it.
 633               (json-bool, optional, default false)
 634 - "on-source-error": the action to take on an error on the source, default
 635                      'report'.  'stop' and 'enospc' can only be used
 636                      if the block device supports io-status.
 637                      (BlockdevOnError, optional)
 638 - "on-target-error": the action to take on an error on the target, default
 639                      'report' (no limitations, since this applies to
 640                      a different block device than device).
 641                      (BlockdevOnError, optional)
 642
 643 Example:
 644 -> { "execute": "blockdev-backup", "arguments": { "device": "src-id",
 645                                                   "sync": "full",
 646                                                   "target": "tgt-id" } }
 647 <- { "return": {} }
 648
 649 block-dirty-bitmap-add
 650 ----------------------
 651 Since 2.4
 652
 653 Create a dirty bitmap with a name on the device, and start tracking the writes.
 654
 655 Arguments:
 656
 657 - "node": device/node on which to create dirty bitmap (json-string)
 658 - "name": name of the new dirty bitmap (json-string)
 659 - "granularity": granularity to track writes with (int, optional)
 660
 661 Example:
 662
 663 -> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0",
 664                                                    "name": "bitmap0" } }
 665 <- { "return": {} }
 666
 667 block-dirty-bitmap-remove
 668 -------------------------
 669 Since 2.4
 670
 671 Stop write tracking and remove the dirty bitmap that was created with
 672 block-dirty-bitmap-add.
 673
 674 Arguments:
 675
 676 - "node": device/node on which to remove dirty bitmap (json-string)
 677 - "name": name of the dirty bitmap to remove (json-string)
 678
 679 Example:
 680
 681 -> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0",
 682                                                       "name": "bitmap0" } }
 683 <- { "return": {} }
 684
 685 block-dirty-bitmap-clear
 686 ------------------------
 687 Since 2.4
 688
 689 Reset the dirty bitmap associated with a node so that an incremental backup
 690 from this point in time forward will only backup clusters modified after this
 691 clear operation.
 692
 693 Arguments:
 694
 695 - "node": device/node on which to remove dirty bitmap (json-string)
 696 - "name": name of the dirty bitmap to remove (json-string)
 697
 698 Example:
 699
 700 -> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0",
 701                                                            "name": "bitmap0" } }
 702 <- { "return": {} }
 703
 704 blockdev-snapshot-sync
 705 ----------------------
 706
 707 Synchronous snapshot of a block device. snapshot-file specifies the
 708 target of the new image. If the file exists, or if it is a device, the
 709 snapshot will be created in the existing file/device. If does not
 710 exist, a new file will be created. format specifies the format of the
 711 snapshot image, default is qcow2.
 712
 713 Arguments:
 714
 715 - "device": device name to snapshot (json-string)
 716 - "node-name": graph node name to snapshot (json-string)
 717 - "snapshot-file": name of new image file (json-string)
 718 - "snapshot-node-name": graph node name of the new snapshot (json-string)
 719 - "mode": whether and how QEMU should create the snapshot file
 720   (NewImageMode, optional, default "absolute-paths")
 721 - "format": format of new image (json-string, optional)
 722
 723 Example:
 724
 725 -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
 726                                                          "snapshot-file":
 727                                                         "/some/place/my-image",
 728                                                         "format": "qcow2" } }
 729 <- { "return": {} }
 730
 731 blockdev-snapshot
 732 -----------------
 733 Since 2.5
 734
 735 Create a snapshot, by installing 'node' as the backing image of
 736 'overlay'. Additionally, if 'node' is associated with a block
 737 device, the block device changes to using 'overlay' as its new active
 738 image.
 739
 740 Arguments:
 741
 742 - "node": device that will have a snapshot created (json-string)
 743 - "overlay": device that will have 'node' as its backing image (json-string)
 744
 745 Example:
 746
 747 -> { "execute": "blockdev-add",
 748                 "arguments": { "driver": "qcow2",
 749                                "node-name": "node1534",
 750                                "file": { "driver": "file",
 751                                          "filename": "hd1.qcow2" },
 752                                "backing": "" } }
 753
 754 <- { "return": {} }
 755
 756 -> { "execute": "blockdev-snapshot", "arguments": { "node": "ide-hd0",
 757                                                     "overlay": "node1534" } }
 758 <- { "return": {} }
 759
 760 blockdev-snapshot-internal-sync
 761 -------------------------------
 762
 763 Synchronously take an internal snapshot of a block device when the format of
 764 image used supports it.  If the name is an empty string, or a snapshot with
 765 name already exists, the operation will fail.
 766
 767 Arguments:
 768
 769 - "device": the device name or node-name of a root node to snapshot
 770             (json-string)
 771 - "name": name of the new snapshot (json-string)
 772
 773 Example:
 774
 775 -> { "execute": "blockdev-snapshot-internal-sync",
 776                 "arguments": { "device": "ide-hd0",
 777                                "name": "snapshot0" }
 778    }
 779 <- { "return": {} }
 780
 781 blockdev-snapshot-delete-internal-sync
 782 --------------------------------------
 783
 784 Synchronously delete an internal snapshot of a block device when the format of
 785 image used supports it.  The snapshot is identified by name or id or both.  One
 786 of name or id is required.  If the snapshot is not found, the operation will
 787 fail.
 788
 789 Arguments:
 790
 791 - "device": the device name or node-name of a root node (json-string)
 792 - "id": ID of the snapshot (json-string, optional)
 793 - "name": name of the snapshot (json-string, optional)
 794
 795 Example:
 796
 797 -> { "execute": "blockdev-snapshot-delete-internal-sync",
 798                 "arguments": { "device": "ide-hd0",
 799                                "name": "snapshot0" }
 800    }
 801 <- { "return": {
 802                    "id": "1",
 803                    "name": "snapshot0",
 804                    "vm-state-size": 0,
 805                    "date-sec": 1000012,
 806                    "date-nsec": 10,
 807                    "vm-clock-sec": 100,
 808                    "vm-clock-nsec": 20
 809      }
 810    }
 811
 812 drive-mirror
 813 ------------
 814
 815 Start mirroring a block device's writes to a new destination. target
 816 specifies the target of the new image. If the file exists, or if it is
 817 a device, it will be used as the new destination for writes. If it does not
 818 exist, a new file will be created. format specifies the format of the
 819 mirror image, default is to probe if mode='existing', else the format
 820 of the source.
 821
 822 Arguments:
 823
 824 - "job-id": Identifier for the newly-created block job. If omitted,
 825             the device name will be used. (json-string, optional)
 826 - "device": the device name or node-name of a root node whose writes should be
 827             mirrored. (json-string)
 828 - "target": name of new image file (json-string)
 829 - "format": format of new image (json-string, optional)
 830 - "node-name": the name of the new block driver state in the node graph
 831                (json-string, optional)
 832 - "replaces": the block driver node name to replace when finished
 833               (json-string, optional)
 834 - "mode": how an image file should be created into the target
 835   file/device (NewImageMode, optional, default 'absolute-paths')
 836 - "speed": maximum speed of the streaming job, in bytes per second
 837   (json-int)
 838 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
 839 - "buf-size": maximum amount of data in flight from source to target, in bytes
 840   (json-int, default 10M)
 841 - "sync": what parts of the disk image should be copied to the destination;
 842   possibilities include "full" for all the disk, "top" for only the sectors
 843   allocated in the topmost image, or "none" to only replicate new I/O
 844   (MirrorSyncMode).
 845 - "on-source-error": the action to take on an error on the source
 846   (BlockdevOnError, default 'report')
 847 - "on-target-error": the action to take on an error on the target
 848   (BlockdevOnError, default 'report')
 849 - "unmap": whether the target sectors should be discarded where source has only
 850   zeroes. (json-bool, optional, default true)
 851
 852 The default value of the granularity is the image cluster size clamped
 853 between 4096 and 65536, if the image format defines one.  If the format
 854 does not define a cluster size, the default value of the granularity
 855 is 65536.
 856
 857
 858 Example:
 859
 860 -> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
 861                                                "target": "/some/place/my-image",
 862                                                "sync": "full",
 863                                                "format": "qcow2" } }
 864 <- { "return": {} }
 865
 866 blockdev-mirror
 867 ------------
 868
 869 Start mirroring a block device's writes to another block device. target
 870 specifies the target of mirror operation.
 871
 872 Arguments:
 873
 874 - "job-id": Identifier for the newly-created block job. If omitted,
 875             the device name will be used. (json-string, optional)
 876 - "device": The device name or node-name of a root node whose writes should be
 877             mirrored (json-string)
 878 - "target": device name to mirror to (json-string)
 879 - "replaces": the block driver node name to replace when finished
 880               (json-string, optional)
 881 - "speed": maximum speed of the streaming job, in bytes per second
 882   (json-int)
 883 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
 884 - "buf_size": maximum amount of data in flight from source to target, in bytes
 885   (json-int, default 10M)
 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 sectors
 888   allocated in the topmost image, or "none" to only replicate new I/O
 889   (MirrorSyncMode).
 890 - "on-source-error": the action to take on an error on the source
 891   (BlockdevOnError, default 'report')
 892 - "on-target-error": the action to take on an error on the target
 893   (BlockdevOnError, default 'report')
 894
 895 The default value of the granularity is the image cluster size clamped
 896 between 4096 and 65536, if the image format defines one.  If the format
 897 does not define a cluster size, the default value of the granularity
 898 is 65536.
 899
 900 Example:
 901
 902 -> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
 903                                                   "target": "target0",
 904                                                   "sync": "full" } }
 905 <- { "return": {} }
 906
 907 change-backing-file
 908 -------------------
 909 Since: 2.1
 910
 911 Change the backing file in the image file metadata.  This does not cause
 912 QEMU to reopen the image file to reparse the backing filename (it may,
 913 however, perform a reopen to change permissions from r/o -> r/w -> r/o,
 914 if needed). The new backing file string is written into the image file
 915 metadata, and the QEMU internal strings are updated.
 916
 917 Arguments:
 918
 919 - "image-node-name":    The name of the block driver state node of the
 920                         image to modify.  The "device" is argument is used to
 921                         verify "image-node-name" is in the chain described by
 922                         "device".
 923                         (json-string, optional)
 924
 925 - "device":             The device name or node-name of the root node that owns
 926                         image-node-name.
 927                         (json-string)
 928
 929 - "backing-file":       The string to write as the backing file.  This string is
 930                         not validated, so care should be taken when specifying
 931                         the string or the image chain may not be able to be
 932                         reopened again.
 933                         (json-string)
 934
 935 Returns: Nothing on success
 936          If "device" does not exist or cannot be determined, DeviceNotFound
 937
 938 getfd
 939 -----
 940
 941 Receive a file descriptor via SCM rights and assign it a name.
 942
 943 Arguments:
 944
 945 - "fdname": file descriptor name (json-string)
 946
 947 Example:
 948
 949 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
 950 <- { "return": {} }
 951
 952 Notes:
 953
 954 (1) If the name specified by the "fdname" argument already exists,
 955     the file descriptor assigned to it will be closed and replaced
 956     by the received file descriptor.
 957 (2) The 'closefd' command can be used to explicitly close the file
 958     descriptor when it is no longer needed.
 959
 960 closefd
 961 -------
 962
 963 Close a file descriptor previously passed via SCM rights.
 964
 965 Arguments:
 966
 967 - "fdname": file descriptor name (json-string)
 968
 969 Example:
 970
 971 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
 972 <- { "return": {} }
 973
 974 add-fd
 975 -------
 976
 977 Add a file descriptor, that was passed via SCM rights, to an fd set.
 978
 979 Arguments:
 980
 981 - "fdset-id": The ID of the fd set to add the file descriptor to.
 982               (json-int, optional)
 983 - "opaque": A free-form string that can be used to describe the fd.
 984             (json-string, optional)
 985
 986 Return a json-object with the following information:
 987
 988 - "fdset-id": The ID of the fd set that the fd was added to. (json-int)
 989 - "fd": The file descriptor that was received via SCM rights and added to the
 990         fd set. (json-int)
 991
 992 Example:
 993
 994 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
 995 <- { "return": { "fdset-id": 1, "fd": 3 } }
 996
 997 Notes:
 998
 999 (1) The list of fd sets is shared by all monitor connections.
1000 (2) If "fdset-id" is not specified, a new fd set will be created.
1001
1002 remove-fd
1003 ---------
1004
1005 Remove a file descriptor from an fd set.
1006
1007 Arguments:
1008
1009 - "fdset-id": The ID of the fd set that the file descriptor belongs to.
1010               (json-int)
1011 - "fd": The file descriptor that is to be removed. (json-int, optional)
1012
1013 Example:
1014
1015 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1016 <- { "return": {} }
1017
1018 Notes:
1019
1020 (1) The list of fd sets is shared by all monitor connections.
1021 (2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1022     removed.
1023
1024 query-fdsets
1025 -------------
1026
1027 Return information describing all fd sets.
1028
1029 Arguments: None
1030
1031 Example:
1032
1033 -> { "execute": "query-fdsets" }
1034 <- { "return": [
1035        {
1036          "fds": [
1037            {
1038              "fd": 30,
1039              "opaque": "rdonly:/path/to/file"
1040            },
1041            {
1042              "fd": 24,
1043              "opaque": "rdwr:/path/to/file"
1044            }
1045          ],
1046          "fdset-id": 1
1047        },
1048        {
1049          "fds": [
1050            {
1051              "fd": 28
1052            },
1053            {
1054              "fd": 29
1055            }
1056          ],
1057          "fdset-id": 0
1058        }
1059      ]
1060    }
1061
1062 Note: The list of fd sets is shared by all monitor connections.
1063
1064 block_passwd
1065 ------------
1066
1067 Set the password of encrypted block devices.
1068
1069 Arguments:
1070
1071 - "device": device name (json-string)
1072 - "node-name": name in the block driver state graph (json-string)
1073 - "password": password (json-string)
1074
1075 Example:
1076
1077 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1078                                                "password": "12345" } }
1079 <- { "return": {} }
1080
1081 block_set_io_throttle
1082 ------------
1083
1084 Change I/O throttle limits for a block drive.
1085
1086 Arguments:
1087
1088 - "device": block device name (deprecated, use @id instead)
1089             (json-string, optional)
1090 - "id": the name or QOM path of the guest device (json-string, optional)
1091 - "bps": total throughput limit in bytes per second (json-int)
1092 - "bps_rd": read throughput limit in bytes per second (json-int)
1093 - "bps_wr": write throughput limit in bytes per second (json-int)
1094 - "iops": total I/O operations per second (json-int)
1095 - "iops_rd": read I/O operations per second (json-int)
1096 - "iops_wr": write I/O operations per second (json-int)
1097 - "bps_max": total throughput limit during bursts, in bytes (json-int, optional)
1098 - "bps_rd_max": read throughput limit during bursts, in bytes (json-int, optional)
1099 - "bps_wr_max": write throughput limit during bursts, in bytes (json-int, optional)
1100 - "iops_max": total I/O operations per second during bursts (json-int, optional)
1101 - "iops_rd_max": read I/O operations per second during bursts (json-int, optional)
1102 - "iops_wr_max": write I/O operations per second during bursts (json-int, optional)
1103 - "bps_max_length": maximum length of the @bps_max burst period, in seconds (json-int, optional)
1104 - "bps_rd_max_length": maximum length of the @bps_rd_max burst period, in seconds (json-int, optional)
1105 - "bps_wr_max_length": maximum length of the @bps_wr_max burst period, in seconds (json-int, optional)
1106 - "iops_max_length": maximum length of the @iops_max burst period, in seconds (json-int, optional)
1107 - "iops_rd_max_length": maximum length of the @iops_rd_max burst period, in seconds (json-int, optional)
1108 - "iops_wr_max_length": maximum length of the @iops_wr_max burst period, in seconds (json-int, optional)
1109 - "iops_size":  I/O size in bytes when limiting (json-int, optional)
1110 - "group": throttle group name (json-string, optional)
1111
1112 Example:
1113
1114 -> { "execute": "block_set_io_throttle", "arguments": { "id": "ide0-1-0",
1115                                                "bps": 1000000,
1116                                                "bps_rd": 0,
1117                                                "bps_wr": 0,
1118                                                "iops": 0,
1119                                                "iops_rd": 0,
1120                                                "iops_wr": 0,
1121                                                "bps_max": 8000000,
1122                                                "bps_rd_max": 0,
1123                                                "bps_wr_max": 0,
1124                                                "iops_max": 0,
1125                                                "iops_rd_max": 0,
1126                                                "iops_wr_max": 0,
1127                                                "bps_max_length": 60,
1128                                                "iops_size": 0 } }
1129 <- { "return": {} }
1130
1131 expire_password
1132 ---------------
1133
1134 Set the password expire time for vnc/spice protocols.
1135
1136 Arguments:
1137
1138 - "protocol": protocol name (json-string)
1139 - "time": [ now | never | +secs | secs ] (json-string)
1140
1141 Example:
1142
1143 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
1144                                                   "time": "+60" } }
1145 <- { "return": {} }
1146
1147 qmp_capabilities
1148 ----------------
1149
1150 Enable QMP capabilities.
1151
1152 Arguments: None.
1153
1154 Example:
1155
1156 -> { "execute": "qmp_capabilities" }
1157 <- { "return": {} }
1158
1159 Note: This command must be issued before issuing any other command.
1160
1161 3. Query Commands
1162 =================
1163
1164
1165 query-version
1166 -------------
1167
1168 Show QEMU version.
1169
1170 Return a json-object with the following information:
1171
1172 - "qemu": A json-object containing three integer values:
1173     - "major": QEMU's major version (json-int)
1174     - "minor": QEMU's minor version (json-int)
1175     - "micro": QEMU's micro version (json-int)
1176 - "package": package's version (json-string)
1177
1178 Example:
1179
1180 -> { "execute": "query-version" }
1181 <- {
1182       "return":{
1183          "qemu":{
1184             "major":0,
1185             "minor":11,
1186             "micro":5
1187          },
1188          "package":""
1189       }
1190    }
1191
1192 query-commands
1193 --------------
1194
1195 List QMP available commands.
1196
1197 Each command is represented by a json-object, the returned value is a json-array
1198 of all commands.
1199
1200 Each json-object contain:
1201
1202 - "name": command's name (json-string)
1203
1204 Example:
1205
1206 -> { "execute": "query-commands" }
1207 <- {
1208       "return":[
1209          {
1210             "name":"query-balloon"
1211          },
1212          {
1213             "name":"system_powerdown"
1214          }
1215       ]
1216    }
1217
1218 Note: This example has been shortened as the real response is too long.
1219
1220 query-qmp-schema
1221 ----------------
1222
1223 Return the QMP wire schema.  The returned value is a json-array of
1224 named schema entities.  Entities are commands, events and various
1225 types.  See docs/qapi-code-gen.txt for information on their structure
1226 and intended use.
1227
1228 query-block
1229 -----------
1230
1231 Show the block devices.
1232
1233 Each block device information is stored in a json-object and the returned value
1234 is a json-array of all devices.
1235
1236 Each json-object contain the following:
1237
1238 - "device": device name (json-string)
1239 - "type": device type (json-string)
1240          - deprecated, retained for backward compatibility
1241          - Possible values: "unknown"
1242 - "removable": true if the device is removable, false otherwise (json-bool)
1243 - "locked": true if the device is locked, false otherwise (json-bool)
1244 - "tray_open": only present if removable, true if the device has a tray,
1245                and it is open (json-bool)
1246 - "inserted": only present if the device is inserted, it is a json-object
1247    containing the following:
1248          - "file": device file name (json-string)
1249          - "ro": true if read-only, false otherwise (json-bool)
1250          - "drv": driver format name (json-string)
1251              - Possible values: "blkdebug", "bochs", "cloop", "dmg",
1252                                 "file", "file", "ftp", "ftps", "host_cdrom",
1253                                 "host_device", "http", "https",
1254                                 "nbd", "parallels", "qcow", "qcow2", "raw",
1255                                 "vdi", "vmdk", "vpc", "vvfat"
1256          - "backing_file": backing file name (json-string, optional)
1257          - "backing_file_depth": number of files in the backing file chain (json-int)
1258          - "encrypted": true if encrypted, false otherwise (json-bool)
1259          - "bps": limit total bytes per second (json-int)
1260          - "bps_rd": limit read bytes per second (json-int)
1261          - "bps_wr": limit write bytes per second (json-int)
1262          - "iops": limit total I/O operations per second (json-int)
1263          - "iops_rd": limit read operations per second (json-int)
1264          - "iops_wr": limit write operations per second (json-int)
1265          - "bps_max":  total max in bytes (json-int)
1266          - "bps_rd_max":  read max in bytes (json-int)
1267          - "bps_wr_max":  write max in bytes (json-int)
1268          - "iops_max":  total I/O operations max (json-int)
1269          - "iops_rd_max":  read I/O operations max (json-int)
1270          - "iops_wr_max":  write I/O operations max (json-int)
1271          - "iops_size": I/O size when limiting by iops (json-int)
1272          - "detect_zeroes": detect and optimize zero writing (json-string)
1273              - Possible values: "off", "on", "unmap"
1274          - "write_threshold": write offset threshold in bytes, a event will be
1275                               emitted if crossed. Zero if disabled (json-int)
1276          - "image": the detail of the image, it is a json-object containing
1277             the following:
1278              - "filename": image file name (json-string)
1279              - "format": image format (json-string)
1280              - "virtual-size": image capacity in bytes (json-int)
1281              - "dirty-flag": true if image is not cleanly closed, not present
1282                              means clean (json-bool, optional)
1283              - "actual-size": actual size on disk in bytes of the image, not
1284                               present when image does not support thin
1285                               provision (json-int, optional)
1286              - "cluster-size": size of a cluster in bytes, not present if image
1287                                format does not support it (json-int, optional)
1288              - "encrypted": true if the image is encrypted, not present means
1289                             false or the image format does not support
1290                             encryption (json-bool, optional)
1291              - "backing_file": backing file name, not present means no backing
1292                                file is used or the image format does not
1293                                support backing file chain
1294                                (json-string, optional)
1295              - "full-backing-filename": full path of the backing file, not
1296                                         present if it equals backing_file or no
1297                                         backing file is used
1298                                         (json-string, optional)
1299              - "backing-filename-format": the format of the backing file, not
1300                                           present means unknown or no backing
1301                                           file (json-string, optional)
1302              - "snapshots": the internal snapshot info, it is an optional list
1303                 of json-object containing the following:
1304                  - "id": unique snapshot id (json-string)
1305                  - "name": snapshot name (json-string)
1306                  - "vm-state-size": size of the VM state in bytes (json-int)
1307                  - "date-sec": UTC date of the snapshot in seconds (json-int)
1308                  - "date-nsec": fractional part in nanoseconds to be used with
1309                                 date-sec (json-int)
1310                  - "vm-clock-sec": VM clock relative to boot in seconds
1311                                    (json-int)
1312                  - "vm-clock-nsec": fractional part in nanoseconds to be used
1313                                     with vm-clock-sec (json-int)
1314              - "backing-image": the detail of the backing image, it is an
1315                                 optional json-object only present when a
1316                                 backing image present for this image
1317
1318 - "io-status": I/O operation status, only present if the device supports it
1319                and the VM is configured to stop on errors. It's always reset
1320                to "ok" when the "cont" command is issued (json_string, optional)
1321              - Possible values: "ok", "failed", "nospace"
1322
1323 Example:
1324
1325 -> { "execute": "query-block" }
1326 <- {
1327       "return":[
1328          {
1329             "io-status": "ok",
1330             "device":"ide0-hd0",
1331             "locked":false,
1332             "removable":false,
1333             "inserted":{
1334                "ro":false,
1335                "drv":"qcow2",
1336                "encrypted":false,
1337                "file":"disks/test.qcow2",
1338                "backing_file_depth":1,
1339                "bps":1000000,
1340                "bps_rd":0,
1341                "bps_wr":0,
1342                "iops":1000000,
1343                "iops_rd":0,
1344                "iops_wr":0,
1345                "bps_max": 8000000,
1346                "bps_rd_max": 0,
1347                "bps_wr_max": 0,
1348                "iops_max": 0,
1349                "iops_rd_max": 0,
1350                "iops_wr_max": 0,
1351                "iops_size": 0,
1352                "detect_zeroes": "on",
1353                "write_threshold": 0,
1354                "image":{
1355                   "filename":"disks/test.qcow2",
1356                   "format":"qcow2",
1357                   "virtual-size":2048000,
1358                   "backing_file":"base.qcow2",
1359                   "full-backing-filename":"disks/base.qcow2",
1360                   "backing-filename-format":"qcow2",
1361                   "snapshots":[
1362                      {
1363                         "id": "1",
1364                         "name": "snapshot1",
1365                         "vm-state-size": 0,
1366                         "date-sec": 10000200,
1367                         "date-nsec": 12,
1368                         "vm-clock-sec": 206,
1369                         "vm-clock-nsec": 30
1370                      }
1371                   ],
1372                   "backing-image":{
1373                       "filename":"disks/base.qcow2",
1374                       "format":"qcow2",
1375                       "virtual-size":2048000
1376                   }
1377                }
1378             },
1379             "type":"unknown"
1380          },
1381          {
1382             "io-status": "ok",
1383             "device":"ide1-cd0",
1384             "locked":false,
1385             "removable":true,
1386             "type":"unknown"
1387          },
1388          {
1389             "device":"floppy0",
1390             "locked":false,
1391             "removable":true,
1392             "type":"unknown"
1393          },
1394          {
1395             "device":"sd0",
1396             "locked":false,
1397             "removable":true,
1398             "type":"unknown"
1399          }
1400       ]
1401    }
1402
1403 query-blockstats
1404 ----------------
1405
1406 Show block device statistics.
1407
1408 Each device statistic information is stored in a json-object and the returned
1409 value is a json-array of all devices.
1410
1411 Each json-object contain the following:
1412
1413 - "device": device name (json-string)
1414 - "stats": A json-object with the statistics information, it contains:
1415     - "rd_bytes": bytes read (json-int)
1416     - "wr_bytes": bytes written (json-int)
1417     - "rd_operations": read operations (json-int)
1418     - "wr_operations": write operations (json-int)
1419     - "flush_operations": cache flush operations (json-int)
1420     - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
1421     - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
1422     - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
1423     - "wr_highest_offset": The offset after the greatest byte written to the
1424                            BlockDriverState since it has been opened (json-int)
1425     - "rd_merged": number of read requests that have been merged into
1426                    another request (json-int)
1427     - "wr_merged": number of write requests that have been merged into
1428                    another request (json-int)
1429     - "idle_time_ns": time since the last I/O operation, in
1430                       nanoseconds. If the field is absent it means
1431                       that there haven't been any operations yet
1432                       (json-int, optional)
1433     - "failed_rd_operations": number of failed read operations
1434                               (json-int)
1435     - "failed_wr_operations": number of failed write operations
1436                               (json-int)
1437     - "failed_flush_operations": number of failed flush operations
1438                                (json-int)
1439     - "invalid_rd_operations": number of invalid read operations
1440                                (json-int)
1441     - "invalid_wr_operations": number of invalid write operations
1442                                (json-int)
1443     - "invalid_flush_operations": number of invalid flush operations
1444                                   (json-int)
1445     - "account_invalid": whether invalid operations are included in
1446                          the last access statistics (json-bool)
1447     - "account_failed": whether failed operations are included in the
1448                          latency and last access statistics
1449                          (json-bool)
1450     - "timed_stats": A json-array containing statistics collected in
1451                      specific intervals, with the following members:
1452         - "interval_length": interval used for calculating the
1453                              statistics, in seconds (json-int)
1454         - "min_rd_latency_ns": minimum latency of read operations in
1455                                the defined interval, in nanoseconds
1456                                (json-int)
1457         - "min_wr_latency_ns": minimum latency of write operations in
1458                                the defined interval, in nanoseconds
1459                                (json-int)
1460         - "min_flush_latency_ns": minimum latency of flush operations
1461                                   in the defined interval, in
1462                                   nanoseconds (json-int)
1463         - "max_rd_latency_ns": maximum latency of read operations in
1464                                the defined interval, in nanoseconds
1465                                (json-int)
1466         - "max_wr_latency_ns": maximum latency of write operations in
1467                                the defined interval, in nanoseconds
1468                                (json-int)
1469         - "max_flush_latency_ns": maximum latency of flush operations
1470                                   in the defined interval, in
1471                                   nanoseconds (json-int)
1472         - "avg_rd_latency_ns": average latency of read operations in
1473                                the defined interval, in nanoseconds
1474                                (json-int)
1475         - "avg_wr_latency_ns": average latency of write operations in
1476                                the defined interval, in nanoseconds
1477                                (json-int)
1478         - "avg_flush_latency_ns": average latency of flush operations
1479                                   in the defined interval, in
1480                                   nanoseconds (json-int)
1481         - "avg_rd_queue_depth": average number of pending read
1482                                 operations in the defined interval
1483                                 (json-number)
1484         - "avg_wr_queue_depth": average number of pending write
1485                                 operations in the defined interval
1486                                 (json-number).
1487 - "parent": Contains recursively the statistics of the underlying
1488             protocol (e.g. the host file for a qcow2 image). If there is
1489             no underlying protocol, this field is omitted
1490             (json-object, optional)
1491
1492 Example:
1493
1494 -> { "execute": "query-blockstats" }
1495 <- {
1496       "return":[
1497          {
1498             "device":"ide0-hd0",
1499             "parent":{
1500                "stats":{
1501                   "wr_highest_offset":3686448128,
1502                   "wr_bytes":9786368,
1503                   "wr_operations":751,
1504                   "rd_bytes":122567168,
1505                   "rd_operations":36772
1506                   "wr_total_times_ns":313253456
1507                   "rd_total_times_ns":3465673657
1508                   "flush_total_times_ns":49653
1509                   "flush_operations":61,
1510                   "rd_merged":0,
1511                   "wr_merged":0,
1512                   "idle_time_ns":2953431879,
1513                   "account_invalid":true,
1514                   "account_failed":false
1515                }
1516             },
1517             "stats":{
1518                "wr_highest_offset":2821110784,
1519                "wr_bytes":9786368,
1520                "wr_operations":692,
1521                "rd_bytes":122739200,
1522                "rd_operations":36604
1523                "flush_operations":51,
1524                "wr_total_times_ns":313253456
1525                "rd_total_times_ns":3465673657
1526                "flush_total_times_ns":49653,
1527                "rd_merged":0,
1528                "wr_merged":0,
1529                "idle_time_ns":2953431879,
1530                "account_invalid":true,
1531                "account_failed":false
1532             }
1533          },
1534          {
1535             "device":"ide1-cd0",
1536             "stats":{
1537                "wr_highest_offset":0,
1538                "wr_bytes":0,
1539                "wr_operations":0,
1540                "rd_bytes":0,
1541                "rd_operations":0
1542                "flush_operations":0,
1543                "wr_total_times_ns":0
1544                "rd_total_times_ns":0
1545                "flush_total_times_ns":0,
1546                "rd_merged":0,
1547                "wr_merged":0,
1548                "account_invalid":false,
1549                "account_failed":false
1550             }
1551          },
1552          {
1553             "device":"floppy0",
1554             "stats":{
1555                "wr_highest_offset":0,
1556                "wr_bytes":0,
1557                "wr_operations":0,
1558                "rd_bytes":0,
1559                "rd_operations":0
1560                "flush_operations":0,
1561                "wr_total_times_ns":0
1562                "rd_total_times_ns":0
1563                "flush_total_times_ns":0,
1564                "rd_merged":0,
1565                "wr_merged":0,
1566                "account_invalid":false,
1567                "account_failed":false
1568             }
1569          },
1570          {
1571             "device":"sd0",
1572             "stats":{
1573                "wr_highest_offset":0,
1574                "wr_bytes":0,
1575                "wr_operations":0,
1576                "rd_bytes":0,
1577                "rd_operations":0
1578                "flush_operations":0,
1579                "wr_total_times_ns":0
1580                "rd_total_times_ns":0
1581                "flush_total_times_ns":0,
1582                "rd_merged":0,
1583                "wr_merged":0,
1584                "account_invalid":false,
1585                "account_failed":false
1586             }
1587          }
1588       ]
1589    }
1590
1591 query-command-line-options
1592 --------------------------
1593
1594 Show command line option schema.
1595
1596 Return a json-array of command line option schema for all options (or for
1597 the given option), returning an error if the given option doesn't exist.
1598
1599 Each array entry contains the following:
1600
1601 - "option": option name (json-string)
1602 - "parameters": a json-array describes all parameters of the option:
1603     - "name": parameter name (json-string)
1604     - "type": parameter type (one of 'string', 'boolean', 'number',
1605               or 'size')
1606     - "help": human readable description of the parameter
1607               (json-string, optional)
1608     - "default": default value string for the parameter
1609                  (json-string, optional)
1610
1611 Example:
1612
1613 -> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } }
1614 <- { "return": [
1615         {
1616             "parameters": [
1617                 {
1618                     "name": "romfile",
1619                     "type": "string"
1620                 },
1621                 {
1622                     "name": "bootindex",
1623                     "type": "number"
1624                 }
1625             ],
1626             "option": "option-rom"
1627         }
1628      ]
1629    }
1630
1631 query-tpm
1632 ---------
1633
1634 Return information about the TPM device.
1635
1636 Arguments: None
1637
1638 Example:
1639
1640 -> { "execute": "query-tpm" }
1641 <- { "return":
1642      [
1643        { "model": "tpm-tis",
1644          "options":
1645            { "type": "passthrough",
1646              "data":
1647                { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
1648                  "path": "/dev/tpm0"
1649                }
1650            },
1651          "id": "tpm0"
1652        }
1653      ]
1654    }
1655
1656 query-tpm-models
1657 ----------------
1658
1659 Return a list of supported TPM models.
1660
1661 Arguments: None
1662
1663 Example:
1664
1665 -> { "execute": "query-tpm-models" }
1666 <- { "return": [ "tpm-tis" ] }
1667
1668 query-tpm-types
1669 ---------------
1670
1671 Return a list of supported TPM types.
1672
1673 Arguments: None
1674
1675 Example:
1676
1677 -> { "execute": "query-tpm-types" }
1678 <- { "return": [ "passthrough" ] }
1679
1680 chardev-add
1681 ----------------
1682
1683 Add a chardev.
1684
1685 Arguments:
1686
1687 - "id": the chardev's ID, must be unique (json-string)
1688 - "backend": chardev backend type + parameters
1689
1690 Examples:
1691
1692 -> { "execute" : "chardev-add",
1693      "arguments" : { "id" : "foo",
1694                      "backend" : { "type" : "null", "data" : {} } } }
1695 <- { "return": {} }
1696
1697 -> { "execute" : "chardev-add",
1698      "arguments" : { "id" : "bar",
1699                      "backend" : { "type" : "file",
1700                                    "data" : { "out" : "/tmp/bar.log" } } } }
1701 <- { "return": {} }
1702
1703 -> { "execute" : "chardev-add",
1704      "arguments" : { "id" : "baz",
1705                      "backend" : { "type" : "pty", "data" : {} } } }
1706 <- { "return": { "pty" : "/dev/pty/42" } }
1707
1708 chardev-remove
1709 --------------
1710
1711 Remove a chardev.
1712
1713 Arguments:
1714
1715 - "id": the chardev's ID, must exist and not be in use (json-string)
1716
1717 Example:
1718
1719 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
1720 <- { "return": {} }
1721
1722 query-rx-filter
1723 ---------------
1724
1725 Show rx-filter information.
1726
1727 Returns a json-array of rx-filter information for all NICs (or for the
1728 given NIC), returning an error if the given NIC doesn't exist, or
1729 given NIC doesn't support rx-filter querying, or given net client
1730 isn't a NIC.
1731
1732 The query will clear the event notification flag of each NIC, then qemu
1733 will start to emit event to QMP monitor.
1734
1735 Each array entry contains the following:
1736
1737 - "name": net client name (json-string)
1738 - "promiscuous": promiscuous mode is enabled (json-bool)
1739 - "multicast": multicast receive state (one of 'normal', 'none', 'all')
1740 - "unicast": unicast receive state  (one of 'normal', 'none', 'all')
1741 - "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0)
1742 - "broadcast-allowed": allow to receive broadcast (json-bool)
1743 - "multicast-overflow": multicast table is overflowed (json-bool)
1744 - "unicast-overflow": unicast table is overflowed (json-bool)
1745 - "main-mac": main macaddr string (json-string)
1746 - "vlan-table": a json-array of active vlan id
1747 - "unicast-table": a json-array of unicast macaddr string
1748 - "multicast-table": a json-array of multicast macaddr string
1749
1750 Example:
1751
1752 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
1753 <- { "return": [
1754         {
1755             "promiscuous": true,
1756             "name": "vnet0",
1757             "main-mac": "52:54:00:12:34:56",
1758             "unicast": "normal",
1759             "vlan": "normal",
1760             "vlan-table": [
1761                 4,
1762                 0
1763             ],
1764             "unicast-table": [
1765             ],
1766             "multicast": "normal",
1767             "multicast-overflow": false,
1768             "unicast-overflow": false,
1769             "multicast-table": [
1770                 "01:00:5e:00:00:01",
1771                 "33:33:00:00:00:01",
1772                 "33:33:ff:12:34:56"
1773             ],
1774             "broadcast-allowed": false
1775         }
1776       ]
1777    }
1778
1779 blockdev-add
1780 ------------
1781
1782 Add a block device.
1783
1784 This command is still a work in progress.  It doesn't support all
1785 block drivers among other things.  Stay away from it unless you want
1786 to help with its development.
1787
1788 For the arguments, see the QAPI schema documentation of BlockdevOptions.
1789
1790 Example (1):
1791
1792 -> { "execute": "blockdev-add",
1793     "arguments": { "driver": "qcow2",
1794                    "file": { "driver": "file",
1795                              "filename": "test.qcow2" } } }
1796 <- { "return": {} }
1797
1798 Example (2):
1799
1800 -> { "execute": "blockdev-add",
1801      "arguments": {
1802          "driver": "qcow2",
1803          "node-name": "my_disk",
1804          "discard": "unmap",
1805          "cache": {
1806              "direct": true,
1807              "writeback": true
1808          },
1809          "file": {
1810              "driver": "file",
1811              "filename": "/tmp/test.qcow2"
1812          },
1813          "backing": {
1814              "driver": "raw",
1815              "file": {
1816                  "driver": "file",
1817                  "filename": "/dev/fdset/4"
1818              }
1819          }
1820        }
1821      }
1822
1823 <- { "return": {} }
1824
1825 x-blockdev-del
1826 ------------
1827 Since 2.5
1828
1829 Deletes a block device that has been added using blockdev-add.
1830 The command will fail if the node is attached to a device or is
1831 otherwise being used.
1832
1833 This command is still a work in progress and is considered
1834 experimental. Stay away from it unless you want to help with its
1835 development.
1836
1837 Arguments:
1838
1839 - "node-name": Name of the graph node to delete (json-string)
1840
1841 Example:
1842
1843 -> { "execute": "blockdev-add",
1844      "arguments": {
1845          "driver": "qcow2",
1846          "node-name": "node0",
1847          "file": {
1848              "driver": "file",
1849              "filename": "test.qcow2"
1850          }
1851      }
1852    }
1853
1854 <- { "return": {} }
1855
1856 -> { "execute": "x-blockdev-del",
1857      "arguments": { "node-name": "node0" }
1858    }
1859 <- { "return": {} }
1860
1861 blockdev-open-tray
1862 ------------------
1863
1864 Opens a block device's tray. If there is a block driver state tree inserted as a
1865 medium, it will become inaccessible to the guest (but it will remain associated
1866 to the block device, so closing the tray will make it accessible again).
1867
1868 If the tray was already open before, this will be a no-op.
1869
1870 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
1871 which no such event will be generated, these include:
1872 - if the guest has locked the tray, @force is false and the guest does not
1873   respond to the eject request
1874 - if the BlockBackend denoted by @device does not have a guest device attached
1875   to it
1876 - if the guest device does not have an actual tray and is empty, for instance
1877   for floppy disk drives
1878
1879 Arguments:
1880
1881 - "device": block device name (deprecated, use @id instead)
1882             (json-string, optional)
1883 - "id": the name or QOM path of the guest device (json-string, optional)
1884 - "force": if false (the default), an eject request will be sent to the guest if
1885            it has locked the tray (and the tray will not be opened immediately);
1886            if true, the tray will be opened regardless of whether it is locked
1887            (json-bool, optional)
1888
1889 Example:
1890
1891 -> { "execute": "blockdev-open-tray",
1892      "arguments": { "id": "ide0-1-0" } }
1893
1894 <- { "timestamp": { "seconds": 1418751016,
1895                     "microseconds": 716996 },
1896      "event": "DEVICE_TRAY_MOVED",
1897      "data": { "device": "ide1-cd0",
1898                "id": "ide0-1-0",
1899                "tray-open": true } }
1900
1901 <- { "return": {} }
1902
1903 blockdev-close-tray
1904 -------------------
1905
1906 Closes a block device's tray. If there is a block driver state tree associated
1907 with the block device (which is currently ejected), that tree will be loaded as
1908 the medium.
1909
1910 If the tray was already closed before, this will be a no-op.
1911
1912 Arguments:
1913
1914 - "device": block device name (deprecated, use @id instead)
1915             (json-string, optional)
1916 - "id": the name or QOM path of the guest device (json-string, optional)
1917
1918 Example:
1919
1920 -> { "execute": "blockdev-close-tray",
1921      "arguments": { "id": "ide0-1-0" } }
1922
1923 <- { "timestamp": { "seconds": 1418751345,
1924                     "microseconds": 272147 },
1925      "event": "DEVICE_TRAY_MOVED",
1926      "data": { "device": "ide1-cd0",
1927                "id": "ide0-1-0",
1928                "tray-open": false } }
1929
1930 <- { "return": {} }
1931
1932 x-blockdev-remove-medium
1933 ------------------------
1934
1935 Removes a medium (a block driver state tree) from a block device. That block
1936 device's tray must currently be open (unless there is no attached guest device).
1937
1938 If the tray is open and there is no medium inserted, this will be a no-op.
1939
1940 This command is still a work in progress and is considered experimental.
1941 Stay away from it unless you want to help with its development.
1942
1943 Arguments:
1944
1945 - "device": block device name (deprecated, use @id instead)
1946             (json-string, optional)
1947 - "id": the name or QOM path of the guest device (json-string, optional)
1948
1949 Example:
1950
1951 -> { "execute": "x-blockdev-remove-medium",
1952      "arguments": { "id": "ide0-1-0" } }
1953
1954 <- { "error": { "class": "GenericError",
1955                 "desc": "Tray of device 'ide0-1-0' is not open" } }
1956
1957 -> { "execute": "blockdev-open-tray",
1958      "arguments": { "id": "ide0-1-0" } }
1959
1960 <- { "timestamp": { "seconds": 1418751627,
1961                     "microseconds": 549958 },
1962      "event": "DEVICE_TRAY_MOVED",
1963      "data": { "device": "ide1-cd0",
1964                "id": "ide0-1-0",
1965                "tray-open": true } }
1966
1967 <- { "return": {} }
1968
1969 -> { "execute": "x-blockdev-remove-medium",
1970      "arguments": { "device": "ide0-1-0" } }
1971
1972 <- { "return": {} }
1973
1974 x-blockdev-insert-medium
1975 ------------------------
1976
1977 Inserts a medium (a block driver state tree) into a block device. That block
1978 device's tray must currently be open (unless there is no attached guest device)
1979 and there must be no medium inserted already.
1980
1981 This command is still a work in progress and is considered experimental.
1982 Stay away from it unless you want to help with its development.
1983
1984 Arguments:
1985
1986 - "device": block device name (deprecated, use @id instead)
1987             (json-string, optional)
1988 - "id": the name or QOM path of the guest device (json-string, optional)
1989 - "node-name": root node of the BDS tree to insert into the block device
1990
1991 Example:
1992
1993 -> { "execute": "blockdev-add",
1994      "arguments": { { "node-name": "node0",
1995                       "driver": "raw",
1996                       "file": { "driver": "file",
1997                                 "filename": "fedora.iso" } } }
1998
1999 <- { "return": {} }
2000
2001 -> { "execute": "x-blockdev-insert-medium",
2002      "arguments": { "id": "ide0-1-0",
2003                     "node-name": "node0" } }
2004
2005 <- { "return": {} }
2006
2007 x-blockdev-change
2008 -----------------
2009
2010 Dynamically reconfigure the block driver state graph. It can be used
2011 to add, remove, insert or replace a graph node. Currently only the
2012 Quorum driver implements this feature to add or remove its child. This
2013 is useful to fix a broken quorum child.
2014
2015 If @node is specified, it will be inserted under @parent. @child
2016 may not be specified in this case. If both @parent and @child are
2017 specified but @node is not, @child will be detached from @parent.
2018
2019 Arguments:
2020 - "parent": the id or name of the parent node (json-string)
2021 - "child": the name of a child under the given parent node (json-string, optional)
2022 - "node": the name of the node that will be added (json-string, optional)
2023
2024 Note: this command is experimental, and not a stable API. It doesn't
2025 support all kinds of operations, all kinds of children, nor all block
2026 drivers.
2027
2028 Warning: The data in a new quorum child MUST be consistent with that of
2029 the rest of the array.
2030
2031 Example:
2032
2033 Add a new node to a quorum
2034 -> { "execute": "blockdev-add",
2035      "arguments": { "driver": "raw",
2036                     "node-name": "new_node",
2037                     "file": { "driver": "file",
2038                               "filename": "test.raw" } } }
2039 <- { "return": {} }
2040 -> { "execute": "x-blockdev-change",
2041      "arguments": { "parent": "disk1",
2042                     "node": "new_node" } }
2043 <- { "return": {} }
2044
2045 Delete a quorum's node
2046 -> { "execute": "x-blockdev-change",
2047      "arguments": { "parent": "disk1",
2048                     "child": "children.1" } }
2049 <- { "return": {} }
2050
2051 query-named-block-nodes
2052 -----------------------
2053
2054 Return a list of BlockDeviceInfo for all the named block driver nodes
2055
2056 Example:
2057
2058 -> { "execute": "query-named-block-nodes" }
2059 <- { "return": [ { "ro":false,
2060                    "drv":"qcow2",
2061                    "encrypted":false,
2062                    "file":"disks/test.qcow2",
2063                    "node-name": "my-node",
2064                    "backing_file_depth":1,
2065                    "bps":1000000,
2066                    "bps_rd":0,
2067                    "bps_wr":0,
2068                    "iops":1000000,
2069                    "iops_rd":0,
2070                    "iops_wr":0,
2071                    "bps_max": 8000000,
2072                    "bps_rd_max": 0,
2073                    "bps_wr_max": 0,
2074                    "iops_max": 0,
2075                    "iops_rd_max": 0,
2076                    "iops_wr_max": 0,
2077                    "iops_size": 0,
2078                    "write_threshold": 0,
2079                    "image":{
2080                       "filename":"disks/test.qcow2",
2081                       "format":"qcow2",
2082                       "virtual-size":2048000,
2083                       "backing_file":"base.qcow2",
2084                       "full-backing-filename":"disks/base.qcow2",
2085                       "backing-filename-format":"qcow2",
2086                       "snapshots":[
2087                          {
2088                             "id": "1",
2089                             "name": "snapshot1",
2090                             "vm-state-size": 0,
2091                             "date-sec": 10000200,
2092                             "date-nsec": 12,
2093                             "vm-clock-sec": 206,
2094                             "vm-clock-nsec": 30
2095                          }
2096                       ],
2097                       "backing-image":{
2098                           "filename":"disks/base.qcow2",
2099                           "format":"qcow2",
2100                           "virtual-size":2048000
2101                       }
2102                    } } ] }
2103
2104 blockdev-change-medium
2105 ----------------------
2106
2107 Changes the medium inserted into a block device by ejecting the current medium
2108 and loading a new image file which is inserted as the new medium.
2109
2110 Arguments:
2111
2112 - "device": block device name (deprecated, use @id instead)
2113             (json-string, optional)
2114 - "id": the name or QOM path of the guest device (json-string, optional)
2115 - "filename": filename of the new image (json-string)
2116 - "format": format of the new image (json-string, optional)
2117 - "read-only-mode": new read-only mode (json-string, optional)
2118           - Possible values: "retain" (default), "read-only", "read-write"
2119
2120 Examples:
2121
2122 1. Change a removable medium
2123
2124 -> { "execute": "blockdev-change-medium",
2125              "arguments": { "id": "ide0-1-0",
2126                             "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
2127                             "format": "raw" } }
2128 <- { "return": {} }
2129
2130 2. Load a read-only medium into a writable drive
2131
2132 -> { "execute": "blockdev-change-medium",
2133              "arguments": { "id": "floppyA",
2134                             "filename": "/srv/images/ro.img",
2135                             "format": "raw",
2136                             "read-only-mode": "retain" } }
2137
2138 <- { "error":
2139      { "class": "GenericError",
2140        "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
2141
2142 -> { "execute": "blockdev-change-medium",
2143              "arguments": { "id": "floppyA",
2144                             "filename": "/srv/images/ro.img",
2145                             "format": "raw",
2146                             "read-only-mode": "read-only" } }
2147
2148 <- { "return": {} }
2149
2150 query-memdev
2151 ------------
2152
2153 Show memory devices information.
2154
2155
2156 Example (1):
2157
2158 -> { "execute": "query-memdev" }
2159 <- { "return": [
2160        {
2161          "size": 536870912,
2162          "merge": false,
2163          "dump": true,
2164          "prealloc": false,
2165          "host-nodes": [0, 1],
2166          "policy": "bind"
2167        },
2168        {
2169          "id": "mem1",
2170          "size": 536870912,
2171          "merge": false,
2172          "dump": true,
2173          "prealloc": true,
2174          "host-nodes": [2, 3],
2175          "policy": "preferred"
2176        }
2177      ]
2178    }
2179
2180 query-memory-devices
2181 --------------------
2182
2183 Return a list of memory devices.
2184
2185 Example:
2186 -> { "execute": "query-memory-devices" }
2187 <- { "return": [ { "data":
2188                       { "addr": 5368709120,
2189                         "hotpluggable": true,
2190                         "hotplugged": true,
2191                         "id": "d1",
2192                         "memdev": "/objects/memX",
2193                         "node": 0,
2194                         "size": 1073741824,
2195                         "slot": 0},
2196                    "type": "dimm"
2197                  } ] }
2198
2199 query-acpi-ospm-status
2200 ----------------------
2201
2202 Return list of ACPIOSTInfo for devices that support status reporting
2203 via ACPI _OST method.
2204
2205 Example:
2206 -> { "execute": "query-acpi-ospm-status" }
2207 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
2208                  { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
2209                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
2210                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
2211    ]}
2212
2213 rtc-reset-reinjection
2214 ---------------------
2215
2216 Reset the RTC interrupt reinjection backlog.
2217
2218 Arguments: None.
2219
2220 Example:
2221
2222 -> { "execute": "rtc-reset-reinjection" }
2223 <- { "return": {} }
2224
2225 trace-event-get-state
2226 ---------------------
2227
2228 Query the state of events.
2229
2230 Arguments:
2231
2232 - "name": Event name pattern (json-string).
2233 - "vcpu": The vCPU to query, any vCPU by default (json-int, optional).
2234
2235 An event is returned if:
2236 - its name matches the "name" pattern, and
2237 - if "vcpu" is given, the event has the "vcpu" property.
2238
2239 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
2240 returning their state on the specified vCPU. Special case: if "name" is an exact
2241 match, "vcpu" is given and the event does not have the "vcpu" property, an error
2242 is returned.
2243
2244 Example:
2245
2246 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
2247 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
2248
2249 trace-event-set-state
2250 ---------------------
2251
2252 Set the state of events.
2253
2254 Arguments:
2255
2256 - "name": Event name pattern (json-string).
2257 - "enable": Whether to enable or disable the event (json-bool).
2258 - "ignore-unavailable": Whether to ignore errors for events that cannot be
2259   changed (json-bool, optional).
2260 - "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional).
2261
2262 An event's state is modified if:
2263 - its name matches the "name" pattern, and
2264 - if "vcpu" is given, the event has the "vcpu" property.
2265
2266 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
2267 setting their state on the specified vCPU. Special case: if "name" is an exact
2268 match, "vcpu" is given and the event does not have the "vcpu" property, an error
2269 is returned.
2270
2271 Example:
2272
2273 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
2274 <- { "return": {} }
2275
2276 input-send-event
2277 ----------------
2278
2279 Send input event to guest.
2280
2281 Arguments:
2282
2283 - "device": display device (json-string, optional)
2284 - "head": display head (json-int, optional)
2285 - "events": list of input events
2286
2287 The consoles are visible in the qom tree, under
2288 /backend/console[$index]. They have a device link and head property, so
2289 it is possible to map which console belongs to which device and display.
2290
2291 Example (1):
2292
2293 Press left mouse button.
2294
2295 -> { "execute": "input-send-event",
2296     "arguments": { "device": "video0",
2297                    "events": [ { "type": "btn",
2298                    "data" : { "down": true, "button": "left" } } ] } }
2299 <- { "return": {} }
2300
2301 -> { "execute": "input-send-event",
2302     "arguments": { "device": "video0",
2303                    "events": [ { "type": "btn",
2304                    "data" : { "down": false, "button": "left" } } ] } }
2305 <- { "return": {} }
2306
2307 Example (2):
2308
2309 Press ctrl-alt-del.
2310
2311 -> { "execute": "input-send-event",
2312      "arguments": { "events": [
2313         { "type": "key", "data" : { "down": true,
2314           "key": {"type": "qcode", "data": "ctrl" } } },
2315         { "type": "key", "data" : { "down": true,
2316           "key": {"type": "qcode", "data": "alt" } } },
2317         { "type": "key", "data" : { "down": true,
2318           "key": {"type": "qcode", "data": "delete" } } } ] } }
2319 <- { "return": {} }
2320
2321 Example (3):
2322
2323 Move mouse pointer to absolute coordinates (20000, 400).
2324
2325 -> { "execute": "input-send-event" ,
2326   "arguments": { "events": [
2327                { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
2328                { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
2329 <- { "return": {} }
2330
2331 block-set-write-threshold
2332 ------------
2333
2334 Change the write threshold for a block drive. The threshold is an offset,
2335 thus must be non-negative. Default is no write threshold.
2336 Setting the threshold to zero disables it.
2337
2338 Arguments:
2339
2340 - "node-name": the node name in the block driver state graph (json-string)
2341 - "write-threshold": the write threshold in bytes (json-int)
2342
2343 Example:
2344
2345 -> { "execute": "block-set-write-threshold",
2346   "arguments": { "node-name": "mydev",
2347                  "write-threshold": 17179869184 } }
2348 <- { "return": {} }
2349
2350 Show rocker switch
2351 ------------------
2352
2353 Arguments:
2354
2355 - "name": switch name
2356
2357 Example:
2358
2359 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
2360 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
2361
2362 Show rocker switch ports
2363 ------------------------
2364
2365 Arguments:
2366
2367 - "name": switch name
2368
2369 Example:
2370
2371 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
2372 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
2373                   "autoneg": "off", "link-up": true, "speed": 10000},
2374                  {"duplex": "full", "enabled": true, "name": "sw1.2",
2375                   "autoneg": "off", "link-up": true, "speed": 10000}
2376    ]}
2377
2378 Show rocker switch OF-DPA flow tables
2379 -------------------------------------
2380
2381 Arguments:
2382
2383 - "name": switch name
2384 - "tbl-id": (optional) flow table ID
2385
2386 Example:
2387
2388 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
2389 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
2390                   "hits": 138,
2391                   "cookie": 0,
2392                   "action": {"goto-tbl": 10},
2393                   "mask": {"in-pport": 4294901760}
2394                  },
2395                  {...more...},
2396    ]}
2397
2398 Show rocker OF-DPA group tables
2399 -------------------------------
2400
2401 Arguments:
2402
2403 - "name": switch name
2404 - "type": (optional) group type
2405
2406 Example:
2407
2408 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
2409 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
2410                   "pop-vlan": 1, "id": 251723778},
2411                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
2412                   "pop-vlan": 1, "id": 251723776},
2413                  {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
2414                   "pop-vlan": 1, "id": 251658241},
2415                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
2416                   "pop-vlan": 1, "id": 251658240}
2417    ]}
2418
2419 query-gic-capabilities
2420 ---------------
2421
2422 Return a list of GICCapability objects, describing supported GIC
2423 (Generic Interrupt Controller) versions.
2424
2425 Arguments: None
2426
2427 Example:
2428
2429 -> { "execute": "query-gic-capabilities" }
2430 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
2431                 { "version": 3, "emulated": false, "kernel": true } ] }
2432
2433 Show existing/possible CPUs
2434 ---------------------------
2435
2436 Arguments: None.
2437
2438 Example for pseries machine type started with
2439 -smp 2,cores=2,maxcpus=4 -cpu POWER8:
2440
2441 -> { "execute": "query-hotpluggable-cpus" }
2442 <- {"return": [
2443      { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
2444        "vcpus-count": 1 },
2445      { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
2446        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
2447    ]}'
2448
2449 Example for pc machine type started with
2450 -smp 1,maxcpus=2:
2451     -> { "execute": "query-hotpluggable-cpus" }
2452     <- {"return": [
2453          {
2454             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
2455             "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
2456          },
2457          {
2458             "qom-path": "/machine/unattached/device[0]",
2459             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
2460             "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
2461          }
2462        ]}