Re: [Qemu-devel] [PATCH] QMP: Spec: Private Extensions support

[Anthony Liguori <anthony@codemonkey.ws>]

On 02/18/2010 02:24 PM, Luiz Capitulino wrote:
> Vendors might want to add their own extensions to QMP, as JSON itself
> (and several other protocols) allow this someway, I think QMP should
> allow too.
>
> We just have to choose a naming convention that is guaranteed not to
> clash with any future new commands, arguments, parameters and event
> names.
>
> Signed-off-by: Luiz Capitulino<lcapitulino@redhat.com>
> ---
>   QMP/qmp-spec.txt |   23 +++++++++++++++++++++++
>   1 files changed, 23 insertions(+), 0 deletions(-)
>
> diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
> index f3c0327..bc92c7e 100644
> --- a/QMP/qmp-spec.txt
> +++ b/QMP/qmp-spec.txt
> @@ -215,3 +215,26 @@ 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 Private Extensions
> +--------------------
> +
> +QMP provides a special naming convention to allow the creation of independent
> +namespaces, which allows vendors to introduce private extensions to the
> +protocol. It is guaranteed that no future QMP version will expose any name
> +that follows this convention.
> +
> +Private extensions must be in the following format:
> +
> +v_NAMESPACE__NAME
> +
> + Where,
> +
> +- NAME is any argument, command, event or parameter name
> +- NAMESPACE is the namespace that NAME belongs to
> +
> +For example, the following command:
> +
> +v_ABC__insert
> +
> +Is called 'insert' and is part of the 'ABC' namespace.
>    

We need a bit more than just this.  Here's my suggestion:

6. Downstream modification of QMP
-----------------------------------------------------------

We strongly recommend that downstream consumers of QEMU do _not_
modify the behaviour of any QMP command or introduce new QMP commands.
This is important to allow management tools to support both upstream and
downstream versions of QMP without special logic.

However, we recognize that it is sometimes impossible for downstreams to
avoid modifying QMP.  If this happens, the following rules should be 
observed
to attempt to preserve long term compatibility and interoperability.

1) Only introduce new commands.  If you want to change an existing command,
leave the old command in place and introduce a new one with the new 
behaviour.

2) Only introduce new asynchronous messages.  Do not change an existing 
message.

3) Only introduce new error types and only use those error types in new 
commands.
New commands can use existing error types, but you should never add a 
new error type
to an existing command.

4) Do not introduce any new capabilities.  Capabilities directly affect 
a client's ability to
parse the protocol correctly and new capabilities can not be supported 
in an upstream
compatible way.  Please work capabilities through upstream first.

5) QMP names will never begin with '__' (double underscore).  When 
introducing new
commands, asynchronous events, or error messages, a downstream must 
prefix those
names with a '__' to ensure future compatibility with upstream.

6) To ensure compatibility with other downstreams, it is strongly 
recommended that
you prefix the commands 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

7) Do not change the QMP banner.  QMP supports introspection which will 
allow a
management tool to differentiate between a downstream QMP session and an
upstream QMP session.

Regards,

Anthony Liguori