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

[Markus Armbruster]

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.


Markus Armbruster <address@hidden> 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.