docs/qmp-commands.txt

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