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:o",
 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-int)
 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       = "set_password",
 742         .args_type  = "protocol:s,password:s,connected:s?",
 743         .params     = "protocol password action-if-connected",
 744         .help       = "set spice/vnc password",
 745         .user_print = monitor_user_noop,
 746         .mhandler.cmd_new = set_password,
 747     },
 748
 749 SQMP
 750 set_password
 751 ------------
 752
 753 Set the password for vnc/spice protocols.
 754
 755 Arguments:
 756
 757 - "protocol": protocol name (json-string)
 758 - "password": password (json-string)
 759 - "connected": [ keep | disconnect | fail ] (josn-string, optional)
 760
 761 Example:
 762
 763 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
 764                                                "password": "secret" } }
 765 <- { "return": {} }
 766
 767 EQMP
 768
 769     {
 770         .name       = "expire_password",
 771         .args_type  = "protocol:s,time:s",
 772         .params     = "protocol time",
 773         .help       = "set spice/vnc password expire-time",
 774         .user_print = monitor_user_noop,
 775         .mhandler.cmd_new = expire_password,
 776     },
 777
 778 SQMP
 779 expire_password
 780 ---------------
 781
 782 Set the password expire time for vnc/spice protocols.
 783
 784 Arguments:
 785
 786 - "protocol": protocol name (json-string)
 787 - "time": [ now | never | +secs | secs ] (json-string)
 788
 789 Example:
 790
 791 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
 792                                                   "time": "+60" } }
 793 <- { "return": {} }
 794
 795 EQMP
 796
 797     {
 798         .name       = "qmp_capabilities",
 799         .args_type  = "",
 800         .params     = "",
 801         .help       = "enable QMP capabilities",
 802         .user_print = monitor_user_noop,
 803         .mhandler.cmd_new = do_qmp_capabilities,
 804     },
 805
 806 SQMP
 807 qmp_capabilities
 808 ----------------
 809
 810 Enable QMP capabilities.
 811
 812 Arguments: None.
 813
 814 Example:
 815
 816 -> { "execute": "qmp_capabilities" }
 817 <- { "return": {} }
 818
 819 Note: This command must be issued before issuing any other command.
 820
 821 EQMP
 822
 823     {
 824         .name       = "human-monitor-command",
 825         .args_type  = "command-line:s,cpu-index:i?",
 826         .params     = "",
 827         .help       = "",
 828         .user_print = monitor_user_noop,
 829         .mhandler.cmd_new = do_hmp_passthrough,
 830     },
 831
 832 SQMP
 833 human-monitor-command
 834 ---------------------
 835
 836 Execute a Human Monitor command.
 837
 838 Arguments:
 839
 840 - command-line: the command name and its arguments, just like the
 841                 Human Monitor's shell (json-string)
 842 - cpu-index: select the CPU number to be used by commands which access CPU
 843              data, like 'info registers'. The Monitor selects CPU 0 if this
 844              argument is not provided (json-int, optional)
 845
 846 Example:
 847
 848 -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
 849 <- { "return": "kvm support: enabled\r\n" }
 850
 851 Notes:
 852
 853 (1) The Human Monitor is NOT an stable interface, this means that command
 854     names, arguments and responses can change or be removed at ANY time.
 855     Applications that rely on long term stability guarantees should NOT
 856     use this command
 857
 858 (2) Limitations:
 859
 860     o This command is stateless, this means that commands that depend
 861       on state information (such as getfd) might not work
 862
 863     o Commands that prompt the user for data (eg. 'cont' when the block
 864       device is encrypted) don't currently work
 865
 866 3. Query Commands
 867 =================
 868
 869 HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
 870 HXCOMM this! We will possibly move query commands definitions inside those
 871 HXCOMM sections, just like regular commands.
 872
 873 EQMP
 874
 875 SQMP
 876 query-version
 877 -------------
 878
 879 Show QEMU version.
 880
 881 Return a json-object with the following information:
 882
 883 - "qemu": A json-object containing three integer values:
 884     - "major": QEMU's major version (json-int)
 885     - "minor": QEMU's minor version (json-int)
 886     - "micro": QEMU's micro version (json-int)
 887 - "package": package's version (json-string)
 888
 889 Example:
 890
 891 -> { "execute": "query-version" }
 892 <- {
 893       "return":{
 894          "qemu":{
 895             "major":0,
 896             "minor":11,
 897             "micro":5
 898          },
 899          "package":""
 900       }
 901    }
 902
 903 EQMP
 904
 905 SQMP
 906 query-commands
 907 --------------
 908
 909 List QMP available commands.
 910
 911 Each command is represented by a json-object, the returned value is a json-array
 912 of all commands.
 913
 914 Each json-object contain:
 915
 916 - "name": command's name (json-string)
 917
 918 Example:
 919
 920 -> { "execute": "query-commands" }
 921 <- {
 922       "return":[
 923          {
 924             "name":"query-balloon"
 925          },
 926          {
 927             "name":"system_powerdown"
 928          }
 929       ]
 930    }
 931
 932 Note: This example has been shortened as the real response is too long.
 933
 934 EQMP
 935
 936 SQMP
 937 query-chardev
 938 -------------
 939
 940 Each device is represented by a json-object. The returned value is a json-array
 941 of all devices.
 942
 943 Each json-object contain the following:
 944
 945 - "label": device's label (json-string)
 946 - "filename": device's file (json-string)
 947
 948 Example:
 949
 950 -> { "execute": "query-chardev" }
 951 <- {
 952       "return":[
 953          {
 954             "label":"monitor",
 955             "filename":"stdio"
 956          },
 957          {
 958             "label":"serial0",
 959             "filename":"vc"
 960          }
 961       ]
 962    }
 963
 964 EQMP
 965
 966 SQMP
 967 query-block
 968 -----------
 969
 970 Show the block devices.
 971
 972 Each block device information is stored in a json-object and the returned value
 973 is a json-array of all devices.
 974
 975 Each json-object contain the following:
 976
 977 - "device": device name (json-string)
 978 - "type": device type (json-string)
 979          - Possible values: "hd", "cdrom", "floppy", "unknown"
 980 - "removable": true if the device is removable, false otherwise (json-bool)
 981 - "locked": true if the device is locked, false otherwise (json-bool)
 982 - "inserted": only present if the device is inserted, it is a json-object
 983    containing the following:
 984          - "file": device file name (json-string)
 985          - "ro": true if read-only, false otherwise (json-bool)
 986          - "drv": driver format name (json-string)
 987              - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
 988                                 "file", "file", "ftp", "ftps", "host_cdrom",
 989                                 "host_device", "host_floppy", "http", "https",
 990                                 "nbd", "parallels", "qcow", "qcow2", "raw",
 991                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
 992          - "backing_file": backing file name (json-string, optional)
 993          - "encrypted": true if encrypted, false otherwise (json-bool)
 994
 995 Example:
 996
 997 -> { "execute": "query-block" }
 998 <- {
 999       "return":[
1000          {
1001             "device":"ide0-hd0",
1002             "locked":false,
1003             "removable":false,
1004             "inserted":{
1005                "ro":false,
1006                "drv":"qcow2",
1007                "encrypted":false,
1008                "file":"disks/test.img"
1009             },
1010             "type":"hd"
1011          },
1012          {
1013             "device":"ide1-cd0",
1014             "locked":false,
1015             "removable":true,
1016             "type":"cdrom"
1017          },
1018          {
1019             "device":"floppy0",
1020             "locked":false,
1021             "removable":true,
1022             "type": "floppy"
1023          },
1024          {
1025             "device":"sd0",
1026             "locked":false,
1027             "removable":true,
1028             "type":"floppy"
1029          }
1030       ]
1031    }
1032
1033 EQMP
1034
1035 SQMP
1036 query-blockstats
1037 ----------------
1038
1039 Show block device statistics.
1040
1041 Each device statistic information is stored in a json-object and the returned
1042 value is a json-array of all devices.
1043
1044 Each json-object contain the following:
1045
1046 - "device": device name (json-string)
1047 - "stats": A json-object with the statistics information, it contains:
1048     - "rd_bytes": bytes read (json-int)
1049     - "wr_bytes": bytes written (json-int)
1050     - "rd_operations": read operations (json-int)
1051     - "wr_operations": write operations (json-int)
1052     - "wr_highest_offset": Highest offset of a sector written since the
1053                            BlockDriverState has been opened (json-int)
1054 - "parent": Contains recursively the statistics of the underlying
1055             protocol (e.g. the host file for a qcow2 image). If there is
1056             no underlying protocol, this field is omitted
1057             (json-object, optional)
1058
1059 Example:
1060
1061 -> { "execute": "query-blockstats" }
1062 <- {
1063       "return":[
1064          {
1065             "device":"ide0-hd0",
1066             "parent":{
1067                "stats":{
1068                   "wr_highest_offset":3686448128,
1069                   "wr_bytes":9786368,
1070                   "wr_operations":751,
1071                   "rd_bytes":122567168,
1072                   "rd_operations":36772
1073                }
1074             },
1075             "stats":{
1076                "wr_highest_offset":2821110784,
1077                "wr_bytes":9786368,
1078                "wr_operations":692,
1079                "rd_bytes":122739200,
1080                "rd_operations":36604
1081             }
1082          },
1083          {
1084             "device":"ide1-cd0",
1085             "stats":{
1086                "wr_highest_offset":0,
1087                "wr_bytes":0,
1088                "wr_operations":0,
1089                "rd_bytes":0,
1090                "rd_operations":0
1091             }
1092          },
1093          {
1094             "device":"floppy0",
1095             "stats":{
1096                "wr_highest_offset":0,
1097                "wr_bytes":0,
1098                "wr_operations":0,
1099                "rd_bytes":0,
1100                "rd_operations":0
1101             }
1102          },
1103          {
1104             "device":"sd0",
1105             "stats":{
1106                "wr_highest_offset":0,
1107                "wr_bytes":0,
1108                "wr_operations":0,
1109                "rd_bytes":0,
1110                "rd_operations":0
1111             }
1112          }
1113       ]
1114    }
1115
1116 EQMP
1117
1118 SQMP
1119 query-cpus
1120 ----------
1121
1122 Show CPU information.
1123
1124 Return a json-array. Each CPU is represented by a json-object, which contains:
1125
1126 - "CPU": CPU index (json-int)
1127 - "current": true if this is the current CPU, false otherwise (json-bool)
1128 - "halted": true if the cpu is halted, false otherwise (json-bool)
1129 - Current program counter. The key's name depends on the architecture:
1130      "pc": i386/x86_64 (json-int)
1131      "nip": PPC (json-int)
1132      "pc" and "npc": sparc (json-int)
1133      "PC": mips (json-int)
1134
1135 Example:
1136
1137 -> { "execute": "query-cpus" }
1138 <- {
1139       "return":[
1140          {
1141             "CPU":0,
1142             "current":true,
1143             "halted":false,
1144             "pc":3227107138
1145          },
1146          {
1147             "CPU":1,
1148             "current":false,
1149             "halted":true,
1150             "pc":7108165
1151          }
1152       ]
1153    }
1154
1155 EQMP
1156
1157 SQMP
1158 query-pci
1159 ---------
1160
1161 PCI buses and devices information.
1162
1163 The returned value is a json-array of all buses. Each bus is represented by
1164 a json-object, which has a key with a json-array of all PCI devices attached
1165 to it. Each device is represented by a json-object.
1166
1167 The bus json-object contains the following:
1168
1169 - "bus": bus number (json-int)
1170 - "devices": a json-array of json-objects, each json-object represents a
1171              PCI device
1172
1173 The PCI device json-object contains the following:
1174
1175 - "bus": identical to the parent's bus number (json-int)
1176 - "slot": slot number (json-int)
1177 - "function": function number (json-int)
1178 - "class_info": a json-object containing:
1179      - "desc": device class description (json-string, optional)
1180      - "class": device class number (json-int)
1181 - "id": a json-object containing:
1182      - "device": device ID (json-int)
1183      - "vendor": vendor ID (json-int)
1184 - "irq": device's IRQ if assigned (json-int, optional)
1185 - "qdev_id": qdev id string (json-string)
1186 - "pci_bridge": It's a json-object, only present if this device is a
1187                 PCI bridge, contains:
1188      - "bus": bus number (json-int)
1189      - "secondary": secondary bus number (json-int)
1190      - "subordinate": subordinate bus number (json-int)
1191      - "io_range": I/O memory range information, a json-object with the
1192                    following members:
1193                  - "base": base address, in bytes (json-int)
1194                  - "limit": limit address, in bytes (json-int)
1195      - "memory_range": memory range information, a json-object with the
1196                        following members:
1197                  - "base": base address, in bytes (json-int)
1198                  - "limit": limit address, in bytes (json-int)
1199      - "prefetchable_range": Prefetchable memory range information, a
1200                              json-object with the following members:
1201                  - "base": base address, in bytes (json-int)
1202                  - "limit": limit address, in bytes (json-int)
1203      - "devices": a json-array of PCI devices if there's any attached, each
1204                   each element is represented by a json-object, which contains
1205                   the same members of the 'PCI device json-object' described
1206                   above (optional)
1207 - "regions": a json-array of json-objects, each json-object represents a
1208              memory region of this device
1209
1210 The memory range json-object contains the following:
1211
1212 - "base": base memory address (json-int)
1213 - "limit": limit value (json-int)
1214
1215 The region json-object can be an I/O region or a memory region, an I/O region
1216 json-object contains the following:
1217
1218 - "type": "io" (json-string, fixed)
1219 - "bar": BAR number (json-int)
1220 - "address": memory address (json-int)
1221 - "size": memory size (json-int)
1222
1223 A memory region json-object contains the following:
1224
1225 - "type": "memory" (json-string, fixed)
1226 - "bar": BAR number (json-int)
1227 - "address": memory address (json-int)
1228 - "size": memory size (json-int)
1229 - "mem_type_64": true or false (json-bool)
1230 - "prefetch": true or false (json-bool)
1231
1232 Example:
1233
1234 -> { "execute": "query-pci" }
1235 <- {
1236       "return":[
1237          {
1238             "bus":0,
1239             "devices":[
1240                {
1241                   "bus":0,
1242                   "qdev_id":"",
1243                   "slot":0,
1244                   "class_info":{
1245                      "class":1536,
1246                      "desc":"Host bridge"
1247                   },
1248                   "id":{
1249                      "device":32902,
1250                      "vendor":4663
1251                   },
1252                   "function":0,
1253                   "regions":[
1254
1255                   ]
1256                },
1257                {
1258                   "bus":0,
1259                   "qdev_id":"",
1260                   "slot":1,
1261                   "class_info":{
1262                      "class":1537,
1263                      "desc":"ISA bridge"
1264                   },
1265                   "id":{
1266                      "device":32902,
1267                      "vendor":28672
1268                   },
1269                   "function":0,
1270                   "regions":[
1271
1272                   ]
1273                },
1274                {
1275                   "bus":0,
1276                   "qdev_id":"",
1277                   "slot":1,
1278                   "class_info":{
1279                      "class":257,
1280                      "desc":"IDE controller"
1281                   },
1282                   "id":{
1283                      "device":32902,
1284                      "vendor":28688
1285                   },
1286                   "function":1,
1287                   "regions":[
1288                      {
1289                         "bar":4,
1290                         "size":16,
1291                         "address":49152,
1292                         "type":"io"
1293                      }
1294                   ]
1295                },
1296                {
1297                   "bus":0,
1298                   "qdev_id":"",
1299                   "slot":2,
1300                   "class_info":{
1301                      "class":768,
1302                      "desc":"VGA controller"
1303                   },
1304                   "id":{
1305                      "device":4115,
1306                      "vendor":184
1307                   },
1308                   "function":0,
1309                   "regions":[
1310                      {
1311                         "prefetch":true,
1312                         "mem_type_64":false,
1313                         "bar":0,
1314                         "size":33554432,
1315                         "address":4026531840,
1316                         "type":"memory"
1317                      },
1318                      {
1319                         "prefetch":false,
1320                         "mem_type_64":false,
1321                         "bar":1,
1322                         "size":4096,
1323                         "address":4060086272,
1324                         "type":"memory"
1325                      },
1326                      {
1327                         "prefetch":false,
1328                         "mem_type_64":false,
1329                         "bar":6,
1330                         "size":65536,
1331                         "address":-1,
1332                         "type":"memory"
1333                      }
1334                   ]
1335                },
1336                {
1337                   "bus":0,
1338                   "qdev_id":"",
1339                   "irq":11,
1340                   "slot":4,
1341                   "class_info":{
1342                      "class":1280,
1343                      "desc":"RAM controller"
1344                   },
1345                   "id":{
1346                      "device":6900,
1347                      "vendor":4098
1348                   },
1349                   "function":0,
1350                   "regions":[
1351                      {
1352                         "bar":0,
1353                         "size":32,
1354                         "address":49280,
1355                         "type":"io"
1356                      }
1357                   ]
1358                }
1359             ]
1360          }
1361       ]
1362    }
1363
1364 Note: This example has been shortened as the real response is too long.
1365
1366 EQMP
1367
1368 SQMP
1369 query-kvm
1370 ---------
1371
1372 Show KVM information.
1373
1374 Return a json-object with the following information:
1375
1376 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
1377 - "present": true if QEMU has KVM support, false otherwise (json-bool)
1378
1379 Example:
1380
1381 -> { "execute": "query-kvm" }
1382 <- { "return": { "enabled": true, "present": true } }
1383
1384 EQMP
1385
1386 SQMP
1387 query-status
1388 ------------
1389
1390 Return a json-object with the following information:
1391
1392 - "running": true if the VM is running, or false if it is paused (json-bool)
1393 - "singlestep": true if the VM is in single step mode,
1394                 false otherwise (json-bool)
1395
1396 Example:
1397
1398 -> { "execute": "query-status" }
1399 <- { "return": { "running": true, "singlestep": false } }
1400
1401 EQMP
1402
1403 SQMP
1404 query-mice
1405 ----------
1406
1407 Show VM mice information.
1408
1409 Each mouse is represented by a json-object, the returned value is a json-array
1410 of all mice.
1411
1412 The mouse json-object contains the following:
1413
1414 - "name": mouse's name (json-string)
1415 - "index": mouse's index (json-int)
1416 - "current": true if this mouse is receiving events, false otherwise (json-bool)
1417 - "absolute": true if the mouse generates absolute input events (json-bool)
1418
1419 Example:
1420
1421 -> { "execute": "query-mice" }
1422 <- {
1423       "return":[
1424          {
1425             "name":"QEMU Microsoft Mouse",
1426             "index":0,
1427             "current":false,
1428             "absolute":false
1429          },
1430          {
1431             "name":"QEMU PS/2 Mouse",
1432             "index":1,
1433             "current":true,
1434             "absolute":true
1435          }
1436       ]
1437    }
1438
1439 EQMP
1440
1441 SQMP
1442 query-vnc
1443 ---------
1444
1445 Show VNC server information.
1446
1447 Return a json-object with server information. Connected clients are returned
1448 as a json-array of json-objects.
1449
1450 The main json-object contains the following:
1451
1452 - "enabled": true or false (json-bool)
1453 - "host": server's IP address (json-string)
1454 - "family": address family (json-string)
1455          - Possible values: "ipv4", "ipv6", "unix", "unknown"
1456 - "service": server's port number (json-string)
1457 - "auth": authentication method (json-string)
1458          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
1459                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
1460                             "vencrypt+plain", "vencrypt+tls+none",
1461                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
1462                             "vencrypt+tls+vnc", "vencrypt+x509+none",
1463                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
1464                             "vencrypt+x509+vnc", "vnc"
1465 - "clients": a json-array of all connected clients
1466
1467 Clients are described by a json-object, each one contain the following:
1468
1469 - "host": client's IP address (json-string)
1470 - "family": address family (json-string)
1471          - Possible values: "ipv4", "ipv6", "unix", "unknown"
1472 - "service": client's port number (json-string)
1473 - "x509_dname": TLS dname (json-string, optional)
1474 - "sasl_username": SASL username (json-string, optional)
1475
1476 Example:
1477
1478 -> { "execute": "query-vnc" }
1479 <- {
1480       "return":{
1481          "enabled":true,
1482          "host":"0.0.0.0",
1483          "service":"50402",
1484          "auth":"vnc",
1485          "family":"ipv4",
1486          "clients":[
1487             {
1488                "host":"127.0.0.1",
1489                "service":"50401",
1490                "family":"ipv4"
1491             }
1492          ]
1493       }
1494    }
1495
1496 EQMP
1497
1498 SQMP
1499 query-spice
1500 -----------
1501
1502 Show SPICE server information.
1503
1504 Return a json-object with server information. Connected clients are returned
1505 as a json-array of json-objects.
1506
1507 The main json-object contains the following:
1508
1509 - "enabled": true or false (json-bool)
1510 - "host": server's IP address (json-string)
1511 - "port": server's port number (json-int, optional)
1512 - "tls-port": server's port number (json-int, optional)
1513 - "auth": authentication method (json-string)
1514          - Possible values: "none", "spice"
1515 - "channels": a json-array of all active channels clients
1516
1517 Channels are described by a json-object, each one contain the following:
1518
1519 - "host": client's IP address (json-string)
1520 - "family": address family (json-string)
1521          - Possible values: "ipv4", "ipv6", "unix", "unknown"
1522 - "port": client's port number (json-string)
1523 - "connection-id": spice connection id.  All channels with the same id
1524                    belong to the same spice session (json-int)
1525 - "channel-type": channel type.  "1" is the main control channel, filter for
1526                   this one if you want track spice sessions only (json-int)
1527 - "channel-id": channel id.  Usually "0", might be different needed when
1528                 multiple channels of the same type exist, such as multiple
1529                 display channels in a multihead setup (json-int)
1530 - "tls": whevener the channel is encrypted (json-bool)
1531
1532 Example:
1533
1534 -> { "execute": "query-spice" }
1535 <- {
1536       "return": {
1537          "enabled": true,
1538          "auth": "spice",
1539          "port": 5920,
1540          "tls-port": 5921,
1541          "host": "0.0.0.0",
1542          "channels": [
1543             {
1544                "port": "54924",
1545                "family": "ipv4",
1546                "channel-type": 1,
1547                "connection-id": 1804289383,
1548                "host": "127.0.0.1",
1549                "channel-id": 0,
1550                "tls": true
1551             },
1552             {
1553                "port": "36710",
1554                "family": "ipv4",
1555                "channel-type": 4,
1556                "connection-id": 1804289383,
1557                "host": "127.0.0.1",
1558                "channel-id": 0,
1559                "tls": false
1560             },
1561             [ ... more channels follow ... ]
1562          ]
1563       }
1564    }
1565
1566 EQMP
1567
1568 SQMP
1569 query-name
1570 ----------
1571
1572 Show VM name.
1573
1574 Return a json-object with the following information:
1575
1576 - "name": VM's name (json-string, optional)
1577
1578 Example:
1579
1580 -> { "execute": "query-name" }
1581 <- { "return": { "name": "qemu-name" } }
1582
1583 EQMP
1584
1585 SQMP
1586 query-uuid
1587 ----------
1588
1589 Show VM UUID.
1590
1591 Return a json-object with the following information:
1592
1593 - "UUID": Universally Unique Identifier (json-string)
1594
1595 Example:
1596
1597 -> { "execute": "query-uuid" }
1598 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
1599
1600 EQMP
1601
1602 SQMP
1603 query-migrate
1604 -------------
1605
1606 Migration status.
1607
1608 Return a json-object. If migration is active there will be another json-object
1609 with RAM migration status and if block migration is active another one with
1610 block migration status.
1611
1612 The main json-object contains the following:
1613
1614 - "status": migration status (json-string)
1615      - Possible values: "active", "completed", "failed", "cancelled"
1616 - "ram": only present if "status" is "active", it is a json-object with the
1617   following RAM information (in bytes):
1618          - "transferred": amount transferred (json-int)
1619          - "remaining": amount remaining (json-int)
1620          - "total": total (json-int)
1621 - "disk": only present if "status" is "active" and it is a block migration,
1622   it is a json-object with the following disk information (in bytes):
1623          - "transferred": amount transferred (json-int)
1624          - "remaining": amount remaining (json-int)
1625          - "total": total (json-int)
1626
1627 Examples:
1628
1629 1. Before the first migration
1630
1631 -> { "execute": "query-migrate" }
1632 <- { "return": {} }
1633
1634 2. Migration is done and has succeeded
1635
1636 -> { "execute": "query-migrate" }
1637 <- { "return": { "status": "completed" } }
1638
1639 3. Migration is done and has failed
1640
1641 -> { "execute": "query-migrate" }
1642 <- { "return": { "status": "failed" } }
1643
1644 4. Migration is being performed and is not a block migration:
1645
1646 -> { "execute": "query-migrate" }
1647 <- {
1648       "return":{
1649          "status":"active",
1650          "ram":{
1651             "transferred":123,
1652             "remaining":123,
1653             "total":246
1654          }
1655       }
1656    }
1657
1658 5. Migration is being performed and is a block migration:
1659
1660 -> { "execute": "query-migrate" }
1661 <- {
1662       "return":{
1663          "status":"active",
1664          "ram":{
1665             "total":1057024,
1666             "remaining":1053304,
1667             "transferred":3720
1668          },
1669          "disk":{
1670             "total":20971520,
1671             "remaining":20880384,
1672             "transferred":91136
1673          }
1674       }
1675    }
1676
1677 EQMP
1678
1679 SQMP
1680 query-balloon
1681 -------------
1682
1683 Show balloon information.
1684
1685 Make an asynchronous request for balloon info. When the request completes a
1686 json-object will be returned containing the following data:
1687
1688 - "actual": current balloon value in bytes (json-int)
1689 - "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
1690 - "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
1691 - "major_page_faults": Number of major faults (json-int, optional)
1692 - "minor_page_faults": Number of minor faults (json-int, optional)
1693 - "free_mem": Total amount of free and unused memory in
1694               bytes (json-int, optional)
1695 - "total_mem": Total amount of available memory in bytes (json-int, optional)
1696
1697 Example:
1698
1699 -> { "execute": "query-balloon" }
1700 <- {
1701       "return":{
1702          "actual":1073741824,
1703          "mem_swapped_in":0,
1704          "mem_swapped_out":0,
1705          "major_page_faults":142,
1706          "minor_page_faults":239245,
1707          "free_mem":1014185984,
1708          "total_mem":1044668416
1709       }
1710    }
1711
1712 EQMP
1713