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 quit
  57 ----
  58
  59 Quit the emulator.
  60
  61 Arguments: None.
  62
  63 Example:
  64
  65 -> { "execute": "quit" }
  66 <- { "return": {} }
  67
  68 eject
  69 -----
  70
  71 Eject a removable medium.
  72
  73 Arguments:
  74
  75 - "force": force ejection (json-bool, optional)
  76 - "device": block device name (deprecated, use @id instead)
  77             (json-string, optional)
  78 - "id": the name or QOM path of the guest device (json-string, optional)
  79
  80 Example:
  81
  82 -> { "execute": "eject", "arguments": { "id": "ide0-1-0" } }
  83 <- { "return": {} }
  84
  85 Note: The "force" argument defaults to false.
  86
  87 change
  88 ------
  89
  90 Change a removable medium or VNC configuration.
  91
  92 Arguments:
  93
  94 - "device": device name (json-string)
  95 - "target": filename or item (json-string)
  96 - "arg": additional argument (json-string, optional)
  97
  98 Examples:
  99
 100 1. Change a removable medium
 101
 102 -> { "execute": "change",
 103              "arguments": { "device": "ide1-cd0",
 104                             "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
 105 <- { "return": {} }
 106
 107 2. Change VNC password
 108
 109 -> { "execute": "change",
 110              "arguments": { "device": "vnc", "target": "password",
 111                             "arg": "foobar1" } }
 112 <- { "return": {} }
 113
 114 screendump
 115 ----------
 116
 117 Save screen into PPM image.
 118
 119 Arguments:
 120
 121 - "filename": file path (json-string)
 122
 123 Example:
 124
 125 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 126 <- { "return": {} }
 127
 128 stop
 129 ----
 130
 131 Stop the emulator.
 132
 133 Arguments: None.
 134
 135 Example:
 136
 137 -> { "execute": "stop" }
 138 <- { "return": {} }
 139
 140 cont
 141 ----
 142
 143 Resume emulation.
 144
 145 Arguments: None.
 146
 147 Example:
 148
 149 -> { "execute": "cont" }
 150 <- { "return": {} }
 151
 152 system_wakeup
 153 -------------
 154
 155 Wakeup guest from suspend.
 156
 157 Arguments: None.
 158
 159 Example:
 160
 161 -> { "execute": "system_wakeup" }
 162 <- { "return": {} }
 163
 164 system_reset
 165 ------------
 166
 167 Reset the system.
 168
 169 Arguments: None.
 170
 171 Example:
 172
 173 -> { "execute": "system_reset" }
 174 <- { "return": {} }
 175
 176 system_powerdown
 177 ----------------
 178
 179 Send system power down event.
 180
 181 Arguments: None.
 182
 183 Example:
 184
 185 -> { "execute": "system_powerdown" }
 186 <- { "return": {} }
 187
 188 device_add
 189 ----------
 190
 191 Add a device.
 192
 193 Arguments:
 194
 195 - "driver": the name of the new device's driver (json-string)
 196 - "bus": the device's parent bus (device tree path, json-string, optional)
 197 - "id": the device's ID, must be unique (json-string)
 198 - device properties
 199
 200 Example:
 201
 202 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
 203 <- { "return": {} }
 204
 205 Notes:
 206
 207 (1) For detailed information about this command, please refer to the
 208     'docs/qdev-device-use.txt' file.
 209
 210 (2) It's possible to list device properties by running QEMU with the
 211     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
 212
 213 device_del
 214 ----------
 215
 216 Remove a device.
 217
 218 Arguments:
 219
 220 - "id": the device's ID or QOM path (json-string)
 221
 222 Example:
 223
 224 -> { "execute": "device_del", "arguments": { "id": "net1" } }
 225 <- { "return": {} }
 226
 227 Example:
 228
 229 -> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
 230 <- { "return": {} }
 231
 232 send-key
 233 ----------
 234
 235 Send keys to VM.
 236
 237 Arguments:
 238
 239 keys array:
 240     - "key": key sequence (a json-array of key union values,
 241              union can be number or qcode enum)
 242
 243 - hold-time: time to delay key up events, milliseconds. Defaults to 100
 244              (json-int, optional)
 245
 246 Example:
 247
 248 -> { "execute": "send-key",
 249      "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
 250                               { "type": "qcode", "data": "alt" },
 251                               { "type": "qcode", "data": "delete" } ] } }
 252 <- { "return": {} }
 253
 254 cpu
 255 ---
 256
 257 Set the default CPU.
 258
 259 Arguments:
 260
 261 - "index": the CPU's index (json-int)
 262
 263 Example:
 264
 265 -> { "execute": "cpu", "arguments": { "index": 0 } }
 266 <- { "return": {} }
 267
 268 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 269
 270 cpu-add
 271 -------
 272
 273 Adds virtual cpu
 274
 275 Arguments:
 276
 277 - "id": cpu id (json-int)
 278
 279 Example:
 280
 281 -> { "execute": "cpu-add", "arguments": { "id": 2 } }
 282 <- { "return": {} }
 283
 284 memsave
 285 -------
 286
 287 Save to disk virtual memory dump starting at 'val' of size 'size'.
 288
 289 Arguments:
 290
 291 - "val": the starting address (json-int)
 292 - "size": the memory size, in bytes (json-int)
 293 - "filename": file path (json-string)
 294 - "cpu": virtual CPU index (json-int, optional)
 295
 296 Example:
 297
 298 -> { "execute": "memsave",
 299              "arguments": { "val": 10,
 300                             "size": 100,
 301                             "filename": "/tmp/virtual-mem-dump" } }
 302 <- { "return": {} }
 303
 304 pmemsave
 305 --------
 306
 307 Save to disk physical memory dump starting at 'val' of size 'size'.
 308
 309 Arguments:
 310
 311 - "val": the starting address (json-int)
 312 - "size": the memory size, in bytes (json-int)
 313 - "filename": file path (json-string)
 314
 315 Example:
 316
 317 -> { "execute": "pmemsave",
 318              "arguments": { "val": 10,
 319                             "size": 100,
 320                             "filename": "/tmp/physical-mem-dump" } }
 321 <- { "return": {} }
 322
 323 inject-nmi
 324 ----------
 325
 326 Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64).
 327
 328 Arguments: None.
 329
 330 Example:
 331
 332 -> { "execute": "inject-nmi" }
 333 <- { "return": {} }
 334
 335 Note: inject-nmi fails when the guest doesn't support injecting.
 336
 337 xen-save-devices-state
 338 -------
 339
 340 Save the state of all devices to file. The RAM and the block devices
 341 of the VM are not saved by this command.
 342
 343 Arguments:
 344
 345 - "filename": the file to save the state of the devices to as binary
 346 data. See xen-save-devices-state.txt for a description of the binary
 347 format.
 348
 349 Example:
 350
 351 -> { "execute": "xen-save-devices-state",
 352      "arguments": { "filename": "/tmp/save" } }
 353 <- { "return": {} }
 354
 355 xen-load-devices-state
 356 ----------------------
 357
 358 Load the state of all devices from file. The RAM and the block devices
 359 of the VM are not loaded by this command.
 360
 361 Arguments:
 362
 363 - "filename": the file to load the state of the devices from as binary
 364 data. See xen-save-devices-state.txt for a description of the binary
 365 format.
 366
 367 Example:
 368
 369 -> { "execute": "xen-load-devices-state",
 370      "arguments": { "filename": "/tmp/resume" } }
 371 <- { "return": {} }
 372
 373 xen-set-global-dirty-log
 374 -------
 375
 376 Enable or disable the global dirty log mode.
 377
 378 Arguments:
 379
 380 - "enable": Enable it or disable it.
 381
 382 Example:
 383
 384 -> { "execute": "xen-set-global-dirty-log",
 385      "arguments": { "enable": true } }
 386 <- { "return": {} }
 387
 388 migrate
 389 -------
 390
 391 Migrate to URI.
 392
 393 Arguments:
 394
 395 - "blk": block migration, full disk copy (json-bool, optional)
 396 - "inc": incremental disk copy (json-bool, optional)
 397 - "uri": Destination URI (json-string)
 398
 399 Example:
 400
 401 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
 402 <- { "return": {} }
 403
 404 Notes:
 405
 406 (1) The 'query-migrate' command should be used to check migration's progress
 407     and final result (this information is provided by the 'status' member)
 408 (2) All boolean arguments default to false
 409 (3) The user Monitor's "detach" argument is invalid in QMP and should not
 410     be used
 411
 412 migrate_cancel
 413 --------------
 414
 415 Cancel the current migration.
 416
 417 Arguments: None.
 418
 419 Example:
 420
 421 -> { "execute": "migrate_cancel" }
 422 <- { "return": {} }
 423
 424 migrate-incoming
 425 ----------------
 426
 427 Continue an incoming migration
 428
 429 Arguments:
 430
 431 - "uri": Source/listening URI (json-string)
 432
 433 Example:
 434
 435 -> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } }
 436 <- { "return": {} }
 437
 438 Notes:
 439
 440 (1) QEMU must be started with -incoming defer to allow migrate-incoming to
 441     be used
 442 (2) The uri format is the same as for -incoming
 443
 444 migrate-set-cache-size
 445 ----------------------
 446
 447 Set cache size to be used by XBZRLE migration, the cache size will be rounded
 448 down to the nearest power of 2
 449
 450 Arguments:
 451
 452 - "value": cache size in bytes (json-int)
 453
 454 Example:
 455
 456 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 457 <- { "return": {} }
 458
 459 migrate-start-postcopy
 460 ----------------------
 461
 462 Switch an in-progress migration to postcopy mode. Ignored after the end of
 463 migration (or once already in postcopy).
 464
 465 Example:
 466 -> { "execute": "migrate-start-postcopy" }
 467 <- { "return": {} }
 468
 469 query-migrate-cache-size
 470 ------------------------
 471
 472 Show cache size to be used by XBZRLE migration
 473
 474 returns a json-object with the following information:
 475 - "size" : json-int
 476
 477 Example:
 478
 479 -> { "execute": "query-migrate-cache-size" }
 480 <- { "return": 67108864 }
 481
 482 migrate_set_speed
 483 -----------------
 484
 485 Set maximum speed for migrations.
 486
 487 Arguments:
 488
 489 - "value": maximum speed, in bytes per second (json-int)
 490
 491 Example:
 492
 493 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
 494 <- { "return": {} }
 495
 496 migrate_set_downtime
 497 --------------------
 498
 499 Set maximum tolerated downtime (in seconds) for migrations.
 500
 501 Arguments:
 502
 503 - "value": maximum downtime (json-number)
 504
 505 Example:
 506
 507 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
 508 <- { "return": {} }
 509
 510 x-colo-lost-heartbeat
 511 --------------------
 512
 513 Tell COLO that heartbeat is lost, a failover or takeover is needed.
 514
 515 Example:
 516
 517 -> { "execute": "x-colo-lost-heartbeat" }
 518 <- { "return": {} }
 519
 520 client_migrate_info
 521 -------------------
 522
 523 Set migration information for remote display.  This makes the server
 524 ask the client to automatically reconnect using the new parameters
 525 once migration finished successfully.  Only implemented for SPICE.
 526
 527 Arguments:
 528
 529 - "protocol":     must be "spice" (json-string)
 530 - "hostname":     migration target hostname (json-string)
 531 - "port":         spice tcp port for plaintext channels (json-int, optional)
 532 - "tls-port":     spice tcp port for tls-secured channels (json-int, optional)
 533 - "cert-subject": server certificate subject (json-string, optional)
 534
 535 Example:
 536
 537 -> { "execute": "client_migrate_info",
 538      "arguments": { "protocol": "spice",
 539                     "hostname": "virt42.lab.kraxel.org",
 540                     "port": 1234 } }
 541 <- { "return": {} }
 542
 543 dump
 544
 545
 546 Dump guest memory to file. The file can be processed with crash or gdb.
 547
 548 Arguments:
 549
 550 - "paging": do paging to get guest's memory mapping (json-bool)
 551 - "protocol": destination file(started with "file:") or destination file
 552               descriptor (started with "fd:") (json-string)
 553 - "detach": if specified, command will return immediately, without waiting
 554             for the dump to finish. The user can track progress using
 555             "query-dump". (json-bool)
 556 - "begin": the starting physical address. It's optional, and should be specified
 557            with length together (json-int)
 558 - "length": the memory size, in bytes. It's optional, and should be specified
 559             with begin together (json-int)
 560 - "format": the format of guest memory dump. It's optional, and can be
 561             elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will
 562             conflict with paging and filter, ie. begin and length (json-string)
 563
 564 Example:
 565
 566 -> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
 567 <- { "return": {} }
 568
 569 Notes:
 570
 571 (1) All boolean arguments default to false
 572
 573 query-dump-guest-memory-capability
 574 ----------
 575
 576 Show available formats for 'dump-guest-memory'
 577
 578 Example:
 579
 580 -> { "execute": "query-dump-guest-memory-capability" }
 581 <- { "return": { "formats":
 582                     ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
 583
 584 query-dump
 585 ----------
 586
 587 Query background dump status.
 588
 589 Arguments: None.
 590
 591 Example:
 592
 593 -> { "execute": "query-dump" }
 594 <- { "return": { "status": "active", "completed": 1024000,
 595                  "total": 2048000 } }
 596
 597 dump-skeys
 598 ----------
 599
 600 Save guest storage keys to file.
 601
 602 Arguments:
 603
 604 - "filename": file path (json-string)
 605
 606 Example:
 607
 608 -> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } }
 609 <- { "return": {} }
 610
 611 netdev_add
 612 ----------
 613
 614 Add host network device.
 615
 616 Arguments:
 617
 618 - "type": the device type, "tap", "user", ... (json-string)
 619 - "id": the device's ID, must be unique (json-string)
 620 - device options
 621
 622 Example:
 623
 624 -> { "execute": "netdev_add",
 625      "arguments": { "type": "user", "id": "netdev1",
 626                     "dnssearch": "example.org" } }
 627 <- { "return": {} }
 628
 629 Note: The supported device options are the same ones supported by the '-netdev'
 630       command-line argument, which are listed in the '-help' output or QEMU's
 631       manual
 632
 633 netdev_del
 634 ----------
 635
 636 Remove host network device.
 637
 638 Arguments:
 639
 640 - "id": the device's ID, must be unique (json-string)
 641
 642 Example:
 643
 644 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
 645 <- { "return": {} }
 646
 647
 648 object-add
 649 ----------
 650
 651 Create QOM object.
 652
 653 Arguments:
 654
 655 - "qom-type": the object's QOM type, i.e. the class name (json-string)
 656 - "id": the object's ID, must be unique (json-string)
 657 - "props": a dictionary of object property values (optional, json-dict)
 658
 659 Example:
 660
 661 -> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1",
 662      "props": { "filename": "/dev/hwrng" } } }
 663 <- { "return": {} }
 664
 665 object-del
 666 ----------
 667
 668 Remove QOM object.
 669
 670 Arguments:
 671
 672 - "id": the object's ID (json-string)
 673
 674 Example:
 675
 676 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
 677 <- { "return": {} }
 678
 679
 680 block_resize
 681 ------------
 682
 683 Resize a block image while a guest is running.
 684
 685 Arguments:
 686
 687 - "device": the device's ID, must be unique (json-string)
 688 - "node-name": the node name in the block driver state graph (json-string)
 689 - "size": new size
 690
 691 Example:
 692
 693 -> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
 694 <- { "return": {} }
 695
 696 block-stream
 697 ------------
 698
 699 Copy data from a backing file into a block device.
 700
 701 Arguments:
 702
 703 - "job-id": Identifier for the newly-created block job. If omitted,
 704             the device name will be used. (json-string, optional)
 705 - "device": The device name or node-name of a root node (json-string)
 706 - "base": The file name of the backing image above which copying starts.
 707           It cannot be set if 'base-node' is also set (json-string, optional)
 708 - "base-node": the node name of the backing image above which copying starts.
 709                It cannot be set if 'base' is also set.
 710                (json-string, optional) (Since 2.8)
 711 - "backing-file": The backing file string to write into the active layer. This
 712                   filename is not validated.
 713
 714                   If a pathname string is such that it cannot be resolved by
 715                   QEMU, that means that subsequent QMP or HMP commands must use
 716                   node-names for the image in question, as filename lookup
 717                   methods will fail.
 718
 719                   If not specified, QEMU will automatically determine the
 720                   backing file string to use, or error out if there is no
 721                   obvious choice.  Care should be taken when specifying the
 722                   string, to specify a valid filename or protocol.
 723                   (json-string, optional) (Since 2.1)
 724 - "speed":  the maximum speed, in bytes per second (json-int, optional)
 725 - "on-error": the action to take on an error (default 'report').  'stop' and
 726               'enospc' can only be used if the block device supports io-status.
 727               (json-string, optional) (Since 2.1)
 728
 729 Example:
 730
 731 -> { "execute": "block-stream", "arguments": { "device": "virtio0",
 732                                                "base": "/tmp/master.qcow2" } }
 733 <- { "return": {} }
 734
 735 block-commit
 736 ------------
 737
 738 Live commit of data from overlay image nodes into backing nodes - i.e., writes
 739 data between 'top' and 'base' into 'base'.
 740
 741 Arguments:
 742
 743 - "job-id": Identifier for the newly-created block job. If omitted,
 744             the device name will be used. (json-string, optional)
 745 - "device": The device name or node-name of a root node (json-string)
 746 - "base": The file name of the backing image to write data into.
 747           If not specified, this is the deepest backing image
 748           (json-string, optional)
 749 - "top":  The file name of the backing image within the image chain,
 750           which contains the topmost data to be committed down. If
 751           not specified, this is the active layer. (json-string, optional)
 752
 753 - backing-file:     The backing file string to write into the overlay
 754                     image of 'top'.  If 'top' is the active layer,
 755                     specifying a backing file string is an error. This
 756                     filename is not validated.
 757
 758                     If a pathname string is such that it cannot be
 759                     resolved by QEMU, that means that subsequent QMP or
 760                     HMP commands must use node-names for the image in
 761                     question, as filename lookup methods will fail.
 762
 763                     If not specified, QEMU will automatically determine
 764                     the backing file string to use, or error out if
 765                     there is no obvious choice. Care should be taken
 766                     when specifying the string, to specify a valid
 767                     filename or protocol.
 768                     (json-string, optional) (Since 2.1)
 769
 770           If top == base, that is an error.
 771           If top == active, the job will not be completed by itself,
 772           user needs to complete the job with the block-job-complete
 773           command after getting the ready event. (Since 2.0)
 774
 775           If the base image is smaller than top, then the base image
 776           will be resized to be the same size as top.  If top is
 777           smaller than the base image, the base will not be
 778           truncated.  If you want the base image size to match the
 779           size of the smaller top, you can safely truncate it
 780           yourself once the commit operation successfully completes.
 781           (json-string)
 782 - "speed":  the maximum speed, in bytes per second (json-int, optional)
 783
 784
 785 Example:
 786
 787 -> { "execute": "block-commit", "arguments": { "device": "virtio0",
 788                                               "top": "/tmp/snap1.qcow2" } }
 789 <- { "return": {} }
 790
 791 drive-backup
 792 ------------
 793
 794 Start a point-in-time copy of a block device to a new destination.  The
 795 status of ongoing drive-backup operations can be checked with
 796 query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
 797 The operation can be stopped before it has completed using the
 798 block-job-cancel command.
 799
 800 Arguments:
 801
 802 - "job-id": Identifier for the newly-created block job. If omitted,
 803             the device name will be used. (json-string, optional)
 804 - "device": the device name or node-name of a root node which should be copied.
 805             (json-string)
 806 - "target": the target of the new image. If the file exists, or if it is a
 807             device, the existing file/device will be used as the new
 808             destination.  If it does not exist, a new file will be created.
 809             (json-string)
 810 - "format": the format of the new destination, default is to probe if 'mode' is
 811             'existing', else the format of the source
 812             (json-string, optional)
 813 - "sync": what parts of the disk image should be copied to the destination;
 814   possibilities include "full" for all the disk, "top" for only the sectors
 815   allocated in the topmost image, "incremental" for only the dirty sectors in
 816   the bitmap, or "none" to only replicate new I/O (MirrorSyncMode).
 817 - "bitmap": dirty bitmap name for sync==incremental. Must be present if sync
 818             is "incremental", must NOT be present otherwise.
 819 - "mode": whether and how QEMU should create a new image
 820           (NewImageMode, optional, default 'absolute-paths')
 821 - "speed": the maximum speed, in bytes per second (json-int, optional)
 822 - "compress": true to compress data, if the target format supports it.
 823               (json-bool, optional, default false)
 824 - "on-source-error": the action to take on an error on the source, default
 825                      'report'.  'stop' and 'enospc' can only be used
 826                      if the block device supports io-status.
 827                      (BlockdevOnError, optional)
 828 - "on-target-error": the action to take on an error on the target, default
 829                      'report' (no limitations, since this applies to
 830                      a different block device than device).
 831                      (BlockdevOnError, optional)
 832
 833 Example:
 834 -> { "execute": "drive-backup", "arguments": { "device": "drive0",
 835                                                "sync": "full",
 836                                                "target": "backup.img" } }
 837 <- { "return": {} }
 838
 839 blockdev-backup
 840 ---------------
 841
 842 The device version of drive-backup: this command takes an existing named device
 843 as backup target.
 844
 845 Arguments:
 846
 847 - "job-id": Identifier for the newly-created block job. If omitted,
 848             the device name will be used. (json-string, optional)
 849 - "device": the device name or node-name of a root node which should be copied.
 850             (json-string)
 851 - "target": the name of the backup target device. (json-string)
 852 - "sync": what parts of the disk image should be copied to the destination;
 853           possibilities include "full" for all the disk, "top" for only the
 854           sectors allocated in the topmost image, or "none" to only replicate
 855           new I/O (MirrorSyncMode).
 856 - "speed": the maximum speed, in bytes per second (json-int, optional)
 857 - "compress": true to compress data, if the target format supports it.
 858               (json-bool, optional, default false)
 859 - "on-source-error": the action to take on an error on the source, default
 860                      'report'.  'stop' and 'enospc' can only be used
 861                      if the block device supports io-status.
 862                      (BlockdevOnError, optional)
 863 - "on-target-error": the action to take on an error on the target, default
 864                      'report' (no limitations, since this applies to
 865                      a different block device than device).
 866                      (BlockdevOnError, optional)
 867
 868 Example:
 869 -> { "execute": "blockdev-backup", "arguments": { "device": "src-id",
 870                                                   "sync": "full",
 871                                                   "target": "tgt-id" } }
 872 <- { "return": {} }
 873
 874 transaction
 875 -----------
 876
 877 Atomically operate on one or more block devices.  Operations that are
 878 currently supported:
 879
 880     - drive-backup
 881     - blockdev-backup
 882     - blockdev-snapshot-sync
 883     - blockdev-snapshot-internal-sync
 884     - abort
 885     - block-dirty-bitmap-add
 886     - block-dirty-bitmap-clear
 887
 888 Refer to the qemu/qapi-schema.json file for minimum required QEMU
 889 versions for these operations.  A list of dictionaries is accepted,
 890 that contains the actions to be performed.  If there is any failure
 891 performing any of the operations, all operations for the group are
 892 abandoned.
 893
 894 For external snapshots, the dictionary contains the device, the file to use for
 895 the new snapshot, and the format.  The default format, if not specified, is
 896 qcow2.
 897
 898 Each new snapshot defaults to being created by QEMU (wiping any
 899 contents if the file already exists), but it is also possible to reuse
 900 an externally-created file.  In the latter case, you should ensure that
 901 the new image file has the same contents as the current one; QEMU cannot
 902 perform any meaningful check.  Typically this is achieved by using the
 903 current image file as the backing file for the new image.
 904
 905 On failure, the original disks pre-snapshot attempt will be used.
 906
 907 For internal snapshots, the dictionary contains the device and the snapshot's
 908 name.  If an internal snapshot matching name already exists, the request will
 909 be rejected.  Only some image formats support it, for example, qcow2, rbd,
 910 and sheepdog.
 911
 912 On failure, qemu will try delete the newly created internal snapshot in the
 913 transaction.  When an I/O error occurs during deletion, the user needs to fix
 914 it later with qemu-img or other command.
 915
 916 Arguments:
 917
 918 actions array:
 919     - "type": the operation to perform (json-string).  Possible
 920               values: "drive-backup", "blockdev-backup",
 921                       "blockdev-snapshot-sync",
 922                       "blockdev-snapshot-internal-sync",
 923                       "abort", "block-dirty-bitmap-add",
 924                       "block-dirty-bitmap-clear"
 925     - "data": a dictionary.  The contents depend on the value
 926       of "type".  When "type" is "blockdev-snapshot-sync":
 927       - "device": device name to snapshot (json-string)
 928       - "node-name": graph node name to snapshot (json-string)
 929       - "snapshot-file": name of new image file (json-string)
 930       - "snapshot-node-name": graph node name of the new snapshot (json-string)
 931       - "format": format of new image (json-string, optional)
 932       - "mode": whether and how QEMU should create the snapshot file
 933         (NewImageMode, optional, default "absolute-paths")
 934       When "type" is "blockdev-snapshot-internal-sync":
 935       - "device": the device name or node-name of a root node to snapshot
 936                   (json-string)
 937       - "name": name of the new snapshot (json-string)
 938
 939 Example:
 940
 941 -> { "execute": "transaction",
 942      "arguments": { "actions": [
 943          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
 944                                          "snapshot-file": "/some/place/my-image",
 945                                          "format": "qcow2" } },
 946          { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
 947                                          "snapshot-file": "/some/place/my-image2",
 948                                          "snapshot-node-name": "node3432",
 949                                          "mode": "existing",
 950                                          "format": "qcow2" } },
 951          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
 952                                          "snapshot-file": "/some/place/my-image2",
 953                                          "mode": "existing",
 954                                          "format": "qcow2" } },
 955          { "type": "blockdev-snapshot-internal-sync", "data" : {
 956                                          "device": "ide-hd2",
 957                                          "name": "snapshot0" } } ] } }
 958 <- { "return": {} }
 959
 960 block-dirty-bitmap-add
 961 ----------------------
 962 Since 2.4
 963
 964 Create a dirty bitmap with a name on the device, and start tracking the writes.
 965
 966 Arguments:
 967
 968 - "node": device/node on which to create dirty bitmap (json-string)
 969 - "name": name of the new dirty bitmap (json-string)
 970 - "granularity": granularity to track writes with (int, optional)
 971
 972 Example:
 973
 974 -> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0",
 975                                                    "name": "bitmap0" } }
 976 <- { "return": {} }
 977
 978 block-dirty-bitmap-remove
 979 -------------------------
 980 Since 2.4
 981
 982 Stop write tracking and remove the dirty bitmap that was created with
 983 block-dirty-bitmap-add.
 984
 985 Arguments:
 986
 987 - "node": device/node on which to remove dirty bitmap (json-string)
 988 - "name": name of the dirty bitmap to remove (json-string)
 989
 990 Example:
 991
 992 -> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0",
 993                                                       "name": "bitmap0" } }
 994 <- { "return": {} }
 995
 996 block-dirty-bitmap-clear
 997 ------------------------
 998 Since 2.4
 999
