Archipelago » qemu

6. Downstream extension of QMP

------------------------------

We recommend that downstream consumers of QEMU do *not* modify QMP.

Management tools should be able to support both upstream and downstream

versions of QMP without special logic, and downstream extensions are

inherently at odds with that.

However, we recognize that it is sometimes impossible for downstreams to

avoid modifying QMP.  Both upstream and downstream need to take care to

preserve long-term compatibility and interoperability.

To help with that, QMP reserves JSON object member names beginning with

'__' (double underscore) for downstream use ("downstream names").  This

means upstream will never use any downstream names for its commands,

arguments, errors, asynchronous events, and so forth.

Any new names downstream wishes to add must begin with '__'.  To

ensure compatibility with other downstreams, it is strongly

recommended that you prefix your downstram names with '__RFQDN_' where

RFQDN is a valid, reverse fully qualified domain name which you

control.  For example, a qemu-kvm specific monitor command would be:

    (qemu) __org.linux-kvm_enable_irqchip

Downstream must not change the server greeting (section 2.2) other than

to offer additional capabilities.  But see below for why even that is

discouraged.

Section '5 Compatibility Considerations' applies to downstream as well

as to upstream, obviously.  It follows that downstream must behave

exactly like upstream for any input not containing members with

downstream names ("downstream members"), except it may add members

with downstream names to its output.

Thus, a client should not be able to distinguish downstream from

upstream as long as it doesn't send input with downstream members, and

properly ignores any downstream members in the output it receives.

Advice on downstream modifications:

1. Introducing new commands is okay.  If you want to extend an existing

   command, consider introducing a new one with the new behaviour

   instead.

2. Introducing new asynchronous messages is okay.  If you want to extend

   an existing message, consider adding a new one instead.

3. Introducing new errors for use in new commands is okay.  Adding new

   errors to existing commands counts as extension, so 1. applies.

4. New capabilities are strongly discouraged.  Capabilities are for

   evolving the basic protocol, and multiple diverging basic protocol

   dialects are most undesirable.