> +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...
TYPE_DEVICE is mentioned here because it appears in the code (the part that is not changing and thus is not included in the diff). It's not mixing QOM with qdev.
Paolo
> 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>