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-stream
 173 ------------
 174
 175 Copy data from a backing file into a block device.
 176
 177 Arguments:
 178
 179 - "job-id": Identifier for the newly-created block job. If omitted,
 180             the device name will be used. (json-string, optional)
 181 - "device": The device name or node-name of a root node (json-string)
 182 - "base": The file name of the backing image above which copying starts.
 183           It cannot be set if 'base-node' is also set (json-string, optional)
 184 - "base-node": the node name of the backing image above which copying starts.
 185                It cannot be set if 'base' is also set.
 186                (json-string, optional) (Since 2.8)
 187 - "backing-file": The backing file string to write into the active layer. This
 188                   filename is not validated.
 189
 190                   If a pathname string is such that it cannot be resolved by
 191                   QEMU, that means that subsequent QMP or HMP commands must use
 192                   node-names for the image in question, as filename lookup
 193                   methods will fail.
 194
 195                   If not specified, QEMU will automatically determine the
 196                   backing file string to use, or error out if there is no
 197                   obvious choice.  Care should be taken when specifying the
 198                   string, to specify a valid filename or protocol.
 199                   (json-string, optional) (Since 2.1)
 200 - "speed":  the maximum speed, in bytes per second (json-int, optional)
 201 - "on-error": the action to take on an error (default 'report').  'stop' and
 202               'enospc' can only be used if the block device supports io-status.
 203               (json-string, optional) (Since 2.1)
 204
 205 Example:
 206
 207 -> { "execute": "block-stream", "arguments": { "device": "virtio0",
 208                                                "base": "/tmp/master.qcow2" } }
 209 <- { "return": {} }
 210
 211 drive-backup
 212 ------------
 213
 214 Start a point-in-time copy of a block device to a new destination.  The
 215 status of ongoing drive-backup operations can be checked with
 216 query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
 217 The operation can be stopped before it has completed using the
 218 block-job-cancel command.
 219
 220 Arguments:
 221
 222 - "job-id": Identifier for the newly-created block job. If omitted,
 223             the device name will be used. (json-string, optional)
 224 - "device": the device name or node-name of a root node which should be copied.
 225             (json-string)
 226 - "target": the target of the new image. If the file exists, or if it is a
 227             device, the existing file/device will be used as the new
 228             destination.  If it does not exist, a new file will be created.
 229             (json-string)
 230 - "format": the format of the new destination, default is to probe if 'mode' is
 231             'existing', else the format of the source
 232             (json-string, optional)
 233 - "sync": what parts of the disk image should be copied to the destination;
 234   possibilities include "full" for all the disk, "top" for only the sectors
 235   allocated in the topmost image, "incremental" for only the dirty sectors in
 236   the bitmap, or "none" to only replicate new I/O (MirrorSyncMode).
 237 - "bitmap": dirty bitmap name for sync==incremental. Must be present if sync
 238             is "incremental", must NOT be present otherwise.
 239 - "mode": whether and how QEMU should create a new image
 240           (NewImageMode, optional, default 'absolute-paths')
 241 - "speed": the maximum speed, in bytes per second (json-int, optional)
 242 - "compress": true to compress data, if the target format supports it.
 243               (json-bool, optional, default false)
 244 - "on-source-error": the action to take on an error on the source, default
 245                      'report'.  'stop' and 'enospc' can only be used
 246                      if the block device supports io-status.
 247                      (BlockdevOnError, optional)
 248 - "on-target-error": the action to take on an error on the target, default
 249                      'report' (no limitations, since this applies to
 250                      a different block device than device).
 251                      (BlockdevOnError, optional)
 252
 253 Example:
 254 -> { "execute": "drive-backup", "arguments": { "device": "drive0",
 255                                                "sync": "full",
 256                                                "target": "backup.img" } }
 257 <- { "return": {} }
 258
 259 blockdev-backup
 260 ---------------
 261
 262 The device version of drive-backup: this command takes an existing named device
 263 as backup target.
 264
 265 Arguments:
 266
 267 - "job-id": Identifier for the newly-created block job. If omitted,
 268             the device name will be used. (json-string, optional)
 269 - "device": the device name or node-name of a root node which should be copied.
 270             (json-string)
 271 - "target": the name of the backup target device. (json-string)
 272 - "sync": what parts of the disk image should be copied to the destination;
 273           possibilities include "full" for all the disk, "top" for only the
 274           sectors allocated in the topmost image, or "none" to only replicate
 275           new I/O (MirrorSyncMode).
 276 - "speed": the maximum speed, in bytes per second (json-int, optional)
 277 - "compress": true to compress data, if the target format supports it.
 278               (json-bool, optional, default false)
 279 - "on-source-error": the action to take on an error on the source, default
 280                      'report'.  'stop' and 'enospc' can only be used
 281                      if the block device supports io-status.
 282                      (BlockdevOnError, optional)
 283 - "on-target-error": the action to take on an error on the target, default
 284                      'report' (no limitations, since this applies to
 285                      a different block device than device).
 286                      (BlockdevOnError, optional)
 287
 288 Example:
 289 -> { "execute": "blockdev-backup", "arguments": { "device": "src-id",
 290                                                   "sync": "full",
 291                                                   "target": "tgt-id" } }
 292 <- { "return": {} }
 293
 294 block-dirty-bitmap-add
 295 ----------------------
 296 Since 2.4
 297
 298 Create a dirty bitmap with a name on the device, and start tracking the writes.
 299
 300 Arguments:
 301
 302 - "node": device/node on which to create dirty bitmap (json-string)
 303 - "name": name of the new dirty bitmap (json-string)
 304 - "granularity": granularity to track writes with (int, optional)
 305
 306 Example:
 307
 308 -> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0",
 309                                                    "name": "bitmap0" } }
 310 <- { "return": {} }
 311
 312 block-dirty-bitmap-remove
 313 -------------------------
 314 Since 2.4
 315
 316 Stop write tracking and remove the dirty bitmap that was created with
 317 block-dirty-bitmap-add.
 318
 319 Arguments:
 320
 321 - "node": device/node on which to remove dirty bitmap (json-string)
 322 - "name": name of the dirty bitmap to remove (json-string)
 323
 324 Example:
 325
 326 -> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0",
 327                                                       "name": "bitmap0" } }
 328 <- { "return": {} }
 329
 330 block-dirty-bitmap-clear
 331 ------------------------
 332 Since 2.4
 333
 334 Reset the dirty bitmap associated with a node so that an incremental backup
 335 from this point in time forward will only backup clusters modified after this
 336 clear operation.
 337
 338 Arguments:
 339
 340 - "node": device/node on which to remove dirty bitmap (json-string)
 341 - "name": name of the dirty bitmap to remove (json-string)
 342
 343 Example:
 344
 345 -> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0",
 346                                                            "name": "bitmap0" } }
 347 <- { "return": {} }
 348
 349 blockdev-snapshot-internal-sync
 350 -------------------------------
 351
 352 Synchronously take an internal snapshot of a block device when the format of
 353 image used supports it.  If the name is an empty string, or a snapshot with
 354 name already exists, the operation will fail.
 355
 356 Arguments:
 357
 358 - "device": the device name or node-name of a root node to snapshot
 359             (json-string)
 360 - "name": name of the new snapshot (json-string)
 361
 362 Example:
 363
 364 -> { "execute": "blockdev-snapshot-internal-sync",
 365                 "arguments": { "device": "ide-hd0",
 366                                "name": "snapshot0" }
 367    }
 368 <- { "return": {} }
 369
 370 blockdev-snapshot-delete-internal-sync
 371 --------------------------------------
 372
 373 Synchronously delete an internal snapshot of a block device when the format of
 374 image used supports it.  The snapshot is identified by name or id or both.  One
 375 of name or id is required.  If the snapshot is not found, the operation will
 376 fail.
 377
 378 Arguments:
 379
 380 - "device": the device name or node-name of a root node (json-string)
 381 - "id": ID of the snapshot (json-string, optional)
 382 - "name": name of the snapshot (json-string, optional)
 383
 384 Example:
 385
 386 -> { "execute": "blockdev-snapshot-delete-internal-sync",
 387                 "arguments": { "device": "ide-hd0",
 388                                "name": "snapshot0" }
 389    }
 390 <- { "return": {
 391                    "id": "1",
 392                    "name": "snapshot0",
 393                    "vm-state-size": 0,
 394                    "date-sec": 1000012,
 395                    "date-nsec": 10,
 396                    "vm-clock-sec": 100,
 397                    "vm-clock-nsec": 20
 398      }
 399    }
 400
 401 drive-mirror
 402 ------------
 403
 404 Start mirroring a block device's writes to a new destination. target
 405 specifies the target of the new image. If the file exists, or if it is
 406 a device, it will be used as the new destination for writes. If it does not
 407 exist, a new file will be created. format specifies the format of the
 408 mirror image, default is to probe if mode='existing', else the format
 409 of the source.
 410
 411 Arguments:
 412
 413 - "job-id": Identifier for the newly-created block job. If omitted,
 414             the device name will be used. (json-string, optional)
 415 - "device": the device name or node-name of a root node whose writes should be
 416             mirrored. (json-string)
 417 - "target": name of new image file (json-string)
 418 - "format": format of new image (json-string, optional)
 419 - "node-name": the name of the new block driver state in the node graph
 420                (json-string, optional)
 421 - "replaces": the block driver node name to replace when finished
 422               (json-string, optional)
 423 - "mode": how an image file should be created into the target
 424   file/device (NewImageMode, optional, default 'absolute-paths')
 425 - "speed": maximum speed of the streaming job, in bytes per second
 426   (json-int)
 427 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
 428 - "buf-size": maximum amount of data in flight from source to target, in bytes
 429   (json-int, default 10M)
 430 - "sync": what parts of the disk image should be copied to the destination;
 431   possibilities include "full" for all the disk, "top" for only the sectors
 432   allocated in the topmost image, or "none" to only replicate new I/O
 433   (MirrorSyncMode).
 434 - "on-source-error": the action to take on an error on the source
 435   (BlockdevOnError, default 'report')
 436 - "on-target-error": the action to take on an error on the target
 437   (BlockdevOnError, default 'report')
 438 - "unmap": whether the target sectors should be discarded where source has only
 439   zeroes. (json-bool, optional, default true)
 440
 441 The default value of the granularity is the image cluster size clamped
 442 between 4096 and 65536, if the image format defines one.  If the format
 443 does not define a cluster size, the default value of the granularity
 444 is 65536.
 445
 446
 447 Example:
 448
 449 -> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
 450                                                "target": "/some/place/my-image",
 451                                                "sync": "full",
 452                                                "format": "qcow2" } }
 453 <- { "return": {} }
 454
 455 blockdev-mirror
 456 ------------
 457
 458 Start mirroring a block device's writes to another block device. target
 459 specifies the target of mirror operation.
 460
 461 Arguments:
 462
 463 - "job-id": Identifier for the newly-created block job. If omitted,
 464             the device name will be used. (json-string, optional)
 465 - "device": The device name or node-name of a root node whose writes should be
 466             mirrored (json-string)
 467 - "target": device name to mirror to (json-string)
 468 - "replaces": the block driver node name to replace when finished
 469               (json-string, optional)
 470 - "speed": maximum speed of the streaming job, in bytes per second
 471   (json-int)
 472 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
 473 - "buf_size": maximum amount of data in flight from source to target, in bytes
 474   (json-int, default 10M)
 475 - "sync": what parts of the disk image should be copied to the destination;
 476   possibilities include "full" for all the disk, "top" for only the sectors
 477   allocated in the topmost image, or "none" to only replicate new I/O
 478   (MirrorSyncMode).
 479 - "on-source-error": the action to take on an error on the source
 480   (BlockdevOnError, default 'report')
 481 - "on-target-error": the action to take on an error on the target
 482   (BlockdevOnError, default 'report')
 483
 484 The default value of the granularity is the image cluster size clamped
 485 between 4096 and 65536, if the image format defines one.  If the format
 486 does not define a cluster size, the default value of the granularity
 487 is 65536.
 488
 489 Example:
 490
 491 -> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
 492                                                   "target": "target0",
 493                                                   "sync": "full" } }
 494 <- { "return": {} }
 495
 496 block_set_io_throttle
 497 ------------
 498
 499 Change I/O throttle limits for a block drive.
 500
 501 Arguments:
 502
 503 - "device": block device name (deprecated, use @id instead)
 504             (json-string, optional)
 505 - "id": the name or QOM path of the guest device (json-string, optional)
 506 - "bps": total throughput limit in bytes per second (json-int)
 507 - "bps_rd": read throughput limit in bytes per second (json-int)
 508 - "bps_wr": write throughput limit in bytes per second (json-int)
 509 - "iops": total I/O operations per second (json-int)
 510 - "iops_rd": read I/O operations per second (json-int)
 511 - "iops_wr": write I/O operations per second (json-int)
 512 - "bps_max": total throughput limit during bursts, in bytes (json-int, optional)
 513 - "bps_rd_max": read throughput limit during bursts, in bytes (json-int, optional)
 514 - "bps_wr_max": write throughput limit during bursts, in bytes (json-int, optional)
 515 - "iops_max": total I/O operations per second during bursts (json-int, optional)
 516 - "iops_rd_max": read I/O operations per second during bursts (json-int, optional)
 517 - "iops_wr_max": write I/O operations per second during bursts (json-int, optional)
 518 - "bps_max_length": maximum length of the @bps_max burst period, in seconds (json-int, optional)
 519 - "bps_rd_max_length": maximum length of the @bps_rd_max burst period, in seconds (json-int, optional)
 520 - "bps_wr_max_length": maximum length of the @bps_wr_max burst period, in seconds (json-int, optional)
 521 - "iops_max_length": maximum length of the @iops_max burst period, in seconds (json-int, optional)
 522 - "iops_rd_max_length": maximum length of the @iops_rd_max burst period, in seconds (json-int, optional)
 523 - "iops_wr_max_length": maximum length of the @iops_wr_max burst period, in seconds (json-int, optional)
 524 - "iops_size":  I/O size in bytes when limiting (json-int, optional)
 525 - "group": throttle group name (json-string, optional)
 526
 527 Example:
 528
 529 -> { "execute": "block_set_io_throttle", "arguments": { "id": "ide0-1-0",
 530                                                "bps": 1000000,
 531                                                "bps_rd": 0,
 532                                                "bps_wr": 0,
 533                                                "iops": 0,
 534                                                "iops_rd": 0,
 535                                                "iops_wr": 0,
 536                                                "bps_max": 8000000,
 537                                                "bps_rd_max": 0,
 538                                                "bps_wr_max": 0,
 539                                                "iops_max": 0,
 540                                                "iops_rd_max": 0,
 541                                                "iops_wr_max": 0,
 542                                                "bps_max_length": 60,
 543                                                "iops_size": 0 } }
 544 <- { "return": {} }
 545
 546 qmp_capabilities
 547 ----------------
 548
 549 Enable QMP capabilities.
 550
 551 Arguments: None.
 552
 553 Example:
 554
 555 -> { "execute": "qmp_capabilities" }
 556 <- { "return": {} }
 557
 558 Note: This command must be issued before issuing any other command.
 559
 560 3. Query Commands
 561 =================
 562
 563
 564 query-version
 565 -------------
 566
 567 Show QEMU version.
 568
 569 Return a json-object with the following information:
 570
 571 - "qemu": A json-object containing three integer values:
 572     - "major": QEMU's major version (json-int)
 573     - "minor": QEMU's minor version (json-int)
 574     - "micro": QEMU's micro version (json-int)
 575 - "package": package's version (json-string)
 576
 577 Example:
 578
 579 -> { "execute": "query-version" }
 580 <- {
 581       "return":{
 582          "qemu":{
 583             "major":0,
 584             "minor":11,
 585             "micro":5
 586          },
 587          "package":""
 588       }
 589    }
 590
 591 query-commands
 592 --------------
 593
 594 List QMP available commands.
 595
 596 Each command is represented by a json-object, the returned value is a json-array
 597 of all commands.
 598
 599 Each json-object contain:
 600
 601 - "name": command's name (json-string)
 602
 603 Example:
 604
 605 -> { "execute": "query-commands" }
 606 <- {
 607       "return":[
 608          {
 609             "name":"query-balloon"
 610          },
 611          {
 612             "name":"system_powerdown"
 613          }
 614       ]
 615    }
 616
 617 Note: This example has been shortened as the real response is too long.
 618
 619 query-qmp-schema
 620 ----------------
 621
 622 Return the QMP wire schema.  The returned value is a json-array of
 623 named schema entities.  Entities are commands, events and various
 624 types.  See docs/qapi-code-gen.txt for information on their structure
 625 and intended use.
 626
 627 blockdev-add
 628 ------------
 629
 630 Add a block device.
 631
 632 This command is still a work in progress.  It doesn't support all
 633 block drivers among other things.  Stay away from it unless you want
 634 to help with its development.
 635
 636 For the arguments, see the QAPI schema documentation of BlockdevOptions.
 637
 638 Example (1):
 639
 640 -> { "execute": "blockdev-add",
 641     "arguments": { "driver": "qcow2",
 642                    "file": { "driver": "file",
 643                              "filename": "test.qcow2" } } }
 644 <- { "return": {} }
 645
 646 Example (2):
 647
 648 -> { "execute": "blockdev-add",
 649      "arguments": {
 650          "driver": "qcow2",
 651          "node-name": "my_disk",
 652          "discard": "unmap",
 653          "cache": {
 654              "direct": true,
 655              "writeback": true
 656          },
 657          "file": {
 658              "driver": "file",
 659              "filename": "/tmp/test.qcow2"
 660          },
 661          "backing": {
 662              "driver": "raw",
 663              "file": {
 664                  "driver": "file",
 665                  "filename": "/dev/fdset/4"
 666              }
 667          }
 668        }
 669      }
 670
 671 <- { "return": {} }
 672
 673 x-blockdev-del
 674 ------------
 675 Since 2.5
 676
 677 Deletes a block device that has been added using blockdev-add.
 678 The command will fail if the node is attached to a device or is
 679 otherwise being used.
 680
 681 This command is still a work in progress and is considered
 682 experimental. Stay away from it unless you want to help with its
 683 development.
 684
 685 Arguments:
 686
 687 - "node-name": Name of the graph node to delete (json-string)
 688
 689 Example:
 690
 691 -> { "execute": "blockdev-add",
 692      "arguments": {
 693          "driver": "qcow2",
 694          "node-name": "node0",
 695          "file": {
 696              "driver": "file",
 697              "filename": "test.qcow2"
 698          }
 699      }
 700    }
 701
 702 <- { "return": {} }
 703
 704 -> { "execute": "x-blockdev-del",
 705      "arguments": { "node-name": "node0" }
 706    }
 707 <- { "return": {} }
 708
 709 blockdev-open-tray
 710 ------------------
 711
 712 Opens a block device's tray. If there is a block driver state tree inserted as a
 713 medium, it will become inaccessible to the guest (but it will remain associated
 714 to the block device, so closing the tray will make it accessible again).
 715
 716 If the tray was already open before, this will be a no-op.
 717
 718 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
 719 which no such event will be generated, these include:
 720 - if the guest has locked the tray, @force is false and the guest does not
 721   respond to the eject request
 722 - if the BlockBackend denoted by @device does not have a guest device attached
 723   to it
 724 - if the guest device does not have an actual tray and is empty, for instance
 725   for floppy disk drives
 726
 727 Arguments:
 728
 729 - "device": block device name (deprecated, use @id instead)
 730             (json-string, optional)
 731 - "id": the name or QOM path of the guest device (json-string, optional)
 732 - "force": if false (the default), an eject request will be sent to the guest if
 733            it has locked the tray (and the tray will not be opened immediately);
 734            if true, the tray will be opened regardless of whether it is locked
 735            (json-bool, optional)
 736
 737 Example:
 738
 739 -> { "execute": "blockdev-open-tray",
 740      "arguments": { "id": "ide0-1-0" } }
 741
 742 <- { "timestamp": { "seconds": 1418751016,
 743                     "microseconds": 716996 },
 744      "event": "DEVICE_TRAY_MOVED",
 745      "data": { "device": "ide1-cd0",
 746                "id": "ide0-1-0",
 747                "tray-open": true } }
 748
 749 <- { "return": {} }
 750
 751 blockdev-close-tray
 752 -------------------
 753
 754 Closes a block device's tray. If there is a block driver state tree associated
 755 with the block device (which is currently ejected), that tree will be loaded as
 756 the medium.
 757
 758 If the tray was already closed before, this will be a no-op.
 759
 760 Arguments:
 761
 762 - "device": block device name (deprecated, use @id instead)
 763             (json-string, optional)
 764 - "id": the name or QOM path of the guest device (json-string, optional)
 765
 766 Example:
 767
 768 -> { "execute": "blockdev-close-tray",
 769      "arguments": { "id": "ide0-1-0" } }
 770
 771 <- { "timestamp": { "seconds": 1418751345,
 772                     "microseconds": 272147 },
 773      "event": "DEVICE_TRAY_MOVED",
 774      "data": { "device": "ide1-cd0",
 775                "id": "ide0-1-0",
 776                "tray-open": false } }
 777
 778 <- { "return": {} }
 779
 780 x-blockdev-remove-medium
 781 ------------------------
 782
 783 Removes a medium (a block driver state tree) from a block device. That block
 784 device's tray must currently be open (unless there is no attached guest device).
 785
 786 If the tray is open and there is no medium inserted, this will be a no-op.
 787
 788 This command is still a work in progress and is considered experimental.
 789 Stay away from it unless you want to help with its development.
 790
 791 Arguments:
 792
 793 - "device": block device name (deprecated, use @id instead)
 794             (json-string, optional)
 795 - "id": the name or QOM path of the guest device (json-string, optional)
 796
 797 Example:
 798
 799 -> { "execute": "x-blockdev-remove-medium",
 800      "arguments": { "id": "ide0-1-0" } }
 801
 802 <- { "error": { "class": "GenericError",
 803                 "desc": "Tray of device 'ide0-1-0' is not open" } }
 804
 805 -> { "execute": "blockdev-open-tray",
 806      "arguments": { "id": "ide0-1-0" } }
 807
 808 <- { "timestamp": { "seconds": 1418751627,
 809                     "microseconds": 549958 },
 810      "event": "DEVICE_TRAY_MOVED",
 811      "data": { "device": "ide1-cd0",
 812                "id": "ide0-1-0",
 813                "tray-open": true } }
 814
 815 <- { "return": {} }
 816
 817 -> { "execute": "x-blockdev-remove-medium",
 818      "arguments": { "device": "ide0-1-0" } }
 819
 820 <- { "return": {} }
 821
 822 x-blockdev-insert-medium
 823 ------------------------
 824
 825 Inserts a medium (a block driver state tree) into a block device. That block
 826 device's tray must currently be open (unless there is no attached guest device)
 827 and there must be no medium inserted already.
 828
 829 This command is still a work in progress and is considered experimental.
 830 Stay away from it unless you want to help with its development.
 831
 832 Arguments:
 833
 834 - "device": block device name (deprecated, use @id instead)
 835             (json-string, optional)
 836 - "id": the name or QOM path of the guest device (json-string, optional)
 837 - "node-name": root node of the BDS tree to insert into the block device
 838
 839 Example:
 840
 841 -> { "execute": "blockdev-add",
 842      "arguments": { { "node-name": "node0",
 843                       "driver": "raw",
 844                       "file": { "driver": "file",
 845                                 "filename": "fedora.iso" } } }
 846
 847 <- { "return": {} }
 848
 849 -> { "execute": "x-blockdev-insert-medium",
 850      "arguments": { "id": "ide0-1-0",
 851                     "node-name": "node0" } }
 852
 853 <- { "return": {} }
 854
 855 x-blockdev-change
 856 -----------------
 857
 858 Dynamically reconfigure the block driver state graph. It can be used
 859 to add, remove, insert or replace a graph node. Currently only the
 860 Quorum driver implements this feature to add or remove its child. This
 861 is useful to fix a broken quorum child.
 862
 863 If @node is specified, it will be inserted under @parent. @child
 864 may not be specified in this case. If both @parent and @child are
 865 specified but @node is not, @child will be detached from @parent.
 866
 867 Arguments:
 868 - "parent": the id or name of the parent node (json-string)
 869 - "child": the name of a child under the given parent node (json-string, optional)
 870 - "node": the name of the node that will be added (json-string, optional)
 871
 872 Note: this command is experimental, and not a stable API. It doesn't
 873 support all kinds of operations, all kinds of children, nor all block
 874 drivers.
 875
 876 Warning: The data in a new quorum child MUST be consistent with that of
 877 the rest of the array.
 878
 879 Example:
 880
 881 Add a new node to a quorum
 882 -> { "execute": "blockdev-add",
 883      "arguments": { "driver": "raw",
 884                     "node-name": "new_node",
 885                     "file": { "driver": "file",
 886                               "filename": "test.raw" } } }
 887 <- { "return": {} }
 888 -> { "execute": "x-blockdev-change",
 889      "arguments": { "parent": "disk1",
 890                     "node": "new_node" } }
 891 <- { "return": {} }
 892
 893 Delete a quorum's node
 894 -> { "execute": "x-blockdev-change",
 895      "arguments": { "parent": "disk1",
 896                     "child": "children.1" } }
 897 <- { "return": {} }
 898
 899 query-named-block-nodes
 900 -----------------------
 901
 902 Return a list of BlockDeviceInfo for all the named block driver nodes
 903
 904 Example:
 905
 906 -> { "execute": "query-named-block-nodes" }
 907 <- { "return": [ { "ro":false,
 908                    "drv":"qcow2",
 909                    "encrypted":false,
 910                    "file":"disks/test.qcow2",
 911                    "node-name": "my-node",
 912                    "backing_file_depth":1,
 913                    "bps":1000000,
 914                    "bps_rd":0,
 915                    "bps_wr":0,
 916                    "iops":1000000,
 917                    "iops_rd":0,
 918                    "iops_wr":0,
 919                    "bps_max": 8000000,
 920                    "bps_rd_max": 0,
 921                    "bps_wr_max": 0,
 922                    "iops_max": 0,
 923                    "iops_rd_max": 0,
 924                    "iops_wr_max": 0,
 925                    "iops_size": 0,
 926                    "write_threshold": 0,
 927                    "image":{
 928                       "filename":"disks/test.qcow2",
 929                       "format":"qcow2",
 930                       "virtual-size":2048000,
 931                       "backing_file":"base.qcow2",
 932                       "full-backing-filename":"disks/base.qcow2",
 933                       "backing-filename-format":"qcow2",
 934                       "snapshots":[
 935                          {
 936                             "id": "1",
 937                             "name": "snapshot1",
 938                             "vm-state-size": 0,
 939                             "date-sec": 10000200,
 940                             "date-nsec": 12,
 941                             "vm-clock-sec": 206,
 942                             "vm-clock-nsec": 30
 943                          }
 944                       ],
 945                       "backing-image":{
 946                           "filename":"disks/base.qcow2",
 947                           "format":"qcow2",
 948                           "virtual-size":2048000
 949                       }
 950                    } } ] }
 951
 952 blockdev-change-medium
 953 ----------------------
 954
 955 Changes the medium inserted into a block device by ejecting the current medium
 956 and loading a new image file which is inserted as the new medium.
 957
 958 Arguments:
 959
 960 - "device": block device name (deprecated, use @id instead)
 961             (json-string, optional)
 962 - "id": the name or QOM path of the guest device (json-string, optional)
 963 - "filename": filename of the new image (json-string)
 964 - "format": format of the new image (json-string, optional)
 965 - "read-only-mode": new read-only mode (json-string, optional)
 966           - Possible values: "retain" (default), "read-only", "read-write"
 967
 968 Examples:
 969
 970 1. Change a removable medium
 971
 972 -> { "execute": "blockdev-change-medium",
 973              "arguments": { "id": "ide0-1-0",
 974                             "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
 975                             "format": "raw" } }
 976 <- { "return": {} }
 977
 978 2. Load a read-only medium into a writable drive
 979
 980 -> { "execute": "blockdev-change-medium",
 981              "arguments": { "id": "floppyA",
 982                             "filename": "/srv/images/ro.img",
 983                             "format": "raw",
 984                             "read-only-mode": "retain" } }
 985
 986 <- { "error":
 987      { "class": "GenericError",
 988        "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
 989
 990 -> { "execute": "blockdev-change-medium",
 991              "arguments": { "id": "floppyA",
 992                             "filename": "/srv/images/ro.img",
 993                             "format": "raw",
 994                             "read-only-mode": "read-only" } }
 995
 996 <- { "return": {} }
 997
 998 trace-event-get-state
 999 ---------------------
1000
1001 Query the state of events.
1002
1003 Arguments:
1004
1005 - "name": Event name pattern (json-string).
1006 - "vcpu": The vCPU to query, any vCPU by default (json-int, optional).
1007
1008 An event is returned if:
1009 - its name matches the "name" pattern, and
1010 - if "vcpu" is given, the event has the "vcpu" property.
1011
1012 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
1013 returning their state on the specified vCPU. Special case: if "name" is an exact
1014 match, "vcpu" is given and the event does not have the "vcpu" property, an error
1015 is returned.
1016
1017 Example:
1018
1019 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
1020 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
1021
1022 trace-event-set-state
1023 ---------------------
1024
1025 Set the state of events.
1026
1027 Arguments:
1028
1029 - "name": Event name pattern (json-string).
1030 - "enable": Whether to enable or disable the event (json-bool).
1031 - "ignore-unavailable": Whether to ignore errors for events that cannot be
1032   changed (json-bool, optional).
1033 - "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional).
1034
1035 An event's state is modified if:
1036 - its name matches the "name" pattern, and
1037 - if "vcpu" is given, the event has the "vcpu" property.
1038
1039 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
1040 setting their state on the specified vCPU. Special case: if "name" is an exact
1041 match, "vcpu" is given and the event does not have the "vcpu" property, an error
1042 is returned.
1043
1044 Example:
1045
1046 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
1047 <- { "return": {} }
1048
1049 block-set-write-threshold
1050 ------------
1051
1052 Change the write threshold for a block drive. The threshold is an offset,
1053 thus must be non-negative. Default is no write threshold.
1054 Setting the threshold to zero disables it.
1055
1056 Arguments:
1057
1058 - "node-name": the node name in the block driver state graph (json-string)
1059 - "write-threshold": the write threshold in bytes (json-int)
1060
1061 Example:
1062
1063 -> { "execute": "block-set-write-threshold",
1064   "arguments": { "node-name": "mydev",
1065                  "write-threshold": 17179869184 } }
1066 <- { "return": {} }
1067
1068 Show rocker switch
1069 ------------------
1070
1071 Arguments:
1072
1073 - "name": switch name
1074
1075 Example:
1076
1077 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
1078 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
1079
1080 Show rocker switch ports
1081 ------------------------
1082
1083 Arguments:
1084
1085 - "name": switch name
1086
1087 Example:
1088
1089 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
1090 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
1091                   "autoneg": "off", "link-up": true, "speed": 10000},
1092                  {"duplex": "full", "enabled": true, "name": "sw1.2",
1093                   "autoneg": "off", "link-up": true, "speed": 10000}
1094    ]}
1095
1096 Show rocker switch OF-DPA flow tables
1097 -------------------------------------
1098
1099 Arguments:
1100
1101 - "name": switch name
1102 - "tbl-id": (optional) flow table ID
1103
1104 Example:
1105
1106 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
1107 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
1108                   "hits": 138,
1109                   "cookie": 0,
1110                   "action": {"goto-tbl": 10},
1111                   "mask": {"in-pport": 4294901760}
1112                  },
1113                  {...more...},
1114    ]}
1115
1116 Show rocker OF-DPA group tables
1117 -------------------------------
1118
1119 Arguments:
1120
1121 - "name": switch name
1122 - "type": (optional) group type
1123
1124 Example:
1125
1126 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
1127 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
1128                   "pop-vlan": 1, "id": 251723778},
1129                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
1130                   "pop-vlan": 1, "id": 251723776},
1131                  {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
1132                   "pop-vlan": 1, "id": 251658241},
1133                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
1134                   "pop-vlan": 1, "id": 251658240}
1135    ]}
1136
1137 query-gic-capabilities
1138 ---------------
1139
1140 Return a list of GICCapability objects, describing supported GIC
1141 (Generic Interrupt Controller) versions.
1142
1143 Arguments: None
1144
1145 Example:
1146
1147 -> { "execute": "query-gic-capabilities" }
1148 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
1149                 { "version": 3, "emulated": false, "kernel": true } ] }
1150
1151 Show existing/possible CPUs
1152 ---------------------------
1153
1154 Arguments: None.
1155
1156 Example for pseries machine type started with
1157 -smp 2,cores=2,maxcpus=4 -cpu POWER8:
1158
1159 -> { "execute": "query-hotpluggable-cpus" }
1160 <- {"return": [
1161      { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
1162        "vcpus-count": 1 },
1163      { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
1164        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
1165    ]}'
1166
1167 Example for pc machine type started with
1168 -smp 1,maxcpus=2:
1169     -> { "execute": "query-hotpluggable-cpus" }
1170     <- {"return": [
1171          {
1172             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
1173             "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
1174          },
1175          {
1176             "qom-path": "/machine/unattached/device[0]",
1177             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
1178             "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
1179          }
1180        ]}