Re: [Qemu-devel] What's our ABI promise for externally visible QOM?

["Daniel P. Berrangé" <berrange@redhat.com>]

On Fri, Nov 30, 2018 at 07:59:59AM +0100, Markus Armbruster wrote:
> QOM types and the QOM graph are externally visible:
> 
> * qom-list-types returns QOM type names and parents.
> 
>   Fine print: the result is limited to concrete types by default.
>   Aside: that's the only way to figure out whether a type is abstract.
>   Interface design fail.  The result can optionally be limited to
>   sub-types of a certain type.
> 
> * qom-list-properties returns a named type's static properties.
> 
> * qom-list returns an object's properties.  This lets clients traverse
>   the QOM graph.
> 
> * qom-get returns a property's value.
> 
> * qom-set changes a property's value.
> 
> * -object and object-add create a QOM object of a certain type with
>   certain property values.  The type must be a sub-type of
>   "user-creatable".
> 
> * Types are identified by name.
> 
> * Objects and properties are identified by QOM path.  An absolute QOM
>   paths is the path within the composition tree starting at the root.
>   Partial paths are a convenience you don't want to understand.
> 
> What promises do we make regarding the stability  / backward
> compatibility of these externally visible entities?
> 
> The QMP command documentation is silent on it.  A user could reasonably
> assume that the general QMP stability promise extends to all of QOM.
> Does it?

Since we've never declared this, perhaps we need to turn it around and
ask what aspects are current users of QMP relying on to be stable ?

If we expect the values passed to CLI args to be stable, then we have
to say that type names and property names that can be given to -device
and -object have an implied stability promise. This would cover any
type which implements the 'user-creatable' interface IIUC.

The qom-list-properties / qom-list commands return both property names
and property types. Apps reasonably expect the property names to be
stable since that's how they determine if the feature exists.

The type names listed here are questionable though. The names we give
to property types are surprisingly adhoc once you get awya from the
basic scalar types.

eg qom-list path=/machine shows some really questionable type names

 - struct tm
 - OnOffAuto
 - on|off|split


I think I'd say that non-user-creatable typenames for objects which
are not devices are considerd unstable. They're not usable with
-object and so should only be exposed to internal code, never QMP
or CLI.

Non-user-creatable typenames for devices though are trickier, as
they are exposed to the CLI via -global, so that effectively makes
them a public API.

CPU type names were historically internal only, but with the
query-cpu-definitions command, these type names are now exposed
to apps.  We could possibly claim the typenames are non-stable
as we'd expect apps to use the CPU model name instead ?

> Was that the intent when we created qom-list, qom-set, qom-get?
> Andreas, do you remember?
> 
> Is it practical given the current state of affairs?
> 
> Is it a good idea?

Keeping as much private as possible is obviously desirable, but
in most areas it looks like the horse has bolted given the combo
of -global, -device and -object, together with many QMP commands.

We could perhaps make some targetted efforts to declare certain
things unstable (CPU type names, object property type names).

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|