[Qemu-devel] [RFC] QDev explicit constructors & destructors

[Liviu Ionescu]

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