root / QMP / qmp-spec.txt @ f4918804
History | View | Annotate | Download (6 kB)
1 | 94048982 | Luiz Capitulino | QEMU Monitor Protocol Specification - Version 0.1 |
---|---|---|---|
2 | f544d174 | Luiz Capitulino | |
3 | f544d174 | Luiz Capitulino | 1. Introduction |
4 | f544d174 | Luiz Capitulino | =============== |
5 | f544d174 | Luiz Capitulino | |
6 | f544d174 | Luiz Capitulino | This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol |
7 | f544d174 | Luiz Capitulino | which is available for applications to control QEMU at the machine-level. |
8 | f544d174 | Luiz Capitulino | |
9 | f544d174 | Luiz Capitulino | To enable QMP support, QEMU has to be run in "control mode". This is done by |
10 | f544d174 | Luiz Capitulino | starting QEMU with the appropriate command-line options. Please, refer to the |
11 | f544d174 | Luiz Capitulino | QEMU manual page for more information. |
12 | f544d174 | Luiz Capitulino | |
13 | f544d174 | Luiz Capitulino | 2. Protocol Specification |
14 | f544d174 | Luiz Capitulino | ========================= |
15 | f544d174 | Luiz Capitulino | |
16 | f544d174 | Luiz Capitulino | This section details the protocol format. For the purpose of this document |
17 | f544d174 | Luiz Capitulino | "Client" is any application which is communicating with QEMU in control mode, |
18 | f544d174 | Luiz Capitulino | and "Server" is QEMU itself. |
19 | f544d174 | Luiz Capitulino | |
20 | f544d174 | Luiz Capitulino | JSON data structures, when mentioned in this document, are always in the |
21 | f544d174 | Luiz Capitulino | following format: |
22 | f544d174 | Luiz Capitulino | |
23 | f544d174 | Luiz Capitulino | json-DATA-STRUCTURE-NAME |
24 | f544d174 | Luiz Capitulino | |
25 | f544d174 | Luiz Capitulino | Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by |
26 | f544d174 | Luiz Capitulino | the JSON standard: |
27 | f544d174 | Luiz Capitulino | |
28 | f544d174 | Luiz Capitulino | http://www.ietf.org/rfc/rfc4627.txt |
29 | f544d174 | Luiz Capitulino | |
30 | 94048982 | Luiz Capitulino | For convenience, json-object members and json-array elements mentioned in |
31 | 94048982 | Luiz Capitulino | this document will be in a certain order. However, in real protocol usage |
32 | 94048982 | Luiz Capitulino | they can be in ANY order, thus no particular order should be assumed. |
33 | f544d174 | Luiz Capitulino | |
34 | f544d174 | Luiz Capitulino | 2.1 General Definitions |
35 | f544d174 | Luiz Capitulino | ----------------------- |
36 | f544d174 | Luiz Capitulino | |
37 | f544d174 | Luiz Capitulino | 2.1.1 All interactions transmitted by the Server are json-objects, always |
38 | f544d174 | Luiz Capitulino | terminating with CRLF |
39 | f544d174 | Luiz Capitulino | |
40 | f544d174 | Luiz Capitulino | 2.1.2 All json-objects members are mandatory when not specified otherwise |
41 | f544d174 | Luiz Capitulino | |
42 | f544d174 | Luiz Capitulino | 2.2 Server Greeting |
43 | f544d174 | Luiz Capitulino | ------------------- |
44 | f544d174 | Luiz Capitulino | |
45 | f544d174 | Luiz Capitulino | Right when connected the Server will issue a greeting message, which signals |
46 | f544d174 | Luiz Capitulino | that the connection has been successfully established and that the Server is |
47 | f544d174 | Luiz Capitulino | waiting for commands. |
48 | f544d174 | Luiz Capitulino | |
49 | f544d174 | Luiz Capitulino | The format is: |
50 | f544d174 | Luiz Capitulino | |
51 | f544d174 | Luiz Capitulino | { "QMP": { "capabilities": json-array } } |
52 | f544d174 | Luiz Capitulino | |
53 | f544d174 | Luiz Capitulino | Where, |
54 | f544d174 | Luiz Capitulino | |
55 | f544d174 | Luiz Capitulino | - The "capabilities" member specify the availability of features beyond the |
56 | f544d174 | Luiz Capitulino | baseline specification |
57 | f544d174 | Luiz Capitulino | |
58 | f544d174 | Luiz Capitulino | 2.3 Issuing Commands |
59 | f544d174 | Luiz Capitulino | -------------------- |
60 | f544d174 | Luiz Capitulino | |
61 | f544d174 | Luiz Capitulino | The format for command execution is: |
62 | f544d174 | Luiz Capitulino | |
63 | f544d174 | Luiz Capitulino | { "execute": json-string, "arguments": json-object, "id": json-value } |
64 | f544d174 | Luiz Capitulino | |
65 | f544d174 | Luiz Capitulino | Where, |
66 | f544d174 | Luiz Capitulino | |
67 | f544d174 | Luiz Capitulino | - The "execute" member identifies the command to be executed by the Server |
68 | f544d174 | Luiz Capitulino | - The "arguments" member is used to pass any arguments required for the |
69 | f544d174 | Luiz Capitulino | execution of the command, it is optional when no arguments are required |
70 | f544d174 | Luiz Capitulino | - The "id" member is a transaction identification associated with the |
71 | f544d174 | Luiz Capitulino | command execution, it is optional and will be part of the response if |
72 | f544d174 | Luiz Capitulino | provided |
73 | f544d174 | Luiz Capitulino | |
74 | f544d174 | Luiz Capitulino | 2.4 Commands Responses |
75 | f544d174 | Luiz Capitulino | ---------------------- |
76 | f544d174 | Luiz Capitulino | |
77 | f544d174 | Luiz Capitulino | There are two possible responses which the Server will issue as the result |
78 | f544d174 | Luiz Capitulino | of a command execution: success or error. |
79 | f544d174 | Luiz Capitulino | |
80 | f544d174 | Luiz Capitulino | 2.4.1 success |
81 | f544d174 | Luiz Capitulino | ------------- |
82 | f544d174 | Luiz Capitulino | |
83 | f544d174 | Luiz Capitulino | The success response is issued when the command execution has finished |
84 | f544d174 | Luiz Capitulino | without errors. |
85 | f544d174 | Luiz Capitulino | |
86 | f544d174 | Luiz Capitulino | The format is: |
87 | f544d174 | Luiz Capitulino | |
88 | 94048982 | Luiz Capitulino | { "return": json-object, "id": json-value } |
89 | f544d174 | Luiz Capitulino | |
90 | f544d174 | Luiz Capitulino | Where, |
91 | f544d174 | Luiz Capitulino | |
92 | f544d174 | Luiz Capitulino | - The "return" member contains the command returned data, which is defined |
93 | 94048982 | Luiz Capitulino | in a per-command basis or an empty json-object if the command does not |
94 | 94048982 | Luiz Capitulino | return data |
95 | f544d174 | Luiz Capitulino | - The "id" member contains the transaction identification associated |
96 | f544d174 | Luiz Capitulino | with the command execution (if issued by the Client) |
97 | f544d174 | Luiz Capitulino | |
98 | f544d174 | Luiz Capitulino | 2.4.2 error |
99 | f544d174 | Luiz Capitulino | ----------- |
100 | f544d174 | Luiz Capitulino | |
101 | f544d174 | Luiz Capitulino | The error response is issued when the command execution could not be |
102 | f544d174 | Luiz Capitulino | completed because of an error condition. |
103 | f544d174 | Luiz Capitulino | |
104 | f544d174 | Luiz Capitulino | The format is: |
105 | f544d174 | Luiz Capitulino | |
106 | 94048982 | Luiz Capitulino | { "error": { "class": json-string, "data": json-object, "desc": json-string }, |
107 | 77e595e7 | Markus Armbruster | "id": json-value } |
108 | f544d174 | Luiz Capitulino | |
109 | f544d174 | Luiz Capitulino | Where, |
110 | f544d174 | Luiz Capitulino | |
111 | f544d174 | Luiz Capitulino | - The "class" member contains the error class name (eg. "ServiceUnavailable") |
112 | f544d174 | Luiz Capitulino | - The "data" member contains specific error data and is defined in a |
113 | f544d174 | Luiz Capitulino | per-command basis, it will be an empty json-object if the error has no data |
114 | 94048982 | Luiz Capitulino | - The "desc" member is a human-readable error message. Clients should |
115 | 77e595e7 | Markus Armbruster | not attempt to parse this message. |
116 | f544d174 | Luiz Capitulino | - The "id" member contains the transaction identification associated with |
117 | f544d174 | Luiz Capitulino | the command execution (if issued by the Client) |
118 | f544d174 | Luiz Capitulino | |
119 | f544d174 | Luiz Capitulino | NOTE: Some errors can occur before the Server is able to read the "id" member, |
120 | f544d174 | Luiz Capitulino | in these cases the "id" member will not be part of the error response, even |
121 | f544d174 | Luiz Capitulino | if provided by the client. |
122 | f544d174 | Luiz Capitulino | |
123 | f544d174 | Luiz Capitulino | 2.5 Asynchronous events |
124 | f544d174 | Luiz Capitulino | ----------------------- |
125 | f544d174 | Luiz Capitulino | |
126 | f544d174 | Luiz Capitulino | As a result of state changes, the Server may send messages unilaterally |
127 | f544d174 | Luiz Capitulino | to the Client at any time. They are called 'asynchronous events'. |
128 | f544d174 | Luiz Capitulino | |
129 | f544d174 | Luiz Capitulino | The format is: |
130 | f544d174 | Luiz Capitulino | |
131 | 94048982 | Luiz Capitulino | { "event": json-string, "data": json-object, |
132 | f544d174 | Luiz Capitulino | "timestamp": { "seconds": json-number, "microseconds": json-number } } |
133 | f544d174 | Luiz Capitulino | |
134 | f544d174 | Luiz Capitulino | Where, |
135 | f544d174 | Luiz Capitulino | |
136 | f544d174 | Luiz Capitulino | - The "event" member contains the event's name |
137 | f544d174 | Luiz Capitulino | - The "data" member contains event specific data, which is defined in a |
138 | f544d174 | Luiz Capitulino | per-event basis, it is optional |
139 | 94048982 | Luiz Capitulino | - The "timestamp" member contains the exact time of when the event occurred |
140 | f544d174 | Luiz Capitulino | in the Server. It is a fixed json-object with time in seconds and |
141 | f544d174 | Luiz Capitulino | microseconds |
142 | f544d174 | Luiz Capitulino | |
143 | f544d174 | Luiz Capitulino | For a listing of supported asynchronous events, please, refer to the |
144 | f544d174 | Luiz Capitulino | qmp-events.txt file. |
145 | f544d174 | Luiz Capitulino | |
146 | f544d174 | Luiz Capitulino | 3. QMP Examples |
147 | f544d174 | Luiz Capitulino | =============== |
148 | f544d174 | Luiz Capitulino | |
149 | f544d174 | Luiz Capitulino | This section provides some examples of real QMP usage, in all of them |
150 | f544d174 | Luiz Capitulino | 'C' stands for 'Client' and 'S' stands for 'Server'. |
151 | f544d174 | Luiz Capitulino | |
152 | f544d174 | Luiz Capitulino | 3.1 Server greeting |
153 | f544d174 | Luiz Capitulino | ------------------- |
154 | f544d174 | Luiz Capitulino | |
155 | f544d174 | Luiz Capitulino | S: {"QMP": {"capabilities": []}} |
156 | f544d174 | Luiz Capitulino | |
157 | f544d174 | Luiz Capitulino | 3.2 Simple 'stop' execution |
158 | f544d174 | Luiz Capitulino | --------------------------- |
159 | f544d174 | Luiz Capitulino | |
160 | f544d174 | Luiz Capitulino | C: { "execute": "stop" } |
161 | 94048982 | Luiz Capitulino | S: {"return": {}} |
162 | f544d174 | Luiz Capitulino | |
163 | f544d174 | Luiz Capitulino | 3.3 KVM information |
164 | f544d174 | Luiz Capitulino | ------------------- |
165 | f544d174 | Luiz Capitulino | |
166 | 94048982 | Luiz Capitulino | C: { "execute": "query-kvm", "id": "example" } |
167 | 94048982 | Luiz Capitulino | S: {"return": {"enabled": true, "present": true}, "id": "example"} |
168 | f544d174 | Luiz Capitulino | |
169 | f544d174 | Luiz Capitulino | 3.4 Parsing error |
170 | f544d174 | Luiz Capitulino | ------------------ |
171 | f544d174 | Luiz Capitulino | |
172 | f544d174 | Luiz Capitulino | C: { "execute": } |
173 | 94048982 | Luiz Capitulino | S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data": |
174 | 94048982 | Luiz Capitulino | {}}} |
175 | f544d174 | Luiz Capitulino | |
176 | f544d174 | Luiz Capitulino | 3.5 Powerdown event |
177 | f544d174 | Luiz Capitulino | ------------------- |
178 | f544d174 | Luiz Capitulino | |
179 | f544d174 | Luiz Capitulino | S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event": |
180 | f544d174 | Luiz Capitulino | "POWERDOWN"} |
181 | f544d174 | Luiz Capitulino | |
182 | 94048982 | Luiz Capitulino | 4. Compatibility Considerations |
183 | 94048982 | Luiz Capitulino | -------------------------------- |
184 | f544d174 | Luiz Capitulino | |
185 | 94048982 | Luiz Capitulino | In order to achieve maximum compatibility between versions, Clients must not |
186 | 94048982 | Luiz Capitulino | assume any particular: |
187 | f544d174 | Luiz Capitulino | |
188 | 94048982 | Luiz Capitulino | - Size of json-objects or length of json-arrays |
189 | 94048982 | Luiz Capitulino | - Order of json-object members or json-array elements |
190 | 94048982 | Luiz Capitulino | - Amount of errors generated by a command, that is, new errors can be added |
191 | 94048982 | Luiz Capitulino | to any existing command in newer versions of the Server |
192 | f544d174 | Luiz Capitulino | |
193 | 94048982 | Luiz Capitulino | Additionally, Clients should always: |
194 | f544d174 | Luiz Capitulino | |
195 | 94048982 | Luiz Capitulino | - Check the capabilities json-array at connection time |
196 | 94048982 | Luiz Capitulino | - Check the availability of commands with 'query-commands' before issuing them |
197 | 94048982 | Luiz Capitulino | |
198 | 94048982 | Luiz Capitulino | 5. Recommendations to Client implementors |
199 | 94048982 | Luiz Capitulino | ----------------------------------------- |
200 | 94048982 | Luiz Capitulino | |
201 | 94048982 | Luiz Capitulino | 5.1 The Server should be always started in pause mode, thus the Client is |
202 | 94048982 | Luiz Capitulino | able to perform any setup procedure without the risk of race conditions |
203 | 94048982 | Luiz Capitulino | and related problems |