From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NiEKC-0003rb-3V for qemu-devel@nongnu.org; Thu, 18 Feb 2010 16:54:20 -0500 Received: from [199.232.76.173] (port=57589 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NiEKB-0003qR-GO for qemu-devel@nongnu.org; Thu, 18 Feb 2010 16:54:19 -0500 Received: from Debian-exim by monty-python.gnu.org with spam-scanned (Exim 4.60) (envelope-from ) id 1NiEK9-0006th-Dn for qemu-devel@nongnu.org; Thu, 18 Feb 2010 16:54:19 -0500 Received: from ey-out-1920.google.com ([74.125.78.147]:48040) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1NiEK8-0006tZ-TO for qemu-devel@nongnu.org; Thu, 18 Feb 2010 16:54:17 -0500 Received: by ey-out-1920.google.com with SMTP id 3so1119239eyh.14 for ; Thu, 18 Feb 2010 13:54:14 -0800 (PST) Message-ID: <4B7DB6FC.7040900@codemonkey.ws> Date: Thu, 18 Feb 2010 15:54:04 -0600 From: Anthony Liguori MIME-Version: 1.0 Subject: Re: [Qemu-devel] [PATCH] QMP: Spec: Private Extensions support References: <20100218182458.07c3be6c@redhat.com> In-Reply-To: <20100218182458.07c3be6c@redhat.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Luiz Capitulino Cc: qemu-devel@nongnu.org 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 > --- > 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