docs/qmp/qmp-spec.txt

   1                       QEMU Machine Protocol Specification
   2
   3 1. Introduction
   4 ===============
   5
   6 This document specifies the QEMU Machine Protocol (QMP), a JSON-based protocol
   7 which is available for applications to operate QEMU at the machine-level.
   8
   9 2. Protocol Specification
  10 =========================
  11
  12 This section details the protocol format. For the purpose of this document
  13 "Client" is any application which is using QMP to communicate with QEMU and
  14 "Server" is QEMU itself.
  15
  16 JSON data structures, when mentioned in this document, are always in the
  17 following format:
  18
  19     json-DATA-STRUCTURE-NAME
  20
  21 Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by
  22 the JSON standard:
  23
  24 http://www.ietf.org/rfc/rfc4627.txt
  25
  26 For convenience, json-object members and json-array elements mentioned in
  27 this document will be in a certain order. However, in real protocol usage
  28 they can be in ANY order, thus no particular order should be assumed.
  29
  30 2.1 General Definitions
  31 -----------------------
  32
  33 2.1.1 All interactions transmitted by the Server are json-objects, always
  34       terminating with CRLF
  35
  36 2.1.2 All json-objects members are mandatory when not specified otherwise
  37
  38 2.2 Server Greeting
  39 -------------------
  40
  41 Right when connected the Server will issue a greeting message, which signals
  42 that the connection has been successfully established and that the Server is
  43 ready for capabilities negotiation (for more information refer to section
  44 '4. Capabilities Negotiation').
  45
  46 The greeting message format is:
  47
  48 { "QMP": { "version": json-object, "capabilities": json-array } }
  49
  50  Where,
  51
  52 - The "version" member contains the Server's version information (the format
  53   is the same of the query-version command)
  54 - The "capabilities" member specify the availability of features beyond the
  55   baseline specification
  56
  57 2.3 Issuing Commands
  58 --------------------
  59
  60 The format for command execution is:
  61
  62 { "execute": json-string, "arguments": json-object, "id": json-value }
  63
  64  Where,
  65
  66 - The "execute" member identifies the command to be executed by the Server
  67 - The "arguments" member is used to pass any arguments required for the
  68   execution of the command, it is optional when no arguments are required
  69 - The "id" member is a transaction identification associated with the
  70   command execution, it is optional and will be part of the response if
  71   provided
  72
  73 2.4 Commands Responses
  74 ----------------------
  75
  76 There are two possible responses which the Server will issue as the result
  77 of a command execution: success or error.
  78
  79 2.4.1 success
  80 -------------
  81
  82 The format of a success response is:
  83
  84 { "return": json-object, "id": json-value }
  85
  86  Where,
  87
  88 - The "return" member contains the command returned data, which is defined
  89   in a per-command basis or an empty json-object if the command does not
  90   return data
  91 - The "id" member contains the transaction identification associated
  92   with the command execution if issued by the Client
  93
  94 2.4.2 error
  95 -----------
  96
  97 The format of an error response is:
  98
  99 { "error": { "class": json-string, "desc": json-string }, "id": json-value }
 100
 101  Where,
 102
 103 - The "class" member contains the error class name (eg. "GenericError")
 104 - The "desc" member is a human-readable error message. Clients should
 105   not attempt to parse this message.
 106 - The "id" member contains the transaction identification associated with
 107   the command execution if issued by the Client
 108
 109 NOTE: Some errors can occur before the Server is able to read the "id" member,
 110 in these cases the "id" member will not be part of the error response, even
 111 if provided by the client.
 112
 113 2.5 Asynchronous events
 114 -----------------------
 115
 116 As a result of state changes, the Server may send messages unilaterally
 117 to the Client at any time. They are called "asynchronous events".
 118
 119 The format of asynchronous events is:
 120
 121 { "event": json-string, "data": json-object,
 122   "timestamp": { "seconds": json-number, "microseconds": json-number } }
 123
 124  Where,
 125
 126 - The "event" member contains the event's name
 127 - The "data" member contains event specific data, which is defined in a
 128   per-event basis, it is optional
 129 - The "timestamp" member contains the exact time of when the event occurred
 130   in the Server. It is a fixed json-object with time in seconds and
 131   microseconds
 132
 133 For a listing of supported asynchronous events, please, refer to the
 134 qmp-events.txt file.
 135
 136 3. QMP Examples
 137 ===============
 138
 139 This section provides some examples of real QMP usage, in all of them
 140 "C" stands for "Client" and "S" stands for "Server".
 141
 142 3.1 Server greeting
 143 -------------------
 144
 145 S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 },
 146      "package": ""}, "capabilities": []}}
 147
 148 3.2 Simple 'stop' execution
 149 ---------------------------
 150
 151 C: { "execute": "stop" }
 152 S: { "return": {} }
 153
 154 3.3 KVM information
 155 -------------------
 156
 157 C: { "execute": "query-kvm", "id": "example" }
 158 S: { "return": { "enabled": true, "present": true }, "id": "example"}
 159
 160 3.4 Parsing error
 161 ------------------
 162
 163 C: { "execute": }
 164 S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
 165
 166 3.5 Powerdown event
 167 -------------------
 168
 169 S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
 170     "event": "POWERDOWN" }
 171
 172 4. Capabilities Negotiation
 173 ----------------------------
 174
 175 When a Client successfully establishes a connection, the Server is in
 176 Capabilities Negotiation mode.
 177
 178 In this mode only the qmp_capabilities command is allowed to run, all
 179 other commands will return the CommandNotFound error. Asynchronous
 180 messages are not delivered either.
 181
 182 Clients should use the qmp_capabilities command to enable capabilities
 183 advertised in the Server's greeting (section '2.2 Server Greeting') they
 184 support.
 185
 186 When the qmp_capabilities command is issued, and if it does not return an
 187 error, the Server enters in Command mode where capabilities changes take
 188 effect, all commands (except qmp_capabilities) are allowed and asynchronous
 189 messages are delivered.
 190
 191 5 Compatibility Considerations
 192 ------------------------------
 193
 194 All protocol changes or new features which modify the protocol format in an
 195 incompatible way are disabled by default and will be advertised by the
 196 capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
 197 that array and enable the capabilities they support.
 198
 199 The QMP Server performs a type check on the arguments to a command.  It
 200 generates an error if a value does not have the expected type for its
 201 key, or if it does not understand a key that the Client included.  The
 202 strictness of the Server catches wrong assumptions of Clients about
 203 the Server's schema.  Clients can assume that, when such validation
 204 errors occur, they will be reported before the command generated any
 205 side effect.
 206
 207 However, Clients must not assume any particular:
 208
 209 - Length of json-arrays
 210 - Size of json-objects; in particular, future versions of QEMU may add
 211   new keys and Clients should be able to ignore them.
 212 - Order of json-object members or json-array elements
 213 - Amount of errors generated by a command, that is, new errors can be added
 214   to any existing command in newer versions of the Server
 215
 216 Of course, the Server does guarantee to send valid JSON.  But apart from
 217 this, a Client should be "conservative in what they send, and liberal in
 218 what they accept".
 219
 220 6. Downstream extension of QMP
 221 ------------------------------
 222
 223 We recommend that downstream consumers of QEMU do *not* modify QMP.
 224 Management tools should be able to support both upstream and downstream
 225 versions of QMP without special logic, and downstream extensions are
 226 inherently at odds with that.
 227
 228 However, we recognize that it is sometimes impossible for downstreams to
 229 avoid modifying QMP.  Both upstream and downstream need to take care to
 230 preserve long-term compatibility and interoperability.
 231
 232 To help with that, QMP reserves JSON object member names beginning with
 233 '__' (double underscore) for downstream use ("downstream names").  This
 234 means upstream will never use any downstream names for its commands,
 235 arguments, errors, asynchronous events, and so forth.
 236
 237 Any new names downstream wishes to add must begin with '__'.  To
 238 ensure compatibility with other downstreams, it is strongly
 239 recommended that you prefix your downstream names with '__RFQDN_' where
 240 RFQDN is a valid, reverse fully qualified domain name which you
 241 control.  For example, a qemu-kvm specific monitor command would be:
 242
 243     (qemu) __org.linux-kvm_enable_irqchip
 244
 245 Downstream must not change the server greeting (section 2.2) other than
 246 to offer additional capabilities.  But see below for why even that is
 247 discouraged.
 248
 249 Section '5 Compatibility Considerations' applies to downstream as well
 250 as to upstream, obviously.  It follows that downstream must behave
 251 exactly like upstream for any input not containing members with
 252 downstream names ("downstream members"), except it may add members
 253 with downstream names to its output.
 254
 255 Thus, a client should not be able to distinguish downstream from
 256 upstream as long as it doesn't send input with downstream members, and
 257 properly ignores any downstream members in the output it receives.
 258
 259 Advice on downstream modifications:
 260
 261 1. Introducing new commands is okay.  If you want to extend an existing
 262    command, consider introducing a new one with the new behaviour
 263    instead.
 264
 265 2. Introducing new asynchronous messages is okay.  If you want to extend
 266    an existing message, consider adding a new one instead.
 267
 268 3. Introducing new errors for use in new commands is okay.  Adding new
 269    errors to existing commands counts as extension, so 1. applies.
 270
 271 4. New capabilities are strongly discouraged.  Capabilities are for
 272    evolving the basic protocol, and multiple diverging basic protocol
 273    dialects are most undesirable.