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