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

[Markus Armbruster]

Anthony Liguori <address@hidden> writes:

> We need a bit more than just this.  Here's my suggestion:

I think this is much more restrictive than necessary.  Unnecessarily
restrictive rules are more likely to be ignored, and we don't want that.
Details below.

> 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

Bad line break.

> to attempt to preserve long term compatibility and interoperability.

Better move your items 5-6) here, and make them talk about "names", not
just commands.  Items 1-4) make much more sense with the name space
issue settled.

> 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.

Extending an existing command in a compatible way should be fine.  An
extension is "compatible" if

1. it adds only optional arguments, and

2. it behaves differently only when new optional arguments are supplied.

> 2) Only introduce new asynchronous messages.  Do not change an
> existing message.

Why outlaw adding new data members?  What would that break?

> 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.

A client that can't cope with unknown error types will only ever work on
a single upstream version.  Such clients will go the way of the Dodo
real quick.

With that established: why is adding new error types bad?

> 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.

This is factually incorrect.  Clients that don't recognize new
capabilities just ignore them, and continue to work as before.

The *point* of having capabilities is to permit protocol evolution
without breaking clients.  Why reserve evolution privileges to upstream?
Yes, downstream should probably think twice before mucking with the
basic protocol.  But we should not attempt to stop downstreams from
doing stupid things, as that would also stop them from doing clever
things.

> 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.