[Qemu-devel] Object instantiation vs. device realization: what to do when?

[Markus Armbruster <armbru@redhat.com>]

One of qdev's perennial sources of confusion is what to do at object
instantiation time, i.e. in TypeInfo::instance_init(), and what to do at
device realization time, i.e. in DeviceClass::realize().  qdev-core.h's
comment falls short:

 * # Realization #
 * Devices are constructed in two stages,
 * 1) object instantiation via object_initialize() and
 * 2) device realization via #DeviceState:realized property.
 * The former may not fail (and must not abort or exit, since it is called
 * during device introspection already), and the latter may return error
 * information to the caller and must be re-entrant.
 * Trivial field initializations should go into #TypeInfo.instance_init.

As usual, "trivial" was too trivial to explain; the reader is trusted to
figure it out himself.  Well, I'm afraid I'm not to be trusted.

The easy part is "can fail means it's not trivial", because
::instance_init() must not fail.

What about side effects?  If you already understand how introspection
works, or perhaps even if you read carefully and paranoidly, then "since
it is called during device introspection already" implies "guest-visible
side-effects would be disastrous".  So guest-visible side-effect also
means it's not trivial.

 * Operations depending on @props static properties should go into @realize.

Actually, these *have* to go into realize(), because properties get set
between ::instance_init() and ::realize().

Even if I had a precise definition of "trivial field initializations",
I'd still wonder where operations should go that are neither such
trivial field initializations, nor depend on @props.

 * After successful realization, setting static properties will fail.
 *
 * As an interim step, the #DeviceState:realized property can also be
 * set with qdev_init_nofail().
 * In the future, devices will propagate this state change to their children
 * and along busses they expose.

This sentence is five years old.  Any progress?  If not, any intentions
to make progress?

 * The point in time will be deferred to machine creation, so that values
 * set in @realize will not be introspectable beforehand. Therefore devices
 * must not create children during @realize; they should initialize them via
 * object_initialize() in their own #TypeInfo.instance_init and forward the
 * realization events appropriately.

This is mostly greek to me.  Pity the developer who knows less about
qdev than I do.

 *
 * Any type may override the @realize and/or @unrealize callbacks but needs
 * to call the parent type's implementation if keeping their functionality
 * is desired. Refer to QOM documentation for further discussion and examples.

"Refer to QOM documentation"... okay, but this comment needs to make
sense without having to read the 3000+ lines under include/qom/ (which
by the way requires finding it first; I'd expect the naive reader to
look under docs/ and draw a blank).

Can we come up with clear guidelines on how to split work between
::instance_init() and ::realize()?