[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Improving QOM documentation [Was: Re: Making QEMU easier for managem
From: |
Paolo Bonzini |
Subject: |
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications] |
Date: |
Mon, 3 Feb 2020 09:56:24 +0100 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.1.1 |
On 31/01/20 18:23, Markus Armbruster wrote:
> Kashyap Chamarthy <address@hidden> 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
- Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications],
Paolo Bonzini <=