Statistics
| Branch: | Revision:

root / QMP / qmp-spec.txt @ 5307d7d3

History | View | Annotate | Download (6.8 kB)

1
           QEMU Monitor Protocol Specification - Version 0.1
2

    
3
1. Introduction
4
===============
5

    
6
This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol
7
which is available for applications to control QEMU at the machine-level.
8

    
9
To enable QMP support, QEMU has to be run in "control mode". This is done by
10
starting QEMU with the appropriate command-line options. Please, refer to the
11
QEMU manual page for more information.
12

    
13
2. Protocol Specification
14
=========================
15

    
16
This section details the protocol format. For the purpose of this document
17
"Client" is any application which is communicating with QEMU in control mode,
18
and "Server" is QEMU itself.
19

    
20
JSON data structures, when mentioned in this document, are always in the
21
following format:
22

    
23
    json-DATA-STRUCTURE-NAME
24

    
25
Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by
26
the JSON standard:
27

    
28
http://www.ietf.org/rfc/rfc4627.txt
29

    
30
For convenience, json-object members and json-array elements mentioned in
31
this document will be in a certain order. However, in real protocol usage
32
they can be in ANY order, thus no particular order should be assumed.
33

    
34
2.1 General Definitions
35
-----------------------
36

    
37
2.1.1 All interactions transmitted by the Server are json-objects, always
38
      terminating with CRLF
39

    
40
2.1.2 All json-objects members are mandatory when not specified otherwise
41

    
42
2.2 Server Greeting
43
-------------------
44

    
45
Right when connected the Server will issue a greeting message, which signals
46
that the connection has been successfully established and that the Server is
47
ready for capabilities negotiation (for more information refer to section
48
'4. Capabilities Negotiation').
49

    
50
The format is:
51

    
52
{ "QMP": { "version": json-object, "capabilities": json-array } }
53

    
54
 Where,
55

    
56
- The "version" member contains the Server's version information (the format
57
  is the same of the 'query-version' command)
58
- The "capabilities" member specify the availability of features beyond the
59
  baseline specification
60

    
61
2.3 Issuing Commands
62
--------------------
63

    
64
The format for command execution is:
65

    
66
{ "execute": json-string, "arguments": json-object, "id": json-value }
67

    
68
 Where,
69

    
70
- The "execute" member identifies the command to be executed by the Server
71
- The "arguments" member is used to pass any arguments required for the
72
  execution of the command, it is optional when no arguments are required
73
- The "id" member is a transaction identification associated with the
74
  command execution, it is optional and will be part of the response if
75
  provided
76

    
77
2.4 Commands Responses
78
----------------------
79

    
80
There are two possible responses which the Server will issue as the result
81
of a command execution: success or error.
82

    
83
2.4.1 success
84
-------------
85

    
86
The success response is issued when the command execution has finished
87
without errors.
88

    
89
The format is:
90

    
91
{ "return": json-object, "id": json-value }
92

    
93
 Where,
94

    
95
- The "return" member contains the command returned data, which is defined
96
  in a per-command basis or an empty json-object if the command does not
97
  return data
98
- The "id" member contains the transaction identification associated
99
  with the command execution (if issued by the Client)
100

    
101
2.4.2 error
102
-----------
103

    
104
The error response is issued when the command execution could not be
105
completed because of an error condition.
106

    
107
The format is:
108

    
109
{ "error": { "class": json-string, "data": json-object, "desc": json-string },
110
  "id": json-value }
111

    
112
 Where,
113

    
114
- The "class" member contains the error class name (eg. "ServiceUnavailable")
115
- The "data" member contains specific error data and is defined in a
116
  per-command basis, it will be an empty json-object if the error has no data
117
- The "desc" member is a human-readable error message. Clients should
118
  not attempt to parse this message.
119
- The "id" member contains the transaction identification associated with
120
  the command execution (if issued by the Client)
121

    
122
NOTE: Some errors can occur before the Server is able to read the "id" member,
123
in these cases the "id" member will not be part of the error response, even
124
if provided by the client.
125

    
126
2.5 Asynchronous events
127
-----------------------
128

    
129
As a result of state changes, the Server may send messages unilaterally
130
to the Client at any time. They are called 'asynchronous events'.
131

    
132
The format is:
133

    
134
{ "event": json-string, "data": json-object,
135
  "timestamp": { "seconds": json-number, "microseconds": json-number } }
136

    
137
 Where,
138

    
139
- The "event" member contains the event's name
140
- The "data" member contains event specific data, which is defined in a
141
  per-event basis, it is optional
142
- The "timestamp" member contains the exact time of when the event occurred
143
  in the Server. It is a fixed json-object with time in seconds and
144
  microseconds
145

    
146
For a listing of supported asynchronous events, please, refer to the
147
qmp-events.txt file.
148

    
149
3. QMP Examples
150
===============
151

    
152
This section provides some examples of real QMP usage, in all of them
153
'C' stands for 'Client' and 'S' stands for 'Server'.
154

    
155
3.1 Server greeting
156
-------------------
157

    
158
S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
159

    
160
3.2 Simple 'stop' execution
161
---------------------------
162

    
163
C: { "execute": "stop" }
164
S: {"return": {}}
165

    
166
3.3 KVM information
167
-------------------
168

    
169
C: { "execute": "query-kvm", "id": "example" }
170
S: {"return": {"enabled": true, "present": true}, "id": "example"}
171

    
172
3.4 Parsing error
173
------------------
174

    
175
C: { "execute": }
176
S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
177
{}}}
178

    
179
3.5 Powerdown event
180
-------------------
181

    
182
S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
183
"POWERDOWN"}
184

    
185
4. Capabilities Negotiation
186
----------------------------
187

    
188
When a Client successfully establishes a connection, the Server is in
189
Capabilities Negotiation mode.
190

    
191
In this mode only the 'qmp_capabilities' command is allowed to run, all
192
other commands will return the CommandNotFound error. Asynchronous messages
193
are not delivered either.
194

    
195
Clients should use the 'qmp_capabilities' command to enable capabilities
196
advertised in the Server's greeting (section '2.2 Server Greeting') they
197
support.
198

    
199
When the 'qmp_capabilities' command is issued, and if it does not return an
200
error, the Server enters in Command mode where capabilities changes take
201
effect, all commands (except 'qmp_capabilities') are allowed and asynchronous
202
messages are delivered.
203

    
204
5 Compatibility Considerations
205
------------------------------
206

    
207
All protocol changes or new features which modify the protocol format in an
208
incompatible way are disabled by default and will be advertised by the
209
capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
210
that array and enable the capabilities they support.
211

    
212
Additionally, Clients must not assume any particular:
213

    
214
- Size of json-objects or length of json-arrays
215
- Order of json-object members or json-array elements
216
- Amount of errors generated by a command, that is, new errors can be added
217
  to any existing command in newer versions of the Server