qmp-commands.hx

   1 HXCOMM QMP dispatch table and documentation
   2 HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and
   3 HXCOMM does not show up in the other formats.
   4
   5 SQMP
   6                         QMP Supported Commands
   7                         ----------------------
   8
   9 This document describes all commands currently supported by QMP.
  10
  11 Most of the time their usage is exactly the same as in the user Monitor, this
  12 means that any other document which also describe commands (the manpage,
  13 QEMU's manual, etc) can and should be consulted.
  14
  15 QMP has two types of commands: regular and query commands. Regular commands
  16 usually change the Virtual Machine's state someway, while query commands just
  17 return information. The sections below are divided accordingly.
  18
  19 It's important to observe that all communication examples are formatted in
  20 a reader-friendly way, so that they're easier to understand. However, in real
  21 protocol usage, they're emitted as a single line.
  22
  23 Also, the following notation is used to denote data flow:
  24
  25 -> data issued by the Client
  26 <- Server data response
  27
  28 Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
  29 information on the Server command and response formats.
  30
  31 NOTE: This document is temporary and will be replaced soon.
  32
  33 1. Stability Considerations
  34 ===========================
  35
  36 The current QMP command set (described in this file) may be useful for a
  37 number of use cases, however it's limited and several commands have bad
  38 defined semantics, specially with regard to command completion.
  39
  40 These problems are going to be solved incrementally in the next QEMU releases
  41 and we're going to establish a deprecation policy for badly defined commands.
  42
  43 If you're planning to adopt QMP, please observe the following:
  44
  45     1. The deprecation policy will take effect and be documented soon, please
  46        check the documentation of each used command as soon as a new release of
  47        QEMU is available
  48
  49     2. DO NOT rely on anything which is not explicit documented
  50
  51     3. Errors, in special, are not documented. Applications should NOT check
  52        for specific errors classes or data (it's strongly recommended to only
  53        check for the "error" key)
  54
  55 2. Regular Commands
  56 ===================
  57
  58 Server's responses in the examples below are always a success response, please
  59 refer to the QMP specification for more details on error responses.
  60
  61 EQMP
  62
  63     {
  64         .name       = "quit",
  65         .args_type  = "",
  66         .mhandler.cmd_new = qmp_marshal_input_quit,
  67     },
  68
  69 SQMP
  70 quit
  71 ----
  72
  73 Quit the emulator.
  74
  75 Arguments: None.
  76
  77 Example:
  78
  79 -> { "execute": "quit" }
  80 <- { "return": {} }
  81
  82 EQMP
  83
  84     {
  85         .name       = "eject",
  86         .args_type  = "force:-f,device:B",
  87         .mhandler.cmd_new = qmp_marshal_input_eject,
  88     },
  89
  90 SQMP
  91 eject
  92 -----
  93
  94 Eject a removable medium.
  95
  96 Arguments:
  97
  98 - force: force ejection (json-bool, optional)
  99 - device: device name (json-string)
 100
 101 Example:
 102
 103 -> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
 104 <- { "return": {} }
 105
 106 Note: The "force" argument defaults to false.
 107
 108 EQMP
 109
 110     {
 111         .name       = "change",
 112         .args_type  = "device:B,target:F,arg:s?",
 113         .mhandler.cmd_new = qmp_marshal_input_change,
 114     },
 115
 116 SQMP
 117 change
 118 ------
 119
 120 Change a removable medium or VNC configuration.
 121
 122 Arguments:
 123
 124 - "device": device name (json-string)
 125 - "target": filename or item (json-string)
 126 - "arg": additional argument (json-string, optional)
 127
 128 Examples:
 129
 130 1. Change a removable medium
 131
 132 -> { "execute": "change",
 133              "arguments": { "device": "ide1-cd0",
 134                             "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
 135 <- { "return": {} }
 136
 137 2. Change VNC password
 138
 139 -> { "execute": "change",
 140              "arguments": { "device": "vnc", "target": "password",
 141                             "arg": "foobar1" } }
 142 <- { "return": {} }
 143
 144 EQMP
 145
 146     {
 147         .name       = "screendump",
 148         .args_type  = "filename:F",
 149         .params     = "filename",
 150         .help       = "save screen into PPM image 'filename'",
 151         .user_print = monitor_user_noop,
 152         .mhandler.cmd_new = do_screen_dump,
 153     },
 154
 155 SQMP
 156 screendump
 157 ----------
 158
 159 Save screen into PPM image.
 160
 161 Arguments:
 162
 163 - "filename": file path (json-string)
 164
 165 Example:
 166
 167 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 168 <- { "return": {} }
 169
 170 EQMP
 171
 172     {
 173         .name       = "stop",
 174         .args_type  = "",
 175         .mhandler.cmd_new = qmp_marshal_input_stop,
 176     },
 177
 178 SQMP
 179 stop
 180 ----
 181
 182 Stop the emulator.
 183
 184 Arguments: None.
 185
 186 Example:
 187
 188 -> { "execute": "stop" }
 189 <- { "return": {} }
 190
 191 EQMP
 192
 193     {
 194         .name       = "cont",
 195         .args_type  = "",
 196         .mhandler.cmd_new = qmp_marshal_input_cont,
 197     },
 198
 199 SQMP
 200 cont
 201 ----
 202
 203 Resume emulation.
 204
 205 Arguments: None.
 206
 207 Example:
 208
 209 -> { "execute": "cont" }
 210 <- { "return": {} }
 211
 212 EQMP
 213
 214     {
 215         .name       = "system_wakeup",
 216         .args_type  = "",
 217         .mhandler.cmd_new = qmp_marshal_input_system_wakeup,
 218     },
 219
 220 SQMP
 221 system_wakeup
 222 -------------
 223
 224 Wakeup guest from suspend.
 225
 226 Arguments: None.
 227
 228 Example:
 229
 230 -> { "execute": "system_wakeup" }
 231 <- { "return": {} }
 232
 233 EQMP
 234
 235     {
 236         .name       = "system_reset",
 237         .args_type  = "",
 238         .mhandler.cmd_new = qmp_marshal_input_system_reset,
 239     },
 240
 241 SQMP
 242 system_reset
 243 ------------
 244
 245 Reset the system.
 246
 247 Arguments: None.
 248
 249 Example:
 250
 251 -> { "execute": "system_reset" }
 252 <- { "return": {} }
 253
 254 EQMP
 255
 256     {
 257         .name       = "system_powerdown",
 258         .args_type  = "",
 259         .mhandler.cmd_new = qmp_marshal_input_system_powerdown,
 260     },
 261
 262 SQMP
 263 system_powerdown
 264 ----------------
 265
 266 Send system power down event.
 267
 268 Arguments: None.
 269
 270 Example:
 271
 272 -> { "execute": "system_powerdown" }
 273 <- { "return": {} }
 274
 275 EQMP
 276
 277     {
 278         .name       = "device_add",
 279         .args_type  = "device:O",
 280         .params     = "driver[,prop=value][,...]",
 281         .help       = "add device, like -device on the command line",
 282         .user_print = monitor_user_noop,
 283         .mhandler.cmd_new = do_device_add,
 284     },
 285
 286 SQMP
 287 device_add
 288 ----------
 289
 290 Add a device.
 291
 292 Arguments:
 293
 294 - "driver": the name of the new device's driver (json-string)
 295 - "bus": the device's parent bus (device tree path, json-string, optional)
 296 - "id": the device's ID, must be unique (json-string)
 297 - device properties
 298
 299 Example:
 300
 301 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
 302 <- { "return": {} }
 303
 304 Notes:
 305
 306 (1) For detailed information about this command, please refer to the
 307     'docs/qdev-device-use.txt' file.
 308
 309 (2) It's possible to list device properties by running QEMU with the
 310     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
 311
 312 EQMP
 313
 314     {
 315         .name       = "device_del",
 316         .args_type  = "id:s",
 317         .params     = "device",
 318         .help       = "remove device",
 319         .user_print = monitor_user_noop,
 320         .mhandler.cmd_new = do_device_del,
 321     },
 322
 323 SQMP
 324 device_del
 325 ----------
 326
 327 Remove a device.
 328
 329 Arguments:
 330
 331 - "id": the device's ID (json-string)
 332
 333 Example:
 334
 335 -> { "execute": "device_del", "arguments": { "id": "net1" } }
 336 <- { "return": {} }
 337
 338 EQMP
 339
 340     {
 341         .name       = "cpu",
 342         .args_type  = "index:i",
 343         .mhandler.cmd_new = qmp_marshal_input_cpu,
 344     },
 345
 346 SQMP
 347 cpu
 348 ---
 349
 350 Set the default CPU.
 351
 352 Arguments:
 353
 354 - "index": the CPU's index (json-int)
 355
 356 Example:
 357
 358 -> { "execute": "cpu", "arguments": { "index": 0 } }
 359 <- { "return": {} }
 360
 361 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 362
 363 EQMP
 364
 365     {
 366         .name       = "memsave",
 367         .args_type  = "val:l,size:i,filename:s,cpu:i?",
 368         .mhandler.cmd_new = qmp_marshal_input_memsave,
 369     },
 370
 371 SQMP
 372 memsave
 373 -------
 374
 375 Save to disk virtual memory dump starting at 'val' of size 'size'.
 376
 377 Arguments:
 378
 379 - "val": the starting address (json-int)
 380 - "size": the memory size, in bytes (json-int)
 381 - "filename": file path (json-string)
 382 - "cpu": virtual CPU index (json-int, optional)
 383
 384 Example:
 385
 386 -> { "execute": "memsave",
 387              "arguments": { "val": 10,
 388                             "size": 100,
 389                             "filename": "/tmp/virtual-mem-dump" } }
 390 <- { "return": {} }
 391
 392 EQMP
 393
 394     {
 395         .name       = "pmemsave",
 396         .args_type  = "val:l,size:i,filename:s",
 397         .mhandler.cmd_new = qmp_marshal_input_pmemsave,
 398     },
 399
 400 SQMP
 401 pmemsave
 402 --------
 403
 404 Save to disk physical memory dump starting at 'val' of size 'size'.
 405
 406 Arguments:
 407
 408 - "val": the starting address (json-int)
 409 - "size": the memory size, in bytes (json-int)
 410 - "filename": file path (json-string)
 411
 412 Example:
 413
 414 -> { "execute": "pmemsave",
 415              "arguments": { "val": 10,
 416                             "size": 100,
 417                             "filename": "/tmp/physical-mem-dump" } }
 418 <- { "return": {} }
 419
 420 EQMP
 421
 422     {
 423         .name       = "inject-nmi",
 424         .args_type  = "",
 425         .mhandler.cmd_new = qmp_marshal_input_inject_nmi,
 426     },
 427
 428 SQMP
 429 inject-nmi
 430 ----------
 431
 432 Inject an NMI on guest's CPUs.
 433
 434 Arguments: None.
 435
 436 Example:
 437
 438 -> { "execute": "inject-nmi" }
 439 <- { "return": {} }
 440
 441 Note: inject-nmi is only supported for x86 guest currently, it will
 442       returns "Unsupported" error for non-x86 guest.
 443
 444 EQMP
 445
 446     {
 447         .name       = "migrate",
 448         .args_type  = "detach:-d,blk:-b,inc:-i,uri:s",
 449         .params     = "[-d] [-b] [-i] uri",
 450         .help       = "migrate to URI (using -d to not wait for completion)"
 451                       "\n\t\t\t -b for migration without shared storage with"
 452                       " full copy of disk\n\t\t\t -i for migration without "
 453                       "shared storage with incremental copy of disk "
 454                       "(base image shared between src and destination)",
 455         .user_print = monitor_user_noop,
 456         .mhandler.cmd_new = do_migrate,
 457     },
 458
 459 SQMP
 460 migrate
 461 -------
 462
 463 Migrate to URI.
 464
 465 Arguments:
 466
 467 - "blk": block migration, full disk copy (json-bool, optional)
 468 - "inc": incremental disk copy (json-bool, optional)
 469 - "uri": Destination URI (json-string)
 470
 471 Example:
 472
 473 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
 474 <- { "return": {} }
 475
 476 Notes:
 477
 478 (1) The 'query-migrate' command should be used to check migration's progress
 479     and final result (this information is provided by the 'status' member)
 480 (2) All boolean arguments default to false
 481 (3) The user Monitor's "detach" argument is invalid in QMP and should not
 482     be used
 483
 484 EQMP
 485
 486     {
 487         .name       = "migrate_cancel",
 488         .args_type  = "",
 489         .mhandler.cmd_new = qmp_marshal_input_migrate_cancel,
 490     },
 491
 492 SQMP
 493 migrate_cancel
 494 --------------
 495
 496 Cancel the current migration.
 497
 498 Arguments: None.
 499
 500 Example:
 501
 502 -> { "execute": "migrate_cancel" }
 503 <- { "return": {} }
 504
 505 EQMP
 506
 507     {
 508         .name       = "migrate_set_speed",
 509         .args_type  = "value:o",
 510         .mhandler.cmd_new = qmp_marshal_input_migrate_set_speed,
 511     },
 512
 513 SQMP
 514 migrate_set_speed
 515 -----------------
 516
 517 Set maximum speed for migrations.
 518
 519 Arguments:
 520
 521 - "value": maximum speed, in bytes per second (json-int)
 522
 523 Example:
 524
 525 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
 526 <- { "return": {} }
 527
 528 EQMP
 529
 530     {
 531         .name       = "migrate_set_downtime",
 532         .args_type  = "value:T",
 533         .mhandler.cmd_new = qmp_marshal_input_migrate_set_downtime,
 534     },
 535
 536 SQMP
 537 migrate_set_downtime
 538 --------------------
 539
 540 Set maximum tolerated downtime (in seconds) for migrations.
 541
 542 Arguments:
 543
 544 - "value": maximum downtime (json-number)
 545
 546 Example:
 547
 548 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
 549 <- { "return": {} }
 550
 551 EQMP
 552
 553     {
 554         .name       = "client_migrate_info",
 555         .args_type  = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
 556         .params     = "protocol hostname port tls-port cert-subject",
 557         .help       = "send migration info to spice/vnc client",
 558         .user_print = monitor_user_noop,
 559         .mhandler.cmd_async = client_migrate_info,
 560         .flags      = MONITOR_CMD_ASYNC,
 561     },
 562
 563 SQMP
 564 client_migrate_info
 565 ------------------
 566
 567 Set the spice/vnc connection info for the migration target.  The spice/vnc
 568 server will ask the spice/vnc client to automatically reconnect using the
 569 new parameters (if specified) once the vm migration finished successfully.
 570
 571 Arguments:
 572
 573 - "protocol":     protocol: "spice" or "vnc" (json-string)
 574 - "hostname":     migration target hostname (json-string)
 575 - "port":         spice/vnc tcp port for plaintext channels (json-int, optional)
 576 - "tls-port":     spice tcp port for tls-secured channels (json-int, optional)
 577 - "cert-subject": server certificate subject (json-string, optional)
 578
 579 Example:
 580
 581 -> { "execute": "client_migrate_info",
 582      "arguments": { "protocol": "spice",
 583                     "hostname": "virt42.lab.kraxel.org",
 584                     "port": 1234 } }
 585 <- { "return": {} }
 586
 587 EQMP
 588
 589     {
 590         .name       = "netdev_add",
 591         .args_type  = "netdev:O",
 592         .params     = "[user|tap|socket],id=str[,prop=value][,...]",
 593         .help       = "add host network device",
 594         .user_print = monitor_user_noop,
 595         .mhandler.cmd_new = do_netdev_add,
 596     },
 597
 598 SQMP
 599 netdev_add
 600 ----------
 601
 602 Add host network device.
 603
 604 Arguments:
 605
 606 - "type": the device type, "tap", "user", ... (json-string)
 607 - "id": the device's ID, must be unique (json-string)
 608 - device options
 609
 610 Example:
 611
 612 -> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
 613 <- { "return": {} }
 614
 615 Note: The supported device options are the same ones supported by the '-net'
 616       command-line argument, which are listed in the '-help' output or QEMU's
 617       manual
 618
 619 EQMP
 620
 621     {
 622         .name       = "netdev_del",
 623         .args_type  = "id:s",
 624         .params     = "id",
 625         .help       = "remove host network device",
 626         .user_print = monitor_user_noop,
 627         .mhandler.cmd_new = do_netdev_del,
 628     },
 629
 630 SQMP
 631 netdev_del
 632 ----------
 633
 634 Remove host network device.
 635
 636 Arguments:
 637
 638 - "id": the device's ID, must be unique (json-string)
 639
 640 Example:
 641
 642 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
 643 <- { "return": {} }
 644
 645
 646 EQMP
 647
 648     {
 649         .name       = "block_resize",
 650         .args_type  = "device:B,size:o",
 651         .mhandler.cmd_new = qmp_marshal_input_block_resize,
 652     },
 653
 654 SQMP
 655 block_resize
 656 ------------
 657
 658 Resize a block image while a guest is running.
 659
 660 Arguments:
 661
 662 - "device": the device's ID, must be unique (json-string)
 663 - "size": new size
 664
 665 Example:
 666
 667 -> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
 668 <- { "return": {} }
 669
 670 EQMP
 671
 672     {
 673         .name       = "block_stream",
 674         .args_type  = "device:B,base:s?",
 675         .mhandler.cmd_new = qmp_marshal_input_block_stream,
 676     },
 677
 678     {
 679         .name       = "block_job_set_speed",
 680         .args_type  = "device:B,value:o",
 681         .mhandler.cmd_new = qmp_marshal_input_block_job_set_speed,
 682     },
 683
 684     {
 685         .name       = "block_job_cancel",
 686         .args_type  = "device:B",
 687         .mhandler.cmd_new = qmp_marshal_input_block_job_cancel,
 688     },
 689     {
 690         .name       = "blockdev-group-snapshot-sync",
 691         .args_type  = "devlist:O",
 692         .params  = "device:B,snapshot-file:s,format:s?",
 693         .mhandler.cmd_new = qmp_marshal_input_blockdev_group_snapshot_sync,
 694     },
 695
 696 SQMP
 697 blockdev-group-snapshot-sync
 698 ----------------------
 699
 700 Synchronous snapshot of one or more block devices.  A list array input
 701 is accepted, that contains the device and snapshot file information for
 702 each device in group. The default format, if not specified, is qcow2.
 703
 704 If there is any failure creating or opening a new snapshot, all snapshots
 705 for the group are abandoned, and the original disks pre-snapshot attempt
 706 are used.
 707
 708
 709 Arguments:
 710
 711 devlist array:
 712     - "device": device name to snapshot (json-string)
 713     - "snapshot-file": name of new image file (json-string)
 714     - "format": format of new image (json-string, optional)
 715
 716 Example:
 717
 718 -> { "execute": "blockdev-group-snapshot-sync", "arguments":
 719                       { "devlist": [{ "device": "ide-hd0",
 720                                       "snapshot-file": "/some/place/my-image",
 721                                       "format": "qcow2" },
 722                                     { "device": "ide-hd1",
 723                                       "snapshot-file": "/some/place/my-image2",
 724                                       "format": "qcow2" }] } }
 725 <- { "return": {} }
 726
 727 EQMP
 728
 729     {
 730         .name       = "blockdev-snapshot-sync",
 731         .args_type  = "device:B,snapshot-file:s,format:s?",
 732         .mhandler.cmd_new = qmp_marshal_input_blockdev_snapshot_sync,
 733     },
 734
 735 SQMP
 736 blockdev-snapshot-sync
 737 ----------------------
 738
 739 Synchronous snapshot of a block device. snapshot-file specifies the
 740 target of the new image. If the file exists, or if it is a device, the
 741 snapshot will be created in the existing file/device. If does not
 742 exist, a new file will be created. format specifies the format of the
 743 snapshot image, default is qcow2.
 744
 745 Arguments:
 746
 747 - "device": device name to snapshot (json-string)
 748 - "snapshot-file": name of new image file (json-string)
 749 - "format": format of new image (json-string, optional)
 750
 751 Example:
 752
 753 -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
 754                                                          "snapshot-file":
 755                                                         "/some/place/my-image",
 756                                                         "format": "qcow2" } }
 757 <- { "return": {} }
 758
 759 EQMP
 760
 761     {
 762         .name       = "balloon",
 763         .args_type  = "value:M",
 764         .mhandler.cmd_new = qmp_marshal_input_balloon,
 765     },
 766
 767 SQMP
 768 balloon
 769 -------
 770
 771 Request VM to change its memory allocation (in bytes).
 772
 773 Arguments:
 774
 775 - "value": New memory allocation (json-int)
 776
 777 Example:
 778
 779 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
 780 <- { "return": {} }
 781
 782 EQMP
 783
 784     {
 785         .name       = "set_link",
 786         .args_type  = "name:s,up:b",
 787         .mhandler.cmd_new = qmp_marshal_input_set_link,
 788     },
 789
 790 SQMP
 791 set_link
 792 --------
 793
 794 Change the link status of a network adapter.
 795
 796 Arguments:
 797
 798 - "name": network device name (json-string)
 799 - "up": status is up (json-bool)
 800
 801 Example:
 802
 803 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
 804 <- { "return": {} }
 805
 806 EQMP
 807
 808     {
 809         .name       = "getfd",
 810         .args_type  = "fdname:s",
 811         .params     = "getfd name",
 812         .help       = "receive a file descriptor via SCM rights and assign it a name",
 813         .user_print = monitor_user_noop,
 814         .mhandler.cmd_new = do_getfd,
 815     },
 816
 817 SQMP
 818 getfd
 819 -----
 820
 821 Receive a file descriptor via SCM rights and assign it a name.
 822
 823 Arguments:
 824
 825 - "fdname": file descriptor name (json-string)
 826
 827 Example:
 828
 829 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
 830 <- { "return": {} }
 831
 832 EQMP
 833
 834     {
 835         .name       = "closefd",
 836         .args_type  = "fdname:s",
 837         .params     = "closefd name",
 838         .help       = "close a file descriptor previously passed via SCM rights",
 839         .user_print = monitor_user_noop,
 840         .mhandler.cmd_new = do_closefd,
 841     },
 842
 843 SQMP
 844 closefd
 845 -------
 846
 847 Close a file descriptor previously passed via SCM rights.
 848
 849 Arguments:
 850
 851 - "fdname": file descriptor name (json-string)
 852
 853 Example:
 854
 855 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
 856 <- { "return": {} }
 857
 858 EQMP
 859
 860     {
 861         .name       = "block_passwd",
 862         .args_type  = "device:B,password:s",
 863         .mhandler.cmd_new = qmp_marshal_input_block_passwd,
 864     },
 865
 866 SQMP
 867 block_passwd
 868 ------------
 869
 870 Set the password of encrypted block devices.
 871
 872 Arguments:
 873
 874 - "device": device name (json-string)
 875 - "password": password (json-string)
 876
 877 Example:
 878
 879 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
 880                                                "password": "12345" } }
 881 <- { "return": {} }
 882
 883 EQMP
 884
 885     {
 886         .name       = "block_set_io_throttle",
 887         .args_type  = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l",
 888         .mhandler.cmd_new = qmp_marshal_input_block_set_io_throttle,
 889     },
 890
 891 SQMP
 892 block_set_io_throttle
 893 ------------
 894
 895 Change I/O throttle limits for a block drive.
 896
 897 Arguments:
 898
 899 - "device": device name (json-string)
 900 - "bps":  total throughput limit in bytes per second(json-int)
 901 - "bps_rd":  read throughput limit in bytes per second(json-int)
 902 - "bps_wr":  read throughput limit in bytes per second(json-int)
 903 - "iops":  total I/O operations per second(json-int)
 904 - "iops_rd":  read I/O operations per second(json-int)
 905 - "iops_wr":  write I/O operations per second(json-int)
 906
 907 Example:
 908
 909 -> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
 910                                                "bps": "1000000",
 911                                                "bps_rd": "0",
 912                                                "bps_wr": "0",
 913                                                "iops": "0",
 914                                                "iops_rd": "0",
 915                                                "iops_wr": "0" } }
 916 <- { "return": {} }
 917
 918 EQMP
 919
 920     {
 921         .name       = "set_password",
 922         .args_type  = "protocol:s,password:s,connected:s?",
 923         .mhandler.cmd_new = qmp_marshal_input_set_password,
 924     },
 925
 926 SQMP
 927 set_password
 928 ------------
 929
 930 Set the password for vnc/spice protocols.
 931
 932 Arguments:
 933
 934 - "protocol": protocol name (json-string)
 935 - "password": password (json-string)
 936 - "connected": [ keep | disconnect | fail ] (josn-string, optional)
 937
 938 Example:
 939
 940 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
 941                                                "password": "secret" } }
 942 <- { "return": {} }
 943
 944 EQMP
 945
 946     {
 947         .name       = "expire_password",
 948         .args_type  = "protocol:s,time:s",
 949         .mhandler.cmd_new = qmp_marshal_input_expire_password,
 950     },
 951
 952 SQMP
 953 expire_password
 954 ---------------
 955
 956 Set the password expire time for vnc/spice protocols.
 957
 958 Arguments:
 959
 960 - "protocol": protocol name (json-string)
 961 - "time": [ now | never | +secs | secs ] (json-string)
 962
 963 Example:
 964
 965 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
 966                                                   "time": "+60" } }
 967 <- { "return": {} }
 968
 969 EQMP
 970
 971     {
 972         .name       = "add_client",
 973         .args_type  = "protocol:s,fdname:s,skipauth:b?,tls:b?",
 974         .params     = "protocol fdname skipauth tls",
 975         .help       = "add a graphics client",
 976         .user_print = monitor_user_noop,
 977         .mhandler.cmd_new = add_graphics_client,
 978     },
 979
 980 SQMP
 981 add_client
 982 ----------
 983
 984 Add a graphics client
 985
 986 Arguments:
 987
 988 - "protocol": protocol name (json-string)
 989 - "fdname": file descriptor name (json-string)
 990 - "skipauth": whether to skip authentication (json-bool, optional)
 991 - "tls": whether to perform TLS (json-bool, optional)
 992
 993 Example:
 994
 995 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
 996                                              "fdname": "myclient" } }
 997 <- { "return": {} }
 998
 999 EQMP
