Re: [PATCH 5/5] docs/devel: introduce some key concepts for QOM development

[Paolo Bonzini]

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