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

[Liviu Ionescu <ilg@livius.net>]

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