root / QMP / qmp-spec.txt @ 9ea37780
History | View | Annotate | Download (5.7 kB)
1 | f544d174 | Luiz Capitulino | QEMU Monitor Protocol Draft 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 | f544d174 | Luiz Capitulino | For convenience, json-objects mentioned in this document will have its members |
31 | f544d174 | Luiz Capitulino | in a certain order. However, in real protocol usage json-objects members can |
32 | f544d174 | Luiz Capitulino | 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 | f544d174 | Luiz Capitulino | { "return": json-value, "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 | f544d174 | Luiz Capitulino | in a per-command basis or "OK" if the command does not return data |
94 | f544d174 | Luiz Capitulino | - The "id" member contains the transaction identification associated |
95 | f544d174 | Luiz Capitulino | with the command execution (if issued by the Client) |
96 | f544d174 | Luiz Capitulino | |
97 | f544d174 | Luiz Capitulino | 2.4.2 error |
98 | f544d174 | Luiz Capitulino | ----------- |
99 | f544d174 | Luiz Capitulino | |
100 | f544d174 | Luiz Capitulino | The error response is issued when the command execution could not be |
101 | f544d174 | Luiz Capitulino | completed because of an error condition. |
102 | f544d174 | Luiz Capitulino | |
103 | f544d174 | Luiz Capitulino | The format is: |
104 | f544d174 | Luiz Capitulino | |
105 | f544d174 | Luiz Capitulino | { "error": { "class": json-string, "data": json-value }, "id": json-value } |
106 | f544d174 | Luiz Capitulino | |
107 | f544d174 | Luiz Capitulino | Where, |
108 | f544d174 | Luiz Capitulino | |
109 | f544d174 | Luiz Capitulino | - The "class" member contains the error class name (eg. "ServiceUnavailable") |
110 | f544d174 | Luiz Capitulino | - The "data" member contains specific error data and is defined in a |
111 | f544d174 | Luiz Capitulino | per-command basis, it will be an empty json-object if the error has no data |
112 | f544d174 | Luiz Capitulino | - The "id" member contains the transaction identification associated with |
113 | f544d174 | Luiz Capitulino | the command execution (if issued by the Client) |
114 | f544d174 | Luiz Capitulino | |
115 | f544d174 | Luiz Capitulino | NOTE: Some errors can occur before the Server is able to read the "id" member, |
116 | f544d174 | Luiz Capitulino | in these cases the "id" member will not be part of the error response, even |
117 | f544d174 | Luiz Capitulino | if provided by the client. |
118 | f544d174 | Luiz Capitulino | |
119 | f544d174 | Luiz Capitulino | 2.5 Asynchronous events |
120 | f544d174 | Luiz Capitulino | ----------------------- |
121 | f544d174 | Luiz Capitulino | |
122 | f544d174 | Luiz Capitulino | As a result of state changes, the Server may send messages unilaterally |
123 | f544d174 | Luiz Capitulino | to the Client at any time. They are called 'asynchronous events'. |
124 | f544d174 | Luiz Capitulino | |
125 | f544d174 | Luiz Capitulino | The format is: |
126 | f544d174 | Luiz Capitulino | |
127 | f544d174 | Luiz Capitulino | { "event": json-string, "data": json-value, |
128 | f544d174 | Luiz Capitulino | "timestamp": { "seconds": json-number, "microseconds": json-number } } |
129 | f544d174 | Luiz Capitulino | |
130 | f544d174 | Luiz Capitulino | Where, |
131 | f544d174 | Luiz Capitulino | |
132 | f544d174 | Luiz Capitulino | - The "event" member contains the event's name |
133 | f544d174 | Luiz Capitulino | - The "data" member contains event specific data, which is defined in a |
134 | f544d174 | Luiz Capitulino | per-event basis, it is optional |
135 | f544d174 | Luiz Capitulino | - The "timestamp" member contains the exact time of when the event ocurred |
136 | f544d174 | Luiz Capitulino | in the Server. It is a fixed json-object with time in seconds and |
137 | f544d174 | Luiz Capitulino | microseconds |
138 | f544d174 | Luiz Capitulino | |
139 | f544d174 | Luiz Capitulino | For a listing of supported asynchronous events, please, refer to the |
140 | f544d174 | Luiz Capitulino | qmp-events.txt file. |
141 | f544d174 | Luiz Capitulino | |
142 | f544d174 | Luiz Capitulino | 3. QMP Examples |
143 | f544d174 | Luiz Capitulino | =============== |
144 | f544d174 | Luiz Capitulino | |
145 | f544d174 | Luiz Capitulino | This section provides some examples of real QMP usage, in all of them |
146 | f544d174 | Luiz Capitulino | 'C' stands for 'Client' and 'S' stands for 'Server'. |
147 | f544d174 | Luiz Capitulino | |
148 | f544d174 | Luiz Capitulino | 3.1 Server greeting |
149 | f544d174 | Luiz Capitulino | ------------------- |
150 | f544d174 | Luiz Capitulino | |
151 | f544d174 | Luiz Capitulino | S: {"QMP": {"capabilities": []}} |
152 | f544d174 | Luiz Capitulino | |
153 | f544d174 | Luiz Capitulino | 3.2 Simple 'stop' execution |
154 | f544d174 | Luiz Capitulino | --------------------------- |
155 | f544d174 | Luiz Capitulino | |
156 | f544d174 | Luiz Capitulino | C: { "execute": "stop" } |
157 | f544d174 | Luiz Capitulino | S: {"return": "OK"} |
158 | f544d174 | Luiz Capitulino | |
159 | f544d174 | Luiz Capitulino | 3.3 KVM information |
160 | f544d174 | Luiz Capitulino | ------------------- |
161 | f544d174 | Luiz Capitulino | |
162 | f544d174 | Luiz Capitulino | C: {"execute": "query-kvm", "id": "example"} |
163 | f544d174 | Luiz Capitulino | S: {"return": "enabled", "id": "example"} |
164 | f544d174 | Luiz Capitulino | |
165 | f544d174 | Luiz Capitulino | 3.4 Parsing error |
166 | f544d174 | Luiz Capitulino | ------------------ |
167 | f544d174 | Luiz Capitulino | |
168 | f544d174 | Luiz Capitulino | C: { "execute": } |
169 | f544d174 | Luiz Capitulino | S: {"error": {"class": "JSONParsing", "data": {}}} |
170 | f544d174 | Luiz Capitulino | |
171 | f544d174 | Luiz Capitulino | 3.5 Powerdown event |
172 | f544d174 | Luiz Capitulino | ------------------- |
173 | f544d174 | Luiz Capitulino | |
174 | f544d174 | Luiz Capitulino | S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event": |
175 | f544d174 | Luiz Capitulino | "POWERDOWN"} |
176 | f544d174 | Luiz Capitulino | |
177 | f544d174 | Luiz Capitulino | 4. Notes to Client implementors |
178 | f544d174 | Luiz Capitulino | ------------------------------- |
179 | f544d174 | Luiz Capitulino | |
180 | f544d174 | Luiz Capitulino | 4.1 It is recommended to always start the Server in pause mode, thus the |
181 | f544d174 | Luiz Capitulino | Client is able to perform any setup procedure without the risk of |
182 | f544d174 | Luiz Capitulino | race conditions and related problems |
183 | f544d174 | Luiz Capitulino | |
184 | f544d174 | Luiz Capitulino | 4.2 It is recommended to always check the capabilities json-array, issued |
185 | f544d174 | Luiz Capitulino | with the greeting message, at connection time |
186 | f544d174 | Luiz Capitulino | |
187 | f544d174 | Luiz Capitulino | 4.3 Json-objects or json-arrays mentioned in this document are not fixed |
188 | f544d174 | Luiz Capitulino | and no particular size or number of members/elements should be assumed. |
189 | f544d174 | Luiz Capitulino | New members/elements can be added at any time. |
190 | f544d174 | Luiz Capitulino | |
191 | f544d174 | Luiz Capitulino | 4.4 No particular order of json-objects members should be assumed, they |
192 | f544d174 | Luiz Capitulino | can change at any time |