instance_init() and the realize() functions

instance_init() and the realize() functions

[Pratik Parvati]

[-- Attachment #1: Type: text/plain, Size: 393 bytes --]

Hi team,

Could someone please guild me to understand the difference between
*instance_init()* and the* realize()* functions? The *class_init() *function
is straight forward (it is similar to the constructor in C++ OOP); But I
am, finding hard to quote the difference between *instance_init()* and
*realize()*.

What is the code flow when both functions are defined?

Thanks & Regards,
Pratik

[-- Attachment #2: Type: text/html, Size: 649 bytes --]

Re: instance_init() and the realize() functions

[Liviu Ionescu]

> On 18 Jul 2020, at 10:09, Pratik Parvati <pratikp@vayavyalabs.com> wrote:
> 
> The class_init() function is straight forward (it is similar to the constructor in C++ OOP

The C++ constructor initialises class **instances**, i.e. C++ objects, not C++ classes.

In QEMU, the OOP functionality is implemented with nested structures used to store class and instance definitions, and callbacks as virtual methods.


The .class_init callbacks are called early, by a mechanism similar to C++ static constructors, and they initialise the structures used to store the class definitions. They are recursively chained, i.e. first the parent callback is called to initialise the parent structure members, then the current callback is called, to fill in its own members.

The .instance_init callback are automatically called when new **instances** of a class are created. Similarly, they are also recursively chained.

.instance_init may also create children objects, recursively.


.realize is a bit trickier. If .instance_init is the very first thing automatically called when creating an object, .realize is the very last thing, it is called manually when the whole hierarchy of objects is created and it signals that everything is ready, a kind of 'rien ne va plus'.

.realize usually has to manually call the parent .realize.

---

For me it was difficult to draw a line of what initialisations should be done in .instance_init and what in .realize, but given that .realise is called when the whole hierarchy is ready, it might do links between objects, which are not available when .instance_init is called.

A simple rule would be for .instance_init to ensure that all members have default values and properties associated with them, and defer all functional initialisations to .realize.


Hope this helps,

Liviu

Re: instance_init() and the realize() functions

[Peter Maydell]

On Sat, 18 Jul 2020 at 09:27, Liviu Ionescu <ilg@livius.net> wrote:
> For me it was difficult to draw a line of what initialisations should be done in .instance_init and what in .realize, but given that .realise is called when the whole hierarchy is ready, it might do links between objects, which are not available when .instance_init is called.

Yeah, we have not been able as a project to come up with a nice
rule for how to do this split. There are a few definite rules:
 * anything that can fail and return an error must go in realize
   (because instance_init has no failure-return mechanism)
 * anything you need to do to set up a QOM property on the
   object must go in instance_init (so that the property can
   be set by the user of the device object before realizing it)
 * anything that changes the state of the simulation must go in
   realize (some QMP monitor commands to introspect objects
   will do instance_init/look at object/delete)
but a lot of things could validly go in either method, and we
haven't set a convention for those cases. (There's a bunch
of inconclusive discussions in the mailing list archives.)

> A simple rule would be for .instance_init to ensure that all members have default values and properties associated with them, and defer all functional initialisations to .realize.

Yeah, this is a reasonable default rule. Note that for a lot
of device state struct members (where they correspond to guest
registers state), you want to set their values in the
device's reset method, not in instance_init or realize.
That's because the guest-visible register state needs to
be set back to its initial value on a system reset anyway,
and QEMU guarantees that we will reset a device before
first use.

thanks
-- PMM

Re: instance_init() and the realize() functions

[Liviu Ionescu]

> On 18 Jul 2020, at 12:43, Peter Maydell <peter.maydell@linaro.org> wrote:
> 
> Note that for a lot
> of device state struct members (where they correspond to guest
> registers state), you want to set their values in the
> device's reset method, not in instance_init or realize.
> That's because the guest-visible register state needs to
> be set back to its initial value on a system reset anyway,
> and QEMU guarantees that we will reset a device before
> first use.

Yes, that's a good point, but must be used with caution; since .reset is called **after** .realize, if the dynamically allocated structures are not set to zero, leaving state members uninitialised up to .reset is risky, it may lead to unexpected behaviour during .realize or other parts of the code.

That's why I mentioned that .instance_init should ensure that all members have default values and properties associated with them, such that later code, like .realize, has a deterministic behaviour.


Of course, for consistent results, both .instance_init and .reset can call a common internal function.


Regards,

Liviu

Re: instance_init() and the realize() functions

[Thomas Huth]

On 18/07/2020 09.09, Pratik Parvati wrote:
> Hi team,
> 
> Could someone please guild me to understand the difference
> between *instance_init()* and the*realize()* functions? The
> *class_init() *function is straight forward (it is similar to the
> constructor in C++ OOP); But I am, finding hard to quote the difference
> between *instance_init()* and *realize()*.
> 
> What is the code flow when both functions are defined?

Beside the other good answers that you've already got, maybe this helps
a little bit, too:

 http://people.redhat.com/~thuth/blog/qemu/2018/09/10/instance-init-realize.html

 Cheers,
  Thomas