[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] Re: [PATCH v2] QMP: Add "Downstream extension of QMP" to sp
[Qemu-devel] Re: [PATCH v2] QMP: Add "Downstream extension of QMP" to spec
Tue, 11 May 2010 17:01:45 -0300
On Mon, 10 May 2010 09:16:05 +0200
Markus Armbruster <address@hidden> wrote:
> Signed-off-by: Markus Armbruster <address@hidden>
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
> +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.