[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Anthony Liguori
Subject: Re: [Qemu-devel] [PATCH] QMP: Spec: Private Extensions support
Date: Thu, 18 Feb 2010 15:54:04 -0600
User-agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv: Gecko/20091209 Fedora/3.0-4.fc12 Lightning/1.0pre Thunderbird/3.0

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

Signed-off-by: Luiz Capitulino<address@hidden>
  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:
+ Where,
+- NAME is any argument, command, event or parameter name
+- NAMESPACE is the namespace that NAME belongs to
+For example, the following command:
+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.


Anthony Liguori

reply via email to

[Prev in Thread] Current Thread [Next in Thread]