]>
Commit | Line | Data |
---|---|---|
f544d174 LC |
1 | QEMU Monitor Protocol Draft 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-objects mentioned in this document will have its members | |
31 | in a certain order. However, in real protocol usage json-objects members can | |
32 | 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 | waiting for commands. | |
48 | ||
49 | The format is: | |
50 | ||
51 | { "QMP": { "capabilities": json-array } } | |
52 | ||
53 | Where, | |
54 | ||
55 | - The "capabilities" member specify the availability of features beyond the | |
56 | baseline specification | |
57 | ||
58 | 2.3 Issuing Commands | |
59 | -------------------- | |
60 | ||
61 | The format for command execution is: | |
62 | ||
63 | { "execute": json-string, "arguments": json-object, "id": json-value } | |
64 | ||
65 | Where, | |
66 | ||
67 | - The "execute" member identifies the command to be executed by the Server | |
68 | - The "arguments" member is used to pass any arguments required for the | |
69 | execution of the command, it is optional when no arguments are required | |
70 | - The "id" member is a transaction identification associated with the | |
71 | command execution, it is optional and will be part of the response if | |
72 | provided | |
73 | ||
74 | 2.4 Commands Responses | |
75 | ---------------------- | |
76 | ||
77 | There are two possible responses which the Server will issue as the result | |
78 | of a command execution: success or error. | |
79 | ||
80 | 2.4.1 success | |
81 | ------------- | |
82 | ||
83 | The success response is issued when the command execution has finished | |
84 | without errors. | |
85 | ||
86 | The format is: | |
87 | ||
88 | { "return": json-value, "id": json-value } | |
89 | ||
90 | Where, | |
91 | ||
92 | - The "return" member contains the command returned data, which is defined | |
93 | in a per-command basis or "OK" if the command does not return data | |
94 | - The "id" member contains the transaction identification associated | |
95 | with the command execution (if issued by the Client) | |
96 | ||
97 | 2.4.2 error | |
98 | ----------- | |
99 | ||
100 | The error response is issued when the command execution could not be | |
101 | completed because of an error condition. | |
102 | ||
103 | The format is: | |
104 | ||
105 | { "error": { "class": json-string, "data": json-value }, "id": json-value } | |
106 | ||
107 | Where, | |
108 | ||
109 | - The "class" member contains the error class name (eg. "ServiceUnavailable") | |
110 | - The "data" member contains specific error data and is defined in a | |
111 | per-command basis, it will be an empty json-object if the error has no data | |
112 | - The "id" member contains the transaction identification associated with | |
113 | the command execution (if issued by the Client) | |
114 | ||
115 | NOTE: Some errors can occur before the Server is able to read the "id" member, | |
116 | in these cases the "id" member will not be part of the error response, even | |
117 | if provided by the client. | |
118 | ||
119 | 2.5 Asynchronous events | |
120 | ----------------------- | |
121 | ||
122 | As a result of state changes, the Server may send messages unilaterally | |
123 | to the Client at any time. They are called 'asynchronous events'. | |
124 | ||
125 | The format is: | |
126 | ||
127 | { "event": json-string, "data": json-value, | |
128 | "timestamp": { "seconds": json-number, "microseconds": json-number } } | |
129 | ||
130 | Where, | |
131 | ||
132 | - The "event" member contains the event's name | |
133 | - The "data" member contains event specific data, which is defined in a | |
134 | per-event basis, it is optional | |
135 | - The "timestamp" member contains the exact time of when the event ocurred | |
136 | in the Server. It is a fixed json-object with time in seconds and | |
137 | microseconds | |
138 | ||
139 | For a listing of supported asynchronous events, please, refer to the | |
140 | qmp-events.txt file. | |
141 | ||
142 | 3. QMP Examples | |
143 | =============== | |
144 | ||
145 | This section provides some examples of real QMP usage, in all of them | |
146 | 'C' stands for 'Client' and 'S' stands for 'Server'. | |
147 | ||
148 | 3.1 Server greeting | |
149 | ------------------- | |
150 | ||
151 | S: {"QMP": {"capabilities": []}} | |
152 | ||
153 | 3.2 Simple 'stop' execution | |
154 | --------------------------- | |
155 | ||
156 | C: { "execute": "stop" } | |
157 | S: {"return": "OK"} | |
158 | ||
159 | 3.3 KVM information | |
160 | ------------------- | |
161 | ||
162 | C: {"execute": "query-kvm", "id": "example"} | |
163 | S: {"return": "enabled", "id": "example"} | |
164 | ||
165 | 3.4 Parsing error | |
166 | ------------------ | |
167 | ||
168 | C: { "execute": } | |
169 | S: {"error": {"class": "JSONParsing", "data": {}}} | |
170 | ||
171 | 3.5 Powerdown event | |
172 | ------------------- | |
173 | ||
174 | S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event": | |
175 | "POWERDOWN"} | |
176 | ||
177 | 4. Notes to Client implementors | |
178 | ------------------------------- | |
179 | ||
180 | 4.1 It is recommended to always start the Server in pause mode, thus the | |
181 | Client is able to perform any setup procedure without the risk of | |
182 | race conditions and related problems | |
183 | ||
184 | 4.2 It is recommended to always check the capabilities json-array, issued | |
185 | with the greeting message, at connection time | |
186 | ||
187 | 4.3 Json-objects or json-arrays mentioned in this document are not fixed | |
188 | and no particular size or number of members/elements should be assumed. | |
189 | New members/elements can be added at any time. | |
190 | ||
191 | 4.4 No particular order of json-objects members should be assumed, they | |
192 | can change at any time |