On Mon, Jun 19, 2023 at 7:15 PM Alex Bennée <[email protected]> wrote: > > Using QOM correctly is increasingly important to maintaining a modern > code base. However the current documentation skips some important > concepts before launching into a simple example. Lets: > > - at least mention properties > - mention TYPE_OBJECT and TYPE_DEVICE > - talk about why we have realize/unrealize > - mention the QOM tree > > Signed-off-by: Alex Bennée <[email protected]> > --- > docs/devel/qom.rst | 47 ++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 47 insertions(+) > > diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst > index 98a4f178d5..53633fbd35 100644 > --- a/docs/devel/qom.rst > +++ b/docs/devel/qom.rst > @@ -13,6 +13,53 @@ features: > - System for dynamically registering types > - Support for single-inheritance of types > - Multiple inheritance of stateless interfaces > +- Mapping internal members to publicly exposed properties > + > +The root object class is TYPE_OBJECT which provides for the basic > +object methods.
Very nice, but I would suggest some changes here. > +The Device Class > +================ > + > +The TYPE_DEVICE class is the parent class for all modern devices > +implemented in QEMU and adds some specific methods to handle QEMU > +device model. This includes managing the lifetime of devices from > +creation through to when they become visible to the guest and > +eventually unrealized. Place this paragraph before "Alternatively several static types". > +Device Life-cycle > +----------------- Make this "=====" level and move it at the very end of the document. Replace these two lines: The first example of such a QOM method was #CPUClass.reset, another example is #DeviceClass.realize. with One example of such methods is ``DeviceClass.reset``. More examples can be found at [link to Device Life-Cycle]. > +As class initialisation cannot fail devices have an two additional > +methods to handle the creation of dynamic devices. The ``realize`` > +function is called with ``Error **`` pointer which should be set if > +the device cannot complete its setup. Otherwise on successful > +completion of the ``realize`` method the device object is added to the > +QOM tree and made visible to the guest. > + > +The reverse function is ``unrealize`` and should be were clean-up > +code lives to tidy up after the system is done with the device. > + > +All devices can be instantiated by C code, however only some can > +created dynamically via the command line or monitor. Likewise only > +some can be unplugged after creation and need an explicit > +``unrealize`` implementation. This is determined by the > +``user_creatable`` and ``hotpluggable`` variables in the root > +``DeviceClass`` structure. Move the second sentence (the one starting with "Likewise") to a separate paragraph. Unpluggability is determined by the HotplugHandler rather than by "user_creatable" and "hotpluggable". > +The QOM tree > +------------ > + > +The QOM tree is a composition tree which represents all of the objects > +that make up a QEMU "machine". You can view this tree by running > +``info qom-tree`` in the :ref:`QEMU monitor`. It will contain both > +objects created by the machine itself as well those created due to > +user configuration. Also make this "===========". > +Creating a minimal device > +========================= Name this "Creating a QOM class", and change "Class Initialization", "Interfaces" and "Methods" to "-------------". > +A simple minimal device implementation may look something like bellow: "below". Paolo
