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
>
> 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.
> * @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.
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.
> * @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.
> 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.
> 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);
}
> 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 ?
Then your
> { 'struct': 'ObjectPropertyInfoLink',
> 'data': { 'qom-type': 'str' } }
could at least reference 'ObjectType' instead of 'str' and be
aligned more with query-qmp-schema.
With regards,
Daniel
--
|: https://berrange.com ~~ https://hachyderm.io/@berrange :|
|: https://libvirt.org ~~ https://entangle-photo.org :|
|: https://pixelfed.art/berrange ~~ https://fstop138.berrange.com :|
