Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
Paolo Bonzini writes: > On 03/02/20 10:54, Markus Armbruster wrote: >>> 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. > > It is not enforced, but it is supposed to be only QAPI type names > (primitive or not), child or link. It's not even documented. Actual names include "struct tm", "guest statistics", and (my favourite) "struct".
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
On 03/02/20 10:54, Markus Armbruster wrote: >> 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. It is not enforced, but it is supposed to be only QAPI type names (primitive or not), child or link. Paolo
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
Paolo Bonzini writes: > On 31/01/20 18:23, Markus Armbruster wrote: >> Kashyap Chamarthy 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' where subtype is a qdev >device type name. Child properties create the composition tree. > > 3) A link type in the form 'link' 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, child, 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
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
On 31/01/20 18:23, Markus Armbruster wrote: > Kashyap Chamarthy 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' where subtype is a qdev device type name. Child properties create the composition tree. 3) A link type in the form 'link' 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, child, 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]
Kashyap Chamarthy writes: > On Fri, Jan 31, 2020 at 12:02:05PM +0100, Paolo Bonzini wrote: >> Il ven 31 gen 2020, 11:36 Peter Maydell ha >> scritto: > > [...] > >> The advantage of putting them in the header is that you have them all in >> one place (inline functions and structs must be in the header). In practice >> that balances for me the disadvantage of having some comments far from the >> code they document, which increases the risk of bitrot especially for >> comments such as "called with lock X held". >> >> I definitely agree that the overview/introduction/conventions >> > side of things is where we'd benefit most if somebody wanted >> > to try to tackle that. We could roll >> > https://wiki.qemu.org/Documentation/QOMConventions >> > into that if we had a better place to put that info. >> > >> >> I am travelling this weekend so I might try to do some kind of thread >> summary and brain dump in the wiki. I'll leave to Kashyap to do the rST >> conversion and patch submission. ;-) > > Thanks! Happy to be the 'scribe' ;-) I have a skeltal > qemu-object-model.rst file sitting with some initial content based on > various sources, including one of your presentations[*] from 2014. > I'll wait for your new Wiki link to incorporate that content. > > (Minor aside: I'm not sure if this file should be in docs/interop/ dir, > which IIRC, is for things that are 'external' interfaces. And I learn > that QOM is used both internally in and as an external interface, e.g. > whenever a device is being created, machine types, CPU config, etc.) 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. > > - - - > > I've re-skimmed your scarily-titled "QOM exegesis and apocalypse" 2014 > KVM Forum talk slides[*], where the "Why QOM?" slide says: > > All device creation, device configuration, backend creation and > backed configuration done through a single interface > > 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. Now compare to QOM: * Documentation QAPI: docs/devel/qapi-code-gen.txt section "Client JSON Protocol introspection" QOM: Nada * 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, child, STR[INT], and you just need to know what that means, too. * 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. > Me wonders how much of the above "Why" still holds true today. Although > further slides give more clues on what worked and what didn't. > > I'll wait for fresher details from your upcoming Wiki :-) > > [*] http://www.linux-kvm.org/images/9/90/Kvmforum14-qom.pdf [*] Gold was too expensive, but we had some tin on hand, so...
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
Paolo Bonzini writes: > Il ven 31 gen 2020, 11:36 Peter Maydell ha > scritto: > >> On Fri, 31 Jan 2020 at 06:11, Markus Armbruster wrote: >> > Beware, personal opinion. >> > >> > When you put documentation next to the code it documents (which you >> > absolutely should, because it's your only realistic chance to keep the >> > two in sync), then extracting API comments is useful, because it >> > collects them in one place. >> > >> > It's of next to no use to me when the comments are all in the same place >> > already, namely the header. >> > > The advantage of putting them in the header is that you have them all in > one place (inline functions and structs must be in the header). In practice > that balances for me the disadvantage of having some comments far from the > code they document, which increases the risk of bitrot especially for > comments such as "called with lock X held". With suitable doc generation from source, we can have them next to the code *and* all in one place, namely the generated interface docs. >> I definitely agree that the overview/introduction/conventions >> side of things is where we'd benefit most if somebody wanted >> to try to tackle that. We could roll >> https://wiki.qemu.org/Documentation/QOMConventions >> into that if we had a better place to put that info. >> > > I am travelling this weekend so I might try to do some kind of thread > summary and brain dump in the wiki. I'll leave to Kashyap to do the rST > conversion and patch submission. ;-) That would be awesome!
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
On 31/01/20 16:37, Christophe de Dinechin wrote: > > >> On 31 Jan 2020, at 08:46, Paolo Bonzini wrote: >> >> On 31/01/20 07:11, Markus Armbruster wrote: >>> May I present you Armbru's Comment Trust Levels: >>> >>> ACTL2: The comment may be overly terse or incomplete, but the >>> probability for it to be outright wrong is low. >>> >>> ACTL1: Treat as helpful guidance (with gratitude), but trust only the >>> code. >>> >>> ACTL0: It is a tale Told by an idiot[**], full of sound and fury, >>> Signifying nothing. >>> >>> Most comments in decently maintained code are at ACTL1. >>> >>> Around the time initial QOM development solidified, object.h's comments >>> were ACTL2. The neglect that is now clearly visible there makes me >>> downgrade to ACTL1. >>> >>> Paolo will have a more informed and possibly different opinion. >> >> I think around initial development it was ACTL3, now it's around 1.8. > > Interestingly, the initial doc suggested ACTL to be an whole value between > 0 and 2. Now it’s fractional and value 3 has a meaning you can guess > to be “above 2”… I won't say if this was accidental or not. : Paolo > How fast this happened tells you everything you need to know about > documentation/specifications and actual implementations :-)
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
> On 31 Jan 2020, at 08:46, Paolo Bonzini wrote: > > On 31/01/20 07:11, Markus Armbruster wrote: >> May I present you Armbru's Comment Trust Levels: >> >> ACTL2: The comment may be overly terse or incomplete, but the >> probability for it to be outright wrong is low. >> >> ACTL1: Treat as helpful guidance (with gratitude), but trust only the >> code. >> >> ACTL0: It is a tale Told by an idiot[**], full of sound and fury, >> Signifying nothing. >> >> Most comments in decently maintained code are at ACTL1. >> >> Around the time initial QOM development solidified, object.h's comments >> were ACTL2. The neglect that is now clearly visible there makes me >> downgrade to ACTL1. >> >> Paolo will have a more informed and possibly different opinion. > > I think around initial development it was ACTL3, now it's around 1.8. Interestingly, the initial doc suggested ACTL to be an whole value between 0 and 2. Now it’s fractional and value 3 has a meaning you can guess to be “above 2”… How fast this happened tells you everything you need to know about documentation/specifications and actual implementations :-) > > Paolo >
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
On Fri, Jan 31, 2020 at 12:02:05PM +0100, Paolo Bonzini wrote: > Il ven 31 gen 2020, 11:36 Peter Maydell ha > scritto: [...] > The advantage of putting them in the header is that you have them all in > one place (inline functions and structs must be in the header). In practice > that balances for me the disadvantage of having some comments far from the > code they document, which increases the risk of bitrot especially for > comments such as "called with lock X held". > > I definitely agree that the overview/introduction/conventions > > side of things is where we'd benefit most if somebody wanted > > to try to tackle that. We could roll > > https://wiki.qemu.org/Documentation/QOMConventions > > into that if we had a better place to put that info. > > > > I am travelling this weekend so I might try to do some kind of thread > summary and brain dump in the wiki. I'll leave to Kashyap to do the rST > conversion and patch submission. ;-) Thanks! Happy to be the 'scribe' ;-) I have a skeltal qemu-object-model.rst file sitting with some initial content based on various sources, including one of your presentations[*] from 2014. I'll wait for your new Wiki link to incorporate that content. (Minor aside: I'm not sure if this file should be in docs/interop/ dir, which IIRC, is for things that are 'external' interfaces. And I learn that QOM is used both internally in and as an external interface, e.g. whenever a device is being created, machine types, CPU config, etc.) - - - I've re-skimmed your scarily-titled "QOM exegesis and apocalypse" 2014 KVM Forum talk slides[*], where the "Why QOM?" slide says: All device creation, device configuration, backend creation and backed configuration done through a single interface Rigorous support for introspection both of runtime objects and type capabilities Me wonders how much of the above "Why" still holds true today. Although further slides give more clues on what worked and what didn't. I'll wait for fresher details from your upcoming Wiki :-) [*] http://www.linux-kvm.org/images/9/90/Kvmforum14-qom.pdf -- /kashyap
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
Il ven 31 gen 2020, 11:36 Peter Maydell ha scritto: > On Fri, 31 Jan 2020 at 06:11, Markus Armbruster wrote: > > Beware, personal opinion. > > > > When you put documentation next to the code it documents (which you > > absolutely should, because it's your only realistic chance to keep the > > two in sync), then extracting API comments is useful, because it > > collects them in one place. > > > > It's of next to no use to me when the comments are all in the same place > > already, namely the header. > The advantage of putting them in the header is that you have them all in one place (inline functions and structs must be in the header). In practice that balances for me the disadvantage of having some comments far from the code they document, which increases the risk of bitrot especially for comments such as "called with lock X held". I definitely agree that the overview/introduction/conventions > side of things is where we'd benefit most if somebody wanted > to try to tackle that. We could roll > https://wiki.qemu.org/Documentation/QOMConventions > into that if we had a better place to put that info. > I am travelling this weekend so I might try to do some kind of thread summary and brain dump in the wiki. I'll leave to Kashyap to do the rST conversion and patch submission. ;-) Paolo > thanks > -- PMM > >
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
On Fri, 31 Jan 2020 at 06:11, Markus Armbruster wrote: > Beware, personal opinion. > > When you put documentation next to the code it documents (which you > absolutely should, because it's your only realistic chance to keep the > two in sync), then extracting API comments is useful, because it > collects them in one place. > > It's of next to no use to me when the comments are all in the same place > already, namely the header. To throw in a personal opinion on the other side, API comments should be in the header, not the .c file, because they're your external interface and as an external consumer of that interface I shouldn't have to go digging around in your implementation source file to find the documentation. Since Paolo put in the effort to upstream the kerneldoc Sphinx plugin, it's now relatively simple to pull in the doc comments into a rST file, so you might as well I guess, though I agree that the cumulative benefit over just reading the .h file is not enormous. I definitely agree that the overview/introduction/conventions side of things is where we'd benefit most if somebody wanted to try to tackle that. We could roll https://wiki.qemu.org/Documentation/QOMConventions into that if we had a better place to put that info. thanks -- PMM
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
On Fri, Jan 31, 2020 at 07:11:15AM +0100, Markus Armbruster wrote: > Kashyap Chamarthy writes: [...] > > What can be done to improve QOM documentation (or lack thereof)? > > Are you trying to push us from idle grousing to actually improve things? > No fair! I first wrote it as a semi-complaint, and then I caught myself: "you're not helping"; so I rephrased it to be more constructive. :-) > > From a couple of hurried `grep` queries in the QEMU tree, there seems to > > be no explicit qom.rst|txt, or qemu-object-model.txt|rst or some such. > > (I hope I haven't missed any other files.) > > As far as I know, all we have is the lovingly[*] written comments in > include/qom/object.h. Sadly, we've let them rot in places. In > particular, many newer functions are undocumented. > > This is *reference* documentation. What we lack (sorely!) is an > overview / friendly introduction, and a design document with rationale. > Reconstructing rationale now would involve guesswork. Me nods; that (guesswork in retroactive rationale construction) makes matters slightly more difficult. [...] > > Opening qom/object.h[2], indeed there is copious amounts of docs, > > expressed as commented-out text. Two questions: > > > > - How much of this is still accurate? (Sorry, if that's a loaded > > question.) > > May I present you Armbru's Comment Trust Levels: > > ACTL2: The comment may be overly terse or incomplete, but the > probability for it to be outright wrong is low. > > ACTL1: Treat as helpful guidance (with gratitude), but trust only the > code. > > ACTL0: It is a tale Told by an idiot[**], full of sound and fury, > Signifying nothing. > > Most comments in decently maintained code are at ACTL1. Noted. (And thanks for the useful reference scale :-)) > Around the time initial QOM development solidified, object.h's comments > were ACTL2. The neglect that is now clearly visible there makes me > downgrade to ACTL1. > > Paolo will have a more informed and possibly different opinion. > > > - If at least 60% is still accurate, is it valuable to extract and > > publish it as rendered rST, as part of the on-going QEMU Docs > > improvement? > > Beware, personal opinion. > > When you put documentation next to the code it documents (which you > absolutely should, because it's your only realistic chance to keep the > two in sync), then extracting API comments is useful, because it > collects them in one place. > > It's of next to no use to me when the comments are all in the same place > already, namely the header. Yeah, reasonable point. > > (b) The other clue is also from the same post, where Eduardo provides > > pointers to past KVM Forum presentations by MarkusA, PaoloB, > > AndreasF on QOM, Qdev et al. > > > > Is it worth slapping all these references (with a clear intro and > > outro) into a qom.rst file in QEMU tree, even if only for > > reference/context? Or are these references, in-tree docs in > > object.h out-of-date beyond repair? > > Uff. > > My qdev talks predate the rebase onto QOM. They may well confuse / > mislead as much as inform now. Good to know. (We don't want to add additional sources of confusion.) > > If it is useful, I'm happy to get the initial doc going, secure in the > > knowledge that more clueful people than me will chip in during the > > review :-) > > Ha, nerd sniping! :-) Thanks for the response; it was useful. [...] -- /kashyap
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
On 31/01/20 07:11, Markus Armbruster wrote: > May I present you Armbru's Comment Trust Levels: > > ACTL2: The comment may be overly terse or incomplete, but the > probability for it to be outright wrong is low. > > ACTL1: Treat as helpful guidance (with gratitude), but trust only the > code. > > ACTL0: It is a tale Told by an idiot[**], full of sound and fury, > Signifying nothing. > > Most comments in decently maintained code are at ACTL1. > > Around the time initial QOM development solidified, object.h's comments > were ACTL2. The neglect that is now clearly visible there makes me > downgrade to ACTL1. > > Paolo will have a more informed and possibly different opinion. I think around initial development it was ACTL3, now it's around 1.8. Paolo
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
Kashyap Chamarthy writes:
> On Wed, Jan 15, 2020 at 03:02:48PM +0100, Markus Armbruster wrote:
>> Daniel P. Berrangé writes:
>
> [Changed the subject-line to indicate deviation from the original
> topic.]
>
> [...]
>
>> > Libvirt is of course happy to switch to something else instead of
>> > qom-set for these features if QEMU wants to provide a safer
>> > alternative.
>>
>> Noted.
>>
>> libvirt's use of qom-set is okay. What's not okay is the near-complete
>> lack of QOM documentation, its poor QMP interface, in part due to
>> non-integration with QAPI, and last but not least the lack of QOM
>> leadership leaving it adrift.
>
> What can be done to improve QOM documentation (or lack thereof)?
Are you trying to push us from idle grousing to actually improve things?
No fair!
> From a couple of hurried `grep` queries in the QEMU tree, there seems to
> be no explicit qom.rst|txt, or qemu-object-model.txt|rst or some such.
> (I hope I haven't missed any other files.)
As far as I know, all we have is the lovingly[*] written comments in
include/qom/object.h. Sadly, we've let them rot in places. In
particular, many newer functions are undocumented.
This is *reference* documentation. What we lack (sorely!) is an
overview / friendly introduction, and a design document with rationale.
Reconstructing rationale now would involve guesswork.
> Let's dig further. Ah, I come across this helpful 2016 blog post[1]
> ("An incomplete list of QEMU APIs") by Eduardo from my bookmarks. Here
> I get some clues:
>
> (a) In the section titled "QOM", Eduardo writes:
>
> "QOM is short for QEMU Object Model and was introduced in 2011.
> It is heavily documented on its header file
> [include/qom/object.h]"
>
> Opening qom/object.h[2], indeed there is copious amounts of docs,
> expressed as commented-out text. Two questions:
>
> - How much of this is still accurate? (Sorry, if that's a loaded
> question.)
May I present you Armbru's Comment Trust Levels:
ACTL2: The comment may be overly terse or incomplete, but the
probability for it to be outright wrong is low.
ACTL1: Treat as helpful guidance (with gratitude), but trust only the
code.
ACTL0: It is a tale Told by an idiot[**], full of sound and fury,
Signifying nothing.
Most comments in decently maintained code are at ACTL1.
Around the time initial QOM development solidified, object.h's comments
were ACTL2. The neglect that is now clearly visible there makes me
downgrade to ACTL1.
Paolo will have a more informed and possibly different opinion.
> - If at least 60% is still accurate, is it valuable to extract and
> publish it as rendered rST, as part of the on-going QEMU Docs
> improvement?
Beware, personal opinion.
When you put documentation next to the code it documents (which you
absolutely should, because it's your only realistic chance to keep the
two in sync), then extracting API comments is useful, because it
collects them in one place.
It's of next to no use to me when the comments are all in the same place
already, namely the header.
> (b) The other clue is also from the same post, where Eduardo provides
> pointers to past KVM Forum presentations by MarkusA, PaoloB,
> AndreasF on QOM, Qdev et al.
>
> Is it worth slapping all these references (with a clear intro and
> outro) into a qom.rst file in QEMU tree, even if only for
> reference/context? Or are these references, in-tree docs in
> object.h out-of-date beyond repair?
Uff.
My qdev talks predate the rebase onto QOM. They may well confuse /
mislead as much as inform now.
> If it is useful, I'm happy to get the initial doc going, secure in the
> knowledge that more clueful people than me will chip in during the
> review :-)
Ha, nerd sniping!
> [1] https://habkost.net/posts/2016/11/incomplete-list-of-qemu-apis.html
> [2] https://git.qemu.org/?p=qemu.git;a=blob;f=include/qom/object.h
> [3] http://www.linux-kvm.org/images/9/90/Kvmforum14-qom.pdf
[*] Absolutely no irony intended. Honest, officer!
[**] Don't take it personally, we're all part-time idiots. Besides,
this is literature.
Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
On Wed, Jan 15, 2020 at 03:02:48PM +0100, Markus Armbruster wrote:
> Daniel P. Berrangé writes:
[Changed the subject-line to indicate deviation from the original
topic.]
[...]
> > Libvirt is of course happy to switch to something else instead of
> > qom-set for these features if QEMU wants to provide a safer
> > alternative.
>
> Noted.
>
> libvirt's use of qom-set is okay. What's not okay is the near-complete
> lack of QOM documentation, its poor QMP interface, in part due to
> non-integration with QAPI, and last but not least the lack of QOM
> leadership leaving it adrift.
What can be done to improve QOM documentation (or lack thereof)?
>From a couple of hurried `grep` queries in the QEMU tree, there seems to
be no explicit qom.rst|txt, or qemu-object-model.txt|rst or some such.
(I hope I haven't missed any other files.)
Let's dig further. Ah, I come across this helpful 2016 blog post[1]
("An incomplete list of QEMU APIs") by Eduardo from my bookmarks. Here
I get some clues:
(a) In the section titled "QOM", Eduardo writes:
"QOM is short for QEMU Object Model and was introduced in 2011.
It is heavily documented on its header file
[include/qom/object.h]"
Opening qom/object.h[2], indeed there is copious amounts of docs,
expressed as commented-out text. Two questions:
- How much of this is still accurate? (Sorry, if that's a loaded
question.)
- If at least 60% is still accurate, is it valuable to extract and
publish it as rendered rST, as part of the on-going QEMU Docs
improvement?
(b) The other clue is also from the same post, where Eduardo provides
pointers to past KVM Forum presentations by MarkusA, PaoloB,
AndreasF on QOM, Qdev et al.
Is it worth slapping all these references (with a clear intro and
outro) into a qom.rst file in QEMU tree, even if only for
reference/context? Or are these references, in-tree docs in
object.h out-of-date beyond repair?
If it is useful, I'm happy to get the initial doc going, secure in the
knowledge that more clueful people than me will chip in during the
review :-)
[1] https://habkost.net/posts/2016/11/incomplete-list-of-qemu-apis.html
[2] https://git.qemu.org/?p=qemu.git;a=blob;f=include/qom/object.h
[3] http://www.linux-kvm.org/images/9/90/Kvmforum14-qom.pdf
--
/kashyap
