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 blockdev-add
1167 ------------
1168
1169 Add a block device.
1170
1171 This command is still a work in progress.  It doesn't support all
1172 block drivers among other things.  Stay away from it unless you want
1173 to help with its development.
1174
1175 For the arguments, see the QAPI schema documentation of BlockdevOptions.
1176
1177 Example (1):
1178
1179 -> { "execute": "blockdev-add",
1180     "arguments": { "driver": "qcow2",
1181                    "file": { "driver": "file",
1182                              "filename": "test.qcow2" } } }
1183 <- { "return": {} }
1184
1185 Example (2):
1186
1187 -> { "execute": "blockdev-add",
1188      "arguments": {
1189          "driver": "qcow2",
1190          "node-name": "my_disk",
1191          "discard": "unmap",
1192          "cache": {
1193              "direct": true,
1194              "writeback": true
1195          },
1196          "file": {
1197              "driver": "file",
1198              "filename": "/tmp/test.qcow2"
1199          },
1200          "backing": {
1201              "driver": "raw",
1202              "file": {
1203                  "driver": "file",
1204                  "filename": "/dev/fdset/4"
1205              }
1206          }
1207        }
1208      }
1209
1210 <- { "return": {} }
1211
1212 x-blockdev-del
1213 ------------
1214 Since 2.5
1215
1216 Deletes a block device that has been added using blockdev-add.
1217 The command will fail if the node is attached to a device or is
1218 otherwise being used.
1219
1220 This command is still a work in progress and is considered
1221 experimental. Stay away from it unless you want to help with its
1222 development.
1223
1224 Arguments:
1225
1226 - "node-name": Name of the graph node to delete (json-string)
1227
1228 Example:
1229
1230 -> { "execute": "blockdev-add",
1231      "arguments": {
1232          "driver": "qcow2",
1233          "node-name": "node0",
1234          "file": {
1235              "driver": "file",
1236              "filename": "test.qcow2"
1237          }
1238      }
1239    }
1240
1241 <- { "return": {} }
1242
1243 -> { "execute": "x-blockdev-del",
1244      "arguments": { "node-name": "node0" }
1245    }
1246 <- { "return": {} }
1247
1248 blockdev-open-tray
1249 ------------------
1250
1251 Opens a block device's tray. If there is a block driver state tree inserted as a
1252 medium, it will become inaccessible to the guest (but it will remain associated
1253 to the block device, so closing the tray will make it accessible again).
1254
1255 If the tray was already open before, this will be a no-op.
1256
1257 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
1258 which no such event will be generated, these include:
1259 - if the guest has locked the tray, @force is false and the guest does not
1260   respond to the eject request
1261 - if the BlockBackend denoted by @device does not have a guest device attached
1262   to it
1263 - if the guest device does not have an actual tray and is empty, for instance
1264   for floppy disk drives
1265
1266 Arguments:
1267
1268 - "device": block device name (deprecated, use @id instead)
1269             (json-string, optional)
1270 - "id": the name or QOM path of the guest device (json-string, optional)
1271 - "force": if false (the default), an eject request will be sent to the guest if
1272            it has locked the tray (and the tray will not be opened immediately);
1273            if true, the tray will be opened regardless of whether it is locked
1274            (json-bool, optional)
1275
1276 Example:
1277
1278 -> { "execute": "blockdev-open-tray",
1279      "arguments": { "id": "ide0-1-0" } }
1280
1281 <- { "timestamp": { "seconds": 1418751016,
1282                     "microseconds": 716996 },
1283      "event": "DEVICE_TRAY_MOVED",
1284      "data": { "device": "ide1-cd0",
1285                "id": "ide0-1-0",
1286                "tray-open": true } }
1287
1288 <- { "return": {} }
1289
1290 blockdev-close-tray
1291 -------------------
1292
1293 Closes a block device's tray. If there is a block driver state tree associated
1294 with the block device (which is currently ejected), that tree will be loaded as
1295 the medium.
1296
1297 If the tray was already closed before, this will be a no-op.
1298
1299 Arguments:
1300
1301 - "device": block device name (deprecated, use @id instead)
1302             (json-string, optional)
1303 - "id": the name or QOM path of the guest device (json-string, optional)
1304
1305 Example:
1306
1307 -> { "execute": "blockdev-close-tray",
1308      "arguments": { "id": "ide0-1-0" } }
1309
1310 <- { "timestamp": { "seconds": 1418751345,
1311                     "microseconds": 272147 },
1312      "event": "DEVICE_TRAY_MOVED",
1313      "data": { "device": "ide1-cd0",
1314                "id": "ide0-1-0",
1315                "tray-open": false } }
1316
1317 <- { "return": {} }
1318
1319 x-blockdev-remove-medium
1320 ------------------------
1321
1322 Removes a medium (a block driver state tree) from a block device. That block
1323 device's tray must currently be open (unless there is no attached guest device).
1324
1325 If the tray is open and there is no medium inserted, this will be a no-op.
1326
1327 This command is still a work in progress and is considered experimental.
1328 Stay away from it unless you want to help with its development.
1329
1330 Arguments:
1331
1332 - "device": block device name (deprecated, use @id instead)
1333             (json-string, optional)
1334 - "id": the name or QOM path of the guest device (json-string, optional)
1335
1336 Example:
1337
1338 -> { "execute": "x-blockdev-remove-medium",
1339      "arguments": { "id": "ide0-1-0" } }
1340
1341 <- { "error": { "class": "GenericError",
1342                 "desc": "Tray of device 'ide0-1-0' is not open" } }
1343
1344 -> { "execute": "blockdev-open-tray",
1345      "arguments": { "id": "ide0-1-0" } }
1346
1347 <- { "timestamp": { "seconds": 1418751627,
1348                     "microseconds": 549958 },
1349      "event": "DEVICE_TRAY_MOVED",
1350      "data": { "device": "ide1-cd0",
1351                "id": "ide0-1-0",
1352                "tray-open": true } }
1353
1354 <- { "return": {} }
1355
1356 -> { "execute": "x-blockdev-remove-medium",
1357      "arguments": { "device": "ide0-1-0" } }
1358
1359 <- { "return": {} }
1360
1361 x-blockdev-insert-medium
1362 ------------------------
1363
1364 Inserts a medium (a block driver state tree) into a block device. That block
1365 device's tray must currently be open (unless there is no attached guest device)
1366 and there must be no medium inserted already.
1367
1368 This command is still a work in progress and is considered experimental.
1369 Stay away from it unless you want to help with its development.
1370
1371 Arguments:
1372
1373 - "device": block device name (deprecated, use @id instead)
1374             (json-string, optional)
1375 - "id": the name or QOM path of the guest device (json-string, optional)
1376 - "node-name": root node of the BDS tree to insert into the block device
1377
1378 Example:
1379
1380 -> { "execute": "blockdev-add",
1381      "arguments": { { "node-name": "node0",
1382                       "driver": "raw",
1383                       "file": { "driver": "file",
1384                                 "filename": "fedora.iso" } } }
1385
1386 <- { "return": {} }
1387
1388 -> { "execute": "x-blockdev-insert-medium",
1389      "arguments": { "id": "ide0-1-0",
1390                     "node-name": "node0" } }
1391
1392 <- { "return": {} }
1393
1394 x-blockdev-change
1395 -----------------
1396
1397 Dynamically reconfigure the block driver state graph. It can be used
1398 to add, remove, insert or replace a graph node. Currently only the
1399 Quorum driver implements this feature to add or remove its child. This
1400 is useful to fix a broken quorum child.
1401
1402 If @node is specified, it will be inserted under @parent. @child
1403 may not be specified in this case. If both @parent and @child are
1404 specified but @node is not, @child will be detached from @parent.
1405
1406 Arguments:
1407 - "parent": the id or name of the parent node (json-string)
1408 - "child": the name of a child under the given parent node (json-string, optional)
1409 - "node": the name of the node that will be added (json-string, optional)
1410
1411 Note: this command is experimental, and not a stable API. It doesn't
1412 support all kinds of operations, all kinds of children, nor all block
1413 drivers.
1414
1415 Warning: The data in a new quorum child MUST be consistent with that of
1416 the rest of the array.
1417
1418 Example:
1419
1420 Add a new node to a quorum
1421 -> { "execute": "blockdev-add",
1422      "arguments": { "driver": "raw",
1423                     "node-name": "new_node",
1424                     "file": { "driver": "file",
1425                               "filename": "test.raw" } } }
1426 <- { "return": {} }
1427 -> { "execute": "x-blockdev-change",
1428      "arguments": { "parent": "disk1",
1429                     "node": "new_node" } }
1430 <- { "return": {} }
1431
1432 Delete a quorum's node
1433 -> { "execute": "x-blockdev-change",
1434      "arguments": { "parent": "disk1",
1435                     "child": "children.1" } }
1436 <- { "return": {} }
1437
1438 query-named-block-nodes
1439 -----------------------
1440
1441 Return a list of BlockDeviceInfo for all the named block driver nodes
1442
1443 Example:
1444
1445 -> { "execute": "query-named-block-nodes" }
1446 <- { "return": [ { "ro":false,
1447                    "drv":"qcow2",
1448                    "encrypted":false,
1449                    "file":"disks/test.qcow2",
1450                    "node-name": "my-node",
1451                    "backing_file_depth":1,
1452                    "bps":1000000,
1453                    "bps_rd":0,
1454                    "bps_wr":0,
1455                    "iops":1000000,
1456                    "iops_rd":0,
1457                    "iops_wr":0,
1458                    "bps_max": 8000000,
1459                    "bps_rd_max": 0,
1460                    "bps_wr_max": 0,
1461                    "iops_max": 0,
1462                    "iops_rd_max": 0,
1463                    "iops_wr_max": 0,
1464                    "iops_size": 0,
1465                    "write_threshold": 0,
1466                    "image":{
1467                       "filename":"disks/test.qcow2",
1468                       "format":"qcow2",
1469                       "virtual-size":2048000,
1470                       "backing_file":"base.qcow2",
1471                       "full-backing-filename":"disks/base.qcow2",
1472                       "backing-filename-format":"qcow2",
1473                       "snapshots":[
1474                          {
1475                             "id": "1",
1476                             "name": "snapshot1",
1477                             "vm-state-size": 0,
1478                             "date-sec": 10000200,
1479                             "date-nsec": 12,
1480                             "vm-clock-sec": 206,
1481                             "vm-clock-nsec": 30
1482                          }
1483                       ],
1484                       "backing-image":{
1485                           "filename":"disks/base.qcow2",
1486                           "format":"qcow2",
1487                           "virtual-size":2048000
1488                       }
1489                    } } ] }
1490
1491 blockdev-change-medium
1492 ----------------------
1493
1494 Changes the medium inserted into a block device by ejecting the current medium
1495 and loading a new image file which is inserted as the new medium.
1496
1497 Arguments:
1498
1499 - "device": block device name (deprecated, use @id instead)
1500             (json-string, optional)
1501 - "id": the name or QOM path of the guest device (json-string, optional)
1502 - "filename": filename of the new image (json-string)
1503 - "format": format of the new image (json-string, optional)
1504 - "read-only-mode": new read-only mode (json-string, optional)
1505           - Possible values: "retain" (default), "read-only", "read-write"
1506
1507 Examples:
1508
1509 1. Change a removable medium
1510
1511 -> { "execute": "blockdev-change-medium",
1512              "arguments": { "id": "ide0-1-0",
1513                             "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
1514                             "format": "raw" } }
1515 <- { "return": {} }
1516
1517 2. Load a read-only medium into a writable drive
1518
1519 -> { "execute": "blockdev-change-medium",
1520              "arguments": { "id": "floppyA",
1521                             "filename": "/srv/images/ro.img",
1522                             "format": "raw",
1523                             "read-only-mode": "retain" } }
1524
1525 <- { "error":
1526      { "class": "GenericError",
1527        "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
1528
1529 -> { "execute": "blockdev-change-medium",
1530              "arguments": { "id": "floppyA",
1531                             "filename": "/srv/images/ro.img",
1532                             "format": "raw",
1533                             "read-only-mode": "read-only" } }
1534
1535 <- { "return": {} }
1536
1537 query-acpi-ospm-status
1538 ----------------------
1539
1540 Return list of ACPIOSTInfo for devices that support status reporting
1541 via ACPI _OST method.
1542
1543 Example:
1544 -> { "execute": "query-acpi-ospm-status" }
1545 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
1546                  { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
1547                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
1548                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
1549    ]}
1550
1551 rtc-reset-reinjection
1552 ---------------------
1553
1554 Reset the RTC interrupt reinjection backlog.
1555
1556 Arguments: None.
1557
1558 Example:
1559
1560 -> { "execute": "rtc-reset-reinjection" }
1561 <- { "return": {} }
1562
1563 trace-event-get-state
1564 ---------------------
1565
1566 Query the state of events.
1567
1568 Arguments:
1569
1570 - "name": Event name pattern (json-string).
1571 - "vcpu": The vCPU to query, any vCPU by default (json-int, optional).
1572
1573 An event is returned if:
1574 - its name matches the "name" pattern, and
1575 - if "vcpu" is given, the event has the "vcpu" property.
1576
1577 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
1578 returning their state on the specified vCPU. Special case: if "name" is an exact
1579 match, "vcpu" is given and the event does not have the "vcpu" property, an error
1580 is returned.
1581
1582 Example:
1583
1584 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
1585 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
1586
1587 trace-event-set-state
1588 ---------------------
1589
1590 Set the state of events.
1591
1592 Arguments:
1593
1594 - "name": Event name pattern (json-string).
1595 - "enable": Whether to enable or disable the event (json-bool).
1596 - "ignore-unavailable": Whether to ignore errors for events that cannot be
1597   changed (json-bool, optional).
1598 - "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional).
1599
1600 An event's state is modified if:
1601 - its name matches the "name" pattern, and
1602 - if "vcpu" is given, the event has the "vcpu" property.
1603
1604 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
1605 setting their state on the specified vCPU. Special case: if "name" is an exact
1606 match, "vcpu" is given and the event does not have the "vcpu" property, an error
1607 is returned.
1608
1609 Example:
1610
1611 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
1612 <- { "return": {} }
1613
1614 block-set-write-threshold
1615 ------------
1616
1617 Change the write threshold for a block drive. The threshold is an offset,
1618 thus must be non-negative. Default is no write threshold.
1619 Setting the threshold to zero disables it.
1620
1621 Arguments:
1622
1623 - "node-name": the node name in the block driver state graph (json-string)
1624 - "write-threshold": the write threshold in bytes (json-int)
1625
1626 Example:
1627
1628 -> { "execute": "block-set-write-threshold",
1629   "arguments": { "node-name": "mydev",
1630                  "write-threshold": 17179869184 } }
1631 <- { "return": {} }
1632
1633 Show rocker switch
1634 ------------------
1635
1636 Arguments:
1637
1638 - "name": switch name
1639
1640 Example:
1641
1642 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
1643 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
1644
1645 Show rocker switch ports
1646 ------------------------
1647
1648 Arguments:
1649
1650 - "name": switch name
1651
1652 Example:
1653
1654 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
1655 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
1656                   "autoneg": "off", "link-up": true, "speed": 10000},
1657                  {"duplex": "full", "enabled": true, "name": "sw1.2",
1658                   "autoneg": "off", "link-up": true, "speed": 10000}
1659    ]}
1660
1661 Show rocker switch OF-DPA flow tables
1662 -------------------------------------
1663
1664 Arguments:
1665
1666 - "name": switch name
1667 - "tbl-id": (optional) flow table ID
1668
1669 Example:
1670
1671 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
1672 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
1673                   "hits": 138,
1674                   "cookie": 0,
1675                   "action": {"goto-tbl": 10},
1676                   "mask": {"in-pport": 4294901760}
1677                  },
1678                  {...more...},
1679    ]}
1680
1681 Show rocker OF-DPA group tables
1682 -------------------------------
1683
1684 Arguments:
1685
1686 - "name": switch name
1687 - "type": (optional) group type
1688
1689 Example:
1690
1691 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
1692 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
1693                   "pop-vlan": 1, "id": 251723778},
1694                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
1695                   "pop-vlan": 1, "id": 251723776},
1696                  {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
1697                   "pop-vlan": 1, "id": 251658241},
1698                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
1699                   "pop-vlan": 1, "id": 251658240}
1700    ]}
1701
1702 query-gic-capabilities
1703 ---------------
1704
1705 Return a list of GICCapability objects, describing supported GIC
1706 (Generic Interrupt Controller) versions.
1707
1708 Arguments: None
1709
1710 Example:
1711
1712 -> { "execute": "query-gic-capabilities" }
1713 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
1714                 { "version": 3, "emulated": false, "kernel": true } ] }
1715
1716 Show existing/possible CPUs
1717 ---------------------------
1718
1719 Arguments: None.
1720
1721 Example for pseries machine type started with
1722 -smp 2,cores=2,maxcpus=4 -cpu POWER8:
1723
1724 -> { "execute": "query-hotpluggable-cpus" }
1725 <- {"return": [
1726      { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
1727        "vcpus-count": 1 },
1728      { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
1729        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
1730    ]}'
1731
1732 Example for pc machine type started with
1733 -smp 1,maxcpus=2:
1734     -> { "execute": "query-hotpluggable-cpus" }
1735     <- {"return": [
1736          {
1737             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
1738             "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
1739          },
1740          {
1741             "qom-path": "/machine/unattached/device[0]",
1742             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
1743             "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
1744          }
1745        ]}