[Qemu-devel] Re: [PATCH v2] QMP: Add "Downstream extension of QMP" to spec

[Luiz Capitulino <lcapitulino@redhat.com>]

On Mon, 10 May 2010 09:16:05 +0200
Markus Armbruster <armbru@redhat.com> wrote:

> Signed-off-by: Markus Armbruster <armbru@redhat.com>

 Looks good to me.

> ---
> v2: Clarify use of __RFQDN (Thanks, Luiz!)
> 
>  QMP/qmp-spec.txt |   55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 55 insertions(+), 0 deletions(-)
> 
> diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
> index f3c0327..9d30a8c 100644
> --- a/QMP/qmp-spec.txt
> +++ b/QMP/qmp-spec.txt
> @@ -215,3 +215,58 @@ Additionally, Clients must not assume any particular:
>  - Order of json-object members or json-array elements
>  - Amount of errors generated by a command, that is, new errors can be added
>    to any existing command in newer versions of the Server
> +
> +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.