Revision 30f5041e

b/monitor.c
2352 2352
        .mhandler.info_new = do_info_version,
2353 2353
    },
2354 2354
    {
2355
        .name       = "commands",
2356
        .args_type  = "",
2357
        .params     = "",
2358
        .help       = "list QMP available commands",
2359
        .user_print = monitor_user_noop,
2360
        .mhandler.info_new = do_info_commands,
2361
    },
2362
    {
2363 2355
        .name       = "network",
2364 2356
        .args_type  = "",
2365 2357
        .params     = "",
b/qemu-monitor.hx
1 1
HXCOMM Use DEFHEADING() to define headings in both help text and texi
2 2
HXCOMM Text between STEXI and ETEXI are copied to texi version and
3 3
HXCOMM discarded from C version
4
HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and
5
HXCOMM does not show up in the other formats.
6 4
HXCOMM DEF(command, args, callback, arg_string, help) is used to construct
7 5
HXCOMM monitor commands
8 6
HXCOMM HXCOMM can be used for comments, discarded from both texi and C
9 7

  
10
SQMP
11
                        QMP Supported Commands
12
                        ----------------------
13

  
14
This document describes all commands currently supported by QMP.
15

  
16
Most of the time their usage is exactly the same as in the user Monitor, this
17
means that any other document which also describe commands (the manpage,
18
QEMU's manual, etc) can and should be consulted.
19

  
20
QMP has two types of commands: regular and query commands. Regular commands
21
usually change the Virtual Machine's state someway, while query commands just
22
return information. The sections below are divided accordingly.
23

  
24
It's important to observe that all communication examples are formatted in
25
a reader-friendly way, so that they're easier to understand. However, in real
26
protocol usage, they're emitted as a single line.
27

  
28
Also, the following notation is used to denote data flow:
29

  
30
-> data issued by the Client
31
<- Server data response
32

  
33
Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
34
information on the Server command and response formats.
35

  
36
NOTE: This document is temporary and will be replaced soon.
37

  
38
1. Stability Considerations
39
===========================
40

  
41
The current QMP command set (described in this file) may be useful for a
42
number of use cases, however it's limited and several commands have bad
43
defined semantics, specially with regard to command completion.
44

  
45
These problems are going to be solved incrementally in the next QEMU releases
46
and we're going to establish a deprecation policy for badly defined commands.
47

  
48
If you're planning to adopt QMP, please observe the following:
49

  
50
    1. The deprecation policy will take efect and be documented soon, please
51
       check the documentation of each used command as soon as a new release of
52
       QEMU is available
53

  
54
    2. DO NOT rely on anything which is not explicit documented
55

  
56
    3. Errors, in special, are not documented. Applications should NOT check
57
       for specific errors classes or data (it's strongly recommended to only
58
       check for the "error" key)
59

  
60
2. Regular Commands
61
===================
62

  
63
Server's responses in the examples below are always a success response, please
64
refer to the QMP specification for more details on error responses.
65

  
66
EQMP
67

  
68 8
STEXI
69 9
@table @option
70 10
ETEXI
......
111 51
@findex quit
112 52
Quit the emulator.
113 53
ETEXI
114
SQMP
115
quit
116
----
117

  
118
Quit the emulator.
119

  
120
Arguments: None.
121

  
122
Example:
123

  
124
-> { "execute": "quit" }
125
<- { "return": {} }
126

  
127
EQMP
128 54

  
129 55
    {
130 56
        .name       = "eject",
......
140 66
@findex eject
141 67
Eject a removable medium (use -f to force it).
142 68
ETEXI
143
SQMP
144
eject
145
-----
146

  
147
Eject a removable medium.
148

  
149
Arguments: 
150

  
151
- force: force ejection (json-bool, optional)
152
- device: device name (json-string)
153

  
154
Example:
155

  
156
-> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
157
<- { "return": {} }
158

  
159
Note: The "force" argument defaults to false.
160

  
161
EQMP
162 69

  
163 70
    {
164 71
        .name       = "change",
......
206 113

  
207 114
@end table
208 115
ETEXI
209
SQMP
210
change
211
------
212

  
213
Change a removable medium or VNC configuration.
214

  
215
Arguments:
216

  
217
- "device": device name (json-string)
218
- "target": filename or item (json-string)
219
- "arg": additional argument (json-string, optional)
220

  
221
Examples:
222

  
223
1. Change a removable medium
224

  
225
-> { "execute": "change",
226
             "arguments": { "device": "ide1-cd0",
227
                            "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
228
<- { "return": {} }
229

  
230
2. Change VNC password
231

  
232
-> { "execute": "change",
233
             "arguments": { "device": "vnc", "target": "password",
234
                            "arg": "foobar1" } }
235
<- { "return": {} }
236

  
237
EQMP
238 116

  
239 117
    {
240 118
        .name       = "screendump",
......
250 128
@findex screendump
251 129
Save screen into PPM image @var{filename}.
252 130
ETEXI
253
SQMP
254
screendump
255
----------
256

  
257
Save screen into PPM image.
258

  
259
Arguments:
260

  
261
- "filename": file path (json-string)
262

  
263
Example:
264

  
265
-> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
266
<- { "return": {} }
267

  
268
EQMP
269 131

  
270 132
    {
271 133
        .name       = "logfile",
......
400 262
@findex stop
401 263
Stop emulation.
402 264
ETEXI
403
SQMP
404
stop
405
----
406

  
407
Stop the emulator.
408

  
409
Arguments: None.
410

  
411
Example:
412

  
413
-> { "execute": "stop" }
414
<- { "return": {} }
415

  
416
EQMP
417 265

  
418 266
    {
419 267
        .name       = "c|cont",
......
429 277
@findex cont
430 278
Resume emulation.
431 279
ETEXI
432
SQMP
433
cont
434
----
435

  
436
Resume emulation.
437

  
438
Arguments: None.
439

  
440
Example:
441

  
442
-> { "execute": "cont" }
443
<- { "return": {} }
444

  
445
EQMP
446 280

  
447 281
    {
448 282
        .name       = "gdbserver",
......
617 451

  
618 452
Reset the system.
619 453
ETEXI
620
SQMP
621
system_reset
622
------------
623

  
624
Reset the system.
625

  
626
Arguments: None.
627

  
628
Example:
629

  
630
-> { "execute": "system_reset" }
631
<- { "return": {} }
632

  
633
EQMP
634 454

  
635 455
    {
636 456
        .name       = "system_powerdown",
......
647 467

  
648 468
Power down the system (if supported).
649 469
ETEXI
650
SQMP
651
system_powerdown
652
----------------
653

  
654
Send system power down event.
655

  
656
Arguments: None.
657

  
658
Example:
659

  
660
-> { "execute": "system_powerdown" }
661
<- { "return": {} }
662

  
663
EQMP
664 470

  
665 471
    {
666 472
        .name       = "sum",
......
725 531

  
726 532
Add device.
727 533
ETEXI
728
SQMP
729
device_add
730
----------
731

  
732
Add a device.
733

  
734
Arguments:
735

  
736
- "driver": the name of the new device's driver (json-string)
737
- "bus": the device's parent bus (device tree path, json-string, optional)
738
- "id": the device's ID, must be unique (json-string)
739
- device properties
740

  
741
Example:
742

  
743
-> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
744
<- { "return": {} }
745

  
746
Notes:
747

  
748
(1) For detailed information about this command, please refer to the
749
    'docs/qdev-device-use.txt' file.
750

  
751
(2) It's possible to list device properties by running QEMU with the
752
    "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
753

  
754
EQMP
755 534

  
756 535
    {
757 536
        .name       = "device_del",
......
768 547

  
769 548
Remove device @var{id}.
770 549
ETEXI
771
SQMP
772
device_del
773
----------
774

  
775
Remove a device.
776

  
777
Arguments:
778

  
779
- "id": the device's ID (json-string)
780

  
781
Example:
782

  
783
-> { "execute": "device_del", "arguments": { "id": "net1" } }
784
<- { "return": {} }
785

  
786
EQMP
787 550

  
788 551
    {
789 552
        .name       = "cpu",
......
799 562
@findex cpu
800 563
Set the default CPU.
801 564
ETEXI
802
SQMP
803
cpu
804
---
805

  
806
Set the default CPU.
807

  
808
Arguments:
809

  
810
- "index": the CPU's index (json-int)
811

  
812
Example:
813

  
814
-> { "execute": "cpu", "arguments": { "index": 0 } }
815
<- { "return": {} }
816

  
817
Note: CPUs' indexes are obtained with the 'query-cpus' command.
818

  
819
EQMP
820 565

  
821 566
    {
822 567
        .name       = "mouse_move",
......
920 665
@findex memsave
921 666
save to disk virtual memory dump starting at @var{addr} of size @var{size}.
922 667
ETEXI
923
SQMP
924
memsave
925
-------
926

  
927
Save to disk virtual memory dump starting at 'val' of size 'size'.
928

  
929
Arguments:
930

  
931
- "val": the starting address (json-int)
932
- "size": the memory size, in bytes (json-int)
933
- "filename": file path (json-string)
934

  
935
Example:
936

  
937
-> { "execute": "memsave",
938
             "arguments": { "val": 10,
939
                            "size": 100,
940
                            "filename": "/tmp/virtual-mem-dump" } }
941
<- { "return": {} }
942

  
943
Note: Depends on the current CPU.
944

  
945
EQMP
946 668

  
947 669
    {
948 670
        .name       = "pmemsave",
......
958 680
@findex pmemsave
959 681
save to disk physical memory dump starting at @var{addr} of size @var{size}.
960 682
ETEXI
961
SQMP
962
pmemsave
963
--------
964

  
965
Save to disk physical memory dump starting at 'val' of size 'size'.
966

  
967
Arguments:
968

  
969
- "val": the starting address (json-int)
970
- "size": the memory size, in bytes (json-int)
971
- "filename": file path (json-string)
972

  
973
Example:
974

  
975
-> { "execute": "pmemsave",
976
             "arguments": { "val": 10,
977
                            "size": 100,
978
                            "filename": "/tmp/physical-mem-dump" } }
979
<- { "return": {} }
980

  
981
EQMP
982 683

  
983 684
    {
984 685
        .name       = "boot_set",
......
1035 736
	-b for migration with full copy of disk
1036 737
	-i for migration with incremental copy of disk (base image is shared)
1037 738
ETEXI
1038
SQMP
1039
migrate
1040
-------
1041

  
1042
Migrate to URI.
1043

  
1044
Arguments:
1045

  
1046
- "blk": block migration, full disk copy (json-bool, optional)
1047
- "inc": incremental disk copy (json-bool, optional)
1048
- "uri": Destination URI (json-string)
1049

  
1050
Example:
1051

  
1052
-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
1053
<- { "return": {} }
1054

  
1055
Notes:
1056

  
1057
(1) The 'query-migrate' command should be used to check migration's progress
1058
    and final result (this information is provided by the 'status' member)
1059
(2) All boolean arguments default to false
1060
(3) The user Monitor's "detach" argument is invalid in QMP and should not
1061
    be used
1062

  
1063
EQMP
1064 739

  
1065 740
    {
1066 741
        .name       = "migrate_cancel",
......
1076 751
@findex migrate_cancel
1077 752
Cancel the current VM migration.
1078 753
ETEXI
1079
SQMP
1080
migrate_cancel
1081
--------------
1082

  
1083
Cancel the current migration.
1084

  
1085
Arguments: None.
1086

  
1087
Example:
1088

  
1089
-> { "execute": "migrate_cancel" }
1090
<- { "return": {} }
1091

  
1092
EQMP
1093 754

  
1094 755
    {
1095 756
        .name       = "migrate_set_speed",
......
1105 766
@findex migrate_set_speed
1106 767
Set maximum speed to @var{value} (in bytes) for migrations.
1107 768
ETEXI
1108
SQMP
1109
migrate_set_speed
1110
-----------------
1111

  
1112
Set maximum speed for migrations.
1113

  
1114
Arguments:
1115

  
1116
- "value": maximum speed, in bytes per second (json-number)
1117

  
1118
Example:
1119

  
1120
-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
1121
<- { "return": {} }
1122

  
1123
EQMP
1124 769

  
1125 770
    {
1126 771
        .name       = "migrate_set_downtime",
......
1136 781
@findex migrate_set_downtime
1137 782
Set maximum tolerated downtime (in seconds) for migration.
1138 783
ETEXI
1139
SQMP
1140
migrate_set_downtime
1141
--------------------
1142

  
1143
Set maximum tolerated downtime (in seconds) for migrations.
1144

  
1145
Arguments:
1146

  
1147
- "value": maximum downtime (json-number)
1148

  
1149
Example:
1150

  
1151
-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
1152
<- { "return": {} }
1153

  
1154
EQMP
1155 784

  
1156 785
#if defined(TARGET_I386)
1157 786
    {
......
1247 876
@findex netdev_add
1248 877
Add host network device.
1249 878
ETEXI
1250
SQMP
1251
netdev_add
1252
----------
1253

  
1254
Add host network device.
1255

  
1256
Arguments:
1257

  
1258
- "type": the device type, "tap", "user", ... (json-string)
1259
- "id": the device's ID, must be unique (json-string)
1260
- device options
1261

  
1262
Example:
1263

  
1264
-> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
1265
<- { "return": {} }
1266

  
1267
Note: The supported device options are the same ones supported by the '-net'
1268
      command-line argument, which are listed in the '-help' output or QEMU's
1269
      manual
1270

  
1271
EQMP
1272 879

  
1273 880
    {
1274 881
        .name       = "netdev_del",
......
1284 891
@findex netdev_del
1285 892
Remove host network device.
1286 893
ETEXI
1287
SQMP
1288
netdev_del
1289
----------
1290

  
1291
Remove host network device.
1292

  
1293
Arguments:
1294

  
1295
- "id": the device's ID, must be unique (json-string)
1296

  
1297
Example:
1298

  
1299
-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
1300
<- { "return": {} }
1301

  
1302
EQMP
1303 894

  
1304 895
#ifdef CONFIG_SLIRP
1305 896
    {
......
1347 938
@findex balloon
1348 939
Request VM to change its memory allocation to @var{value} (in MB).
1349 940
ETEXI
1350
SQMP
1351
balloon
1352
-------
1353

  
1354
Request VM to change its memory allocation (in bytes).
1355

  
1356
Arguments:
1357

  
1358
- "value": New memory allocation (json-int)
1359

  
1360
Example:
1361

  
1362
-> { "execute": "balloon", "arguments": { "value": 536870912 } }
1363
<- { "return": {} }
1364

  
1365
EQMP
1366 941

  
1367 942
    {
1368 943
        .name       = "set_link",
......
1378 953
@findex set_link
1379 954
Switch link @var{name} on (i.e. up) or off (i.e. down).
1380 955
ETEXI
1381
SQMP
1382
set_link
1383
--------
1384

  
1385
Change the link status of a network adapter.
1386

  
1387
Arguments:
1388

  
1389
- "name": network device name (json-string)
1390
- "up": status is up (json-bool)
1391

  
1392
Example:
1393

  
1394
-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1395
<- { "return": {} }
1396

  
1397
EQMP
1398 956

  
1399 957
    {
1400 958
        .name       = "watchdog_action",
......
1524 1082
mechanism on unix sockets, it is stored using the name @var{fdname} for
1525 1083
later use by other monitor commands.
1526 1084
ETEXI
1527
SQMP
1528
getfd
1529
-----
1530

  
1531
Receive a file descriptor via SCM rights and assign it a name.
1532

  
1533
Arguments:
1534

  
1535
- "fdname": file descriptor name (json-string)
1536

  
1537
Example:
1538

  
1539
-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1540
<- { "return": {} }
1541

  
1542
EQMP
1543 1085

  
1544 1086
    {
1545 1087
        .name       = "closefd",
......
1557 1099
@code{getfd} command. This is only needed if the file descriptor was never
1558 1100
used by another monitor command.
1559 1101
ETEXI
1560
SQMP
1561
closefd
1562
-------
1563

  
1564
Close a file descriptor previously passed via SCM rights.
1565

  
1566
Arguments:
1567

  
1568
- "fdname": file descriptor name (json-string)
1569

  
1570
Example:
1571

  
1572
-> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1573
<- { "return": {} }
1574

  
1575
EQMP
1576 1102

  
1577 1103
    {
1578 1104
        .name       = "block_passwd",
......
1588 1114
@findex block_passwd
1589 1115
Set the encrypted device @var{device} password to @var{password}
1590 1116
ETEXI
1591
SQMP
1592
block_passwd
1593
------------
1594

  
1595
Set the password of encrypted block devices.
1596

  
1597
Arguments:
1598

  
1599
- "device": device name (json-string)
1600
- "password": password (json-string)
1601

  
1602
Example:
1603

  
1604
-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1605
                                               "password": "12345" } }
1606
<- { "return": {} }
1607

  
1608
EQMP
1609

  
1610
    {
1611
        .name       = "qmp_capabilities",
1612
        .args_type  = "",
1613
        .params     = "",
1614
        .help       = "enable QMP capabilities",
1615
        .user_print = monitor_user_noop,
1616
        .mhandler.cmd_new = do_qmp_capabilities,
1617
    },
1618

  
1619
STEXI
1620
@item qmp_capabilities
1621
@findex qmp_capabilities
1622
Enable the specified QMP capabilities
1623
ETEXI
1624
SQMP
1625
qmp_capabilities
1626
----------------
1627

  
1628
Enable QMP capabilities.
1629

  
1630
Arguments: None.
1631

  
1632
Example:
1633

  
1634
-> { "execute": "qmp_capabilities" }
1635
<- { "return": {} }
1636

  
1637
Note: This command must be issued before issuing any other command.
1638

  
1639
EQMP
1640

  
1641

  
1642
HXCOMM Keep the 'info' command at the end!
1643
HXCOMM This is required for the QMP documentation layout.
1644

  
1645
SQMP
1646

  
1647
3. Query Commands
1648
=================
1649

  
1650
EQMP
1651 1117

  
1652 1118
    {
1653 1119
        .name       = "info",
......
1665 1131
@table @option
1666 1132
@item info version
1667 1133
show the version of QEMU
1668
ETEXI
1669
SQMP
1670
query-version
1671
-------------
1672

  
1673
Show QEMU version.
1674

  
1675
Return a json-object with the following information:
1676

  
1677
- "qemu": A json-object containing three integer values:
1678
    - "major": QEMU's major version (json-int)
1679
    - "minor": QEMU's minor version (json-int)
1680
    - "micro": QEMU's micro version (json-int)
1681
- "package": package's version (json-string)
1682

  
1683
Example:
1684

  
1685
-> { "execute": "query-version" }
1686
<- {
1687
      "return":{
1688
         "qemu":{
1689
            "major":0,
1690
            "minor":11,
1691
            "micro":5
1692
         },
1693
         "package":""
1694
      }
1695
   }
1696

  
1697
EQMP
1698

  
1699
STEXI
1700
@item info commands
1701
list QMP available commands
1702
ETEXI
1703
SQMP
1704
query-commands
1705
--------------
1706

  
1707
List QMP available commands.
1708

  
1709
Each command is represented by a json-object, the returned value is a json-array
1710
of all commands.
1711

  
1712
Each json-object contain:
1713

  
1714
- "name": command's name (json-string)
1715

  
1716
Example:
1717

  
1718
-> { "execute": "query-commands" }
1719
<- {
1720
      "return":[
1721
         {
1722
            "name":"query-balloon"
1723
         },
1724
         {
1725
            "name":"system_powerdown"
1726
         }
1727
      ]
1728
   }
1729

  
1730
Note: This example has been shortened as the real response is too long.
1731

  
1732
EQMP
1733

  
1734
STEXI
1735 1134
@item info network
1736 1135
show the various VLANs and the associated devices
1737
ETEXI
1738

  
1739
STEXI
1740 1136
@item info chardev
1741 1137
show the character devices
1742
ETEXI
1743
SQMP
1744
query-chardev
1745
-------------
1746

  
1747
Each device is represented by a json-object. The returned value is a json-array
1748
of all devices.
1749

  
1750
Each json-object contain the following:
1751

  
1752
- "label": device's label (json-string)
1753
- "filename": device's file (json-string)
1754

  
1755
Example:
1756

  
1757
-> { "execute": "query-chardev" }
1758
<- {
1759
      "return":[
1760
         {
1761
            "label":"monitor",
1762
            "filename":"stdio"
1763
         },
1764
         {
1765
            "label":"serial0",
1766
            "filename":"vc"
1767
         }
1768
      ]
1769
   }
1770

  
1771
EQMP
1772

  
1773
STEXI
1774 1138
@item info block
1775 1139
show the block devices
1776
ETEXI
1777
SQMP
1778
query-block
1779
-----------
1780

  
1781
Show the block devices.
1782

  
1783
Each block device information is stored in a json-object and the returned value
1784
is a json-array of all devices.
1785

  
1786
Each json-object contain the following:
1787

  
1788
- "device": device name (json-string)
1789
- "type": device type (json-string)
1790
         - Possible values: "hd", "cdrom", "floppy", "unknown"
1791
- "removable": true if the device is removable, false otherwise (json-bool)
1792
- "locked": true if the device is locked, false otherwise (json-bool)
1793
- "inserted": only present if the device is inserted, it is a json-object
1794
   containing the following:
1795
         - "file": device file name (json-string)
1796
         - "ro": true if read-only, false otherwise (json-bool)
1797
         - "drv": driver format name (json-string)
1798
             - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1799
                                "file", "file", "ftp", "ftps", "host_cdrom",
1800
                                "host_device", "host_floppy", "http", "https",
1801
                                "nbd", "parallels", "qcow", "qcow2", "raw",
1802
                                "tftp", "vdi", "vmdk", "vpc", "vvfat"
1803
         - "backing_file": backing file name (json-string, optional)
1804
         - "encrypted": true if encrypted, false otherwise (json-bool)
1805

  
1806
Example:
1807

  
1808
-> { "execute": "query-block" }
1809
<- {
1810
      "return":[
1811
         {
1812
            "device":"ide0-hd0",
1813
            "locked":false,
1814
            "removable":false,
1815
            "inserted":{
1816
               "ro":false,
1817
               "drv":"qcow2",
1818
               "encrypted":false,
1819
               "file":"disks/test.img"
1820
            },
1821
            "type":"hd"
1822
         },
1823
         {
1824
            "device":"ide1-cd0",
1825
            "locked":false,
1826
            "removable":true,
1827
            "type":"cdrom"
1828
         },
1829
         {
1830
            "device":"floppy0",
1831
            "locked":false,
1832
            "removable":true,
1833
            "type": "floppy"
1834
         },
1835
         {
1836
            "device":"sd0",
1837
            "locked":false,
1838
            "removable":true,
1839
            "type":"floppy"
1840
         }
1841
      ]
1842
   }
1843

  
1844
EQMP
1845

  
1846
STEXI
1847 1140
@item info blockstats
1848 1141
show block device statistics
1849
ETEXI
1850
SQMP
1851
query-blockstats
1852
----------------
1853

  
1854
Show block device statistics.
1855

  
1856
Each device statistic information is stored in a json-object and the returned
1857
value is a json-array of all devices.
1858

  
1859
Each json-object contain the following:
1860

  
1861
- "device": device name (json-string)
1862
- "stats": A json-object with the statistics information, it contains:
1863
    - "rd_bytes": bytes read (json-int)
1864
    - "wr_bytes": bytes written (json-int)
1865
    - "rd_operations": read operations (json-int)
1866
    - "wr_operations": write operations (json-int)
1867
    - "wr_highest_offset": Highest offset of a sector written since the
1868
                           BlockDriverState has been opened (json-int)
1869
- "parent": Contains recursively the statistics of the underlying
1870
            protocol (e.g. the host file for a qcow2 image). If there is
1871
            no underlying protocol, this field is omitted
1872
            (json-object, optional)
1873

  
1874
Example:
1875

  
1876
-> { "execute": "query-blockstats" }
1877
<- {
1878
      "return":[
1879
         {
1880
            "device":"ide0-hd0",
1881
            "parent":{
1882
               "stats":{
1883
                  "wr_highest_offset":3686448128,
1884
                  "wr_bytes":9786368,
1885
                  "wr_operations":751,
1886
                  "rd_bytes":122567168,
1887
                  "rd_operations":36772
1888
               }
1889
            },
1890
            "stats":{
1891
               "wr_highest_offset":2821110784,
1892
               "wr_bytes":9786368,
1893
               "wr_operations":692,
1894
               "rd_bytes":122739200,
1895
               "rd_operations":36604
1896
            }
1897
         },
1898
         {
1899
            "device":"ide1-cd0",
1900
            "stats":{
1901
               "wr_highest_offset":0,
1902
               "wr_bytes":0,
1903
               "wr_operations":0,
1904
               "rd_bytes":0,
1905
               "rd_operations":0
1906
            }
1907
         },
1908
         {
1909
            "device":"floppy0",
1910
            "stats":{
1911
               "wr_highest_offset":0,
1912
               "wr_bytes":0,
1913
               "wr_operations":0,
1914
               "rd_bytes":0,
1915
               "rd_operations":0
1916
            }
1917
         },
1918
         {
1919
            "device":"sd0",
1920
            "stats":{
1921
               "wr_highest_offset":0,
1922
               "wr_bytes":0,
1923
               "wr_operations":0,
1924
               "rd_bytes":0,
1925
               "rd_operations":0
1926
            }
1927
         }
1928
      ]
1929
   }
1930

  
1931
EQMP
1932

  
1933
STEXI
1934 1142
@item info registers
1935 1143
show the cpu registers
1936 1144
@item info cpus
1937 1145
show infos for each CPU
1938
ETEXI
1939
SQMP
1940
query-cpus
1941
----------
1942

  
1943
Show CPU information.
1944

  
1945
Return a json-array. Each CPU is represented by a json-object, which contains:
1946

  
1947
- "CPU": CPU index (json-int)
1948
- "current": true if this is the current CPU, false otherwise (json-bool)
1949
- "halted": true if the cpu is halted, false otherwise (json-bool)
1950
- Current program counter. The key's name depends on the architecture:
1951
     "pc": i386/x86_64 (json-int)
1952
     "nip": PPC (json-int)
1953
     "pc" and "npc": sparc (json-int)
1954
     "PC": mips (json-int)
1955

  
1956
Example:
1957

  
1958
-> { "execute": "query-cpus" }
1959
<- {
1960
      "return":[
1961
         {
1962
            "CPU":0,
1963
            "current":true,
1964
            "halted":false,
1965
            "pc":3227107138
1966
         },
1967
         {
1968
            "CPU":1,
1969
            "current":false,
1970
            "halted":true,
1971
            "pc":7108165
1972
         }
1973
      ]
1974
   }
1975

  
1976
EQMP
1977

  
1978
STEXI
1979 1146
@item info history
1980 1147
show the command line history
1981 1148
@item info irq
1982 1149
show the interrupts statistics (if available)
1983 1150
@item info pic
1984 1151
show i8259 (PIC) state
1985
ETEXI
1986

  
1987
STEXI
1988 1152
@item info pci
1989 1153
show emulated PCI device info
1990
ETEXI
1991
SQMP
1992
query-pci
1993
---------
1994

  
1995
PCI buses and devices information.
1996

  
1997
The returned value is a json-array of all buses. Each bus is represented by
1998
a json-object, which has a key with a json-array of all PCI devices attached
1999
to it. Each device is represented by a json-object.
2000

  
2001
The bus json-object contains the following:
2002

  
2003
- "bus": bus number (json-int)
2004
- "devices": a json-array of json-objects, each json-object represents a
2005
             PCI device
2006

  
2007
The PCI device json-object contains the following:
2008

  
2009
- "bus": identical to the parent's bus number (json-int)
2010
- "slot": slot number (json-int)
2011
- "function": function number (json-int)
2012
- "class_info": a json-object containing:
2013
     - "desc": device class description (json-string, optional)
2014
     - "class": device class number (json-int)
2015
- "id": a json-object containing:
2016
     - "device": device ID (json-int)
2017
     - "vendor": vendor ID (json-int)
2018
- "irq": device's IRQ if assigned (json-int, optional)
2019
- "qdev_id": qdev id string (json-string)
2020
- "pci_bridge": It's a json-object, only present if this device is a
2021
                PCI bridge, contains:
2022
     - "bus": bus number (json-int)
2023
     - "secondary": secondary bus number (json-int)
2024
     - "subordinate": subordinate bus number (json-int)
2025
     - "io_range": I/O memory range information, a json-object with the
2026
                   following members:
2027
                 - "base": base address, in bytes (json-int)
2028
                 - "limit": limit address, in bytes (json-int)
2029
     - "memory_range": memory range information, a json-object with the
2030
                       following members:
2031
                 - "base": base address, in bytes (json-int)
2032
                 - "limit": limit address, in bytes (json-int)
2033
     - "prefetchable_range": Prefetchable memory range information, a
2034
                             json-object with the following members:
2035
                 - "base": base address, in bytes (json-int)
2036
                 - "limit": limit address, in bytes (json-int)
2037
     - "devices": a json-array of PCI devices if there's any attached, each
2038
                  each element is represented by a json-object, which contains
2039
                  the same members of the 'PCI device json-object' described
2040
                  above (optional)
2041
- "regions": a json-array of json-objects, each json-object represents a
2042
             memory region of this device
2043

  
2044
The memory range json-object contains the following:
2045

  
2046
- "base": base memory address (json-int)
2047
- "limit": limit value (json-int)
2048

  
2049
The region json-object can be an I/O region or a memory region, an I/O region
2050
json-object contains the following:
2051

  
2052
- "type": "io" (json-string, fixed)
2053
- "bar": BAR number (json-int)
2054
- "address": memory address (json-int)
2055
- "size": memory size (json-int)
2056

  
2057
A memory region json-object contains the following:
2058

  
2059
- "type": "memory" (json-string, fixed)
2060
- "bar": BAR number (json-int)
2061
- "address": memory address (json-int)
2062
- "size": memory size (json-int)
2063
- "mem_type_64": true or false (json-bool)
2064
- "prefetch": true or false (json-bool)
2065

  
2066
Example:
2067

  
2068
-> { "execute": "query-pci" }
2069
<- {
2070
      "return":[
2071
         {
2072
            "bus":0,
2073
            "devices":[
2074
               {
2075
                  "bus":0,
2076
                  "qdev_id":"",
2077
                  "slot":0,
2078
                  "class_info":{
2079
                     "class":1536,
2080
                     "desc":"Host bridge"
2081
                  },
2082
                  "id":{
2083
                     "device":32902,
2084
                     "vendor":4663
2085
                  },
2086
                  "function":0,
2087
                  "regions":[
2088
   
2089
                  ]
2090
               },
2091
               {
2092
                  "bus":0,
2093
                  "qdev_id":"",
2094
                  "slot":1,
2095
                  "class_info":{
2096
                     "class":1537,
2097
                     "desc":"ISA bridge"
2098
                  },
2099
                  "id":{
2100
                     "device":32902,
2101
                     "vendor":28672
2102
                  },
2103
                  "function":0,
2104
                  "regions":[
2105
   
2106
                  ]
2107
               },
2108
               {
2109
                  "bus":0,
2110
                  "qdev_id":"",
2111
                  "slot":1,
2112
                  "class_info":{
2113
                     "class":257,
2114
                     "desc":"IDE controller"
2115
                  },
2116
                  "id":{
2117
                     "device":32902,
2118
                     "vendor":28688
2119
                  },
2120
                  "function":1,
2121
                  "regions":[
2122
                     {
2123
                        "bar":4,
2124
                        "size":16,
2125
                        "address":49152,
2126
                        "type":"io"
2127
                     }
2128
                  ]
2129
               },
2130
               {
2131
                  "bus":0,
2132
                  "qdev_id":"",
2133
                  "slot":2,
2134
                  "class_info":{
2135
                     "class":768,
2136
                     "desc":"VGA controller"
2137
                  },
2138
                  "id":{
2139
                     "device":4115,
2140
                     "vendor":184
2141
                  },
2142
                  "function":0,
2143
                  "regions":[
2144
                     {
2145
                        "prefetch":true,
2146
                        "mem_type_64":false,
2147
                        "bar":0,
2148
                        "size":33554432,
2149
                        "address":4026531840,
2150
                        "type":"memory"
2151
                     },
2152
                     {
2153
                        "prefetch":false,
2154
                        "mem_type_64":false,
2155
                        "bar":1,
2156
                        "size":4096,
2157
                        "address":4060086272,
2158
                        "type":"memory"
2159
                     },
2160
                     {
2161
                        "prefetch":false,
2162
                        "mem_type_64":false,
2163
                        "bar":6,
2164
                        "size":65536,
2165
                        "address":-1,
2166
                        "type":"memory"
2167
                     }
2168
                  ]
2169
               },
2170
               {
2171
                  "bus":0,
2172
                  "qdev_id":"",
2173
                  "irq":11,
2174
                  "slot":4,
2175
                  "class_info":{
2176
                     "class":1280,
2177
                     "desc":"RAM controller"
2178
                  },
2179
                  "id":{
2180
                     "device":6900,
2181
                     "vendor":4098
2182
                  },
2183
                  "function":0,
2184
                  "regions":[
2185
                     {
2186
                        "bar":0,
2187
                        "size":32,
2188
                        "address":49280,
2189
                        "type":"io"
2190
                     }
2191
                  ]
2192
               }
2193
            ]
2194
         }
2195
      ]
2196
   }
2197

  
2198
Note: This example has been shortened as the real response is too long.
2199

  
2200
EQMP
2201

  
2202
STEXI
2203 1154
@item info tlb
2204 1155
show virtual to physical memory mappings (i386 only)
2205 1156
@item info mem
2206 1157
show the active virtual memory mappings (i386 only)
2207
ETEXI
2208

  
2209
STEXI
2210 1158
@item info jit
2211 1159
show dynamic compiler info
2212 1160
@item info kvm
2213 1161
show KVM information
2214 1162
@item info numa
2215 1163
show NUMA information
2216
ETEXI
2217

  
2218
STEXI
2219 1164
@item info kvm
2220 1165
show KVM information
2221
ETEXI
2222
SQMP
2223
query-kvm
2224
---------
2225

  
2226
Show KVM information.
2227

  
2228
Return a json-object with the following information:
2229

  
2230
- "enabled": true if KVM support is enabled, false otherwise (json-bool)
2231
- "present": true if QEMU has KVM support, false otherwise (json-bool)
2232

  
2233
Example:
2234

  
2235
-> { "execute": "query-kvm" }
2236
<- { "return": { "enabled": true, "present": true } }
2237

  
2238
EQMP
2239

  
2240
STEXI
2241 1166
@item info usb
2242 1167
show USB devices plugged on the virtual USB hub
2243 1168
@item info usbhost
......
2248 1173
show information about active capturing
2249 1174
@item info snapshots
2250 1175
show list of VM snapshots
2251
ETEXI
2252

  
2253
STEXI
2254 1176
@item info status
2255 1177
show the current VM status (running|paused)
2256
ETEXI
2257
SQMP
2258
query-status
2259
------------
2260

  
2261
Return a json-object with the following information:
2262

  
2263
- "running": true if the VM is running, or false if it is paused (json-bool)
2264
- "singlestep": true if the VM is in single step mode,
2265
                false otherwise (json-bool)
2266

  
2267
Example:
2268

  
2269
-> { "execute": "query-status" }
2270
<- { "return": { "running": true, "singlestep": false } }
2271

  
2272
EQMP
2273

  
2274
STEXI
2275 1178
@item info pcmcia
2276 1179
show guest PCMCIA status
2277
ETEXI
2278

  
2279
STEXI
2280 1180
@item info mice
2281 1181
show which guest mouse is receiving events
2282
ETEXI
2283
SQMP
2284
query-mice
2285
----------
2286

  
2287
Show VM mice information.
2288

  
2289
Each mouse is represented by a json-object, the returned value is a json-array
2290
of all mice.
2291

  
2292
The mouse json-object contains the following:
2293

  
2294
- "name": mouse's name (json-string)
2295
- "index": mouse's index (json-int)
2296
- "current": true if this mouse is receiving events, false otherwise (json-bool)
2297
- "absolute": true if the mouse generates absolute input events (json-bool)
2298

  
2299
Example:
2300

  
2301
-> { "execute": "query-mice" }
2302
<- {
2303
      "return":[
2304
         {
2305
            "name":"QEMU Microsoft Mouse",
2306
            "index":0,
2307
            "current":false,
2308
            "absolute":false
2309
         },
2310
         {
2311
            "name":"QEMU PS/2 Mouse",
2312
            "index":1,
2313
            "current":true,
2314
            "absolute":true
2315
         }
2316
      ]
2317
   }
2318

  
2319
EQMP
2320

  
2321
STEXI
2322 1182
@item info vnc
2323 1183
show the vnc server status
2324
ETEXI
2325
SQMP
2326
query-vnc
2327
---------
2328

  
2329
Show VNC server information.
2330

  
2331
Return a json-object with server information. Connected clients are returned
2332
as a json-array of json-objects.
2333

  
2334
The main json-object contains the following:
2335

  
2336
- "enabled": true or false (json-bool)
2337
- "host": server's IP address (json-string)
2338
- "family": address family (json-string)
2339
         - Possible values: "ipv4", "ipv6", "unix", "unknown"
2340
- "service": server's port number (json-string)
2341
- "auth": authentication method (json-string)
2342
         - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2343
                            "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2344
                            "vencrypt+plain", "vencrypt+tls+none",
2345
                            "vencrypt+tls+plain", "vencrypt+tls+sasl",
2346
                            "vencrypt+tls+vnc", "vencrypt+x509+none",
2347
                            "vencrypt+x509+plain", "vencrypt+x509+sasl",
2348
                            "vencrypt+x509+vnc", "vnc"
2349
- "clients": a json-array of all connected clients
2350

  
2351
Clients are described by a json-object, each one contain the following:
2352

  
2353
- "host": client's IP address (json-string)
2354
- "family": address family (json-string)
2355
         - Possible values: "ipv4", "ipv6", "unix", "unknown"
2356
- "service": client's port number (json-string)
2357
- "x509_dname": TLS dname (json-string, optional)
2358
- "sasl_username": SASL username (json-string, optional)
2359

  
2360
Example:
2361

  
2362
-> { "execute": "query-vnc" }
2363
<- {
2364
      "return":{
2365
         "enabled":true,
2366
         "host":"0.0.0.0",
2367
         "service":"50402",
2368
         "auth":"vnc",
2369
         "family":"ipv4",
2370
         "clients":[
2371
            {
2372
               "host":"127.0.0.1",
2373
               "service":"50401",
2374
               "family":"ipv4"
2375
            }
2376
         ]
2377
      }
2378
   }
2379

  
2380
EQMP
2381

  
2382
STEXI
2383 1184
@item info name
2384 1185
show the current VM name
2385
ETEXI
2386
SQMP
2387
query-name
2388
----------
2389

  
2390
Show VM name.
2391

  
2392
Return a json-object with the following information:
2393

  
2394
- "name": VM's name (json-string, optional)
2395

  
2396
Example:
2397

  
2398
-> { "execute": "query-name" }
2399
<- { "return": { "name": "qemu-name" } }
2400

  
2401
EQMP
2402

  
2403
STEXI
2404 1186
@item info uuid
2405 1187
show the current VM UUID
2406
ETEXI
2407
SQMP
2408
query-uuid
2409
----------
2410

  
2411
Show VM UUID.
2412

  
... This diff was truncated because it exceeds the maximum size that can be displayed.

Also available in: Unified diff