Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]

[Markus Armbruster <armbru@redhat.com>]

Paolo Bonzini <pbonzini@redhat.com> writes:

> On 31/01/20 18:23, Markus Armbruster wrote:
>> Kashyap Chamarthy <kchamart@redhat.com> writes:
>> docs/devel/qapi-code-gen.txt has the same problem: it's mostly internal
>> stuff, but there's also introspection, which is an external interface.
>
> We should move introspection to docs/interop.  Any takers?
>
>>>     Rigorous support for introspection both of runtime objects and type
>>>     capabilities
>> 
>> For a value of "rigorous".
>> 
>> Let me propose QAPI's query-qmp-schema as the tin standard[*] of
>> introspection:
>> 
>> * It's documented
>> 
>> * It comes with something that can pass as a type system
>> 
>> * It actually tells you the full truth.
>
> Well, not all statements age equally well.  But compared to netdev_add 
> and device_add, it was still an improvement. :)

I think "rigorous" is to be read as ambition, not description.  Sadly,
QOM stagnated before getting close to realizing its ambitions.

> It's certainly worse than QAPI *now*, but it's not nonexistent:
>
>> * Documentation
>> 
>>   QAPI: docs/devel/qapi-code-gen.txt section "Client JSON Protocol
>>   introspection"
>> 
>>   QOM: Nada
>
> Well, there is qom.json.  So slightly more than nothing, though I have 
> already found an off-by-one error and it could definitely be improved:
>
>  @type: the type of the property.  This will typically come in one of four
>         forms:
>
>         1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
>            These types are mapped to the appropriate JSON type.
>
>         2) A child type in the form 'child<subtype>' where subtype is a qdev
>            device type name.  Child properties create the composition tree.
>
>         3) A link type in the form 'link<subtype>' where subtype is a qdev
>            device type name.  Link properties form the device model graph.

If the off-by-one you found is "four forms" followed by a list of three,
then the error isn't "four", it's the omitted fourth list item.

Anyway, I grant you "nada" was an exaggeration for effect.

Note that the doc comments are reference documentation.  QAPI got that,
too.  Reference documentation is useful, but no replacement for an
explainer like qapi-code-gen.txt.

>> * Type system
>> 
>>   QAPI: A few built-in types specified in the documentation, type
>>   constructors for complex types.
>> 
>>   QOM: Types are strings, and you just need to know what they mean.
>>   Some string patterns are special: link<STR>, child<STR>, STR[INT], and
>>   you just need to know what that means, too.
>
> str[int] is not a type as far as I understood it, it's a property name.  

You're right.

> Types are documented as above; however types other than link<> and 
> child<>, which are QAPI types, can be user-defined types (structs, 
> enums) and this is not included in (1).

Specifically, three of four kinds of type names are documented:
primitive, child, scalar.  The fourth kind is not, and it can be
anything.  It need not be a QAPI type name.  In any case, you just have
to know what the type name means.

In contrast, QAPI introspection defines all types in terms of type
constructors and primitive types.  It completely hides user-defined QAPI
type names, so they don't become ABI.

Do you think we could somehow appropriate QAPI's type system for QOM
introspection?

>> * Full truth
>> 
>>   QAPI: If you can access it at the interface, you can also see it in
>>   introspection.
>> 
>>   QOM: Type introspection can show you only the properties of a freshly
>>   created object.  Properties that get created only later are invisible.
>>   Properties that depend on global state are unreliable.  Object
>>   introspection is reliable, but only for that object in its current
>>   state.
>
> Right, that's array properties and at least theoretically child 
> properties (I don't know if there are examples).
>
> Paolo