Patchwork [v2] QMP: Add "Downstream extension of QMP" to spec

login
register
mail settings
Submitter Markus Armbruster
Date May 10, 2010, 7:16 a.m.
Message ID <m3hbmg9qh6.fsf_-_@blackfin.pond.sub.org>
Download mbox | patch
Permalink /patch/52011/
State New
Headers show

Comments

Markus Armbruster - May 10, 2010, 7:16 a.m.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
v2: Clarify use of __RFQDN (Thanks, Luiz!)

 QMP/qmp-spec.txt |   55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 55 insertions(+), 0 deletions(-)
Luiz Capitulino - May 11, 2010, 8:01 p.m.
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.

Patch

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.