1000 Reset the dirty bitmap associated with a node so that an incremental backup
1001 from this point in time forward will only backup clusters modified after this
1002 clear operation.
1003
1004 Arguments:
1005
1006 - "node": device/node on which to remove dirty bitmap (json-string)
1007 - "name": name of the dirty bitmap to remove (json-string)
1008
1009 Example:
1010
1011 -> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0",
1012                                                            "name": "bitmap0" } }
1013 <- { "return": {} }
1014
1015 blockdev-snapshot-sync
1016 ----------------------
1017
1018 Synchronous snapshot of a block device. snapshot-file specifies the
1019 target of the new image. If the file exists, or if it is a device, the
1020 snapshot will be created in the existing file/device. If does not
1021 exist, a new file will be created. format specifies the format of the
1022 snapshot image, default is qcow2.
1023
1024 Arguments:
1025
1026 - "device": device name to snapshot (json-string)
1027 - "node-name": graph node name to snapshot (json-string)
1028 - "snapshot-file": name of new image file (json-string)
1029 - "snapshot-node-name": graph node name of the new snapshot (json-string)
1030 - "mode": whether and how QEMU should create the snapshot file
1031   (NewImageMode, optional, default "absolute-paths")
1032 - "format": format of new image (json-string, optional)
1033
1034 Example:
1035
1036 -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
1037                                                          "snapshot-file":
1038                                                         "/some/place/my-image",
1039                                                         "format": "qcow2" } }
1040 <- { "return": {} }
1041
1042 blockdev-snapshot
1043 -----------------
1044 Since 2.5
1045
1046 Create a snapshot, by installing 'node' as the backing image of
1047 'overlay'. Additionally, if 'node' is associated with a block
1048 device, the block device changes to using 'overlay' as its new active
1049 image.
1050
1051 Arguments:
1052
1053 - "node": device that will have a snapshot created (json-string)
1054 - "overlay": device that will have 'node' as its backing image (json-string)
1055
1056 Example:
1057
1058 -> { "execute": "blockdev-add",
1059                 "arguments": { "driver": "qcow2",
1060                                "node-name": "node1534",
1061                                "file": { "driver": "file",
1062                                          "filename": "hd1.qcow2" },
1063                                "backing": "" } }
1064
1065 <- { "return": {} }
1066
1067 -> { "execute": "blockdev-snapshot", "arguments": { "node": "ide-hd0",
1068                                                     "overlay": "node1534" } }
1069 <- { "return": {} }
1070
1071 blockdev-snapshot-internal-sync
1072 -------------------------------
1073
1074 Synchronously take an internal snapshot of a block device when the format of
1075 image used supports it.  If the name is an empty string, or a snapshot with
1076 name already exists, the operation will fail.
1077
1078 Arguments:
1079
1080 - "device": the device name or node-name of a root node to snapshot
1081             (json-string)
1082 - "name": name of the new snapshot (json-string)
1083
1084 Example:
1085
1086 -> { "execute": "blockdev-snapshot-internal-sync",
1087                 "arguments": { "device": "ide-hd0",
1088                                "name": "snapshot0" }
1089    }
1090 <- { "return": {} }
1091
1092 blockdev-snapshot-delete-internal-sync
1093 --------------------------------------
1094
1095 Synchronously delete an internal snapshot of a block device when the format of
1096 image used supports it.  The snapshot is identified by name or id or both.  One
1097 of name or id is required.  If the snapshot is not found, the operation will
1098 fail.
1099
1100 Arguments:
1101
1102 - "device": the device name or node-name of a root node (json-string)
1103 - "id": ID of the snapshot (json-string, optional)
1104 - "name": name of the snapshot (json-string, optional)
1105
1106 Example:
1107
1108 -> { "execute": "blockdev-snapshot-delete-internal-sync",
1109                 "arguments": { "device": "ide-hd0",
1110                                "name": "snapshot0" }
1111    }
1112 <- { "return": {
1113                    "id": "1",
1114                    "name": "snapshot0",
1115                    "vm-state-size": 0,
1116                    "date-sec": 1000012,
1117                    "date-nsec": 10,
1118                    "vm-clock-sec": 100,
1119                    "vm-clock-nsec": 20
1120      }
1121    }
1122
1123 drive-mirror
1124 ------------
1125
1126 Start mirroring a block device's writes to a new destination. target
1127 specifies the target of the new image. If the file exists, or if it is
1128 a device, it will be used as the new destination for writes. If it does not
1129 exist, a new file will be created. format specifies the format of the
1130 mirror image, default is to probe if mode='existing', else the format
1131 of the source.
1132
1133 Arguments:
1134
1135 - "job-id": Identifier for the newly-created block job. If omitted,
1136             the device name will be used. (json-string, optional)
1137 - "device": the device name or node-name of a root node whose writes should be
1138             mirrored. (json-string)
1139 - "target": name of new image file (json-string)
1140 - "format": format of new image (json-string, optional)
1141 - "node-name": the name of the new block driver state in the node graph
1142                (json-string, optional)
1143 - "replaces": the block driver node name to replace when finished
1144               (json-string, optional)
1145 - "mode": how an image file should be created into the target
1146   file/device (NewImageMode, optional, default 'absolute-paths')
1147 - "speed": maximum speed of the streaming job, in bytes per second
1148   (json-int)
1149 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1150 - "buf-size": maximum amount of data in flight from source to target, in bytes
1151   (json-int, default 10M)
1152 - "sync": what parts of the disk image should be copied to the destination;
1153   possibilities include "full" for all the disk, "top" for only the sectors
1154   allocated in the topmost image, or "none" to only replicate new I/O
1155   (MirrorSyncMode).
1156 - "on-source-error": the action to take on an error on the source
1157   (BlockdevOnError, default 'report')
1158 - "on-target-error": the action to take on an error on the target
1159   (BlockdevOnError, default 'report')
1160 - "unmap": whether the target sectors should be discarded where source has only
1161   zeroes. (json-bool, optional, default true)
1162
1163 The default value of the granularity is the image cluster size clamped
1164 between 4096 and 65536, if the image format defines one.  If the format
1165 does not define a cluster size, the default value of the granularity
1166 is 65536.
1167
1168
1169 Example:
1170
1171 -> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
1172                                                "target": "/some/place/my-image",
1173                                                "sync": "full",
1174                                                "format": "qcow2" } }
1175 <- { "return": {} }
1176
1177 blockdev-mirror
1178 ------------
1179
1180 Start mirroring a block device's writes to another block device. target
1181 specifies the target of mirror operation.
1182
1183 Arguments:
1184
1185 - "job-id": Identifier for the newly-created block job. If omitted,
1186             the device name will be used. (json-string, optional)
1187 - "device": The device name or node-name of a root node whose writes should be
1188             mirrored (json-string)
1189 - "target": device name to mirror to (json-string)
1190 - "replaces": the block driver node name to replace when finished
1191               (json-string, optional)
1192 - "speed": maximum speed of the streaming job, in bytes per second
1193   (json-int)
1194 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1195 - "buf_size": maximum amount of data in flight from source to target, in bytes
1196   (json-int, default 10M)
1197 - "sync": what parts of the disk image should be copied to the destination;
1198   possibilities include "full" for all the disk, "top" for only the sectors
1199   allocated in the topmost image, or "none" to only replicate new I/O
1200   (MirrorSyncMode).
1201 - "on-source-error": the action to take on an error on the source
1202   (BlockdevOnError, default 'report')
1203 - "on-target-error": the action to take on an error on the target
1204   (BlockdevOnError, default 'report')
1205
1206 The default value of the granularity is the image cluster size clamped
1207 between 4096 and 65536, if the image format defines one.  If the format
1208 does not define a cluster size, the default value of the granularity
1209 is 65536.
1210
1211 Example:
1212
1213 -> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
1214                                                   "target": "target0",
1215                                                   "sync": "full" } }
1216 <- { "return": {} }
1217
1218 change-backing-file
1219 -------------------
1220 Since: 2.1
1221
1222 Change the backing file in the image file metadata.  This does not cause
1223 QEMU to reopen the image file to reparse the backing filename (it may,
1224 however, perform a reopen to change permissions from r/o -> r/w -> r/o,
1225 if needed). The new backing file string is written into the image file
1226 metadata, and the QEMU internal strings are updated.
1227
1228 Arguments:
1229
1230 - "image-node-name":    The name of the block driver state node of the
1231                         image to modify.  The "device" is argument is used to
1232                         verify "image-node-name" is in the chain described by
1233                         "device".
1234                         (json-string, optional)
1235
1236 - "device":             The device name or node-name of the root node that owns
1237                         image-node-name.
1238                         (json-string)
1239
1240 - "backing-file":       The string to write as the backing file.  This string is
1241                         not validated, so care should be taken when specifying
1242                         the string or the image chain may not be able to be
1243                         reopened again.
1244                         (json-string)
1245
1246 Returns: Nothing on success
1247          If "device" does not exist or cannot be determined, DeviceNotFound
1248
1249 balloon
1250 -------
1251
1252 Request VM to change its memory allocation (in bytes).
1253
1254 Arguments:
1255
1256 - "value": New memory allocation (json-int)
1257
1258 Example:
1259
1260 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1261 <- { "return": {} }
1262
1263 set_link
1264 --------
1265
1266 Change the link status of a network adapter.
1267
1268 Arguments:
1269
1270 - "name": network device name (json-string)
1271 - "up": status is up (json-bool)
1272
1273 Example:
1274
1275 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1276 <- { "return": {} }
1277
1278 getfd
1279 -----
1280
1281 Receive a file descriptor via SCM rights and assign it a name.
1282
1283 Arguments:
1284
1285 - "fdname": file descriptor name (json-string)
1286
1287 Example:
1288
1289 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1290 <- { "return": {} }
1291
1292 Notes:
1293
1294 (1) If the name specified by the "fdname" argument already exists,
1295     the file descriptor assigned to it will be closed and replaced
1296     by the received file descriptor.
1297 (2) The 'closefd' command can be used to explicitly close the file
1298     descriptor when it is no longer needed.
1299
1300 closefd
1301 -------
1302
1303 Close a file descriptor previously passed via SCM rights.
1304
1305 Arguments:
1306
1307 - "fdname": file descriptor name (json-string)
1308
1309 Example:
1310
1311 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1312 <- { "return": {} }
1313
1314 add-fd
1315 -------
1316
1317 Add a file descriptor, that was passed via SCM rights, to an fd set.
1318
1319 Arguments:
1320
1321 - "fdset-id": The ID of the fd set to add the file descriptor to.
1322               (json-int, optional)
1323 - "opaque": A free-form string that can be used to describe the fd.
1324             (json-string, optional)
1325
1326 Return a json-object with the following information:
1327
1328 - "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1329 - "fd": The file descriptor that was received via SCM rights and added to the
1330         fd set. (json-int)
1331
1332 Example:
1333
1334 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1335 <- { "return": { "fdset-id": 1, "fd": 3 } }
1336
1337 Notes:
1338
1339 (1) The list of fd sets is shared by all monitor connections.
1340 (2) If "fdset-id" is not specified, a new fd set will be created.
1341
1342 remove-fd
1343 ---------
1344
1345 Remove a file descriptor from an fd set.
1346
1347 Arguments:
1348
1349 - "fdset-id": The ID of the fd set that the file descriptor belongs to.
1350               (json-int)
1351 - "fd": The file descriptor that is to be removed. (json-int, optional)
1352
1353 Example:
1354
1355 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1356 <- { "return": {} }
1357
1358 Notes:
1359
1360 (1) The list of fd sets is shared by all monitor connections.
1361 (2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1362     removed.
1363
1364 query-fdsets
1365 -------------
1366
1367 Return information describing all fd sets.
1368
1369 Arguments: None
1370
1371 Example:
1372
1373 -> { "execute": "query-fdsets" }
1374 <- { "return": [
1375        {
1376          "fds": [
1377            {
1378              "fd": 30,
1379              "opaque": "rdonly:/path/to/file"
1380            },
1381            {
1382              "fd": 24,
1383              "opaque": "rdwr:/path/to/file"
1384            }
1385          ],
1386          "fdset-id": 1
1387        },
1388        {
1389          "fds": [
1390            {
1391              "fd": 28
1392            },
1393            {
1394              "fd": 29
1395            }
1396          ],
1397          "fdset-id": 0
1398        }
1399      ]
1400    }
1401
1402 Note: The list of fd sets is shared by all monitor connections.
1403
1404 block_passwd
1405 ------------
1406
1407 Set the password of encrypted block devices.
1408
1409 Arguments:
1410
1411 - "device": device name (json-string)
1412 - "node-name": name in the block driver state graph (json-string)
1413 - "password": password (json-string)
1414
1415 Example:
1416
1417 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1418                                                "password": "12345" } }
1419 <- { "return": {} }
1420
1421 block_set_io_throttle
1422 ------------
1423
1424 Change I/O throttle limits for a block drive.
1425
1426 Arguments:
1427
1428 - "device": block device name (deprecated, use @id instead)
1429             (json-string, optional)
1430 - "id": the name or QOM path of the guest device (json-string, optional)
1431 - "bps": total throughput limit in bytes per second (json-int)
1432 - "bps_rd": read throughput limit in bytes per second (json-int)
1433 - "bps_wr": write throughput limit in bytes per second (json-int)
1434 - "iops": total I/O operations per second (json-int)
1435 - "iops_rd": read I/O operations per second (json-int)
1436 - "iops_wr": write I/O operations per second (json-int)
1437 - "bps_max": total throughput limit during bursts, in bytes (json-int, optional)
1438 - "bps_rd_max": read throughput limit during bursts, in bytes (json-int, optional)
1439 - "bps_wr_max": write throughput limit during bursts, in bytes (json-int, optional)
1440 - "iops_max": total I/O operations per second during bursts (json-int, optional)
1441 - "iops_rd_max": read I/O operations per second during bursts (json-int, optional)
1442 - "iops_wr_max": write I/O operations per second during bursts (json-int, optional)
1443 - "bps_max_length": maximum length of the @bps_max burst period, in seconds (json-int, optional)
1444 - "bps_rd_max_length": maximum length of the @bps_rd_max burst period, in seconds (json-int, optional)
1445 - "bps_wr_max_length": maximum length of the @bps_wr_max burst period, in seconds (json-int, optional)
1446 - "iops_max_length": maximum length of the @iops_max burst period, in seconds (json-int, optional)
1447 - "iops_rd_max_length": maximum length of the @iops_rd_max burst period, in seconds (json-int, optional)
1448 - "iops_wr_max_length": maximum length of the @iops_wr_max burst period, in seconds (json-int, optional)
1449 - "iops_size":  I/O size in bytes when limiting (json-int, optional)
1450 - "group": throttle group name (json-string, optional)
1451
1452 Example:
1453
1454 -> { "execute": "block_set_io_throttle", "arguments": { "id": "ide0-1-0",
1455                                                "bps": 1000000,
1456                                                "bps_rd": 0,
1457                                                "bps_wr": 0,
1458                                                "iops": 0,
1459                                                "iops_rd": 0,
1460                                                "iops_wr": 0,
1461                                                "bps_max": 8000000,
1462                                                "bps_rd_max": 0,
1463                                                "bps_wr_max": 0,
1464                                                "iops_max": 0,
1465                                                "iops_rd_max": 0,
1466                                                "iops_wr_max": 0,
1467                                                "bps_max_length": 60,
1468                                                "iops_size": 0 } }
1469 <- { "return": {} }
1470
1471 set_password
1472 ------------
1473
1474 Set the password for vnc/spice protocols.
1475
1476 Arguments:
1477
1478 - "protocol": protocol name (json-string)
1479 - "password": password (json-string)
1480 - "connected": [ keep | disconnect | fail ] (json-string, optional)
1481
1482 Example:
1483
1484 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
1485                                                "password": "secret" } }
1486 <- { "return": {} }
1487
1488 expire_password
1489 ---------------
1490
1491 Set the password expire time for vnc/spice protocols.
1492
1493 Arguments:
1494
1495 - "protocol": protocol name (json-string)
1496 - "time": [ now | never | +secs | secs ] (json-string)
1497
1498 Example:
1499
1500 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
1501                                                   "time": "+60" } }
1502 <- { "return": {} }
1503
1504 qmp_capabilities
1505 ----------------
1506
1507 Enable QMP capabilities.
1508
1509 Arguments: None.
1510
1511 Example:
1512
1513 -> { "execute": "qmp_capabilities" }
1514 <- { "return": {} }
1515
1516 Note: This command must be issued before issuing any other command.
1517
1518 human-monitor-command
1519 ---------------------
1520
1521 Execute a Human Monitor command.
1522
1523 Arguments:
1524
1525 - command-line: the command name and its arguments, just like the
1526                 Human Monitor's shell (json-string)
1527 - cpu-index: select the CPU number to be used by commands which access CPU
1528              data, like 'info registers'. The Monitor selects CPU 0 if this
1529              argument is not provided (json-int, optional)
1530
1531 Example:
1532
1533 -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
1534 <- { "return": "kvm support: enabled\r\n" }
1535
1536 Notes:
1537
1538 (1) The Human Monitor is NOT an stable interface, this means that command
1539     names, arguments and responses can change or be removed at ANY time.
1540     Applications that rely on long term stability guarantees should NOT
1541     use this command
1542
1543 (2) Limitations:
1544
1545     o This command is stateless, this means that commands that depend
1546       on state information (such as getfd) might not work
1547
1548     o Commands that prompt the user for data (eg. 'cont' when the block
1549       device is encrypted) don't currently work
1550
1551 3. Query Commands
1552 =================
1553
1554
1555 query-version
1556 -------------
1557
1558 Show QEMU version.
1559
1560 Return a json-object with the following information:
1561
1562 - "qemu": A json-object containing three integer values:
1563     - "major": QEMU's major version (json-int)
1564     - "minor": QEMU's minor version (json-int)
1565     - "micro": QEMU's micro version (json-int)
1566 - "package": package's version (json-string)
1567
1568 Example:
1569
1570 -> { "execute": "query-version" }
1571 <- {
1572       "return":{
1573          "qemu":{
1574             "major":0,
1575             "minor":11,
1576             "micro":5
1577          },
1578          "package":""
1579       }
1580    }
1581
1582 query-commands
1583 --------------
1584
1585 List QMP available commands.
1586
1587 Each command is represented by a json-object, the returned value is a json-array
1588 of all commands.
1589
1590 Each json-object contain:
1591
1592 - "name": command's name (json-string)
1593
1594 Example:
1595
1596 -> { "execute": "query-commands" }
1597 <- {
1598       "return":[
1599          {
1600             "name":"query-balloon"
1601          },
1602          {
1603             "name":"system_powerdown"
1604          }
1605       ]
1606    }
1607
1608 Note: This example has been shortened as the real response is too long.
1609
1610 query-qmp-schema
1611 ----------------
1612
1613 Return the QMP wire schema.  The returned value is a json-array of
1614 named schema entities.  Entities are commands, events and various
1615 types.  See docs/qapi-code-gen.txt for information on their structure
1616 and intended use.
1617
1618 query-block
1619 -----------
1620
1621 Show the block devices.
1622
1623 Each block device information is stored in a json-object and the returned value
1624 is a json-array of all devices.
1625
1626 Each json-object contain the following:
1627
1628 - "device": device name (json-string)
1629 - "type": device type (json-string)
1630          - deprecated, retained for backward compatibility
1631          - Possible values: "unknown"
1632 - "removable": true if the device is removable, false otherwise (json-bool)
1633 - "locked": true if the device is locked, false otherwise (json-bool)
1634 - "tray_open": only present if removable, true if the device has a tray,
1635                and it is open (json-bool)
1636 - "inserted": only present if the device is inserted, it is a json-object
1637    containing the following:
1638          - "file": device file name (json-string)
1639          - "ro": true if read-only, false otherwise (json-bool)
1640          - "drv": driver format name (json-string)
1641              - Possible values: "blkdebug", "bochs", "cloop", "dmg",
1642                                 "file", "file", "ftp", "ftps", "host_cdrom",
1643                                 "host_device", "http", "https",
1644                                 "nbd", "parallels", "qcow", "qcow2", "raw",
1645                                 "vdi", "vmdk", "vpc", "vvfat"
1646          - "backing_file": backing file name (json-string, optional)
1647          - "backing_file_depth": number of files in the backing file chain (json-int)
1648          - "encrypted": true if encrypted, false otherwise (json-bool)
1649          - "bps": limit total bytes per second (json-int)
1650          - "bps_rd": limit read bytes per second (json-int)
1651          - "bps_wr": limit write bytes per second (json-int)
1652          - "iops": limit total I/O operations per second (json-int)
1653          - "iops_rd": limit read operations per second (json-int)
1654          - "iops_wr": limit write operations per second (json-int)
1655          - "bps_max":  total max in bytes (json-int)
1656          - "bps_rd_max":  read max in bytes (json-int)
1657          - "bps_wr_max":  write max in bytes (json-int)
1658          - "iops_max":  total I/O operations max (json-int)
1659          - "iops_rd_max":  read I/O operations max (json-int)
1660          - "iops_wr_max":  write I/O operations max (json-int)
1661          - "iops_size": I/O size when limiting by iops (json-int)
1662          - "detect_zeroes": detect and optimize zero writing (json-string)
1663              - Possible values: "off", "on", "unmap"
1664          - "write_threshold": write offset threshold in bytes, a event will be
1665                               emitted if crossed. Zero if disabled (json-int)
1666          - "image": the detail of the image, it is a json-object containing
1667             the following:
1668              - "filename": image file name (json-string)
1669              - "format": image format (json-string)
1670              - "virtual-size": image capacity in bytes (json-int)
1671              - "dirty-flag": true if image is not cleanly closed, not present
1672                              means clean (json-bool, optional)
1673              - "actual-size": actual size on disk in bytes of the image, not
1674                               present when image does not support thin
1675                               provision (json-int, optional)
1676              - "cluster-size": size of a cluster in bytes, not present if image
1677                                format does not support it (json-int, optional)
1678              - "encrypted": true if the image is encrypted, not present means
1679                             false or the image format does not support
1680                             encryption (json-bool, optional)
1681              - "backing_file": backing file name, not present means no backing
1682                                file is used or the image format does not
1683                                support backing file chain
1684                                (json-string, optional)
1685              - "full-backing-filename": full path of the backing file, not
1686                                         present if it equals backing_file or no
1687                                         backing file is used
1688                                         (json-string, optional)
1689              - "backing-filename-format": the format of the backing file, not
1690                                           present means unknown or no backing
1691                                           file (json-string, optional)
1692              - "snapshots": the internal snapshot info, it is an optional list
1693                 of json-object containing the following:
1694                  - "id": unique snapshot id (json-string)
1695                  - "name": snapshot name (json-string)
1696                  - "vm-state-size": size of the VM state in bytes (json-int)
1697                  - "date-sec": UTC date of the snapshot in seconds (json-int)
1698                  - "date-nsec": fractional part in nanoseconds to be used with
1699                                 date-sec (json-int)
1700                  - "vm-clock-sec": VM clock relative to boot in seconds
1701                                    (json-int)
1702                  - "vm-clock-nsec": fractional part in nanoseconds to be used
1703                                     with vm-clock-sec (json-int)
1704              - "backing-image": the detail of the backing image, it is an
1705                                 optional json-object only present when a
1706                                 backing image present for this image
1707
1708 - "io-status": I/O operation status, only present if the device supports it
1709                and the VM is configured to stop on errors. It's always reset
1710                to "ok" when the "cont" command is issued (json_string, optional)
1711              - Possible values: "ok", "failed", "nospace"
1712
1713 Example:
1714
1715 -> { "execute": "query-block" }
1716 <- {
1717       "return":[
1718          {
1719             "io-status": "ok",
1720             "device":"ide0-hd0",
1721             "locked":false,
1722             "removable":false,
1723             "inserted":{
1724                "ro":false,
1725                "drv":"qcow2",
1726                "encrypted":false,
1727                "file":"disks/test.qcow2",
1728                "backing_file_depth":1,
1729                "bps":1000000,
1730                "bps_rd":0,
1731                "bps_wr":0,
1732                "iops":1000000,
1733                "iops_rd":0,
1734                "iops_wr":0,
1735                "bps_max": 8000000,
1736                "bps_rd_max": 0,
1737                "bps_wr_max": 0,
1738                "iops_max": 0,
1739                "iops_rd_max": 0,
1740                "iops_wr_max": 0,
1741                "iops_size": 0,
1742                "detect_zeroes": "on",
1743                "write_threshold": 0,
1744                "image":{
1745                   "filename":"disks/test.qcow2",
1746                   "format":"qcow2",
1747                   "virtual-size":2048000,
1748                   "backing_file":"base.qcow2",
1749                   "full-backing-filename":"disks/base.qcow2",
1750                   "backing-filename-format":"qcow2",
1751                   "snapshots":[
1752                      {
1753                         "id": "1",
1754                         "name": "snapshot1",
1755                         "vm-state-size": 0,
1756                         "date-sec": 10000200,
1757                         "date-nsec": 12,
1758                         "vm-clock-sec": 206,
1759                         "vm-clock-nsec": 30
1760                      }
1761                   ],
1762                   "backing-image":{
1763                       "filename":"disks/base.qcow2",
1764                       "format":"qcow2",
1765                       "virtual-size":2048000
1766                   }
1767                }
1768             },
1769             "type":"unknown"
1770          },
1771          {
1772             "io-status": "ok",
1773             "device":"ide1-cd0",
1774             "locked":false,
1775             "removable":true,
1776             "type":"unknown"
1777          },
1778          {
1779             "device":"floppy0",
1780             "locked":false,
1781             "removable":true,
1782             "type":"unknown"
1783          },
1784          {
1785             "device":"sd0",
1786             "locked":false,
1787             "removable":true,
1788             "type":"unknown"
1789          }
1790       ]
1791    }
1792
1793 query-blockstats
1794 ----------------
1795
1796 Show block device statistics.
1797
1798 Each device statistic information is stored in a json-object and the returned
1799 value is a json-array of all devices.
1800
1801 Each json-object contain the following:
1802
1803 - "device": device name (json-string)
1804 - "stats": A json-object with the statistics information, it contains:
1805     - "rd_bytes": bytes read (json-int)
1806     - "wr_bytes": bytes written (json-int)
1807     - "rd_operations": read operations (json-int)
1808     - "wr_operations": write operations (json-int)
1809     - "flush_operations": cache flush operations (json-int)
1810     - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
1811     - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
1812     - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
1813     - "wr_highest_offset": The offset after the greatest byte written to the
1814                            BlockDriverState since it has been opened (json-int)
1815     - "rd_merged": number of read requests that have been merged into
1816                    another request (json-int)
1817     - "wr_merged": number of write requests that have been merged into
1818                    another request (json-int)
1819     - "idle_time_ns": time since the last I/O operation, in
1820                       nanoseconds. If the field is absent it means
1821                       that there haven't been any operations yet
1822                       (json-int, optional)
1823     - "failed_rd_operations": number of failed read operations
1824                               (json-int)
1825     - "failed_wr_operations": number of failed write operations
1826                               (json-int)
1827     - "failed_flush_operations": number of failed flush operations
1828                                (json-int)
1829     - "invalid_rd_operations": number of invalid read operations
1830                                (json-int)
1831     - "invalid_wr_operations": number of invalid write operations
1832                                (json-int)
1833     - "invalid_flush_operations": number of invalid flush operations
1834                                   (json-int)
1835     - "account_invalid": whether invalid operations are included in
1836                          the last access statistics (json-bool)
1837     - "account_failed": whether failed operations are included in the
1838                          latency and last access statistics
1839                          (json-bool)
1840     - "timed_stats": A json-array containing statistics collected in
1841                      specific intervals, with the following members:
1842         - "interval_length": interval used for calculating the
1843                              statistics, in seconds (json-int)
1844         - "min_rd_latency_ns": minimum latency of read operations in
1845                                the defined interval, in nanoseconds
1846                                (json-int)
1847         - "min_wr_latency_ns": minimum latency of write operations in
1848                                the defined interval, in nanoseconds
1849                                (json-int)
1850         - "min_flush_latency_ns": minimum latency of flush operations
1851                                   in the defined interval, in
1852                                   nanoseconds (json-int)
1853         - "max_rd_latency_ns": maximum latency of read operations in
1854                                the defined interval, in nanoseconds
1855                                (json-int)
1856         - "max_wr_latency_ns": maximum latency of write operations in
1857                                the defined interval, in nanoseconds
1858                                (json-int)
1859         - "max_flush_latency_ns": maximum latency of flush operations
1860                                   in the defined interval, in
1861                                   nanoseconds (json-int)
1862         - "avg_rd_latency_ns": average latency of read operations in
1863                                the defined interval, in nanoseconds
1864                                (json-int)
1865         - "avg_wr_latency_ns": average latency of write operations in
1866                                the defined interval, in nanoseconds
1867                                (json-int)
1868         - "avg_flush_latency_ns": average latency of flush operations
1869                                   in the defined interval, in
1870                                   nanoseconds (json-int)
1871         - "avg_rd_queue_depth": average number of pending read
1872                                 operations in the defined interval
1873                                 (json-number)
1874         - "avg_wr_queue_depth": average number of pending write
1875                                 operations in the defined interval
1876                                 (json-number).
1877 - "parent": Contains recursively the statistics of the underlying
1878             protocol (e.g. the host file for a qcow2 image). If there is
1879             no underlying protocol, this field is omitted
1880             (json-object, optional)
1881
1882 Example:
1883
1884 -> { "execute": "query-blockstats" }
1885 <- {
1886       "return":[
1887          {
1888             "device":"ide0-hd0",
1889             "parent":{
1890                "stats":{
1891                   "wr_highest_offset":3686448128,
1892                   "wr_bytes":9786368,
1893                   "wr_operations":751,
1894                   "rd_bytes":122567168,
1895                   "rd_operations":36772
1896                   "wr_total_times_ns":313253456
1897                   "rd_total_times_ns":3465673657
1898                   "flush_total_times_ns":49653
1899                   "flush_operations":61,
1900                   "rd_merged":0,
1901                   "wr_merged":0,
1902                   "idle_time_ns":2953431879,
1903                   "account_invalid":true,
1904                   "account_failed":false
1905                }
1906             },
1907             "stats":{
1908                "wr_highest_offset":2821110784,
1909                "wr_bytes":9786368,
1910                "wr_operations":692,
1911                "rd_bytes":122739200,
1912                "rd_operations":36604
1913                "flush_operations":51,
1914                "wr_total_times_ns":313253456
1915                "rd_total_times_ns":3465673657
1916                "flush_total_times_ns":49653,
1917                "rd_merged":0,
1918                "wr_merged":0,
1919                "idle_time_ns":2953431879,
1920                "account_invalid":true,
1921                "account_failed":false
1922             }
1923          },
1924          {
1925             "device":"ide1-cd0",
1926             "stats":{
1927                "wr_highest_offset":0,
1928                "wr_bytes":0,
1929                "wr_operations":0,
1930                "rd_bytes":0,
1931                "rd_operations":0
1932                "flush_operations":0,
1933                "wr_total_times_ns":0
1934                "rd_total_times_ns":0
1935                "flush_total_times_ns":0,
1936                "rd_merged":0,
1937                "wr_merged":0,
1938                "account_invalid":false,
1939                "account_failed":false
1940             }
1941          },
1942          {
1943             "device":"floppy0",
1944             "stats":{
1945                "wr_highest_offset":0,
1946                "wr_bytes":0,
1947                "wr_operations":0,
1948                "rd_bytes":0,
1949                "rd_operations":0
1950                "flush_operations":0,
1951                "wr_total_times_ns":0
1952                "rd_total_times_ns":0
1953                "flush_total_times_ns":0,
1954                "rd_merged":0,
1955                "wr_merged":0,
1956                "account_invalid":false,
1957                "account_failed":false
1958             }
1959          },
1960          {
1961             "device":"sd0",
1962             "stats":{
1963                "wr_highest_offset":0,
1964                "wr_bytes":0,
1965                "wr_operations":0,
1966                "rd_bytes":0,
1967                "rd_operations":0
1968                "flush_operations":0,
1969                "wr_total_times_ns":0
1970                "rd_total_times_ns":0
1971                "flush_total_times_ns":0,
1972                "rd_merged":0,
1973                "wr_merged":0,
1974                "account_invalid":false,
1975                "account_failed":false
1976             }
1977          }
1978       ]
1979    }
1980
1981 query-cpus
1982 ----------
1983
1984 Show CPU information.
1985
1986 Return a json-array. Each CPU is represented by a json-object, which contains:
1987
1988 - "CPU": CPU index (json-int)
1989 - "current": true if this is the current CPU, false otherwise (json-bool)
1990 - "halted": true if the cpu is halted, false otherwise (json-bool)
1991 - "qom_path": path to the CPU object in the QOM tree (json-str)
1992 - "arch": architecture of the cpu, which determines what additional
1993           keys will be present (json-str)
1994 - Current program counter. The key's name depends on the architecture:
1995      "pc": i386/x86_64 (json-int)
1996      "nip": PPC (json-int)
1997      "pc" and "npc": sparc (json-int)
1998      "PC": mips (json-int)
1999 - "thread_id": ID of the underlying host thread (json-int)
2000
2001 Example:
2002
2003 -> { "execute": "query-cpus" }
2004 <- {
2005       "return":[
2006          {
2007             "CPU":0,
2008             "current":true,
2009             "halted":false,
2010             "qom_path":"/machine/unattached/device[0]",
2011             "arch":"x86",
2012             "pc":3227107138,
2013             "thread_id":3134
2014          },
2015          {
2016             "CPU":1,
2017             "current":false,
2018             "halted":true,
2019             "qom_path":"/machine/unattached/device[2]",
2020             "arch":"x86",
2021             "pc":7108165,
2022             "thread_id":3135
2023          }
2024       ]
2025    }
2026
2027 query-iothreads
2028 ---------------
2029
2030 Returns a list of information about each iothread.
2031
2032 Note this list excludes the QEMU main loop thread, which is not declared
2033 using the -object iothread command-line option.  It is always the main thread
2034 of the process.
2035
2036 Return a json-array. Each iothread is represented by a json-object, which contains:
2037
2038 - "id": name of iothread (json-str)
2039 - "thread-id": ID of the underlying host thread (json-int)
2040
2041 Example:
2042
2043 -> { "execute": "query-iothreads" }
2044 <- {
2045       "return":[
2046          {
2047             "id":"iothread0",
2048             "thread-id":3134
2049          },
2050          {
2051             "id":"iothread1",
2052             "thread-id":3135
2053          }
2054       ]
2055    }
2056
2057 query-pci
2058 ---------
2059
2060 PCI buses and devices information.
2061
2062 The returned value is a json-array of all buses. Each bus is represented by
2063 a json-object, which has a key with a json-array of all PCI devices attached
2064 to it. Each device is represented by a json-object.
2065
2066 The bus json-object contains the following:
2067
2068 - "bus": bus number (json-int)
2069 - "devices": a json-array of json-objects, each json-object represents a
2070              PCI device
2071
2072 The PCI device json-object contains the following:
2073
2074 - "bus": identical to the parent's bus number (json-int)
2075 - "slot": slot number (json-int)
2076 - "function": function number (json-int)
2077 - "class_info": a json-object containing:
2078      - "desc": device class description (json-string, optional)
2079      - "class": device class number (json-int)
2080 - "id": a json-object containing:
2081      - "device": device ID (json-int)
2082      - "vendor": vendor ID (json-int)
2083 - "irq": device's IRQ if assigned (json-int, optional)
2084 - "qdev_id": qdev id string (json-string)
2085 - "pci_bridge": It's a json-object, only present if this device is a
2086                 PCI bridge, contains:
2087      - "bus": bus number (json-int)
2088      - "secondary": secondary bus number (json-int)
2089      - "subordinate": subordinate bus number (json-int)
2090      - "io_range": I/O memory range information, a json-object with the
2091                    following members:
2092                  - "base": base address, in bytes (json-int)
2093                  - "limit": limit address, in bytes (json-int)
2094      - "memory_range": memory range information, a json-object with the
2095                        following members:
2096                  - "base": base address, in bytes (json-int)
2097                  - "limit": limit address, in bytes (json-int)
2098      - "prefetchable_range": Prefetchable memory range information, a
2099                              json-object with the following members:
2100                  - "base": base address, in bytes (json-int)
2101                  - "limit": limit address, in bytes (json-int)
2102      - "devices": a json-array of PCI devices if there's any attached, each
2103                   each element is represented by a json-object, which contains
2104                   the same members of the 'PCI device json-object' described
2105                   above (optional)
2106 - "regions": a json-array of json-objects, each json-object represents a
2107              memory region of this device
2108
2109 The memory range json-object contains the following:
2110
2111 - "base": base memory address (json-int)
2112 - "limit": limit value (json-int)
2113
2114 The region json-object can be an I/O region or a memory region, an I/O region
2115 json-object contains the following:
2116
2117 - "type": "io" (json-string, fixed)
2118 - "bar": BAR number (json-int)
2119 - "address": memory address (json-int)
2120 - "size": memory size (json-int)
2121
2122 A memory region json-object contains the following:
2123
2124 - "type": "memory" (json-string, fixed)
2125 - "bar": BAR number (json-int)
2126 - "address": memory address (json-int)
2127 - "size": memory size (json-int)
2128 - "mem_type_64": true or false (json-bool)
2129 - "prefetch": true or false (json-bool)
2130
2131 Example:
2132
2133 -> { "execute": "query-pci" }
2134 <- {
2135       "return":[
2136          {
2137             "bus":0,
2138             "devices":[
2139                {
2140                   "bus":0,
2141                   "qdev_id":"",
2142                   "slot":0,
2143                   "class_info":{
2144                      "class":1536,
2145                      "desc":"Host bridge"
2146                   },
2147                   "id":{
2148                      "device":32902,
2149                      "vendor":4663
2150                   },
2151                   "function":0,
2152                   "regions":[
2153
2154                   ]
2155                },
2156                {
2157                   "bus":0,
2158                   "qdev_id":"",
2159                   "slot":1,
2160                   "class_info":{
2161                      "class":1537,
2162                      "desc":"ISA bridge"
2163                   },
2164                   "id":{
2165                      "device":32902,
2166                      "vendor":28672
2167                   },
2168                   "function":0,
2169                   "regions":[
2170
2171                   ]
2172                },
2173                {
2174                   "bus":0,
2175                   "qdev_id":"",
2176                   "slot":1,
2177                   "class_info":{
2178                      "class":257,
2179                      "desc":"IDE controller"
2180                   },
2181                   "id":{
2182                      "device":32902,
2183                      "vendor":28688
2184                   },
2185                   "function":1,
2186                   "regions":[
2187                      {
2188                         "bar":4,
2189                         "size":16,
2190                         "address":49152,
2191                         "type":"io"
2192                      }
2193                   ]
2194                },
2195                {
2196                   "bus":0,
2197                   "qdev_id":"",
2198                   "slot":2,
2199                   "class_info":{
2200                      "class":768,
2201                      "desc":"VGA controller"
2202                   },
2203                   "id":{
2204                      "device":4115,
2205                      "vendor":184
2206                   },
2207                   "function":0,
2208                   "regions":[
2209                      {
2210                         "prefetch":true,
2211                         "mem_type_64":false,
2212                         "bar":0,
2213                         "size":33554432,
2214                         "address":4026531840,
2215                         "type":"memory"
2216                      },
2217                      {
2218                         "prefetch":false,
2219                         "mem_type_64":false,
2220                         "bar":1,
2221                         "size":4096,
2222                         "address":4060086272,
2223                         "type":"memory"
2224                      },
2225                      {
2226                         "prefetch":false,
2227                         "mem_type_64":false,
2228                         "bar":6,
2229                         "size":65536,
2230                         "address":-1,
2231                         "type":"memory"
2232                      }
2233                   ]
2234                },
2235                {
2236                   "bus":0,
2237                   "qdev_id":"",
2238                   "irq":11,
2239                   "slot":4,
2240                   "class_info":{
2241                      "class":1280,
2242                      "desc":"RAM controller"
2243                   },
2244                   "id":{
2245                      "device":6900,
2246                      "vendor":4098
2247                   },
2248                   "function":0,
2249                   "regions":[
2250                      {
2251                         "bar":0,
2252                         "size":32,
2253                         "address":49280,
2254                         "type":"io"
2255                      }
2256                   ]
2257                }
2258             ]
2259          }
2260       ]
2261    }
2262
2263 Note: This example has been shortened as the real response is too long.
2264
2265 query-mice
2266 ----------
2267
2268 Show VM mice information.
2269
2270 Each mouse is represented by a json-object, the returned value is a json-array
2271 of all mice.
2272
2273 The mouse json-object contains the following:
2274
2275 - "name": mouse's name (json-string)
2276 - "index": mouse's index (json-int)
2277 - "current": true if this mouse is receiving events, false otherwise (json-bool)
2278 - "absolute": true if the mouse generates absolute input events (json-bool)
2279
2280 Example:
2281
2282 -> { "execute": "query-mice" }
2283 <- {
2284       "return":[
2285          {
2286             "name":"QEMU Microsoft Mouse",
2287             "index":0,
2288             "current":false,
2289             "absolute":false
2290          },
2291          {
2292             "name":"QEMU PS/2 Mouse",
2293             "index":1,
2294             "current":true,
2295             "absolute":true
2296          }
2297       ]
2298    }
2299
2300 query-vnc
2301 ---------
2302
2303 Show VNC server information.
2304
2305 Return a json-object with server information. Connected clients are returned
2306 as a json-array of json-objects.
2307
2308 The main json-object contains the following:
2309
2310 - "enabled": true or false (json-bool)
2311 - "host": server's IP address (json-string)
2312 - "family": address family (json-string)
2313          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2314 - "service": server's port number (json-string)
2315 - "auth": authentication method (json-string)
2316          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2317                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2318                             "vencrypt+plain", "vencrypt+tls+none",
2319                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
2320                             "vencrypt+tls+vnc", "vencrypt+x509+none",
2321                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
2322                             "vencrypt+x509+vnc", "vnc"
2323 - "clients": a json-array of all connected clients
2324
2325 Clients are described by a json-object, each one contain the following:
2326
2327 - "host": client's IP address (json-string)
2328 - "family": address family (json-string)
2329          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2330 - "service": client's port number (json-string)
2331 - "x509_dname": TLS dname (json-string, optional)
2332 - "sasl_username": SASL username (json-string, optional)
2333
2334 Example:
2335
2336 -> { "execute": "query-vnc" }
2337 <- {
2338       "return":{
2339          "enabled":true,
2340          "host":"0.0.0.0",
2341          "service":"50402",
2342          "auth":"vnc",
2343          "family":"ipv4",
2344          "clients":[
2345             {
2346                "host":"127.0.0.1",
2347                "service":"50401",
2348                "family":"ipv4"
2349             }
2350          ]
2351       }
2352    }
2353
2354 query-spice
2355 -----------
2356
2357 Show SPICE server information.
2358
2359 Return a json-object with server information. Connected clients are returned
2360 as a json-array of json-objects.
2361
2362 The main json-object contains the following:
2363
2364 - "enabled": true or false (json-bool)
2365 - "host": server's IP address (json-string)
2366 - "port": server's port number (json-int, optional)
2367 - "tls-port": server's port number (json-int, optional)
2368 - "auth": authentication method (json-string)
2369          - Possible values: "none", "spice"
2370 - "channels": a json-array of all active channels clients
2371
2372 Channels are described by a json-object, each one contain the following:
2373
2374 - "host": client's IP address (json-string)
2375 - "family": address family (json-string)
2376          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2377 - "port": client's port number (json-string)
2378 - "connection-id": spice connection id.  All channels with the same id
2379                    belong to the same spice session (json-int)
2380 - "channel-type": channel type.  "1" is the main control channel, filter for
2381                   this one if you want track spice sessions only (json-int)
2382 - "channel-id": channel id.  Usually "0", might be different needed when
2383                 multiple channels of the same type exist, such as multiple
2384                 display channels in a multihead setup (json-int)
2385 - "tls": whether the channel is encrypted (json-bool)
2386
2387 Example:
2388
2389 -> { "execute": "query-spice" }
2390 <- {
2391       "return": {
2392          "enabled": true,
2393          "auth": "spice",
2394          "port": 5920,
2395          "tls-port": 5921,
2396          "host": "0.0.0.0",
2397          "channels": [
2398             {
2399                "port": "54924",
2400                "family": "ipv4",
2401                "channel-type": 1,
2402                "connection-id": 1804289383,
2403                "host": "127.0.0.1",
2404                "channel-id": 0,
2405                "tls": true
2406             },
2407             {
2408                "port": "36710",
2409                "family": "ipv4",
2410                "channel-type": 4,
2411                "connection-id": 1804289383,
2412                "host": "127.0.0.1",
2413                "channel-id": 0,
2414                "tls": false
2415             },
2416             [ ... more channels follow ... ]
2417          ]
2418       }
2419    }
2420
2421 query-command-line-options
2422 --------------------------
2423
2424 Show command line option schema.
2425
2426 Return a json-array of command line option schema for all options (or for
2427 the given option), returning an error if the given option doesn't exist.
2428
2429 Each array entry contains the following:
2430
2431 - "option": option name (json-string)
2432 - "parameters": a json-array describes all parameters of the option:
2433     - "name": parameter name (json-string)
2434     - "type": parameter type (one of 'string', 'boolean', 'number',
2435               or 'size')
2436     - "help": human readable description of the parameter
2437               (json-string, optional)
2438     - "default": default value string for the parameter
2439                  (json-string, optional)
2440
2441 Example:
2442
2443 -> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } }
2444 <- { "return": [
2445         {
2446             "parameters": [
2447                 {
2448                     "name": "romfile",
2449                     "type": "string"
2450                 },
2451                 {
2452                     "name": "bootindex",
2453                     "type": "number"
2454                 }
2455             ],
2456             "option": "option-rom"
2457         }
2458      ]
2459    }
2460
2461 query-migrate-parameters
2462 ------------------------
2463
2464 Query current migration parameters
2465
2466 - "parameters": migration parameters value
2467          - "compress-level" : compression level value (json-int)
2468          - "compress-threads" : compression thread count value (json-int)
2469          - "decompress-threads" : decompression thread count value (json-int)
2470          - "cpu-throttle-initial" : initial percentage of time guest cpus are
2471                                     throttled (json-int)
2472          - "cpu-throttle-increment" : throttle increasing percentage for
2473                                       auto-converge (json-int)
2474          - "max-bandwidth" : maximium migration speed in bytes per second
2475                              (json-int)
2476          - "downtime-limit" : maximum tolerated downtime of migration in
2477                               milliseconds (json-int)
2478 Arguments:
2479
2480 Example:
2481
2482 -> { "execute": "query-migrate-parameters" }
2483 <- {
2484       "return": {
2485          "decompress-threads": 2,
2486          "cpu-throttle-increment": 10,
2487          "compress-threads": 8,
2488          "compress-level": 1,
2489          "cpu-throttle-initial": 20,
2490          "max-bandwidth": 33554432,
2491          "downtime-limit": 300
2492       }
2493    }
2494
2495 query-balloon
2496 -------------
2497
2498 Show balloon information.
2499
2500 Make an asynchronous request for balloon info. When the request completes a
2501 json-object will be returned containing the following data:
2502
2503 - "actual": current balloon value in bytes (json-int)
2504
2505 Example:
2506
2507 -> { "execute": "query-balloon" }
2508 <- {
2509       "return":{
2510          "actual":1073741824,
2511       }
2512    }
2513
2514 query-tpm
2515 ---------
2516
2517 Return information about the TPM device.
2518
2519 Arguments: None
2520
2521 Example:
2522
2523 -> { "execute": "query-tpm" }
2524 <- { "return":
2525      [
2526        { "model": "tpm-tis",
2527          "options":
2528            { "type": "passthrough",
2529              "data":
2530                { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
2531                  "path": "/dev/tpm0"
2532                }
2533            },
2534          "id": "tpm0"
2535        }
2536      ]
2537    }
2538
2539 query-tpm-models
2540 ----------------
2541
2542 Return a list of supported TPM models.
2543
2544 Arguments: None
2545
2546 Example:
2547
2548 -> { "execute": "query-tpm-models" }
2549 <- { "return": [ "tpm-tis" ] }
2550
2551 query-tpm-types
2552 ---------------
2553
2554 Return a list of supported TPM types.
2555
2556 Arguments: None
2557
2558 Example:
2559
2560 -> { "execute": "query-tpm-types" }
2561 <- { "return": [ "passthrough" ] }
2562
2563 chardev-add
2564 ----------------
2565
2566 Add a chardev.
2567
2568 Arguments:
2569
2570 - "id": the chardev's ID, must be unique (json-string)
2571 - "backend": chardev backend type + parameters
2572
2573 Examples:
2574
2575 -> { "execute" : "chardev-add",
2576      "arguments" : { "id" : "foo",
2577                      "backend" : { "type" : "null", "data" : {} } } }
2578 <- { "return": {} }
2579
2580 -> { "execute" : "chardev-add",
2581      "arguments" : { "id" : "bar",
2582                      "backend" : { "type" : "file",
2583                                    "data" : { "out" : "/tmp/bar.log" } } } }
2584 <- { "return": {} }
2585
2586 -> { "execute" : "chardev-add",
2587      "arguments" : { "id" : "baz",
2588                      "backend" : { "type" : "pty", "data" : {} } } }
2589 <- { "return": { "pty" : "/dev/pty/42" } }
2590
2591 chardev-remove
2592 --------------
2593
2594 Remove a chardev.
2595
2596 Arguments:
2597
2598 - "id": the chardev's ID, must exist and not be in use (json-string)
2599
2600 Example:
2601
2602 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
2603 <- { "return": {} }
2604
2605 query-rx-filter
2606 ---------------
2607
2608 Show rx-filter information.
2609
2610 Returns a json-array of rx-filter information for all NICs (or for the
2611 given NIC), returning an error if the given NIC doesn't exist, or
2612 given NIC doesn't support rx-filter querying, or given net client
2613 isn't a NIC.
2614
2615 The query will clear the event notification flag of each NIC, then qemu
2616 will start to emit event to QMP monitor.
2617
2618 Each array entry contains the following:
2619
2620 - "name": net client name (json-string)
2621 - "promiscuous": promiscuous mode is enabled (json-bool)
2622 - "multicast": multicast receive state (one of 'normal', 'none', 'all')
2623 - "unicast": unicast receive state  (one of 'normal', 'none', 'all')
2624 - "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0)
2625 - "broadcast-allowed": allow to receive broadcast (json-bool)
2626 - "multicast-overflow": multicast table is overflowed (json-bool)
2627 - "unicast-overflow": unicast table is overflowed (json-bool)
2628 - "main-mac": main macaddr string (json-string)
2629 - "vlan-table": a json-array of active vlan id
2630 - "unicast-table": a json-array of unicast macaddr string
2631 - "multicast-table": a json-array of multicast macaddr string
2632
2633 Example:
2634
2635 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
2636 <- { "return": [
2637         {
2638             "promiscuous": true,
2639             "name": "vnet0",
2640             "main-mac": "52:54:00:12:34:56",
2641             "unicast": "normal",
2642             "vlan": "normal",
2643             "vlan-table": [
2644                 4,
2645                 0
2646             ],
2647             "unicast-table": [
2648             ],
2649             "multicast": "normal",
2650             "multicast-overflow": false,
2651             "unicast-overflow": false,
2652             "multicast-table": [
2653                 "01:00:5e:00:00:01",
2654                 "33:33:00:00:00:01",
2655                 "33:33:ff:12:34:56"
2656             ],
2657             "broadcast-allowed": false
2658         }
2659       ]
2660    }
2661
2662 blockdev-add
2663 ------------
2664
2665 Add a block device.
2666
2667 This command is still a work in progress.  It doesn't support all
2668 block drivers among other things.  Stay away from it unless you want
2669 to help with its development.
2670
2671 For the arguments, see the QAPI schema documentation of BlockdevOptions.
2672
2673 Example (1):
2674
2675 -> { "execute": "blockdev-add",
2676     "arguments": { "driver": "qcow2",
2677                    "file": { "driver": "file",
2678                              "filename": "test.qcow2" } } }
2679 <- { "return": {} }
2680
2681 Example (2):
2682
2683 -> { "execute": "blockdev-add",
2684      "arguments": {
2685          "driver": "qcow2",
2686          "node-name": "my_disk",
2687          "discard": "unmap",
2688          "cache": {
2689              "direct": true,
2690              "writeback": true
2691          },
2692          "file": {
2693              "driver": "file",
2694              "filename": "/tmp/test.qcow2"
2695          },
2696          "backing": {
2697              "driver": "raw",
2698              "file": {
2699                  "driver": "file",
2700                  "filename": "/dev/fdset/4"
2701              }
2702          }
2703        }
2704      }
2705
2706 <- { "return": {} }
2707
2708 x-blockdev-del
2709 ------------
2710 Since 2.5
2711
2712 Deletes a block device that has been added using blockdev-add.
2713 The command will fail if the node is attached to a device or is
2714 otherwise being used.
2715
2716 This command is still a work in progress and is considered
2717 experimental. Stay away from it unless you want to help with its
2718 development.
2719
2720 Arguments:
2721
2722 - "node-name": Name of the graph node to delete (json-string)
2723
2724 Example:
2725
2726 -> { "execute": "blockdev-add",
2727      "arguments": {
2728          "driver": "qcow2",
2729          "node-name": "node0",
2730          "file": {
2731              "driver": "file",
2732              "filename": "test.qcow2"
2733          }
2734      }
2735    }
2736
2737 <- { "return": {} }
2738
2739 -> { "execute": "x-blockdev-del",
2740      "arguments": { "node-name": "node0" }
2741    }
2742 <- { "return": {} }
2743
2744 blockdev-open-tray
2745 ------------------
2746
2747 Opens a block device's tray. If there is a block driver state tree inserted as a
2748 medium, it will become inaccessible to the guest (but it will remain associated
2749 to the block device, so closing the tray will make it accessible again).
2750
2751 If the tray was already open before, this will be a no-op.
2752
2753 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
2754 which no such event will be generated, these include:
2755 - if the guest has locked the tray, @force is false and the guest does not
2756   respond to the eject request
2757 - if the BlockBackend denoted by @device does not have a guest device attached
2758   to it
2759 - if the guest device does not have an actual tray and is empty, for instance
2760   for floppy disk drives
2761
2762 Arguments:
2763
2764 - "device": block device name (deprecated, use @id instead)
2765             (json-string, optional)
2766 - "id": the name or QOM path of the guest device (json-string, optional)
2767 - "force": if false (the default), an eject request will be sent to the guest if
2768            it has locked the tray (and the tray will not be opened immediately);
2769            if true, the tray will be opened regardless of whether it is locked
2770            (json-bool, optional)
2771
2772 Example:
2773
2774 -> { "execute": "blockdev-open-tray",
2775      "arguments": { "id": "ide0-1-0" } }
2776
2777 <- { "timestamp": { "seconds": 1418751016,
2778                     "microseconds": 716996 },
2779      "event": "DEVICE_TRAY_MOVED",
2780      "data": { "device": "ide1-cd0",
2781                "id": "ide0-1-0",
2782                "tray-open": true } }
2783
2784 <- { "return": {} }
2785
2786 blockdev-close-tray
2787 -------------------
2788
2789 Closes a block device's tray. If there is a block driver state tree associated
2790 with the block device (which is currently ejected), that tree will be loaded as
2791 the medium.
2792
2793 If the tray was already closed before, this will be a no-op.
2794
2795 Arguments:
2796
2797 - "device": block device name (deprecated, use @id instead)
2798             (json-string, optional)
2799 - "id": the name or QOM path of the guest device (json-string, optional)
2800
2801 Example:
2802
2803 -> { "execute": "blockdev-close-tray",
2804      "arguments": { "id": "ide0-1-0" } }
2805
2806 <- { "timestamp": { "seconds": 1418751345,
2807                     "microseconds": 272147 },
2808      "event": "DEVICE_TRAY_MOVED",
2809      "data": { "device": "ide1-cd0",
2810                "id": "ide0-1-0",
2811                "tray-open": false } }
2812
2813 <- { "return": {} }
2814
2815 x-blockdev-remove-medium
2816 ------------------------
2817
2818 Removes a medium (a block driver state tree) from a block device. That block
2819 device's tray must currently be open (unless there is no attached guest device).
2820
2821 If the tray is open and there is no medium inserted, this will be a no-op.
2822
2823 This command is still a work in progress and is considered experimental.
2824 Stay away from it unless you want to help with its development.
2825
2826 Arguments:
2827
2828 - "device": block device name (deprecated, use @id instead)
2829             (json-string, optional)
2830 - "id": the name or QOM path of the guest device (json-string, optional)
2831
2832 Example:
2833
2834 -> { "execute": "x-blockdev-remove-medium",
2835      "arguments": { "id": "ide0-1-0" } }
2836
2837 <- { "error": { "class": "GenericError",
2838                 "desc": "Tray of device 'ide0-1-0' is not open" } }
2839
2840 -> { "execute": "blockdev-open-tray",
2841      "arguments": { "id": "ide0-1-0" } }
2842
2843 <- { "timestamp": { "seconds": 1418751627,
2844                     "microseconds": 549958 },
2845      "event": "DEVICE_TRAY_MOVED",
2846      "data": { "device": "ide1-cd0",
2847                "id": "ide0-1-0",
2848                "tray-open": true } }
2849
2850 <- { "return": {} }
2851
2852 -> { "execute": "x-blockdev-remove-medium",
2853      "arguments": { "device": "ide0-1-0" } }
2854
2855 <- { "return": {} }
2856
2857 x-blockdev-insert-medium
2858 ------------------------
2859
2860 Inserts a medium (a block driver state tree) into a block device. That block
2861 device's tray must currently be open (unless there is no attached guest device)
2862 and there must be no medium inserted already.
2863
2864 This command is still a work in progress and is considered experimental.
2865 Stay away from it unless you want to help with its development.
2866
2867 Arguments:
2868
2869 - "device": block device name (deprecated, use @id instead)
2870             (json-string, optional)
2871 - "id": the name or QOM path of the guest device (json-string, optional)
2872 - "node-name": root node of the BDS tree to insert into the block device
2873
2874 Example:
2875
2876 -> { "execute": "blockdev-add",
2877      "arguments": { { "node-name": "node0",
2878                       "driver": "raw",
2879                       "file": { "driver": "file",
2880                                 "filename": "fedora.iso" } } }
2881
2882 <- { "return": {} }
2883
2884 -> { "execute": "x-blockdev-insert-medium",
2885      "arguments": { "id": "ide0-1-0",
2886                     "node-name": "node0" } }
2887
2888 <- { "return": {} }
2889
2890 x-blockdev-change
2891 -----------------
2892
2893 Dynamically reconfigure the block driver state graph. It can be used
2894 to add, remove, insert or replace a graph node. Currently only the
2895 Quorum driver implements this feature to add or remove its child. This
2896 is useful to fix a broken quorum child.
2897
2898 If @node is specified, it will be inserted under @parent. @child
2899 may not be specified in this case. If both @parent and @child are
2900 specified but @node is not, @child will be detached from @parent.
2901
2902 Arguments:
2903 - "parent": the id or name of the parent node (json-string)
2904 - "child": the name of a child under the given parent node (json-string, optional)
2905 - "node": the name of the node that will be added (json-string, optional)
2906
2907 Note: this command is experimental, and not a stable API. It doesn't
2908 support all kinds of operations, all kinds of children, nor all block
2909 drivers.
2910
2911 Warning: The data in a new quorum child MUST be consistent with that of
2912 the rest of the array.
2913
2914 Example:
2915
2916 Add a new node to a quorum
2917 -> { "execute": "blockdev-add",
2918      "arguments": { "driver": "raw",
2919                     "node-name": "new_node",
2920                     "file": { "driver": "file",
2921                               "filename": "test.raw" } } }
2922 <- { "return": {} }
2923 -> { "execute": "x-blockdev-change",
2924      "arguments": { "parent": "disk1",
2925                     "node": "new_node" } }
2926 <- { "return": {} }
2927
2928 Delete a quorum's node
2929 -> { "execute": "x-blockdev-change",
2930      "arguments": { "parent": "disk1",
2931                     "child": "children.1" } }
2932 <- { "return": {} }
2933
2934 query-named-block-nodes
2935 -----------------------
2936
2937 Return a list of BlockDeviceInfo for all the named block driver nodes
2938
2939 Example:
2940
2941 -> { "execute": "query-named-block-nodes" }
2942 <- { "return": [ { "ro":false,
2943                    "drv":"qcow2",
2944                    "encrypted":false,
2945                    "file":"disks/test.qcow2",
2946                    "node-name": "my-node",
2947                    "backing_file_depth":1,
2948                    "bps":1000000,
2949                    "bps_rd":0,
2950                    "bps_wr":0,
2951                    "iops":1000000,
2952                    "iops_rd":0,
2953                    "iops_wr":0,
2954                    "bps_max": 8000000,
2955                    "bps_rd_max": 0,
2956                    "bps_wr_max": 0,
2957                    "iops_max": 0,
2958                    "iops_rd_max": 0,
2959                    "iops_wr_max": 0,
2960                    "iops_size": 0,
2961                    "write_threshold": 0,
2962                    "image":{
2963                       "filename":"disks/test.qcow2",
2964                       "format":"qcow2",
2965                       "virtual-size":2048000,
2966                       "backing_file":"base.qcow2",
2967                       "full-backing-filename":"disks/base.qcow2",
2968                       "backing-filename-format":"qcow2",
2969                       "snapshots":[
2970                          {
2971                             "id": "1",
2972                             "name": "snapshot1",
2973                             "vm-state-size": 0,
2974                             "date-sec": 10000200,
2975                             "date-nsec": 12,
2976                             "vm-clock-sec": 206,
2977                             "vm-clock-nsec": 30
2978                          }
2979                       ],
2980                       "backing-image":{
2981                           "filename":"disks/base.qcow2",
2982                           "format":"qcow2",
2983                           "virtual-size":2048000
2984                       }
2985                    } } ] }
2986
2987 blockdev-change-medium
2988 ----------------------
2989
2990 Changes the medium inserted into a block device by ejecting the current medium
2991 and loading a new image file which is inserted as the new medium.
2992
2993 Arguments:
2994
2995 - "device": block device name (deprecated, use @id instead)
2996             (json-string, optional)
2997 - "id": the name or QOM path of the guest device (json-string, optional)
2998 - "filename": filename of the new image (json-string)
2999 - "format": format of the new image (json-string, optional)
3000 - "read-only-mode": new read-only mode (json-string, optional)
3001           - Possible values: "retain" (default), "read-only", "read-write"
3002
3003 Examples:
3004
3005 1. Change a removable medium
3006
3007 -> { "execute": "blockdev-change-medium",
3008              "arguments": { "id": "ide0-1-0",
3009                             "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
3010                             "format": "raw" } }
3011 <- { "return": {} }
3012
3013 2. Load a read-only medium into a writable drive
3014
3015 -> { "execute": "blockdev-change-medium",
3016              "arguments": { "id": "floppyA",
3017                             "filename": "/srv/images/ro.img",
3018                             "format": "raw",
3019                             "read-only-mode": "retain" } }
3020
3021 <- { "error":
3022      { "class": "GenericError",
3023        "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
3024
3025 -> { "execute": "blockdev-change-medium",
3026              "arguments": { "id": "floppyA",
3027                             "filename": "/srv/images/ro.img",
3028                             "format": "raw",
3029                             "read-only-mode": "read-only" } }
3030
3031 <- { "return": {} }
3032
3033 query-memdev
3034 ------------
3035
3036 Show memory devices information.
3037
3038
3039 Example (1):
3040
3041 -> { "execute": "query-memdev" }
3042 <- { "return": [
3043        {
3044          "size": 536870912,
3045          "merge": false,
3046          "dump": true,
3047          "prealloc": false,
3048          "host-nodes": [0, 1],
3049          "policy": "bind"
3050        },
3051        {
3052          "id": "mem1",
3053          "size": 536870912,
3054          "merge": false,
3055          "dump": true,
3056          "prealloc": true,
3057          "host-nodes": [2, 3],
3058          "policy": "preferred"
3059        }
3060      ]
3061    }
3062
3063 query-memory-devices
3064 --------------------
3065
3066 Return a list of memory devices.
3067
3068 Example:
3069 -> { "execute": "query-memory-devices" }
3070 <- { "return": [ { "data":
3071                       { "addr": 5368709120,
3072                         "hotpluggable": true,
3073                         "hotplugged": true,
3074                         "id": "d1",
3075                         "memdev": "/objects/memX",
3076                         "node": 0,
3077                         "size": 1073741824,
3078                         "slot": 0},
3079                    "type": "dimm"
3080                  } ] }
3081
3082 query-acpi-ospm-status
3083 ----------------------
3084
3085 Return list of ACPIOSTInfo for devices that support status reporting
3086 via ACPI _OST method.
3087
3088 Example:
3089 -> { "execute": "query-acpi-ospm-status" }
3090 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
3091                  { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
3092                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
3093                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
3094    ]}
3095
3096 rtc-reset-reinjection
3097 ---------------------
3098
3099 Reset the RTC interrupt reinjection backlog.
3100
3101 Arguments: None.
3102
3103 Example:
3104
3105 -> { "execute": "rtc-reset-reinjection" }
3106 <- { "return": {} }
3107
3108 trace-event-get-state
3109 ---------------------
3110
3111 Query the state of events.
3112
3113 Arguments:
3114
3115 - "name": Event name pattern (json-string).
3116 - "vcpu": The vCPU to query, any vCPU by default (json-int, optional).
3117
3118 An event is returned if:
3119 - its name matches the "name" pattern, and
3120 - if "vcpu" is given, the event has the "vcpu" property.
3121
3122 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
3123 returning their state on the specified vCPU. Special case: if "name" is an exact
3124 match, "vcpu" is given and the event does not have the "vcpu" property, an error
3125 is returned.
3126
3127 Example:
3128
3129 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
3130 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
3131
3132 trace-event-set-state
3133 ---------------------
3134
3135 Set the state of events.
3136
3137 Arguments:
3138
3139 - "name": Event name pattern (json-string).
3140 - "enable": Whether to enable or disable the event (json-bool).
3141 - "ignore-unavailable": Whether to ignore errors for events that cannot be
3142   changed (json-bool, optional).
3143 - "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional).
3144
3145 An event's state is modified if:
3146 - its name matches the "name" pattern, and
3147 - if "vcpu" is given, the event has the "vcpu" property.
3148
3149 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
3150 setting their state on the specified vCPU. Special case: if "name" is an exact
3151 match, "vcpu" is given and the event does not have the "vcpu" property, an error
3152 is returned.
3153
3154 Example:
3155
3156 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
3157 <- { "return": {} }
3158
3159 input-send-event
3160 ----------------
3161
3162 Send input event to guest.
3163
3164 Arguments:
3165
3166 - "device": display device (json-string, optional)
3167 - "head": display head (json-int, optional)
3168 - "events": list of input events
3169
3170 The consoles are visible in the qom tree, under
3171 /backend/console[$index]. They have a device link and head property, so
3172 it is possible to map which console belongs to which device and display.
3173
3174 Example (1):
3175
3176 Press left mouse button.
3177
3178 -> { "execute": "input-send-event",
3179     "arguments": { "device": "video0",
3180                    "events": [ { "type": "btn",
3181                    "data" : { "down": true, "button": "left" } } ] } }
3182 <- { "return": {} }
3183
3184 -> { "execute": "input-send-event",
3185     "arguments": { "device": "video0",
3186                    "events": [ { "type": "btn",
3187                    "data" : { "down": false, "button": "left" } } ] } }
3188 <- { "return": {} }
3189
3190 Example (2):
3191
3192 Press ctrl-alt-del.
3193
3194 -> { "execute": "input-send-event",
3195      "arguments": { "events": [
3196         { "type": "key", "data" : { "down": true,
3197           "key": {"type": "qcode", "data": "ctrl" } } },
3198         { "type": "key", "data" : { "down": true,
3199           "key": {"type": "qcode", "data": "alt" } } },
3200         { "type": "key", "data" : { "down": true,
3201           "key": {"type": "qcode", "data": "delete" } } } ] } }
3202 <- { "return": {} }
3203
3204 Example (3):
3205
3206 Move mouse pointer to absolute coordinates (20000, 400).
3207
3208 -> { "execute": "input-send-event" ,
3209   "arguments": { "events": [
3210                { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
3211                { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
3212 <- { "return": {} }
3213
3214 block-set-write-threshold
3215 ------------
3216
3217 Change the write threshold for a block drive. The threshold is an offset,
3218 thus must be non-negative. Default is no write threshold.
3219 Setting the threshold to zero disables it.
3220
3221 Arguments:
3222
3223 - "node-name": the node name in the block driver state graph (json-string)
3224 - "write-threshold": the write threshold in bytes (json-int)
3225
3226 Example:
3227
3228 -> { "execute": "block-set-write-threshold",
3229   "arguments": { "node-name": "mydev",
3230                  "write-threshold": 17179869184 } }
3231 <- { "return": {} }
3232
3233 Show rocker switch
3234 ------------------
3235
3236 Arguments:
3237
3238 - "name": switch name
3239
3240 Example:
3241
3242 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
3243 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
3244
3245 Show rocker switch ports
3246 ------------------------
3247
3248 Arguments:
3249
3250 - "name": switch name
3251
3252 Example:
3253
3254 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
3255 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
3256                   "autoneg": "off", "link-up": true, "speed": 10000},
3257                  {"duplex": "full", "enabled": true, "name": "sw1.2",
3258                   "autoneg": "off", "link-up": true, "speed": 10000}
3259    ]}
3260
3261 Show rocker switch OF-DPA flow tables
3262 -------------------------------------
3263
3264 Arguments:
3265
3266 - "name": switch name
3267 - "tbl-id": (optional) flow table ID
3268
3269 Example:
3270
3271 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
3272 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
3273                   "hits": 138,
3274                   "cookie": 0,
3275                   "action": {"goto-tbl": 10},
3276                   "mask": {"in-pport": 4294901760}
3277                  },
3278                  {...more...},
3279    ]}
3280
3281 Show rocker OF-DPA group tables
3282 -------------------------------
3283
3284 Arguments:
3285
3286 - "name": switch name
3287 - "type": (optional) group type
3288
3289 Example:
3290
3291 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
3292 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
3293                   "pop-vlan": 1, "id": 251723778},
3294                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
3295                   "pop-vlan": 1, "id": 251723776},
3296                  {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
3297                   "pop-vlan": 1, "id": 251658241},
3298                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
3299                   "pop-vlan": 1, "id": 251658240}
3300    ]}
3301
3302 query-gic-capabilities
3303 ---------------
3304
3305 Return a list of GICCapability objects, describing supported GIC
3306 (Generic Interrupt Controller) versions.
3307
3308 Arguments: None
3309
3310 Example:
3311
3312 -> { "execute": "query-gic-capabilities" }
3313 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
3314                 { "version": 3, "emulated": false, "kernel": true } ] }
3315
3316 Show existing/possible CPUs
3317 ---------------------------
3318
3319 Arguments: None.
3320
3321 Example for pseries machine type started with
3322 -smp 2,cores=2,maxcpus=4 -cpu POWER8:
3323
3324 -> { "execute": "query-hotpluggable-cpus" }
3325 <- {"return": [
3326      { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
3327        "vcpus-count": 1 },
3328      { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
3329        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
3330    ]}'
3331
3332 Example for pc machine type started with
3333 -smp 1,maxcpus=2:
3334     -> { "execute": "query-hotpluggable-cpus" }
3335     <- {"return": [
3336          {
3337             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
3338             "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
3339          },
3340          {
3341             "qom-path": "/machine/unattached/device[0]",
3342             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
3343             "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
3344          }
3345        ]}