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