Re: [PATCH v3 25/36] docs/devel: introduce some key concepts for QOM development

[Philippe Mathieu-Daudé]

On 27/6/23 18:09, Alex Bennée 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
>    - lightly re-arrange the order we mention things
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Message-Id: <20230619171437.357374-6-alex.bennee@linaro.org>
>
> ---
> v3
>    - moved around as per Paolo's review
> ---
>   docs/devel/qom.rst | 58 +++++++++++++++++++++++++++++++++++++++++-----
>   1 file changed, 52 insertions(+), 6 deletions(-)


> +Creating a QOM class
> +====================
> +
> +A simple minimal device implementation may look something like bellow:
>   
>   .. code-block:: c
>      :caption: Creating a minimal type
> @@ -48,6 +66,12 @@ In the above example, we create a simple type that is 
> described by #TypeInfo.
>   #TypeInfo describes information about the type including what it inherits
>   from, the instance and class size, and constructor/destructor hooks.
>   
> +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.

Good enough but we are mixing QOM vs QDev...

>   Alternatively several static types could be registered using helper macro
>   DEFINE_TYPES()


> +.. _device-life-cycle:
> +
> +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.

Worth mentioning hotplug devices must implement it?

> +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.

Ah, here we go.

> This is determined by the
> +``user_creatable`` variable in the root ``DeviceClass`` structure.
> +Devices can only be unplugged if their ``parent_bus`` has a registered
> +``HotplugHandler``.

TODO on top, mentions the reset() handlers are called after realize(),
and can be called multiple times.

>   API Reference
> --------------
> +=============
>   
>   See the :ref:`QOM API<qom-api>` and :ref:`QDEV API<qdev-api>`
>   documents for the complete API description.

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>