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

[Paolo Bonzini <pbonzini@redhat.com>]

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

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.


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

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