Revision b3e5e3e6

b/QMP/qmp-spec.txt
215 215
- Order of json-object members or json-array elements
216 216
- Amount of errors generated by a command, that is, new errors can be added
217 217
  to any existing command in newer versions of the Server
218

  
219
6. Downstream extension of QMP
220
------------------------------
221

  
222
We recommend that downstream consumers of QEMU do *not* modify QMP.
223
Management tools should be able to support both upstream and downstream
224
versions of QMP without special logic, and downstream extensions are
225
inherently at odds with that.
226

  
227
However, we recognize that it is sometimes impossible for downstreams to
228
avoid modifying QMP.  Both upstream and downstream need to take care to
229
preserve long-term compatibility and interoperability.
230

  
231
To help with that, QMP reserves JSON object member names beginning with
232
'__' (double underscore) for downstream use ("downstream names").  This
233
means upstream will never use any downstream names for its commands,
234
arguments, errors, asynchronous events, and so forth.
235

  
236
Any new names downstream wishes to add must begin with '__'.  To
237
ensure compatibility with other downstreams, it is strongly
238
recommended that you prefix your downstram names with '__RFQDN_' where
239
RFQDN is a valid, reverse fully qualified domain name which you
240
control.  For example, a qemu-kvm specific monitor command would be:
241

  
242
    (qemu) __org.linux-kvm_enable_irqchip
243

  
244
Downstream must not change the server greeting (section 2.2) other than
245
to offer additional capabilities.  But see below for why even that is
246
discouraged.
247

  
248
Section '5 Compatibility Considerations' applies to downstream as well
249
as to upstream, obviously.  It follows that downstream must behave
250
exactly like upstream for any input not containing members with
251
downstream names ("downstream members"), except it may add members
252
with downstream names to its output.
253

  
254
Thus, a client should not be able to distinguish downstream from
255
upstream as long as it doesn't send input with downstream members, and
256
properly ignores any downstream members in the output it receives.
257

  
258
Advice on downstream modifications:
259

  
260
1. Introducing new commands is okay.  If you want to extend an existing
261
   command, consider introducing a new one with the new behaviour
262
   instead.
263

  
264
2. Introducing new asynchronous messages is okay.  If you want to extend
265
   an existing message, consider adding a new one instead.
266

  
267
3. Introducing new errors for use in new commands is okay.  Adding new
268
   errors to existing commands counts as extension, so 1. applies.
269

  
270
4. New capabilities are strongly discouraged.  Capabilities are for
271
   evolving the basic protocol, and multiple diverging basic protocol
272
   dialects are most undesirable.

Also available in: Unified diff