Re: ObjectPropertyInfo design

[Markus Armbruster <armbru@redhat.com>]

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Thu, Oct 22, 2026 at 04:04:44PM +0200, Markus Armbruster wrote:
>> Marc-André's series evolves ObjectPropertyInfo and ObjectPropertyValue:
>> it adds member @qapi-type and changes many values of member @type.
>> 
>> I'd like to take a step back and discuss design.  I trimmed Cc:
>> accordingly.
>> 
>> 
>> = The current interface
>> 
>> qom-list returns information on an object's properties, one
>> ObjectPropertyInfo per property.
>> 
>> qom-list-properties returns information on properties an instance of a
>> type is known to have[*], one ObjectPropertyInfo per property.
>
> This is 

Yes?

>> qom-list-get returns information on the properties of several objects,
>> one ObjectPropertyValue per property.
>
> Since 'qom-list-properties' is really introspecting types, rather
> than instances, I'd add its companion:
>
>   query-qmp-schema  returns information on properties from
>   user creatable QOM objects, via the ObjectOptions union
>   which handles data of arbitary complexity and nesting,
>   with strictly QAPI types only. Obviously missing QDev
>   and other internal only types.

Yes.  Ideally, it would cover everything, but QOM's design and the sheer
amount of QOM types and properties has kept that well out of reach.  QOM
introspection filled the gap, but badly.  Marc-André's work makes it
less bad.

>> * @description is rarely present (I see under 15% in a quick test).  The
>>   description text is commonly misleading for QMP.  For instance, qdev
>>   bool properties have description "on/off".  The possible values are
>>   actually JSON false and true.
>
> With query-qmp-schema  we have a description for 100% of properties,
> enforced by the QAPI schema parser. Only applies to UserCreatable QOM
> objects though.

Yes.

QAPI schema doc comments are mandatory, and they get validated against
the schema code.  They become the "QEMU QMP Reference Manual".

QOM property description strings are optional, and they are not checked
in any way.  They are used in help intended for humans.

> I see descriptions as primarily a documentation thing for humans, and
> perhaps for machines which are trying to generate code frmo QAPI
> schema and want to use descriptions for docs. These are both static
> querying tasks.
>
> I don't see descriptions as useful for mgmt apps at runtime for
> deployed QEMus.

Noted.

>> * @default-value can be useful with qom-list-properties, which operates
>>   on types.  I doubt it is with qom-list, which operates on objects.
>
> Likewise, IMHO this is useful info statically, but not at runtime.

Noted.

>> Let's pretend @description doesn't exist, and @default-value exists only
>> with qom-list-properties.
>> 
>> This makes qom-list-get strictly more powerful than qom-list, so let's
>> further pretend qom-list doesn't exist.
>> 
>> 
>> = Simplified interface for the sake of discussion
>> 
>> qom-list-properties returns information on properties an instance of a
>> type is known to have[*]: @name, @type, and maybe @default-value.
>
> In the ideal world 'qom-list-properties' would not need to exist,
> but it has to for the forseeable future, since none of QDev is
> modelled in QAPI schema currently. 

Yes.

>> qom-list-get returns information on the properties of several objects:
>> @name, @type, and maybe @value.
>> 
>> 
>> = The meaning of @type
>> 
>> Three cases:
>> 
>> 1. For a child property (created with object_property_add_child() etc.),
>>    @type is "child<T>", where T is the child's QOM type.
>> 
>> 2. For a link property (created with object_class_property_add_link()
>>    etc.), @type is "link<T>", where T is the target's QOM type.
>> 
>> 3. For other properties, @type can be anything.  We commonly use QAPI
>>    type names (occasionally misspelled), and also "well-known" (but
>>    undocumented) non-QAPI names for primitive types.  Every now and
>>    then, developers get lazy and use values like "list", or creative and
>>    use values like "guest statistics".  Nobody has gotten sufficiently
>>    masochistic to use values starting with "child<" or "link<" so far,
>>    although nothing would stop that.
>> 
>> Cases 1 and 2 go against the QAPI/QMP design maxim "don't encode stuff
>> in strings".
>
> They're not particular nice internally either as part of QDev/QOM.
> ie this is gross as a design approach:
>
>   static inline bool object_property_is_child(ObjectProperty *prop)
>   {
>     return strstart(prop->type, "child<", NULL);
>   }

