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

[Anthony Liguori <anthony@codemonkey.ws>]

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<armbru@redhat.com>  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.
>>