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 efect 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         .params     = "",
  67         .help       = "quit the emulator",
  68         .user_print = monitor_user_noop,
  69         .mhandler.cmd_new = do_quit,
  70     },
  71
  72 SQMP
  73 quit
  74 ----
  75
  76 Quit the emulator.
  77
  78 Arguments: None.
  79
  80 Example:
  81
  82 -> { "execute": "quit" }
  83 <- { "return": {} }
  84
  85 EQMP
  86
  87     {
  88         .name       = "eject",
  89         .args_type  = "force:-f,device:B",
  90         .params     = "[-f] device",
  91         .help       = "eject a removable medium (use -f to force it)",
  92         .user_print = monitor_user_noop,
  93         .mhandler.cmd_new = do_eject,
  94     },
  95
  96 SQMP
  97 eject
  98 -----
  99
 100 Eject a removable medium.
 101
 102 Arguments:
 103
 104 - force: force ejection (json-bool, optional)
 105 - device: device name (json-string)
 106
 107 Example:
 108
 109 -> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
 110 <- { "return": {} }
 111
 112 Note: The "force" argument defaults to false.
 113
 114 EQMP
 115
 116     {
 117         .name       = "change",
 118         .args_type  = "device:B,target:F,arg:s?",
 119         .params     = "device filename [format]",
 120         .help       = "change a removable medium, optional format",
 121         .user_print = monitor_user_noop,
 122         .mhandler.cmd_new = do_change,
 123     },
 124
 125 SQMP
 126 change
 127 ------
 128
 129 Change a removable medium or VNC configuration.
 130
 131 Arguments:
 132
 133 - "device": device name (json-string)
 134 - "target": filename or item (json-string)
 135 - "arg": additional argument (json-string, optional)
 136
 137 Examples:
 138
 139 1. Change a removable medium
 140
 141 -> { "execute": "change",
 142              "arguments": { "device": "ide1-cd0",
 143                             "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
 144 <- { "return": {} }
 145
 146 2. Change VNC password
 147
 148 -> { "execute": "change",
 149              "arguments": { "device": "vnc", "target": "password",
 150                             "arg": "foobar1" } }
 151 <- { "return": {} }
 152
 153 EQMP
 154
 155     {
 156         .name       = "screendump",
 157         .args_type  = "filename:F",
 158         .params     = "filename",
 159         .help       = "save screen into PPM image 'filename'",
 160         .user_print = monitor_user_noop,
 161         .mhandler.cmd_new = do_screen_dump,
 162     },
 163
 164 SQMP
 165 screendump
 166 ----------
 167
 168 Save screen into PPM image.
 169
 170 Arguments:
 171
 172 - "filename": file path (json-string)
 173
 174 Example:
 175
 176 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 177 <- { "return": {} }
 178
 179 EQMP
 180
 181     {
 182         .name       = "stop",
 183         .args_type  = "",
 184         .params     = "",
 185         .help       = "stop emulation",
 186         .user_print = monitor_user_noop,
 187         .mhandler.cmd_new = do_stop,
 188     },
 189
 190 SQMP
 191 stop
 192 ----
 193
 194 Stop the emulator.
 195
 196 Arguments: None.
 197
 198 Example:
 199
 200 -> { "execute": "stop" }
 201 <- { "return": {} }
 202
 203 EQMP
 204
 205     {
 206         .name       = "cont",
 207         .args_type  = "",
 208         .params     = "",
 209         .help       = "resume emulation",
 210         .user_print = monitor_user_noop,
 211         .mhandler.cmd_new = do_cont,
 212     },
 213
 214 SQMP
 215 cont
 216 ----
 217
 218 Resume emulation.
 219
 220 Arguments: None.
 221
 222 Example:
 223
 224 -> { "execute": "cont" }
 225 <- { "return": {} }
 226
 227 EQMP
 228
 229     {
 230         .name       = "system_reset",
 231         .args_type  = "",
 232         .params     = "",
 233         .help       = "reset the system",
 234         .user_print = monitor_user_noop,
 235         .mhandler.cmd_new = do_system_reset,
 236     },
 237
 238 SQMP
 239 system_reset
 240 ------------
 241
 242 Reset the system.
 243
 244 Arguments: None.
 245
 246 Example:
 247
 248 -> { "execute": "system_reset" }
 249 <- { "return": {} }
 250
 251 EQMP
 252
 253     {
 254         .name       = "system_powerdown",
 255         .args_type  = "",
 256         .params     = "",
 257         .help       = "send system power down event",
 258         .user_print = monitor_user_noop,
 259         .mhandler.cmd_new = do_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         .params     = "index",
 344         .help       = "set the default CPU",
 345         .user_print = monitor_user_noop,
 346         .mhandler.cmd_new = do_cpu_set,
 347     },
 348
 349 SQMP
 350 cpu
 351 ---
 352
 353 Set the default CPU.
 354
 355 Arguments:
 356
 357 - "index": the CPU's index (json-int)
 358
 359 Example:
 360
 361 -> { "execute": "cpu", "arguments": { "index": 0 } }
 362 <- { "return": {} }
 363
 364 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 365
 366 EQMP
 367
 368     {
 369         .name       = "memsave",
 370         .args_type  = "val:l,size:i,filename:s",
 371         .params     = "addr size file",
 372         .help       = "save to disk virtual memory dump starting at 'addr' of size 'size'",
 373         .user_print = monitor_user_noop,
 374         .mhandler.cmd_new = do_memory_save,
 375     },
 376
 377 SQMP
 378 memsave
 379 -------
 380
 381 Save to disk virtual memory dump starting at 'val' of size 'size'.
 382
 383 Arguments:
 384
 385 - "val": the starting address (json-int)
 386 - "size": the memory size, in bytes (json-int)
 387 - "filename": file path (json-string)
 388
 389 Example:
 390
 391 -> { "execute": "memsave",
 392              "arguments": { "val": 10,
 393                             "size": 100,
 394                             "filename": "/tmp/virtual-mem-dump" } }
 395 <- { "return": {} }
 396
 397 Note: Depends on the current CPU.
 398
 399 EQMP
 400
 401     {
 402         .name       = "pmemsave",
 403         .args_type  = "val:l,size:i,filename:s",
 404         .params     = "addr size file",
 405         .help       = "save to disk physical memory dump starting at 'addr' of size 'size'",
 406         .user_print = monitor_user_noop,
 407         .mhandler.cmd_new = do_physical_memory_save,
 408     },
 409
 410 SQMP
 411 pmemsave
 412 --------
 413
 414 Save to disk physical memory dump starting at 'val' of size 'size'.
 415
 416 Arguments:
 417
 418 - "val": the starting address (json-int)
 419 - "size": the memory size, in bytes (json-int)
 420 - "filename": file path (json-string)
 421
 422 Example:
 423
 424 -> { "execute": "pmemsave",
 425              "arguments": { "val": 10,
 426                             "size": 100,
 427                             "filename": "/tmp/physical-mem-dump" } }
 428 <- { "return": {} }
 429
 430 EQMP
 431
 432     {
 433         .name       = "migrate",
 434         .args_type  = "detach:-d,blk:-b,inc:-i,uri:s",
 435         .params     = "[-d] [-b] [-i] uri",
 436         .help       = "migrate to URI (using -d to not wait for completion)"
 437                       "\n\t\t\t -b for migration without shared storage with"
 438                       " full copy of disk\n\t\t\t -i for migration without "
 439                       "shared storage with incremental copy of disk "
 440                       "(base image shared between src and destination)",
 441         .user_print = monitor_user_noop,
 442         .mhandler.cmd_new = do_migrate,
 443     },
 444
 445 SQMP
 446 migrate
 447 -------
 448
 449 Migrate to URI.
 450
 451 Arguments:
 452
 453 - "blk": block migration, full disk copy (json-bool, optional)
 454 - "inc": incremental disk copy (json-bool, optional)
 455 - "uri": Destination URI (json-string)
 456
 457 Example:
 458
 459 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
 460 <- { "return": {} }
 461
 462 Notes:
 463
 464 (1) The 'query-migrate' command should be used to check migration's progress
 465     and final result (this information is provided by the 'status' member)
 466 (2) All boolean arguments default to false
 467 (3) The user Monitor's "detach" argument is invalid in QMP and should not
 468     be used
 469
 470 EQMP
 471
 472     {
 473         .name       = "migrate_cancel",
 474         .args_type  = "",
 475         .params     = "",
 476         .help       = "cancel the current VM migration",
 477         .user_print = monitor_user_noop,
 478         .mhandler.cmd_new = do_migrate_cancel,
 479     },
 480
 481 SQMP
 482 migrate_cancel
 483 --------------
 484
 485 Cancel the current migration.
 486
 487 Arguments: None.
 488
 489 Example:
 490
 491 -> { "execute": "migrate_cancel" }
 492 <- { "return": {} }
 493
 494 EQMP
 495
 496     {
 497         .name       = "migrate_set_speed",
 498         .args_type  = "value:f",
 499         .params     = "value",
 500         .help       = "set maximum speed (in bytes) for migrations",
 501         .user_print = monitor_user_noop,
 502         .mhandler.cmd_new = do_migrate_set_speed,
 503     },
 504
 505 SQMP
 506 migrate_set_speed
 507 -----------------
 508
 509 Set maximum speed for migrations.
 510
 511 Arguments:
 512
 513 - "value": maximum speed, in bytes per second (json-number)
 514
 515 Example:
 516
 517 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
 518 <- { "return": {} }
 519
 520 EQMP
 521
 522     {
 523         .name       = "migrate_set_downtime",
 524         .args_type  = "value:T",
 525         .params     = "value",
 526         .help       = "set maximum tolerated downtime (in seconds) for migrations",
 527         .user_print = monitor_user_noop,
 528         .mhandler.cmd_new = do_migrate_set_downtime,
 529     },
 530
 531 SQMP
 532 migrate_set_downtime
 533 --------------------
 534
 535 Set maximum tolerated downtime (in seconds) for migrations.
 536
 537 Arguments:
 538
 539 - "value": maximum downtime (json-number)
 540
 541 Example:
 542
 543 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
 544 <- { "return": {} }
 545
 546 EQMP
 547
 548     {
 549         .name       = "netdev_add",
 550         .args_type  = "netdev:O",
 551         .params     = "[user|tap|socket],id=str[,prop=value][,...]",
 552         .help       = "add host network device",
 553         .user_print = monitor_user_noop,
 554         .mhandler.cmd_new = do_netdev_add,
 555     },
 556
 557 SQMP
 558 netdev_add
 559 ----------
 560
 561 Add host network device.
 562
 563 Arguments:
 564
 565 - "type": the device type, "tap", "user", ... (json-string)
 566 - "id": the device's ID, must be unique (json-string)
 567 - device options
 568
 569 Example:
 570
 571 -> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
 572 <- { "return": {} }
 573
 574 Note: The supported device options are the same ones supported by the '-net'
 575       command-line argument, which are listed in the '-help' output or QEMU's
 576       manual
 577
 578 EQMP
 579
 580     {
 581         .name       = "netdev_del",
 582         .args_type  = "id:s",
 583         .params     = "id",
 584         .help       = "remove host network device",
 585         .user_print = monitor_user_noop,
 586         .mhandler.cmd_new = do_netdev_del,
 587     },
 588
 589 SQMP
 590 netdev_del
 591 ----------
 592
 593 Remove host network device.
 594
 595 Arguments:
 596
 597 - "id": the device's ID, must be unique (json-string)
 598
 599 Example:
 600
 601 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
 602 <- { "return": {} }
 603
 604 EQMP
 605
 606     {
 607         .name       = "balloon",
 608         .args_type  = "value:M",
 609         .params     = "target",
 610         .help       = "request VM to change its memory allocation (in MB)",
 611         .user_print = monitor_user_noop,
 612         .mhandler.cmd_async = do_balloon,
 613         .flags      = MONITOR_CMD_ASYNC,
 614     },
 615
 616 SQMP
 617 balloon
 618 -------
 619
 620 Request VM to change its memory allocation (in bytes).
 621
 622 Arguments:
 623
 624 - "value": New memory allocation (json-int)
 625
 626 Example:
 627
 628 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
 629 <- { "return": {} }
 630
 631 EQMP
 632
 633     {
 634         .name       = "set_link",
 635         .args_type  = "name:s,up:b",
 636         .params     = "name on|off",
 637         .help       = "change the link status of a network adapter",
 638         .user_print = monitor_user_noop,
 639         .mhandler.cmd_new = do_set_link,
 640     },
 641
 642 SQMP
 643 set_link
 644 --------
 645
 646 Change the link status of a network adapter.
 647
 648 Arguments:
 649
 650 - "name": network device name (json-string)
 651 - "up": status is up (json-bool)
 652
 653 Example:
 654
 655 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
 656 <- { "return": {} }
 657
 658 EQMP
 659
 660     {
 661         .name       = "getfd",
 662         .args_type  = "fdname:s",
 663         .params     = "getfd name",
 664         .help       = "receive a file descriptor via SCM rights and assign it a name",
 665         .user_print = monitor_user_noop,
 666         .mhandler.cmd_new = do_getfd,
 667     },
 668
 669 SQMP
 670 getfd
 671 -----
 672
 673 Receive a file descriptor via SCM rights and assign it a name.
 674
 675 Arguments:
 676
 677 - "fdname": file descriptor name (json-string)
 678
 679 Example:
 680
 681 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
 682 <- { "return": {} }
 683
 684 EQMP
 685
 686     {
 687         .name       = "closefd",
 688         .args_type  = "fdname:s",
 689         .params     = "closefd name",
 690         .help       = "close a file descriptor previously passed via SCM rights",
 691         .user_print = monitor_user_noop,
 692         .mhandler.cmd_new = do_closefd,
 693     },
 694
 695 SQMP
 696 closefd
 697 -------
 698
 699 Close a file descriptor previously passed via SCM rights.
 700
 701 Arguments:
 702
 703 - "fdname": file descriptor name (json-string)
 704
 705 Example:
 706
 707 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
 708 <- { "return": {} }
 709
 710 EQMP
 711
 712     {
 713         .name       = "block_passwd",
 714         .args_type  = "device:B,password:s",
 715         .params     = "block_passwd device password",
 716         .help       = "set the password of encrypted block devices",
 717         .user_print = monitor_user_noop,
 718         .mhandler.cmd_new = do_block_set_passwd,
 719     },
 720
 721 SQMP
 722 block_passwd
 723 ------------
 724
 725 Set the password of encrypted block devices.
 726
 727 Arguments:
 728
 729 - "device": device name (json-string)
 730 - "password": password (json-string)
 731
 732 Example:
 733
 734 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
 735                                                "password": "12345" } }
 736 <- { "return": {} }
 737
 738 EQMP
 739
 740     {
 741         .name       = "qmp_capabilities",
 742         .args_type  = "",
 743         .params     = "",
 744         .help       = "enable QMP capabilities",
 745         .user_print = monitor_user_noop,
 746         .mhandler.cmd_new = do_qmp_capabilities,
 747     },
 748
 749 SQMP
 750 qmp_capabilities
 751 ----------------
 752
 753 Enable QMP capabilities.
 754
 755 Arguments: None.
 756
 757 Example:
 758
 759 -> { "execute": "qmp_capabilities" }
 760 <- { "return": {} }
 761
 762 Note: This command must be issued before issuing any other command.
 763
 764 3. Query Commands
 765 =================
 766
 767 HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
 768 HXCOMM this! We will possibly move query commands definitions inside those
 769 HXCOMM sections, just like regular commands.
 770
 771 EQMP
 772
 773 SQMP
 774 query-version
 775 -------------
 776
 777 Show QEMU version.
 778
 779 Return a json-object with the following information:
 780
 781 - "qemu": A json-object containing three integer values:
 782     - "major": QEMU's major version (json-int)
 783     - "minor": QEMU's minor version (json-int)
 784     - "micro": QEMU's micro version (json-int)
 785 - "package": package's version (json-string)
 786
 787 Example:
 788
 789 -> { "execute": "query-version" }
 790 <- {
 791       "return":{
 792          "qemu":{
 793             "major":0,
 794             "minor":11,
 795             "micro":5
 796          },
 797          "package":""
 798       }
 799    }
 800
 801 EQMP
 802
 803 SQMP
 804 query-commands
 805 --------------
 806
 807 List QMP available commands.
 808
 809 Each command is represented by a json-object, the returned value is a json-array
 810 of all commands.
 811
 812 Each json-object contain:
 813
 814 - "name": command's name (json-string)
 815
 816 Example:
 817
 818 -> { "execute": "query-commands" }
 819 <- {
 820       "return":[
 821          {
 822             "name":"query-balloon"
 823          },
 824          {
 825             "name":"system_powerdown"
 826          }
 827       ]
 828    }
 829
 830 Note: This example has been shortened as the real response is too long.
 831
 832 EQMP
 833
 834 SQMP
 835 query-chardev
 836 -------------
 837
 838 Each device is represented by a json-object. The returned value is a json-array
 839 of all devices.
 840
 841 Each json-object contain the following:
 842
 843 - "label": device's label (json-string)
 844 - "filename": device's file (json-string)
 845
 846 Example:
 847
 848 -> { "execute": "query-chardev" }
 849 <- {
 850       "return":[
 851          {
 852             "label":"monitor",
 853             "filename":"stdio"
 854          },
 855          {
 856             "label":"serial0",
 857             "filename":"vc"
 858          }
 859       ]
 860    }
 861
 862 EQMP
 863
 864 SQMP
 865 query-block
 866 -----------
 867
 868 Show the block devices.
 869
 870 Each block device information is stored in a json-object and the returned value
 871 is a json-array of all devices.
 872
 873 Each json-object contain the following:
 874
 875 - "device": device name (json-string)
 876 - "type": device type (json-string)
 877          - Possible values: "hd", "cdrom", "floppy", "unknown"
 878 - "removable": true if the device is removable, false otherwise (json-bool)
 879 - "locked": true if the device is locked, false otherwise (json-bool)
 880 - "inserted": only present if the device is inserted, it is a json-object
 881    containing the following:
 882          - "file": device file name (json-string)
 883          - "ro": true if read-only, false otherwise (json-bool)
 884          - "drv": driver format name (json-string)
 885              - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
 886                                 "file", "file", "ftp", "ftps", "host_cdrom",
 887                                 "host_device", "host_floppy", "http", "https",
 888                                 "nbd", "parallels", "qcow", "qcow2", "raw",
 889                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
 890          - "backing_file": backing file name (json-string, optional)
 891          - "encrypted": true if encrypted, false otherwise (json-bool)
 892
 893 Example:
 894
 895 -> { "execute": "query-block" }
 896 <- {
 897       "return":[
 898          {
 899             "device":"ide0-hd0",
 900             "locked":false,
 901             "removable":false,
 902             "inserted":{
 903                "ro":false,
 904                "drv":"qcow2",
 905                "encrypted":false,
 906                "file":"disks/test.img"
 907             },
 908             "type":"hd"
 909          },
 910          {
 911             "device":"ide1-cd0",
 912             "locked":false,
 913             "removable":true,
 914             "type":"cdrom"
 915          },
 916          {
 917             "device":"floppy0",
 918             "locked":false,
 919             "removable":true,
 920             "type": "floppy"
 921          },
 922          {
 923             "device":"sd0",
 924             "locked":false,
 925             "removable":true,
 926             "type":"floppy"
 927          }
 928       ]
 929    }
 930
 931 EQMP
 932
 933 SQMP
 934 query-blockstats
 935 ----------------
 936
 937 Show block device statistics.
 938
 939 Each device statistic information is stored in a json-object and the returned
 940 value is a json-array of all devices.
 941
 942 Each json-object contain the following:
 943
 944 - "device": device name (json-string)
 945 - "stats": A json-object with the statistics information, it contains:
 946     - "rd_bytes": bytes read (json-int)
 947     - "wr_bytes": bytes written (json-int)
 948     - "rd_operations": read operations (json-int)
 949     - "wr_operations": write operations (json-int)
 950     - "wr_highest_offset": Highest offset of a sector written since the
 951                            BlockDriverState has been opened (json-int)
 952 - "parent": Contains recursively the statistics of the underlying
 953             protocol (e.g. the host file for a qcow2 image). If there is
 954             no underlying protocol, this field is omitted
 955             (json-object, optional)
 956
 957 Example:
 958
 959 -> { "execute": "query-blockstats" }
 960 <- {
 961       "return":[
 962          {
 963             "device":"ide0-hd0",
 964             "parent":{
 965                "stats":{
 966                   "wr_highest_offset":3686448128,
 967                   "wr_bytes":9786368,
 968                   "wr_operations":751,
 969                   "rd_bytes":122567168,
 970                   "rd_operations":36772
 971                }
 972             },
 973             "stats":{
 974                "wr_highest_offset":2821110784,
 975                "wr_bytes":9786368,
 976                "wr_operations":692,
 977                "rd_bytes":122739200,
 978                "rd_operations":36604
 979             }
 980          },
 981          {
 982             "device":"ide1-cd0",
 983             "stats":{
 984                "wr_highest_offset":0,
 985                "wr_bytes":0,
 986                "wr_operations":0,
 987                "rd_bytes":0,
 988                "rd_operations":0
 989             }
 990          },
 991          {
 992             "device":"floppy0",
 993             "stats":{
 994                "wr_highest_offset":0,
 995                "wr_bytes":0,
 996                "wr_operations":0,
 997                "rd_bytes":0,
 998                "rd_operations":0
 999             }
1000          },
1001          {
1002             "device":"sd0",
1003             "stats":{
1004                "wr_highest_offset":0,
1005                "wr_bytes":0,
1006                "wr_operations":0,
1007                "rd_bytes":0,
1008                "rd_operations":0
1009             }
1010          }
1011       ]
1012    }
1013
1014 EQMP
1015
1016 SQMP
1017 query-cpus
1018 ----------
1019
1020 Show CPU information.
1021
1022 Return a json-array. Each CPU is represented by a json-object, which contains:
1023
1024 - "CPU": CPU index (json-int)
1025 - "current": true if this is the current CPU, false otherwise (json-bool)
1026 - "halted": true if the cpu is halted, false otherwise (json-bool)
1027 - Current program counter. The key's name depends on the architecture:
1028      "pc": i386/x86_64 (json-int)
1029      "nip": PPC (json-int)
1030      "pc" and "npc": sparc (json-int)
1031      "PC": mips (json-int)
1032
1033 Example:
1034
1035 -> { "execute": "query-cpus" }
1036 <- {
1037       "return":[
1038          {
1039             "CPU":0,
1040             "current":true,
1041             "halted":false,
1042             "pc":3227107138
1043          },
1044          {
1045             "CPU":1,
1046             "current":false,
1047             "halted":true,
1048             "pc":7108165
1049          }
1050       ]
1051    }
1052
1053 EQMP
1054
1055 SQMP
1056 query-pci
1057 ---------
1058
1059 PCI buses and devices information.
1060
1061 The returned value is a json-array of all buses. Each bus is represented by
1062 a json-object, which has a key with a json-array of all PCI devices attached
1063 to it. Each device is represented by a json-object.
1064
1065 The bus json-object contains the following:
1066
1067 - "bus": bus number (json-int)
1068 - "devices": a json-array of json-objects, each json-object represents a
1069              PCI device
1070
1071 The PCI device json-object contains the following:
1072
1073 - "bus": identical to the parent's bus number (json-int)
1074 - "slot": slot number (json-int)
1075 - "function": function number (json-int)
1076 - "class_info": a json-object containing:
1077      - "desc": device class description (json-string, optional)
1078      - "class": device class number (json-int)
1079 - "id": a json-object containing:
1080      - "device": device ID (json-int)
1081      - "vendor": vendor ID (json-int)
1082 - "irq": device's IRQ if assigned (json-int, optional)
1083 - "qdev_id": qdev id string (json-string)
1084 - "pci_bridge": It's a json-object, only present if this device is a
1085                 PCI bridge, contains:
1086      - "bus": bus number (json-int)
1087      - "secondary": secondary bus number (json-int)
1088      - "subordinate": subordinate bus number (json-int)
1089      - "io_range": I/O memory range information, a json-object with the
1090                    following members:
1091                  - "base": base address, in bytes (json-int)
1092                  - "limit": limit address, in bytes (json-int)
1093      - "memory_range": memory range information, a json-object with the
1094                        following members:
1095                  - "base": base address, in bytes (json-int)
1096                  - "limit": limit address, in bytes (json-int)
1097      - "prefetchable_range": Prefetchable memory range information, a
1098                              json-object with the following members:
1099                  - "base": base address, in bytes (json-int)
1100                  - "limit": limit address, in bytes (json-int)
1101      - "devices": a json-array of PCI devices if there's any attached, each
1102                   each element is represented by a json-object, which contains
1103                   the same members of the 'PCI device json-object' described
1104                   above (optional)
1105 - "regions": a json-array of json-objects, each json-object represents a
1106              memory region of this device
1107
1108 The memory range json-object contains the following:
1109
1110 - "base": base memory address (json-int)
1111 - "limit": limit value (json-int)
1112
1113 The region json-object can be an I/O region or a memory region, an I/O region
1114 json-object contains the following:
1115
1116 - "type": "io" (json-string, fixed)
1117 - "bar": BAR number (json-int)
1118 - "address": memory address (json-int)
1119 - "size": memory size (json-int)
1120
1121 A memory region json-object contains the following:
1122
1123 - "type": "memory" (json-string, fixed)
1124 - "bar": BAR number (json-int)
1125 - "address": memory address (json-int)
1126 - "size": memory size (json-int)
1127 - "mem_type_64": true or false (json-bool)
1128 - "prefetch": true or false (json-bool)
1129
1130 Example:
1131
1132 -> { "execute": "query-pci" }
1133 <- {
1134       "return":[
1135          {
1136             "bus":0,
1137             "devices":[
1138                {
1139                   "bus":0,
1140                   "qdev_id":"",
1141                   "slot":0,
1142                   "class_info":{
1143                      "class":1536,
1144                      "desc":"Host bridge"
1145                   },
1146                   "id":{
1147                      "device":32902,
1148                      "vendor":4663
1149                   },
1150                   "function":0,
1151                   "regions":[
1152
1153                   ]
1154                },
1155                {
1156                   "bus":0,
1157                   "qdev_id":"",
1158                   "slot":1,
1159                   "class_info":{
1160                      "class":1537,
1161                      "desc":"ISA bridge"
1162                   },
1163                   "id":{
1164                      "device":32902,
1165                      "vendor":28672
1166                   },
1167                   "function":0,
1168                   "regions":[
1169
1170                   ]
1171                },
1172                {
1173                   "bus":0,
1174                   "qdev_id":"",
1175                   "slot":1,
1176                   "class_info":{
1177                      "class":257,
1178                      "desc":"IDE controller"
1179                   },
1180                   "id":{
1181                      "device":32902,
1182                      "vendor":28688
1183                   },
1184                   "function":1,
1185                   "regions":[
1186                      {
1187                         "bar":4,
1188                         "size":16,
1189                         "address":49152,
1190                         "type":"io"
1191                      }
1192                   ]
1193                },
1194                {
1195                   "bus":0,
1196                   "qdev_id":"",
1197                   "slot":2,
1198                   "class_info":{
1199                      "class":768,
1200                      "desc":"VGA controller"
1201                   },
1202                   "id":{
1203                      "device":4115,
1204                      "vendor":184
1205                   },
1206                   "function":0,
1207                   "regions":[
1208                      {
1209                         "prefetch":true,
1210                         "mem_type_64":false,
1211                         "bar":0,
1212                         "size":33554432,
1213                         "address":4026531840,
1214                         "type":"memory"
1215                      },
1216                      {
1217                         "prefetch":false,
1218                         "mem_type_64":false,
1219                         "bar":1,
1220                         "size":4096,
1221                         "address":4060086272,
1222                         "type":"memory"
1223                      },
1224                      {
1225                         "prefetch":false,
1226                         "mem_type_64":false,
1227                         "bar":6,
1228                         "size":65536,
1229                         "address":-1,
1230                         "type":"memory"
1231                      }
1232                   ]
1233                },
1234                {
1235                   "bus":0,
1236                   "qdev_id":"",
1237                   "irq":11,
1238                   "slot":4,
1239                   "class_info":{
1240                      "class":1280,
1241                      "desc":"RAM controller"
1242                   },
1243                   "id":{
1244                      "device":6900,
1245                      "vendor":4098
1246                   },
1247                   "function":0,
1248                   "regions":[
1249                      {
1250                         "bar":0,
1251                         "size":32,
1252                         "address":49280,
1253                         "type":"io"
1254                      }
1255                   ]
1256                }
1257             ]
1258          }
1259       ]
1260    }
1261
1262 Note: This example has been shortened as the real response is too long.
1263
1264 EQMP
1265
1266 SQMP
1267 query-kvm
1268 ---------
1269
1270 Show KVM information.
1271
1272 Return a json-object with the following information:
1273
1274 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
1275 - "present": true if QEMU has KVM support, false otherwise (json-bool)
1276
1277 Example:
1278
1279 -> { "execute": "query-kvm" }
1280 <- { "return": { "enabled": true, "present": true } }
1281
1282 EQMP
1283
1284 SQMP
1285 query-status
1286 ------------
1287
1288 Return a json-object with the following information:
1289
1290 - "running": true if the VM is running, or false if it is paused (json-bool)
1291 - "singlestep": true if the VM is in single step mode,
1292                 false otherwise (json-bool)
1293
1294 Example:
1295
1296 -> { "execute": "query-status" }
1297 <- { "return": { "running": true, "singlestep": false } }
1298
1299 EQMP
1300
1301 SQMP
1302 query-mice
1303 ----------
1304
1305 Show VM mice information.
1306
1307 Each mouse is represented by a json-object, the returned value is a json-array
1308 of all mice.
1309
1310 The mouse json-object contains the following:
1311
1312 - "name": mouse's name (json-string)
1313 - "index": mouse's index (json-int)
1314 - "current": true if this mouse is receiving events, false otherwise (json-bool)
1315 - "absolute": true if the mouse generates absolute input events (json-bool)
1316
1317 Example:
1318
1319 -> { "execute": "query-mice" }
1320 <- {
1321       "return":[
1322          {
1323             "name":"QEMU Microsoft Mouse",
1324             "index":0,
1325             "current":false,
1326             "absolute":false
1327          },
1328          {
1329             "name":"QEMU PS/2 Mouse",
1330             "index":1,
1331             "current":true,
1332             "absolute":true
1333          }
1334       ]
1335    }
1336
1337 EQMP
1338
1339 SQMP
1340 query-vnc
1341 ---------
1342
1343 Show VNC server information.
1344
1345 Return a json-object with server information. Connected clients are returned
1346 as a json-array of json-objects.
1347
1348 The main json-object contains the following:
1349
1350 - "enabled": true or false (json-bool)
1351 - "host": server's IP address (json-string)
1352 - "family": address family (json-string)
1353          - Possible values: "ipv4", "ipv6", "unix", "unknown"
1354 - "service": server's port number (json-string)
1355 - "auth": authentication method (json-string)
1356          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
1357                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
1358                             "vencrypt+plain", "vencrypt+tls+none",
1359                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
1360                             "vencrypt+tls+vnc", "vencrypt+x509+none",
1361                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
1362                             "vencrypt+x509+vnc", "vnc"
1363 - "clients": a json-array of all connected clients
1364
1365 Clients are described by a json-object, each one contain the following:
1366
1367 - "host": client's IP address (json-string)
1368 - "family": address family (json-string)
1369          - Possible values: "ipv4", "ipv6", "unix", "unknown"
1370 - "service": client's port number (json-string)
1371 - "x509_dname": TLS dname (json-string, optional)
1372 - "sasl_username": SASL username (json-string, optional)
1373
1374 Example:
1375
1376 -> { "execute": "query-vnc" }
1377 <- {
1378       "return":{
1379          "enabled":true,
1380          "host":"0.0.0.0",
1381          "service":"50402",
1382          "auth":"vnc",
1383          "family":"ipv4",
1384          "clients":[
1385             {
1386                "host":"127.0.0.1",
1387                "service":"50401",
1388                "family":"ipv4"
1389             }
1390          ]
1391       }
1392    }
1393
1394 EQMP
1395
1396 SQMP
1397 query-name
1398 ----------
1399
1400 Show VM name.
1401
1402 Return a json-object with the following information:
1403
1404 - "name": VM's name (json-string, optional)
1405
1406 Example:
1407
1408 -> { "execute": "query-name" }
1409 <- { "return": { "name": "qemu-name" } }
1410
1411 EQMP
1412
1413 SQMP
1414 query-uuid
1415 ----------
1416
1417 Show VM UUID.
1418
1419 Return a json-object with the following information:
1420
1421 - "UUID": Universally Unique Identifier (json-string)
1422
1423 Example:
1424
1425 -> { "execute": "query-uuid" }
1426 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
1427
1428 EQMP
1429
1430 SQMP
1431 query-migrate
1432 -------------
1433
1434 Migration status.
1435
1436 Return a json-object. If migration is active there will be another json-object
1437 with RAM migration status and if block migration is active another one with
1438 block migration status.
1439
1440 The main json-object contains the following:
1441
1442 - "status": migration status (json-string)
1443      - Possible values: "active", "completed", "failed", "cancelled"
1444 - "ram": only present if "status" is "active", it is a json-object with the
1445   following RAM information (in bytes):
1446          - "transferred": amount transferred (json-int)
1447          - "remaining": amount remaining (json-int)
1448          - "total": total (json-int)
1449 - "disk": only present if "status" is "active" and it is a block migration,
1450   it is a json-object with the following disk information (in bytes):
1451          - "transferred": amount transferred (json-int)
1452          - "remaining": amount remaining (json-int)
1453          - "total": total (json-int)
1454
1455 Examples:
1456
1457 1. Before the first migration
1458
1459 -> { "execute": "query-migrate" }
1460 <- { "return": {} }
1461
1462 2. Migration is done and has succeeded
1463
1464 -> { "execute": "query-migrate" }
1465 <- { "return": { "status": "completed" } }
1466
1467 3. Migration is done and has failed
1468
1469 -> { "execute": "query-migrate" }
1470 <- { "return": { "status": "failed" } }
1471
1472 4. Migration is being performed and is not a block migration:
1473
1474 -> { "execute": "query-migrate" }
1475 <- {
1476       "return":{
1477          "status":"active",
1478          "ram":{
1479             "transferred":123,
1480             "remaining":123,
1481             "total":246
1482          }
1483       }
1484    }
1485
1486 5. Migration is being performed and is a block migration:
1487
1488 -> { "execute": "query-migrate" }
1489 <- {
1490       "return":{
1491          "status":"active",
1492          "ram":{
1493             "total":1057024,
1494             "remaining":1053304,
1495             "transferred":3720
1496          },
1497          "disk":{
1498             "total":20971520,
1499             "remaining":20880384,
1500             "transferred":91136
1501          }
1502       }
1503    }
1504
1505 EQMP
1506
1507 SQMP
1508 query-balloon
1509 -------------
1510
1511 Show balloon information.
1512
1513 Make an asynchronous request for balloon info. When the request completes a
1514 json-object will be returned containing the following data:
1515
1516 - "actual": current balloon value in bytes (json-int)
1517 - "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
1518 - "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
1519 - "major_page_faults": Number of major faults (json-int, optional)
1520 - "minor_page_faults": Number of minor faults (json-int, optional)
1521 - "free_mem": Total amount of free and unused memory in
1522               bytes (json-int, optional)
1523 - "total_mem": Total amount of available memory in bytes (json-int, optional)
1524
1525 Example:
1526
1527 -> { "execute": "query-balloon" }
1528 <- {
1529       "return":{
1530          "actual":1073741824,
1531          "mem_swapped_in":0,
1532          "mem_swapped_out":0,
1533          "major_page_faults":142,
1534          "minor_page_faults":239245,
1535          "free_mem":1014185984,
1536          "total_mem":1044668416
1537       }
1538    }
1539
1540 EQMP
1541