1000     {
1001         .name       = "qmp_capabilities",
1002         .args_type  = "",
1003         .params     = "",
1004         .help       = "enable QMP capabilities",
1005         .user_print = monitor_user_noop,
1006         .mhandler.cmd_new = do_qmp_capabilities,
1007     },
1008
1009 SQMP
1010 qmp_capabilities
1011 ----------------
1012
1013 Enable QMP capabilities.
1014
1015 Arguments: None.
1016
1017 Example:
1018
1019 -> { "execute": "qmp_capabilities" }
1020 <- { "return": {} }
1021
1022 Note: This command must be issued before issuing any other command.
1023
1024 EQMP
1025
1026     {
1027         .name       = "human-monitor-command",
1028         .args_type  = "command-line:s,cpu-index:i?",
1029         .mhandler.cmd_new = qmp_marshal_input_human_monitor_command,
1030     },
1031
1032 SQMP
1033 human-monitor-command
1034 ---------------------
1035
1036 Execute a Human Monitor command.
1037
1038 Arguments:
1039
1040 - command-line: the command name and its arguments, just like the
1041                 Human Monitor's shell (json-string)
1042 - cpu-index: select the CPU number to be used by commands which access CPU
1043              data, like 'info registers'. The Monitor selects CPU 0 if this
1044              argument is not provided (json-int, optional)
1045
1046 Example:
1047
1048 -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
1049 <- { "return": "kvm support: enabled\r\n" }
1050
1051 Notes:
1052
1053 (1) The Human Monitor is NOT an stable interface, this means that command
1054     names, arguments and responses can change or be removed at ANY time.
1055     Applications that rely on long term stability guarantees should NOT
1056     use this command
1057
1058 (2) Limitations:
1059
1060     o This command is stateless, this means that commands that depend
1061       on state information (such as getfd) might not work
1062
1063     o Commands that prompt the user for data (eg. 'cont' when the block
1064       device is encrypted) don't currently work
1065
1066 3. Query Commands
1067 =================
1068
1069 HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
1070 HXCOMM this! We will possibly move query commands definitions inside those
1071 HXCOMM sections, just like regular commands.
1072
1073 EQMP
1074
1075 SQMP
1076 query-version
1077 -------------
1078
1079 Show QEMU version.
1080
1081 Return a json-object with the following information:
1082
1083 - "qemu": A json-object containing three integer values:
1084     - "major": QEMU's major version (json-int)
1085     - "minor": QEMU's minor version (json-int)
1086     - "micro": QEMU's micro version (json-int)
1087 - "package": package's version (json-string)
1088
1089 Example:
1090
1091 -> { "execute": "query-version" }
1092 <- {
1093       "return":{
1094          "qemu":{
1095             "major":0,
1096             "minor":11,
1097             "micro":5
1098          },
1099          "package":""
1100       }
1101    }
1102
1103 EQMP
1104
1105     {
1106         .name       = "query-version",
1107         .args_type  = "",
1108         .mhandler.cmd_new = qmp_marshal_input_query_version,
1109     },
1110
1111 SQMP
1112 query-commands
1113 --------------
1114
1115 List QMP available commands.
1116
1117 Each command is represented by a json-object, the returned value is a json-array
1118 of all commands.
1119
1120 Each json-object contain:
1121
1122 - "name": command's name (json-string)
1123
1124 Example:
1125
1126 -> { "execute": "query-commands" }
1127 <- {
1128       "return":[
1129          {
1130             "name":"query-balloon"
1131          },
1132          {
1133             "name":"system_powerdown"
1134          }
1135       ]
1136    }
1137
1138 Note: This example has been shortened as the real response is too long.
1139
1140 EQMP
1141
1142     {
1143         .name       = "query-commands",
1144         .args_type  = "",
1145         .mhandler.cmd_new = qmp_marshal_input_query_commands,
1146     },
1147
1148 SQMP
1149 query-chardev
1150 -------------
1151
1152 Each device is represented by a json-object. The returned value is a json-array
1153 of all devices.
1154
1155 Each json-object contain the following:
1156
1157 - "label": device's label (json-string)
1158 - "filename": device's file (json-string)
1159
1160 Example:
1161
1162 -> { "execute": "query-chardev" }
1163 <- {
1164       "return":[
1165          {
1166             "label":"monitor",
1167             "filename":"stdio"
1168          },
1169          {
1170             "label":"serial0",
1171             "filename":"vc"
1172          }
1173       ]
1174    }
1175
1176 EQMP
1177
1178     {
1179         .name       = "query-chardev",
1180         .args_type  = "",
1181         .mhandler.cmd_new = qmp_marshal_input_query_chardev,
1182     },
1183
1184 SQMP
1185 query-block
1186 -----------
1187
1188 Show the block devices.
1189
1190 Each block device information is stored in a json-object and the returned value
1191 is a json-array of all devices.
1192
1193 Each json-object contain the following:
1194
1195 - "device": device name (json-string)
1196 - "type": device type (json-string)
1197          - deprecated, retained for backward compatibility
1198          - Possible values: "unknown"
1199 - "removable": true if the device is removable, false otherwise (json-bool)
1200 - "locked": true if the device is locked, false otherwise (json-bool)
1201 - "tray-open": only present if removable, true if the device has a tray,
1202                and it is open (json-bool)
1203 - "inserted": only present if the device is inserted, it is a json-object
1204    containing the following:
1205          - "file": device file name (json-string)
1206          - "ro": true if read-only, false otherwise (json-bool)
1207          - "drv": driver format name (json-string)
1208              - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1209                                 "file", "file", "ftp", "ftps", "host_cdrom",
1210                                 "host_device", "host_floppy", "http", "https",
1211                                 "nbd", "parallels", "qcow", "qcow2", "raw",
1212                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1213          - "backing_file": backing file name (json-string, optional)
1214          - "encrypted": true if encrypted, false otherwise (json-bool)
1215          - "bps": limit total bytes per second (json-int)
1216          - "bps_rd": limit read bytes per second (json-int)
1217          - "bps_wr": limit write bytes per second (json-int)
1218          - "iops": limit total I/O operations per second (json-int)
1219          - "iops_rd": limit read operations per second (json-int)
1220          - "iops_wr": limit write operations per second (json-int)
1221
1222 - "io-status": I/O operation status, only present if the device supports it
1223                and the VM is configured to stop on errors. It's always reset
1224                to "ok" when the "cont" command is issued (json_string, optional)
1225              - Possible values: "ok", "failed", "nospace"
1226
1227 Example:
1228
1229 -> { "execute": "query-block" }
1230 <- {
1231       "return":[
1232          {
1233             "io-status": "ok",
1234             "device":"ide0-hd0",
1235             "locked":false,
1236             "removable":false,
1237             "inserted":{
1238                "ro":false,
1239                "drv":"qcow2",
1240                "encrypted":false,
1241                "file":"disks/test.img",
1242                "bps":1000000,
1243                "bps_rd":0,
1244                "bps_wr":0,
1245                "iops":1000000,
1246                "iops_rd":0,
1247                "iops_wr":0,
1248             },
1249             "type":"unknown"
1250          },
1251          {
1252             "io-status": "ok",
1253             "device":"ide1-cd0",
1254             "locked":false,
1255             "removable":true,
1256             "type":"unknown"
1257          },
1258          {
1259             "device":"floppy0",
1260             "locked":false,
1261             "removable":true,
1262             "type":"unknown"
1263          },
1264          {
1265             "device":"sd0",
1266             "locked":false,
1267             "removable":true,
1268             "type":"unknown"
1269          }
1270       ]
1271    }
1272
1273 EQMP
1274
1275     {
1276         .name       = "query-block",
1277         .args_type  = "",
1278         .mhandler.cmd_new = qmp_marshal_input_query_block,
1279     },
1280
1281 SQMP
1282 query-blockstats
1283 ----------------
1284
1285 Show block device statistics.
1286
1287 Each device statistic information is stored in a json-object and the returned
1288 value is a json-array of all devices.
1289
1290 Each json-object contain the following:
1291
1292 - "device": device name (json-string)
1293 - "stats": A json-object with the statistics information, it contains:
1294     - "rd_bytes": bytes read (json-int)
1295     - "wr_bytes": bytes written (json-int)
1296     - "rd_operations": read operations (json-int)
1297     - "wr_operations": write operations (json-int)
1298     - "flush_operations": cache flush operations (json-int)
1299     - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
1300     - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
1301     - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
1302     - "wr_highest_offset": Highest offset of a sector written since the
1303                            BlockDriverState has been opened (json-int)
1304 - "parent": Contains recursively the statistics of the underlying
1305             protocol (e.g. the host file for a qcow2 image). If there is
1306             no underlying protocol, this field is omitted
1307             (json-object, optional)
1308
1309 Example:
1310
1311 -> { "execute": "query-blockstats" }
1312 <- {
1313       "return":[
1314          {
1315             "device":"ide0-hd0",
1316             "parent":{
1317                "stats":{
1318                   "wr_highest_offset":3686448128,
1319                   "wr_bytes":9786368,
1320                   "wr_operations":751,
1321                   "rd_bytes":122567168,
1322                   "rd_operations":36772
1323                   "wr_total_times_ns":313253456
1324                   "rd_total_times_ns":3465673657
1325                   "flush_total_times_ns":49653
1326                   "flush_operations":61,
1327                }
1328             },
1329             "stats":{
1330                "wr_highest_offset":2821110784,
1331                "wr_bytes":9786368,
1332                "wr_operations":692,
1333                "rd_bytes":122739200,
1334                "rd_operations":36604
1335                "flush_operations":51,
1336                "wr_total_times_ns":313253456
1337                "rd_total_times_ns":3465673657
1338                "flush_total_times_ns":49653
1339             }
1340          },
1341          {
1342             "device":"ide1-cd0",
1343             "stats":{
1344                "wr_highest_offset":0,
1345                "wr_bytes":0,
1346                "wr_operations":0,
1347                "rd_bytes":0,
1348                "rd_operations":0
1349                "flush_operations":0,
1350                "wr_total_times_ns":0
1351                "rd_total_times_ns":0
1352                "flush_total_times_ns":0
1353             }
1354          },
1355          {
1356             "device":"floppy0",
1357             "stats":{
1358                "wr_highest_offset":0,
1359                "wr_bytes":0,
1360                "wr_operations":0,
1361                "rd_bytes":0,
1362                "rd_operations":0
1363                "flush_operations":0,
1364                "wr_total_times_ns":0
1365                "rd_total_times_ns":0
1366                "flush_total_times_ns":0
1367             }
1368          },
1369          {
1370             "device":"sd0",
1371             "stats":{
1372                "wr_highest_offset":0,
1373                "wr_bytes":0,
1374                "wr_operations":0,
1375                "rd_bytes":0,
1376                "rd_operations":0
1377                "flush_operations":0,
1378                "wr_total_times_ns":0
1379                "rd_total_times_ns":0
1380                "flush_total_times_ns":0
1381             }
1382          }
1383       ]
1384    }
1385
1386 EQMP
1387
1388     {
1389         .name       = "query-blockstats",
1390         .args_type  = "",
1391         .mhandler.cmd_new = qmp_marshal_input_query_blockstats,
1392     },
1393
1394 SQMP
1395 query-cpus
1396 ----------
1397
1398 Show CPU information.
1399
1400 Return a json-array. Each CPU is represented by a json-object, which contains:
1401
1402 - "CPU": CPU index (json-int)
1403 - "current": true if this is the current CPU, false otherwise (json-bool)
1404 - "halted": true if the cpu is halted, false otherwise (json-bool)
1405 - Current program counter. The key's name depends on the architecture:
1406      "pc": i386/x86_64 (json-int)
1407      "nip": PPC (json-int)
1408      "pc" and "npc": sparc (json-int)
1409      "PC": mips (json-int)
1410 - "thread_id": ID of the underlying host thread (json-int)
1411
1412 Example:
1413
1414 -> { "execute": "query-cpus" }
1415 <- {
1416       "return":[
1417          {
1418             "CPU":0,
1419             "current":true,
1420             "halted":false,
1421             "pc":3227107138
1422             "thread_id":3134
1423          },
1424          {
1425             "CPU":1,
1426             "current":false,
1427             "halted":true,
1428             "pc":7108165
1429             "thread_id":3135
1430          }
1431       ]
1432    }
1433
1434 EQMP
1435
1436     {
1437         .name       = "query-cpus",
1438         .args_type  = "",
1439         .mhandler.cmd_new = qmp_marshal_input_query_cpus,
1440     },
1441
1442 SQMP
1443 query-pci
1444 ---------
1445
1446 PCI buses and devices information.
1447
1448 The returned value is a json-array of all buses. Each bus is represented by
1449 a json-object, which has a key with a json-array of all PCI devices attached
1450 to it. Each device is represented by a json-object.
1451
1452 The bus json-object contains the following:
1453
1454 - "bus": bus number (json-int)
1455 - "devices": a json-array of json-objects, each json-object represents a
1456              PCI device
1457
1458 The PCI device json-object contains the following:
1459
1460 - "bus": identical to the parent's bus number (json-int)
1461 - "slot": slot number (json-int)
1462 - "function": function number (json-int)
1463 - "class_info": a json-object containing:
1464      - "desc": device class description (json-string, optional)
1465      - "class": device class number (json-int)
1466 - "id": a json-object containing:
1467      - "device": device ID (json-int)
1468      - "vendor": vendor ID (json-int)
1469 - "irq": device's IRQ if assigned (json-int, optional)
1470 - "qdev_id": qdev id string (json-string)
1471 - "pci_bridge": It's a json-object, only present if this device is a
1472                 PCI bridge, contains:
1473      - "bus": bus number (json-int)
1474      - "secondary": secondary bus number (json-int)
1475      - "subordinate": subordinate bus number (json-int)
1476      - "io_range": I/O memory range information, a json-object with the
1477                    following members:
1478                  - "base": base address, in bytes (json-int)
1479                  - "limit": limit address, in bytes (json-int)
1480      - "memory_range": memory range information, a json-object with the
1481                        following members:
1482                  - "base": base address, in bytes (json-int)
1483                  - "limit": limit address, in bytes (json-int)
1484      - "prefetchable_range": Prefetchable memory range information, a
1485                              json-object with the following members:
1486                  - "base": base address, in bytes (json-int)
1487                  - "limit": limit address, in bytes (json-int)
1488      - "devices": a json-array of PCI devices if there's any attached, each
1489                   each element is represented by a json-object, which contains
1490                   the same members of the 'PCI device json-object' described
1491                   above (optional)
1492 - "regions": a json-array of json-objects, each json-object represents a
1493              memory region of this device
1494
1495 The memory range json-object contains the following:
1496
1497 - "base": base memory address (json-int)
1498 - "limit": limit value (json-int)
1499
1500 The region json-object can be an I/O region or a memory region, an I/O region
1501 json-object contains the following:
1502
1503 - "type": "io" (json-string, fixed)
1504 - "bar": BAR number (json-int)
1505 - "address": memory address (json-int)
1506 - "size": memory size (json-int)
1507
1508 A memory region json-object contains the following:
1509
1510 - "type": "memory" (json-string, fixed)
1511 - "bar": BAR number (json-int)
1512 - "address": memory address (json-int)
1513 - "size": memory size (json-int)
1514 - "mem_type_64": true or false (json-bool)
1515 - "prefetch": true or false (json-bool)
1516
1517 Example:
1518
1519 -> { "execute": "query-pci" }
1520 <- {
1521       "return":[
1522          {
1523             "bus":0,
1524             "devices":[
1525                {
1526                   "bus":0,
1527                   "qdev_id":"",
1528                   "slot":0,
1529                   "class_info":{
1530                      "class":1536,
1531                      "desc":"Host bridge"
1532                   },
1533                   "id":{
1534                      "device":32902,
1535                      "vendor":4663
1536                   },
1537                   "function":0,
1538                   "regions":[
1539
1540                   ]
1541                },
1542                {
1543                   "bus":0,
1544                   "qdev_id":"",
1545                   "slot":1,
1546                   "class_info":{
1547                      "class":1537,
1548                      "desc":"ISA bridge"
1549                   },
1550                   "id":{
1551                      "device":32902,
1552                      "vendor":28672
1553                   },
1554                   "function":0,
1555                   "regions":[
1556
1557                   ]
1558                },
1559                {
1560                   "bus":0,
1561                   "qdev_id":"",
1562                   "slot":1,
1563                   "class_info":{
1564                      "class":257,
1565                      "desc":"IDE controller"
1566                   },
1567                   "id":{
1568                      "device":32902,
1569                      "vendor":28688
1570                   },
1571                   "function":1,
1572                   "regions":[
1573                      {
1574                         "bar":4,
1575                         "size":16,
1576                         "address":49152,
1577                         "type":"io"
1578                      }
1579                   ]
1580                },
1581                {
1582                   "bus":0,
1583                   "qdev_id":"",
1584                   "slot":2,
1585                   "class_info":{
1586                      "class":768,
1587                      "desc":"VGA controller"
1588                   },
1589                   "id":{
1590                      "device":4115,
1591                      "vendor":184
1592                   },
1593                   "function":0,
1594                   "regions":[
1595                      {
1596                         "prefetch":true,
1597                         "mem_type_64":false,
1598                         "bar":0,
1599                         "size":33554432,
1600                         "address":4026531840,
1601                         "type":"memory"
1602                      },
1603                      {
1604                         "prefetch":false,
1605                         "mem_type_64":false,
1606                         "bar":1,
1607                         "size":4096,
1608                         "address":4060086272,
1609                         "type":"memory"
1610                      },
1611                      {
1612                         "prefetch":false,
1613                         "mem_type_64":false,
1614                         "bar":6,
1615                         "size":65536,
1616                         "address":-1,
1617                         "type":"memory"
1618                      }
1619                   ]
1620                },
1621                {
1622                   "bus":0,
1623                   "qdev_id":"",
1624                   "irq":11,
1625                   "slot":4,
1626                   "class_info":{
1627                      "class":1280,
1628                      "desc":"RAM controller"
1629                   },
1630                   "id":{
1631                      "device":6900,
1632                      "vendor":4098
1633                   },
1634                   "function":0,
1635                   "regions":[
1636                      {
1637                         "bar":0,
1638                         "size":32,
1639                         "address":49280,
1640                         "type":"io"
1641                      }
1642                   ]
1643                }
1644             ]
1645          }
1646       ]
1647    }
1648
1649 Note: This example has been shortened as the real response is too long.
1650
1651 EQMP
1652
1653     {
1654         .name       = "query-pci",
1655         .args_type  = "",
1656         .mhandler.cmd_new = qmp_marshal_input_query_pci,
1657     },
1658
1659 SQMP
1660 query-kvm
1661 ---------
1662
1663 Show KVM information.
1664
1665 Return a json-object with the following information:
1666
1667 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
1668 - "present": true if QEMU has KVM support, false otherwise (json-bool)
1669
1670 Example:
1671
1672 -> { "execute": "query-kvm" }
1673 <- { "return": { "enabled": true, "present": true } }
1674
1675 EQMP
1676
1677     {
1678         .name       = "query-kvm",
1679         .args_type  = "",
1680         .mhandler.cmd_new = qmp_marshal_input_query_kvm,
1681     },
1682
1683 SQMP
1684 query-status
1685 ------------
1686
1687 Return a json-object with the following information:
1688
1689 - "running": true if the VM is running, or false if it is paused (json-bool)
1690 - "singlestep": true if the VM is in single step mode,
1691                 false otherwise (json-bool)
1692 - "status": one of the following values (json-string)
1693     "debug" - QEMU is running on a debugger
1694     "inmigrate" - guest is paused waiting for an incoming migration
1695     "internal-error" - An internal error that prevents further guest
1696     execution has occurred
1697     "io-error" - the last IOP has failed and the device is configured
1698     to pause on I/O errors
1699     "paused" - guest has been paused via the 'stop' command
1700     "postmigrate" - guest is paused following a successful 'migrate'
1701     "prelaunch" - QEMU was started with -S and guest has not started
1702     "finish-migrate" - guest is paused to finish the migration process
1703     "restore-vm" - guest is paused to restore VM state
1704     "running" - guest is actively running
1705     "save-vm" - guest is paused to save the VM state
1706     "shutdown" - guest is shut down (and -no-shutdown is in use)
1707     "watchdog" - the watchdog action is configured to pause and
1708      has been triggered
1709
1710 Example:
1711
1712 -> { "execute": "query-status" }
1713 <- { "return": { "running": true, "singlestep": false, "status": "running" } }
1714
1715 EQMP
1716
1717     {
1718         .name       = "query-status",
1719         .args_type  = "",
1720         .mhandler.cmd_new = qmp_marshal_input_query_status,
1721     },
1722
1723 SQMP
1724 query-mice
1725 ----------
1726
1727 Show VM mice information.
1728
1729 Each mouse is represented by a json-object, the returned value is a json-array
1730 of all mice.
1731
1732 The mouse json-object contains the following:
1733
1734 - "name": mouse's name (json-string)
1735 - "index": mouse's index (json-int)
1736 - "current": true if this mouse is receiving events, false otherwise (json-bool)
1737 - "absolute": true if the mouse generates absolute input events (json-bool)
1738
1739 Example:
1740
1741 -> { "execute": "query-mice" }
1742 <- {
1743       "return":[
1744          {
1745             "name":"QEMU Microsoft Mouse",
1746             "index":0,
1747             "current":false,
1748             "absolute":false
1749          },
1750          {
1751             "name":"QEMU PS/2 Mouse",
1752             "index":1,
1753             "current":true,
1754             "absolute":true
1755          }
1756       ]
1757    }
1758
1759 EQMP
1760
1761     {
1762         .name       = "query-mice",
1763         .args_type  = "",
1764         .mhandler.cmd_new = qmp_marshal_input_query_mice,
1765     },
1766
1767 SQMP
1768 query-vnc
1769 ---------
1770
1771 Show VNC server information.
1772
1773 Return a json-object with server information. Connected clients are returned
1774 as a json-array of json-objects.
1775
1776 The main json-object contains the following:
1777
1778 - "enabled": true or false (json-bool)
1779 - "host": server's IP address (json-string)
1780 - "family": address family (json-string)
1781          - Possible values: "ipv4", "ipv6", "unix", "unknown"
1782 - "service": server's port number (json-string)
1783 - "auth": authentication method (json-string)
1784          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
1785                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
1786                             "vencrypt+plain", "vencrypt+tls+none",
1787                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
1788                             "vencrypt+tls+vnc", "vencrypt+x509+none",
1789                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
1790                             "vencrypt+x509+vnc", "vnc"
1791 - "clients": a json-array of all connected clients
1792
1793 Clients are described by a json-object, each one contain the following:
1794
1795 - "host": client's IP address (json-string)
1796 - "family": address family (json-string)
1797          - Possible values: "ipv4", "ipv6", "unix", "unknown"
1798 - "service": client's port number (json-string)
1799 - "x509_dname": TLS dname (json-string, optional)
1800 - "sasl_username": SASL username (json-string, optional)
1801
1802 Example:
1803
1804 -> { "execute": "query-vnc" }
1805 <- {
1806       "return":{
1807          "enabled":true,
1808          "host":"0.0.0.0",
1809          "service":"50402",
1810          "auth":"vnc",
1811          "family":"ipv4",
1812          "clients":[
1813             {
1814                "host":"127.0.0.1",
1815                "service":"50401",
1816                "family":"ipv4"
1817             }
1818          ]
1819       }
1820    }
1821
1822 EQMP
1823
1824     {
1825         .name       = "query-vnc",
1826         .args_type  = "",
1827         .mhandler.cmd_new = qmp_marshal_input_query_vnc,
1828     },
1829
1830 SQMP
1831 query-spice
1832 -----------
1833
1834 Show SPICE server information.
1835
1836 Return a json-object with server information. Connected clients are returned
1837 as a json-array of json-objects.
1838
1839 The main json-object contains the following:
1840
1841 - "enabled": true or false (json-bool)
1842 - "host": server's IP address (json-string)
1843 - "port": server's port number (json-int, optional)
1844 - "tls-port": server's port number (json-int, optional)
1845 - "auth": authentication method (json-string)
1846          - Possible values: "none", "spice"
1847 - "channels": a json-array of all active channels clients
1848
1849 Channels are described by a json-object, each one contain the following:
1850
1851 - "host": client's IP address (json-string)
1852 - "family": address family (json-string)
1853          - Possible values: "ipv4", "ipv6", "unix", "unknown"
1854 - "port": client's port number (json-string)
1855 - "connection-id": spice connection id.  All channels with the same id
1856                    belong to the same spice session (json-int)
1857 - "channel-type": channel type.  "1" is the main control channel, filter for
1858                   this one if you want track spice sessions only (json-int)
1859 - "channel-id": channel id.  Usually "0", might be different needed when
1860                 multiple channels of the same type exist, such as multiple
1861                 display channels in a multihead setup (json-int)
1862 - "tls": whevener the channel is encrypted (json-bool)
1863
1864 Example:
1865
1866 -> { "execute": "query-spice" }
1867 <- {
1868       "return": {
1869          "enabled": true,
1870          "auth": "spice",
1871          "port": 5920,
1872          "tls-port": 5921,
1873          "host": "0.0.0.0",
1874          "channels": [
1875             {
1876                "port": "54924",
1877                "family": "ipv4",
1878                "channel-type": 1,
1879                "connection-id": 1804289383,
1880                "host": "127.0.0.1",
1881                "channel-id": 0,
1882                "tls": true
1883             },
1884             {
1885                "port": "36710",
1886                "family": "ipv4",
1887                "channel-type": 4,
1888                "connection-id": 1804289383,
1889                "host": "127.0.0.1",
1890                "channel-id": 0,
1891                "tls": false
1892             },
1893             [ ... more channels follow ... ]
1894          ]
1895       }
1896    }
1897
1898 EQMP
1899
1900 #if defined(CONFIG_SPICE)
1901     {
1902         .name       = "query-spice",
1903         .args_type  = "",
1904         .mhandler.cmd_new = qmp_marshal_input_query_spice,
1905     },
1906 #endif
1907
1908 SQMP
1909 query-name
1910 ----------
1911
1912 Show VM name.
1913
1914 Return a json-object with the following information:
1915
1916 - "name": VM's name (json-string, optional)
1917
1918 Example:
1919
1920 -> { "execute": "query-name" }
1921 <- { "return": { "name": "qemu-name" } }
1922
1923 EQMP
1924
1925     {
1926         .name       = "query-name",
1927         .args_type  = "",
1928         .mhandler.cmd_new = qmp_marshal_input_query_name,
1929     },
1930
1931 SQMP
1932 query-uuid
1933 ----------
1934
1935 Show VM UUID.
1936
1937 Return a json-object with the following information:
1938
1939 - "UUID": Universally Unique Identifier (json-string)
1940
1941 Example:
1942
1943 -> { "execute": "query-uuid" }
1944 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
1945
1946 EQMP
1947
1948     {
1949         .name       = "query-uuid",
1950         .args_type  = "",
1951         .mhandler.cmd_new = qmp_marshal_input_query_uuid,
1952     },
1953
1954 SQMP
1955 query-migrate
1956 -------------
1957
1958 Migration status.
1959
1960 Return a json-object. If migration is active there will be another json-object
1961 with RAM migration status and if block migration is active another one with
1962 block migration status.
1963
1964 The main json-object contains the following:
1965
1966 - "status": migration status (json-string)
1967      - Possible values: "active", "completed", "failed", "cancelled"
1968 - "ram": only present if "status" is "active", it is a json-object with the
1969   following RAM information (in bytes):
1970          - "transferred": amount transferred (json-int)
1971          - "remaining": amount remaining (json-int)
1972          - "total": total (json-int)
1973 - "disk": only present if "status" is "active" and it is a block migration,
1974   it is a json-object with the following disk information (in bytes):
1975          - "transferred": amount transferred (json-int)
1976          - "remaining": amount remaining (json-int)
1977          - "total": total (json-int)
1978
1979 Examples:
1980
1981 1. Before the first migration
1982
1983 -> { "execute": "query-migrate" }
1984 <- { "return": {} }
1985
1986 2. Migration is done and has succeeded
1987
1988 -> { "execute": "query-migrate" }
1989 <- { "return": { "status": "completed" } }
1990
1991 3. Migration is done and has failed
1992
1993 -> { "execute": "query-migrate" }
1994 <- { "return": { "status": "failed" } }
1995
1996 4. Migration is being performed and is not a block migration:
1997
1998 -> { "execute": "query-migrate" }
1999 <- {
2000       "return":{
2001          "status":"active",
2002          "ram":{
2003             "transferred":123,
2004             "remaining":123,
2005             "total":246
2006          }
2007       }
2008    }
2009
2010 5. Migration is being performed and is a block migration:
2011
2012 -> { "execute": "query-migrate" }
2013 <- {
2014       "return":{
2015          "status":"active",
2016          "ram":{
2017             "total":1057024,
2018             "remaining":1053304,
2019             "transferred":3720
2020          },
2021          "disk":{
2022             "total":20971520,
2023             "remaining":20880384,
2024             "transferred":91136
2025          }
2026       }
2027    }
2028
2029 EQMP
2030
2031     {
2032         .name       = "query-migrate",
2033         .args_type  = "",
2034         .mhandler.cmd_new = qmp_marshal_input_query_migrate,
2035     },
2036
2037 SQMP
2038 query-balloon
2039 -------------
2040
2041 Show balloon information.
2042
2043 Make an asynchronous request for balloon info. When the request completes a
2044 json-object will be returned containing the following data:
2045
2046 - "actual": current balloon value in bytes (json-int)
2047 - "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
2048 - "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
2049 - "major_page_faults": Number of major faults (json-int, optional)
2050 - "minor_page_faults": Number of minor faults (json-int, optional)
2051 - "free_mem": Total amount of free and unused memory in
2052               bytes (json-int, optional)
2053 - "total_mem": Total amount of available memory in bytes (json-int, optional)
2054
2055 Example:
2056
2057 -> { "execute": "query-balloon" }
2058 <- {
2059       "return":{
2060          "actual":1073741824,
2061          "mem_swapped_in":0,
2062          "mem_swapped_out":0,
2063          "major_page_faults":142,
2064          "minor_page_faults":239245,
2065          "free_mem":1014185984,
2066          "total_mem":1044668416
2067       }
2068    }
2069
2070 EQMP
2071
2072     {
2073         .name       = "query-balloon",
2074         .args_type  = "",
2075         .mhandler.cmd_new = qmp_marshal_input_query_balloon,
2076     },
2077
2078     {
2079         .name       = "query-block-jobs",
2080         .args_type  = "",
2081         .mhandler.cmd_new = qmp_marshal_input_query_block_jobs,
2082     },
2083
2084     {
2085         .name       = "qom-list",
2086         .args_type  = "path:s",
2087         .mhandler.cmd_new = qmp_marshal_input_qom_list,
2088     },
2089
2090     {
2091         .name       = "qom-set",
2092         .args_type  = "path:s,property:s,opts:O",
2093         .mhandler.cmd_new = qmp_qom_set,
2094     },
2095
2096     {
2097         .name       = "qom-get",
2098         .args_type  = "path:s,property:s",
2099         .mhandler.cmd_new = qmp_qom_get,
2100     },
2101
2102     {
2103         .name       = "change-vnc-password",
2104         .args_type  = "password:s",
2105         .mhandler.cmd_new = qmp_marshal_input_change_vnc_password,
2106     },
2107     {
2108         .name       = "qom-list-types",
2109         .args_type  = "implements:s?,abstract:b?",
2110         .mhandler.cmd_new = qmp_marshal_input_qom_list_types,
2111     },