From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1OA5CW-0000z0-TK for qemu-devel@nongnu.org; Thu, 06 May 2010 13:49:33 -0400 Received: from [140.186.70.92] (port=49792 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OA5CS-0000wt-Ii for qemu-devel@nongnu.org; Thu, 06 May 2010 13:49:32 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OA5CK-0007im-EP for qemu-devel@nongnu.org; Thu, 06 May 2010 13:49:27 -0400 Received: from mail-pv0-f173.google.com ([74.125.83.173]:64254) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OA5CK-0007iT-5e for qemu-devel@nongnu.org; Thu, 06 May 2010 13:49:20 -0400 Received: by pvg11 with SMTP id 11so97141pvg.4 for ; Thu, 06 May 2010 10:49:19 -0700 (PDT) Message-ID: <4BE3011B.7040001@codemonkey.ws> Date: Thu, 06 May 2010 12:49:15 -0500 From: Anthony Liguori MIME-Version: 1.0 Subject: Re: [Qemu-devel] [PATCH] QMP: Spec: Private Extensions support References: <20100218182458.07c3be6c@redhat.com> <4B7DB6FC.7040900@codemonkey.ws> In-Reply-To: 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: Markus Armbruster Cc: qemu-devel@nongnu.org, Luiz Capitulino On 05/06/2010 10:52 AM, Markus Armbruster wrote: > Anthony, no reply from you; did it fall through the cracks? If you're > fine with my draft, I'll turn it into a proper patch. > Yes, sorry, I thought I had already responded as such. Regards, Anthony Liguori > Markus Armbruster writes: > > >> Anthony asked me to take a stab at rewriting his draft to something more >> along the lines of what I'm thinking. Here goes. I put some remarks >> [in brackets]. >> >> FYI, I'll be out of town until Wednesday. >> >> >> 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 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 >> >> 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. [That section needs work!] 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. >> >> [I fully support everything up to this point. I have some reservations >> on the rest, and I doubt it'll be all that useful, but I don't really >> mind having it, at least not in this form.] >> >> Advice on downstream modifications: >> [I made a honest effort at capturing Anthony's intentions here, >> my apologies if I screwed it up.] >> >> 1. Introducing new commands is okay. If you want to extend an existing >> command, consider introducing a new one with the new behaviour >> instead. [FIXME Could use a rationale: why is extending bad? Make >> sure to cover errors, because that's needed for 3.] >> >> 2. Introducing new asynchronous messages is okay. If you want to extend >> an existing message, consider adding a new one instead. [FIXME Could >> use a rationale: why is extending bad?] >> >> 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. >>