| Message ID | 20230619171437.357374-6-alex.bennee@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs/devel: improve API documentation for QOM | expand |
On 6/19/23 19:14, Alex Bennée wrote: > +As class initialisation cannot fail devices have an two additional > +methods to handle the creation of dynamic devices. The ``realize`` Beginning with "as" feels like a continuation from something that has been omitted. You've skipped over describing ``init`` entirely, and then assumed it. > +The reverse function is ``unrealize`` and should be were clean-up "and is where clean-up" r~
On Mon, Jun 19, 2023 at 7:15 PM Alex Bennée <alex.bennee@linaro.org> 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 <alex.bennee@linaro.org> > --- > 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
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. + +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. + +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. + +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. + +Creating a minimal device +========================= + +A simple minimal device implementation may look something like bellow: .. code-block:: c :caption: Creating a minimal type
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 <alex.bennee@linaro.org> --- docs/devel/qom.rst | 47 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+)