The .instance_init construction method available in the current QOM provides an
equivalent of the C++ default constructor, that works just fine as long as
there is no need to pass additional data to the construction logic.
One natural solution would be to add an explicit constructor, like in C++.
Since C++ style multiple constructors can be folded into a single constructor
using a pointer to a structure, one single callback would be enough to
accommodate any construction logic.
The generic use case would look like this:
DeviceState *mcu = qdev_alloc(NULL, TYPE_STM32F103RB);
{
qdev_prop_set_uint32(mcu, "param1", value1); /* Optional */
qdev_prop_set_uint32(mcu, "param2", value2); /* Optional */
qdev_construct(mcu, &constructor_data); /* the second pointer may be
NULL */
/* Set the board specific oscillator frequencies. */
qdev_prop_set_uint32(mcu, "hse-freq-hz", 8000000); /* 8.0 MHz */
qdev_prop_set_uint32(mcu, "lse-freq-hz", 32768); /* 32 KHz */
}
qdev_realize(mcu); /* QDev specific step */
The implementation requires only to:
- add a "void (*construct)(DeviceState *dev, void *data)" member to the
DeviceClass structure
- add a qdev_construct() function, that will run all these callbacks in 'parent
first' order
For completeness, although it'll probably be used rarely, a destructor can also
be implemented, by adding:
- a "void (*destruct)(DeviceState *dev)" member to the DeviceClass structure,
and
- a qdev_destruct(dev) function, that will run these callbacks in 'child first'
order
Notes:
- except for setting statically defined properties, the object returned by
qdev_alloc() but not yet constructed, **should not** be used for any other
purposes
- inside the "construct" callback any number of children objects can be
created,
- an object is not considered properly constructed before all children object
are constructed; in other words, the construct callback should not return as
long as it includes objects allocated but not yet constructed
- passing constructor data can be done via standard properties and/or via the
more generic 'data' structure, that will be passed up in the hierarchy (similar
to the object state structure, each child in the hierarchy can extend this
structure with additional members).
- after construction and before freezing the object with realize(), properties
that were dynamically added during construction (like aliases to internal
objects created during construction), can be set as usual.
Please note that these additions do not break any compatibility with existing
code.
The two other functions mentioned are just aliases with more appropriate names
for qdev_create() (create is not accurate, since the object is not yet ready to
use) and qdev_init_nofail() (this name is deprecated, it is not calling init
but realize, and the nofail is confusing, it not only fail, it even exits).
Regards,
Liviu