I can top that!

    /* Go from link<FOO> to FOO.  */
    type = object_property_get_type(obj, name, NULL);
    target_type = g_strndup(&type[5], strlen(type) - 6);

>> Case 3 is is hard to use for anything.  You're forced into stupid and
>> brittle hardcoding.
>> 
>> Marc-André's work adds a new optional member @qapi_type that refers to a
>> QAPI type in the output of query-qmp-schema.  It's present for a large
>> subset of case 3.  When it's present, @type should not be used.
>> 
>> It also cleans up many crap cases of 3, but without making it robust.  I
>> understand this isn't something the series tries to do, it's just
>> something that's easier to do than not to do.  If it creates
>> compatibility problems, we have to not do it.  I hope it doesn't.
>> 
>> 
>> = Can we do better?
>> 
>> What information are we trying to convey?  Four cases:
>> 
>> 1. Child property: the child's QOM type
>> 
>> 2. Link property: the target's QOM type
>> 
>> 3. QAPI-backed property: the property's QAPI type
>> 
>> 4. Other property: we have nothing useful to offer
>> 
>> Case 4 should go away eventually.
>> 
>> How would we encode this in QAPI on a green field?  With a union, of
>> course:
>> 
>>     { 'enum': 'ObjectPropertyKind',
>>       'data': [ 'child', 'link', 'qapi', 'other'] }
>> 
>>     { 'struct': 'ObjectPropertyInfoLink',
>>       'data': { 'qom-type': 'str' } }
>> 
>>     { 'struct': 'ObjectPropertyInfoQAPI',
>>       'data': { 'qapi-type': 'str' } }
>> 
>>     { 'union': 'ObjectProperty...',
>>       'base': { 'kind': 'ObjectPropertyKind',
>>                 ... more ... },
>>       'discriminator': 'kind',
>>       'data': {
>>           'child': 'ObjectPropertyInfoLink',
>>           'link': 'ObjectPropertyInfoLink',
>>           'qapi': 'ObjectPropertyInfoQAPI' } }
>> 
>> To make this a compatible evolution of ObjectPropertyInfo, we need
>> ... more ... to be
>> 
>>                 'type': 'str',
>>                 '*description': 'str'
>>                 '*default-value': 'any',
>> 
>> Sadly, we need to duplicate the union for ObjectPropertyValue.  There,
>> ... more ... needs to be
>> 
>>                 'type': 'str',
>>                 '*value': 'any'
>> 
>> We should deprecate @type.  I'd also deprecate @description.
>> 
>> Thoughts?
>
> We currently have
>
>   { 'enum': 'ObjectType', .... }
>
> which provides a name in QMP schema for every QOM type that
> implements UserCreatable.
>
> We could relatively easily  extend that to cover *all* QOM
> types in existance, with some judicous grepping of TypeInfo
> classes.
>
> It would be nice if we could enforce at runtime though that
> anything passed to type_register() was listed in 'ObjectType'
> enum to catch omissions. Not sure if there are any unexpected
> dragons if we make type_register() check the type name
> against  'ObjectType_lookup' from qapi-types-qom.h ?

Can't see why that wouldn't work.

We use strings instead of a C enum for type names, because a C enum
would be conflict magnet, and also a "recompile the world" header.

Strings weaken the type checker, and also risk typos.  The #define
TYPE_FOO "foo" reduce that risk.  Since we don't always use them, we
always have to grep both for TYPE_FOO and "foo".

If we enumerate all the type names in a QAPI enum, we generate such a C
enum, but use it only to check the strings.  Still a conflict magnet,
but at least not a "recompile the world" header.

> Then your
>
>>     { 'struct': 'ObjectPropertyInfoLink',
>>       'data': { 'qom-type': 'str' } }
>
> could at least reference 'ObjectType' instead of 'str'

Yes.  There are a few more, e.g. CompatProperty member @qom-type.

>                                                        and be
> aligned more with query-qmp-schema.

What do you mean by that?