[PATCH v2] qdev: Clarify instantiation and realization

[PATCH v2] qdev: Clarify instantiation and realization

[Akihiko Odaki]

The distinction of instantiation and realization was vague in the old
documentation so this change clarifies it.

The old documentation said:
> 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.
> Operations depending on @props static properties should go into
> @realize.

The first problem with the old documentation is that it is unclear what
"trivial field initializations" means and why triviality makes
initialization appropriate for #TypeInfo.instance_init. Another problem
is that the documentation is not comprehensive enough; for example, it
mentions @props static properties, but it does not say anything about
the other properties.

The keys to distinguish instantiation and realization are property
setting and device introspection. The fact that property setting happens
after #TypeInfo.instance_init and before realization implies that
operations depending on properties should go into @realize.

The fact that instantiation happens during device introspection but
realization does not implies:
- Instance properties should be added in #TypeInfo.instance_init.
- Instantiation must not have any side effect not contained in the
  instance.
- Any operations without special requirements should go into @realize so
  that they can be skipped during device introspection.

Note these two facts to guide appropriate instantiation and realization.

Signed-off-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>
---
Changes in v2:
- Clarified the ordering of #TypeInfo.instance_init, pre-realize
  property setting, and realization.
- Clarified that #TypeInfo.instance_init is for per-instance properties,
  not class properties.
- Link to v1: https://lore.kernel.org/qemu-devel/20250908-qdev-v1-1-df236f7ce5bd@rsg.ci.i.u-tokyo.ac.jp
---
 include/hw/core/qdev.h | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/include/hw/core/qdev.h b/include/hw/core/qdev.h
index e14762234115..55da09934271 100644
--- a/include/hw/core/qdev.h
+++ b/include/hw/core/qdev.h
@@ -22,16 +22,19 @@
  * Realization
  * -----------
  *
- * Devices are constructed in two stages:
- *
- * 1) object instantiation via object_initialize() and
- * 2) device realization via the #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.
- * Operations depending on @props static properties should go into @realize.
+ * Devices are constructed in the following order:
+ *
+ * 1) #TypeInfo.instance_init
+ * 2) pre-realize property value setting
+ * 3) device realization via the #DeviceState.realized property
+ *
+ * #TypeInfo.instance_init may not fail, and realization may return
+ * error information to the caller and must be re-entrant.
+ * #TypeInfo.instance_init should add instance properties but must not
+ * have any side effect not contained in the instance, since it happens
+ * during device introspection already. Any operations without special
+ * requirements should go @realize so that they can be skipped during
+ * device introspection.
  * After successful realization, setting static properties will fail.
  *
  * As an interim step, the #DeviceState.realized property can also be
@@ -40,9 +43,8 @@
  * 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.
+ * initialize them via #TypeInfo.instance_init and forward the
+ * realization events appropriately.
  *
  * Any type may override the @realize and/or @unrealize callbacks but needs
  * to call the parent type's implementation if keeping their functionality

---
base-commit: b83371668192a705b878e909c5ae9c1233cbd5fb
change-id: 20250906-qdev-9e5cb7c06ffa

Best regards,
--  
Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>

Re: [PATCH v2] qdev: Clarify instantiation and realization

[Peter Maydell]

On Mon, 29 Jun 2026 at 09:18, Akihiko Odaki
<odaki@rsg.ci.i.u-tokyo.ac.jp> wrote:
>
> The distinction of instantiation and realization was vague in the old
> documentation so this change clarifies it.
>
> The old documentation said:
> > 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.
> > Operations depending on @props static properties should go into
> > @realize.
>
> The first problem with the old documentation is that it is unclear what
> "trivial field initializations" means and why triviality makes
> initialization appropriate for #TypeInfo.instance_init. Another problem
> is that the documentation is not comprehensive enough; for example, it
> mentions @props static properties, but it does not say anything about
> the other properties.
>
> The keys to distinguish instantiation and realization are property
> setting and device introspection. The fact that property setting happens
> after #TypeInfo.instance_init and before realization implies that
> operations depending on properties should go into @realize.
>
> The fact that instantiation happens during device introspection but
> realization does not implies:
> - Instance properties should be added in #TypeInfo.instance_init.
> - Instantiation must not have any side effect not contained in the
>   instance.
> - Any operations without special requirements should go into @realize so
>   that they can be skipped during device introspection.
>
> Note these two facts to guide appropriate instantiation and realization.

Thanks for sending this. I think we definitely need to try to be
clearer about what to do in instance_init and what to do in realize.

> Signed-off-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>

>   * Realization
>   * -----------
>   *
> - * Devices are constructed in two stages:
> - *
> - * 1) object instantiation via object_initialize() and
> - * 2) device realization via the #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.
> - * Operations depending on @props static properties should go into @realize.
> + * Devices are constructed in the following order:
> + *
> + * 1) #TypeInfo.instance_init
> + * 2) pre-realize property value setting
> + * 3) device realization via the #DeviceState.realized property
> + *
> + * #TypeInfo.instance_init may not fail, and realization may return
> + * error information to the caller and must be re-entrant.

I know this is in the existing text, but what do we mean by
"must be re-entrant" here ? Does this mean "even if you return
a failure from your realize method you must be able to handle the
caller retrying the realize operation" ?  (I'm not sure why that's
a useful thing for the caller to be able to do...)

I assume we don't mean "even if you successfully realize you must
handle (and treat as a no-op) a second call to realize", because
none of our devices do that :-)

> + * #TypeInfo.instance_init should add instance properties but must not
> + * have any side effect not contained in the instance, since it happens
> + * during device introspection already. Any operations without special
> + * requirements should go @realize so that they can be skipped during
> + * device introspection.
>   * After successful realization, setting static properties will fail.
>   *
>   * As an interim step, the #DeviceState.realized property can also be
> @@ -40,9 +43,8 @@
>   * 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.
> + * initialize them via #TypeInfo.instance_init and forward the
> + * realization events appropriately.

This change doesn't seem to me to match the paragraph it's in.
The intent of the paragraph is clearly "initialize child objects in
your own instance_init method", so we want to say "in" the method.
"via" here is for "how you do it"; we could make that say
"initialize them (e.g. by calling object_initialize())" to be
a bit clearer, something like:

"Therefore
devices must not create children during @realize; they should
initialize them (e.g. by calling object_initialize_child()) in their
own #TypeInfo.instance_init method, and then realize them (e.g. by
calling qdev_realize()) in their own #DeviceClass.realize method."

This whole paragraph is one of those we sometimes like to put in,
which is sketching out a design idea or direction we have not
actually managed to achieve. So it's part aspiration and part
reality. In particular, the flat "must not create children during
realize" statement clashes with "operations depending on static
properties should go into realize", because occasionally we need
to create or not create children based on the value of a property...

thanks
-- PMM

Re: [PATCH v2] qdev: Clarify instantiation and realization

[Akihiko Odaki]

On 2026/07/13 18:13, Peter Maydell wrote:
> On Mon, 29 Jun 2026 at 09:18, Akihiko Odaki
> <odaki@rsg.ci.i.u-tokyo.ac.jp> wrote:
>>
>> The distinction of instantiation and realization was vague in the old
>> documentation so this change clarifies it.
>>
>> The old documentation said:
>>> 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.
>>> Operations depending on @props static properties should go into
>>> @realize.
>>
>> The first problem with the old documentation is that it is unclear what
>> "trivial field initializations" means and why triviality makes
>> initialization appropriate for #TypeInfo.instance_init. Another problem
>> is that the documentation is not comprehensive enough; for example, it
>> mentions @props static properties, but it does not say anything about
>> the other properties.
>>
>> The keys to distinguish instantiation and realization are property
>> setting and device introspection. The fact that property setting happens
>> after #TypeInfo.instance_init and before realization implies that
>> operations depending on properties should go into @realize.
>>
>> The fact that instantiation happens during device introspection but
>> realization does not implies:
>> - Instance properties should be added in #TypeInfo.instance_init.
>> - Instantiation must not have any side effect not contained in the
>>    instance.
>> - Any operations without special requirements should go into @realize so
>>    that they can be skipped during device introspection.
>>
>> Note these two facts to guide appropriate instantiation and realization.
> 
> Thanks for sending this. I think we definitely need to try to be
> clearer about what to do in instance_init and what to do in realize.
> 
>> Signed-off-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>
> 
>>    * Realization
>>    * -----------
>>    *
>> - * Devices are constructed in two stages:
>> - *
>> - * 1) object instantiation via object_initialize() and
>> - * 2) device realization via the #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.
>> - * Operations depending on @props static properties should go into @realize.
>> + * Devices are constructed in the following order:
>> + *
>> + * 1) #TypeInfo.instance_init
>> + * 2) pre-realize property value setting
>> + * 3) device realization via the #DeviceState.realized property
>> + *
>> + * #TypeInfo.instance_init may not fail, and realization may return
>> + * error information to the caller and must be re-entrant.
> 
> I know this is in the existing text, but what do we mean by
> "must be re-entrant" here ? Does this mean "even if you return
> a failure from your realize method you must be able to handle the
> caller retrying the realize operation" ?  (I'm not sure why that's
> a useful thing for the caller to be able to do...)>
> I assume we don't mean "even if you successfully realize you must
> handle (and treat as a no-op) a second call to realize", because
> none of our devices do that :-)

If you take the code literally, device_set_realized() indeed avoids 
calling realize after successful realization, but it doesn't report an 
error when retrying, so I think this means to allow that.

I don't think it's that useful, and it is likely to cause bunch of bugs. 
I can also imagine that careful developers have written device code that 
preserves this contract, though the added complexity is useless in practice.

In my opinion, the property should be tristate: initialized, realized, 
or retired. Then we would have only the following state transitions:

Successful realization: initialized -> realized
Failed realization: initialized -> retired
Unrealization: realized -> retired

This is another opportunity for refactoring, but for this particular 
patch I'm planning to keep it out of scope.

> 
>> + * #TypeInfo.instance_init should add instance properties but must not
>> + * have any side effect not contained in the instance, since it happens
>> + * during device introspection already. Any operations without special
>> + * requirements should go @realize so that they can be skipped during
>> + * device introspection.
>>    * After successful realization, setting static properties will fail.
>>    *
>>    * As an interim step, the #DeviceState.realized property can also be
>> @@ -40,9 +43,8 @@
>>    * 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.
>> + * initialize them via #TypeInfo.instance_init and forward the
>> + * realization events appropriately.
> 
> This change doesn't seem to me to match the paragraph it's in.
> The intent of the paragraph is clearly "initialize child objects in
> your own instance_init method", so we want to say "in" the method.
> "via" here is for "how you do it"; we could make that say
> "initialize them (e.g. by calling object_initialize())" to be
> a bit clearer, something like:
> 
> "Therefore
> devices must not create children during @realize; they should
> initialize them (e.g. by calling object_initialize_child()) in their
> own #TypeInfo.instance_init method, and then realize them (e.g. by
> calling qdev_realize()) in their own #DeviceClass.realize method."

That looks better. I'll use it for the next version.

> 
> This whole paragraph is one of those we sometimes like to put in,
> which is sketching out a design idea or direction we have not
> actually managed to achieve. So it's part aspiration and part
> reality. In particular, the flat "must not create children during
> realize" statement clashes with "operations depending on static
> properties should go into realize", because occasionally we need
> to create or not create children based on the value of a property...

Honestly I would just replace "must" with "should". Hopefully people 
would understand.

Regards,
Akihiko Odaki

Re: [PATCH v2] qdev: Clarify instantiation and realization

[Peter Maydell]

On Mon, 13 Jul 2026 at 12:21, Akihiko Odaki
<odaki@rsg.ci.i.u-tokyo.ac.jp> wrote:
>
> On 2026/07/13 18:13, Peter Maydell wrote:
> > On Mon, 29 Jun 2026 at 09:18, Akihiko Odaki
> > <odaki@rsg.ci.i.u-tokyo.ac.jp> wrote:
> >>
> >> The distinction of instantiation and realization was vague in the old
> >> documentation so this change clarifies it.
> >>
> >> The old documentation said:
> >>> 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.
> >>> Operations depending on @props static properties should go into
> >>> @realize.
> >>
> >> The first problem with the old documentation is that it is unclear what
> >> "trivial field initializations" means and why triviality makes
> >> initialization appropriate for #TypeInfo.instance_init. Another problem
> >> is that the documentation is not comprehensive enough; for example, it
> >> mentions @props static properties, but it does not say anything about
> >> the other properties.
> >>
> >> The keys to distinguish instantiation and realization are property
> >> setting and device introspection. The fact that property setting happens
> >> after #TypeInfo.instance_init and before realization implies that
> >> operations depending on properties should go into @realize.
> >>
> >> The fact that instantiation happens during device introspection but
> >> realization does not implies:
> >> - Instance properties should be added in #TypeInfo.instance_init.
> >> - Instantiation must not have any side effect not contained in the
> >>    instance.
> >> - Any operations without special requirements should go into @realize so
> >>    that they can be skipped during device introspection.
> >>
> >> Note these two facts to guide appropriate instantiation and realization.
> >
> > Thanks for sending this. I think we definitely need to try to be
> > clearer about what to do in instance_init and what to do in realize.
> >
> >> Signed-off-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>
> >
> >>    * Realization
> >>    * -----------
> >>    *
> >> - * Devices are constructed in two stages:
> >> - *
> >> - * 1) object instantiation via object_initialize() and
> >> - * 2) device realization via the #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.
> >> - * Operations depending on @props static properties should go into @realize.
> >> + * Devices are constructed in the following order:
> >> + *
> >> + * 1) #TypeInfo.instance_init
> >> + * 2) pre-realize property value setting
> >> + * 3) device realization via the #DeviceState.realized property
> >> + *
> >> + * #TypeInfo.instance_init may not fail, and realization may return
> >> + * error information to the caller and must be re-entrant.
> >
> > I know this is in the existing text, but what do we mean by
> > "must be re-entrant" here ? Does this mean "even if you return
> > a failure from your realize method you must be able to handle the
> > caller retrying the realize operation" ?  (I'm not sure why that's
> > a useful thing for the caller to be able to do...)>
> > I assume we don't mean "even if you successfully realize you must
> > handle (and treat as a no-op) a second call to realize", because
> > none of our devices do that :-)
>
> If you take the code literally, device_set_realized() indeed avoids
> calling realize after successful realization, but it doesn't report an
> error when retrying, so I think this means to allow that.
>
> I don't think it's that useful, and it is likely to cause bunch of bugs.
> I can also imagine that careful developers have written device code that
> preserves this contract, though the added complexity is useless in practice.
>
> In my opinion, the property should be tristate: initialized, realized,
> or retired. Then we would have only the following state transitions:
>
> Successful realization: initialized -> realized
> Failed realization: initialized -> retired
> Unrealization: realized -> retired
>
> This is another opportunity for refactoring, but for this particular
> patch I'm planning to keep it out of scope.

OK. We could make the text clearer then, I think. Maybe

"#TypeInfo.instance_init may not fail. #DeviceClass.realize can
fail, returning error information to the caller. A device realize
method should handle being called again after it has failed once."

?

> >
> >> + * #TypeInfo.instance_init should add instance properties but must not
> >> + * have any side effect not contained in the instance, since it happens
> >> + * during device introspection already. Any operations without special
> >> + * requirements should go @realize so that they can be skipped during
> >> + * device introspection.
> >>    * After successful realization, setting static properties will fail.
> >>    *
> >>    * As an interim step, the #DeviceState.realized property can also be
> >> @@ -40,9 +43,8 @@
> >>    * 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.
> >> + * initialize them via #TypeInfo.instance_init and forward the
> >> + * realization events appropriately.
> >
> > This change doesn't seem to me to match the paragraph it's in.
> > The intent of the paragraph is clearly "initialize child objects in
> > your own instance_init method", so we want to say "in" the method.
> > "via" here is for "how you do it"; we could make that say
> > "initialize them (e.g. by calling object_initialize())" to be
> > a bit clearer, something like:
> >
> > "Therefore
> > devices must not create children during @realize; they should
> > initialize them (e.g. by calling object_initialize_child()) in their
> > own #TypeInfo.instance_init method, and then realize them (e.g. by
> > calling qdev_realize()) in their own #DeviceClass.realize method."
>
> That looks better. I'll use it for the next version.
>
> >
> > This whole paragraph is one of those we sometimes like to put in,
> > which is sketching out a design idea or direction we have not
> > actually managed to achieve. So it's part aspiration and part
> > reality. In particular, the flat "must not create children during
> > realize" statement clashes with "operations depending on static
> > properties should go into realize", because occasionally we need
> > to create or not create children based on the value of a property...
>
> Honestly I would just replace "must" with "should". Hopefully people
> would understand.

We could maybe say "should not" and add an extra sentence at the end:

"Occasionally a device may need to decide whether or not to create
a child object based on the value of a property. In this case it
will need to both create and realize the child in its realize method,
because the property value is not known until that point."

-- PMM

Re: [PATCH v2] qdev: Clarify instantiation and realization

[Akihiko Odaki]

On 2026/07/13 20:33, Peter Maydell wrote:
> On Mon, 13 Jul 2026 at 12:21, Akihiko Odaki
> <odaki@rsg.ci.i.u-tokyo.ac.jp> wrote:
>>
>> On 2026/07/13 18:13, Peter Maydell wrote:
>>> On Mon, 29 Jun 2026 at 09:18, Akihiko Odaki
>>> <odaki@rsg.ci.i.u-tokyo.ac.jp> wrote:
>>>>
>>>> The distinction of instantiation and realization was vague in the old
>>>> documentation so this change clarifies it.
>>>>
>>>> The old documentation said:
>>>>> 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.
>>>>> Operations depending on @props static properties should go into
>>>>> @realize.
>>>>
>>>> The first problem with the old documentation is that it is unclear what
>>>> "trivial field initializations" means and why triviality makes
>>>> initialization appropriate for #TypeInfo.instance_init. Another problem
>>>> is that the documentation is not comprehensive enough; for example, it
>>>> mentions @props static properties, but it does not say anything about
>>>> the other properties.
>>>>
>>>> The keys to distinguish instantiation and realization are property
>>>> setting and device introspection. The fact that property setting happens
>>>> after #TypeInfo.instance_init and before realization implies that
>>>> operations depending on properties should go into @realize.
>>>>
>>>> The fact that instantiation happens during device introspection but
>>>> realization does not implies:
>>>> - Instance properties should be added in #TypeInfo.instance_init.
>>>> - Instantiation must not have any side effect not contained in the
>>>>     instance.
>>>> - Any operations without special requirements should go into @realize so
>>>>     that they can be skipped during device introspection.
>>>>
>>>> Note these two facts to guide appropriate instantiation and realization.
>>>
>>> Thanks for sending this. I think we definitely need to try to be
>>> clearer about what to do in instance_init and what to do in realize.
>>>
>>>> Signed-off-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>
>>>
>>>>     * Realization
>>>>     * -----------
>>>>     *
>>>> - * Devices are constructed in two stages:
>>>> - *
>>>> - * 1) object instantiation via object_initialize() and
>>>> - * 2) device realization via the #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.
>>>> - * Operations depending on @props static properties should go into @realize.
>>>> + * Devices are constructed in the following order:
>>>> + *
>>>> + * 1) #TypeInfo.instance_init
>>>> + * 2) pre-realize property value setting
>>>> + * 3) device realization via the #DeviceState.realized property
>>>> + *
>>>> + * #TypeInfo.instance_init may not fail, and realization may return
>>>> + * error information to the caller and must be re-entrant.
>>>
>>> I know this is in the existing text, but what do we mean by
>>> "must be re-entrant" here ? Does this mean "even if you return
>>> a failure from your realize method you must be able to handle the
>>> caller retrying the realize operation" ?  (I'm not sure why that's
>>> a useful thing for the caller to be able to do...)>
>>> I assume we don't mean "even if you successfully realize you must
>>> handle (and treat as a no-op) a second call to realize", because
>>> none of our devices do that :-)
>>
>> If you take the code literally, device_set_realized() indeed avoids
>> calling realize after successful realization, but it doesn't report an
>> error when retrying, so I think this means to allow that.
>>
>> I don't think it's that useful, and it is likely to cause bunch of bugs.
>> I can also imagine that careful developers have written device code that
>> preserves this contract, though the added complexity is useless in practice.
>>
>> In my opinion, the property should be tristate: initialized, realized,
>> or retired. Then we would have only the following state transitions:
>>
>> Successful realization: initialized -> realized
>> Failed realization: initialized -> retired
>> Unrealization: realized -> retired
>>
>> This is another opportunity for refactoring, but for this particular
>> patch I'm planning to keep it out of scope.
> 
> OK. We could make the text clearer then, I think. Maybe
> 
> "#TypeInfo.instance_init may not fail. #DeviceClass.realize can
> fail, returning error information to the caller. A device realize
> method should handle being called again after it has failed once."
> 
> ?
> 
>>>
>>>> + * #TypeInfo.instance_init should add instance properties but must not
>>>> + * have any side effect not contained in the instance, since it happens
>>>> + * during device introspection already. Any operations without special
>>>> + * requirements should go @realize so that they can be skipped during
>>>> + * device introspection.
>>>>     * After successful realization, setting static properties will fail.
>>>>     *
>>>>     * As an interim step, the #DeviceState.realized property can also be
>>>> @@ -40,9 +43,8 @@
>>>>     * 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.
>>>> + * initialize them via #TypeInfo.instance_init and forward the
>>>> + * realization events appropriately.
>>>
>>> This change doesn't seem to me to match the paragraph it's in.
>>> The intent of the paragraph is clearly "initialize child objects in
>>> your own instance_init method", so we want to say "in" the method.
>>> "via" here is for "how you do it"; we could make that say
>>> "initialize them (e.g. by calling object_initialize())" to be
>>> a bit clearer, something like:
>>>
>>> "Therefore
>>> devices must not create children during @realize; they should
>>> initialize them (e.g. by calling object_initialize_child()) in their
>>> own #TypeInfo.instance_init method, and then realize them (e.g. by
>>> calling qdev_realize()) in their own #DeviceClass.realize method."
>>
>> That looks better. I'll use it for the next version.
>>
>>>
>>> This whole paragraph is one of those we sometimes like to put in,
>>> which is sketching out a design idea or direction we have not
>>> actually managed to achieve. So it's part aspiration and part
>>> reality. In particular, the flat "must not create children during
>>> realize" statement clashes with "operations depending on static
>>> properties should go into realize", because occasionally we need
>>> to create or not create children based on the value of a property...
>>
>> Honestly I would just replace "must" with "should". Hopefully people
>> would understand.
> 
> We could maybe say "should not" and add an extra sentence at the end:
> 
> "Occasionally a device may need to decide whether or not to create
> a child object based on the value of a property. In this case it
> will need to both create and realize the child in its realize method,
> because the property value is not known until that point."

Thank you for suggestions; both of them are nice improvements. I'll 
incorporate them in the next version.

Regards,
Akihiko Odaki

Re: [PATCH v2] qdev: Clarify instantiation and realization

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Mon, 13 Jul 2026 at 12:21, Akihiko Odaki
> <odaki@rsg.ci.i.u-tokyo.ac.jp> wrote:
>>
>> On 2026/07/13 18:13, Peter Maydell wrote:
>> > On Mon, 29 Jun 2026 at 09:18, Akihiko Odaki
>> > <odaki@rsg.ci.i.u-tokyo.ac.jp> wrote:
>> >>
>> >> The distinction of instantiation and realization was vague in the old
>> >> documentation so this change clarifies it.
>> >>
>> >> The old documentation said:
>> >>> 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.
>> >>> Operations depending on @props static properties should go into
>> >>> @realize.
>> >>
>> >> The first problem with the old documentation is that it is unclear what
>> >> "trivial field initializations" means and why triviality makes
>> >> initialization appropriate for #TypeInfo.instance_init. Another problem
>> >> is that the documentation is not comprehensive enough; for example, it
>> >> mentions @props static properties, but it does not say anything about
>> >> the other properties.
>> >>
>> >> The keys to distinguish instantiation and realization are property
>> >> setting and device introspection. The fact that property setting happens
>> >> after #TypeInfo.instance_init and before realization implies that
>> >> operations depending on properties should go into @realize.
>> >>
>> >> The fact that instantiation happens during device introspection but
>> >> realization does not implies:
>> >> - Instance properties should be added in #TypeInfo.instance_init.
>> >> - Instantiation must not have any side effect not contained in the
>> >>    instance.
>> >> - Any operations without special requirements should go into @realize so
>> >>    that they can be skipped during device introspection.
>> >>
>> >> Note these two facts to guide appropriate instantiation and realization.
>> >
>> > Thanks for sending this. I think we definitely need to try to be
>> > clearer about what to do in instance_init and what to do in realize.
>> >
>> >> Signed-off-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>
>> >
>> >>    * Realization
>> >>    * -----------
>> >>    *
>> >> - * Devices are constructed in two stages:
>> >> - *
>> >> - * 1) object instantiation via object_initialize() and
>> >> - * 2) device realization via the #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.
>> >> - * Operations depending on @props static properties should go into @realize.
>> >> + * Devices are constructed in the following order:
>> >> + *
>> >> + * 1) #TypeInfo.instance_init
>> >> + * 2) pre-realize property value setting

I find "pre-realize" confusing.  Suggest

          2) Set property values

>> >> + * 3) device realization via the #DeviceState.realized property

"via the #DeviceState.realized property" feels like detail.

>> >> + *
>> >> + * #TypeInfo.instance_init may not fail, and realization may return
>> >> + * error information to the caller and must be re-entrant.
>> >
>> > I know this is in the existing text, but what do we mean by
>> > "must be re-entrant" here ? Does this mean "even if you return
>> > a failure from your realize method you must be able to handle the
>> > caller retrying the realize operation" ?  (I'm not sure why that's
>> > a useful thing for the caller to be able to do...)>
>> > I assume we don't mean "even if you successfully realize you must
>> > handle (and treat as a no-op) a second call to realize", because
>> > none of our devices do that :-)
>>
>> If you take the code literally, device_set_realized() indeed avoids
>> calling realize after successful realization, but it doesn't report an
>> error when retrying, so I think this means to allow that.

Note that device_set_realized() is the setter of device property
"realized".

Setting a property to the value it already has is commonly a no-op, not
an error.

>> I don't think it's that useful, and it is likely to cause bunch of bugs.
>> I can also imagine that careful developers have written device code that
>> preserves this contract, though the added complexity is useless in practice.
>>
>> In my opinion, the property should be tristate: initialized, realized,
>> or retired. Then we would have only the following state transitions:
>>
>> Successful realization: initialized -> realized
>> Failed realization: initialized -> retired
>> Unrealization: realized -> retired

Maybe, but this is not the state machine we have.

>> This is another opportunity for refactoring, but for this particular
>> patch I'm planning to keep it out of scope.
>
> OK. We could make the text clearer then, I think. Maybe
>
> "#TypeInfo.instance_init may not fail. #DeviceClass.realize can
> fail, returning error information to the caller. A device realize
> method should handle being called again after it has failed once."
>
> ?

In general, a function should either do its job, or fail cleanly,
i.e. without side effects.

For .realize() "without side effects" includes:

* The failed call is invisible to the guest.

* The device behaves as if the failed call never happened.  This means
  you can try .realize() again.

Does the comment need to spell this out?

[...]

Re: [PATCH v2] qdev: Clarify instantiation and realization

[Peter Maydell]

On Mon, 13 Jul 2026 at 14:20, Markus Armbruster <armbru@redhat.com> wrote:
>
> Peter Maydell <peter.maydell@linaro.org> writes:
> > OK. We could make the text clearer then, I think. Maybe
> >
> > "#TypeInfo.instance_init may not fail. #DeviceClass.realize can
> > fail, returning error information to the caller. A device realize
> > method should handle being called again after it has failed once."
> >
> > ?
>
> In general, a function should either do its job, or fail cleanly,
> i.e. without side effects.
>
> For .realize() "without side effects" includes:
>
> * The failed call is invisible to the guest.
>
> * The device behaves as if the failed call never happened.  This means
>   you can try .realize() again.
>
> Does the comment need to spell this out?

If we want that, I think we should spell it out. I have generally
assumed when writing realize functions that the semantics are
"if this fails, the only thing the caller can usefully do with
the object is destroy it". Realize code very very rarely attempts
to cleanly unwind if it finds an error partway through. I would
expect the only cases where it works at all are the ones where
the only errors are "sanity check of property values etc" that
happens up front.

I would prefer it if we did not require this, because I think
it imposes extra burden on implementations in order to provide
something that is not of any benefit to anybody.

Analogy: for unix sockets, you need to first open() and then
connect(). The connect() manpage and the POSIX spec say that if
connect() fails the only thing you can validly do with the socket
is call close(): you're not allowed to keep it around and try
connect() or some other operation on it.

(We also undoubtedly have a lot of bugs where an error in realize
leaves bits of the device visible to the emulation, or doesn't
free things that were allocated, etc. But that's a separate and
uncontroversial kind of bug. We don't notice these because for
almost all devices the response to "realize failed" is that we're
going to exit QEMU, because the device is part of the machine.)

-- PMM

Re: [PATCH v2] qdev: Clarify instantiation and realization

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Mon, 13 Jul 2026 at 14:20, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Peter Maydell <peter.maydell@linaro.org> writes:
>> > OK. We could make the text clearer then, I think. Maybe
>> >
>> > "#TypeInfo.instance_init may not fail. #DeviceClass.realize can
>> > fail, returning error information to the caller. A device realize
>> > method should handle being called again after it has failed once."
>> >
>> > ?
>>
>> In general, a function should either do its job, or fail cleanly,
>> i.e. without side effects.
>>
>> For .realize() "without side effects" includes:
>>
>> * The failed call is invisible to the guest.
>>
>> * The device behaves as if the failed call never happened.  This means
>>   you can try .realize() again.
>>
>> Does the comment need to spell this out?
>
> If we want that, I think we should spell it out. I have generally
> assumed when writing realize functions that the semantics are
> "if this fails, the only thing the caller can usefully do with
> the object is destroy it". Realize code very very rarely attempts
> to cleanly unwind if it finds an error partway through. I would
> expect the only cases where it works at all are the ones where
> the only errors are "sanity check of property values etc" that
> happens up front.
>
> I would prefer it if we did not require this, because I think
> it imposes extra burden on implementations in order to provide
> something that is not of any benefit to anybody.

No objection, as long as the function contract is clear.

> Analogy: for unix sockets, you need to first open() and then
> connect(). The connect() manpage and the POSIX spec say that if
> connect() fails the only thing you can validly do with the socket
> is call close(): you're not allowed to keep it around and try
> connect() or some other operation on it.
>
> (We also undoubtedly have a lot of bugs where an error in realize
> leaves bits of the device visible to the emulation, or doesn't
> free things that were allocated, etc. But that's a separate and
> uncontroversial kind of bug. We don't notice these because for
> almost all devices the response to "realize failed" is that we're
> going to exit QEMU, because the device is part of the machine.)

Yes.

Re: [PATCH v2] qdev: Clarify instantiation and realization

[Akihiko Odaki]

On 2026/07/13 22:20, Markus Armbruster wrote:
> Peter Maydell <peter.maydell@linaro.org> writes:
> 
>> On Mon, 13 Jul 2026 at 12:21, Akihiko Odaki
>> <odaki@rsg.ci.i.u-tokyo.ac.jp> wrote:
>>>
>>> On 2026/07/13 18:13, Peter Maydell wrote:
>>>> On Mon, 29 Jun 2026 at 09:18, Akihiko Odaki
>>>> <odaki@rsg.ci.i.u-tokyo.ac.jp> wrote:
>>>>>
>>>>> The distinction of instantiation and realization was vague in the old
>>>>> documentation so this change clarifies it.
>>>>>
>>>>> The old documentation said:
>>>>>> 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.
>>>>>> Operations depending on @props static properties should go into
>>>>>> @realize.
>>>>>
>>>>> The first problem with the old documentation is that it is unclear what
>>>>> "trivial field initializations" means and why triviality makes
>>>>> initialization appropriate for #TypeInfo.instance_init. Another problem
>>>>> is that the documentation is not comprehensive enough; for example, it
>>>>> mentions @props static properties, but it does not say anything about
>>>>> the other properties.
>>>>>
>>>>> The keys to distinguish instantiation and realization are property
>>>>> setting and device introspection. The fact that property setting happens
>>>>> after #TypeInfo.instance_init and before realization implies that
>>>>> operations depending on properties should go into @realize.
>>>>>
>>>>> The fact that instantiation happens during device introspection but
>>>>> realization does not implies:
>>>>> - Instance properties should be added in #TypeInfo.instance_init.
>>>>> - Instantiation must not have any side effect not contained in the
>>>>>     instance.
>>>>> - Any operations without special requirements should go into @realize so
>>>>>     that they can be skipped during device introspection.
>>>>>
>>>>> Note these two facts to guide appropriate instantiation and realization.
>>>>
>>>> Thanks for sending this. I think we definitely need to try to be
>>>> clearer about what to do in instance_init and what to do in realize.
>>>>
>>>>> Signed-off-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>
>>>>
>>>>>     * Realization
>>>>>     * -----------
>>>>>     *
>>>>> - * Devices are constructed in two stages:
>>>>> - *
>>>>> - * 1) object instantiation via object_initialize() and
>>>>> - * 2) device realization via the #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.
>>>>> - * Operations depending on @props static properties should go into @realize.
>>>>> + * Devices are constructed in the following order:
>>>>> + *
>>>>> + * 1) #TypeInfo.instance_init
>>>>> + * 2) pre-realize property value setting
> 
> I find "pre-realize" confusing.  Suggest
> 
>            2) Set property values

I used "pre-realize" to distinguish this phase from property changes
that can happen after realization.

> 
>>>>> + * 3) device realization via the #DeviceState.realized property
> 
> "via the #DeviceState.realized property" feels like detail.

Nice catch. I kept the original text here, but this is a good 
opportunity to make it more concise. I'll drop it in the next version.

> 
>>>>> + *
>>>>> + * #TypeInfo.instance_init may not fail, and realization may return
>>>>> + * error information to the caller and must be re-entrant.
>>>>
>>>> I know this is in the existing text, but what do we mean by
>>>> "must be re-entrant" here ? Does this mean "even if you return
>>>> a failure from your realize method you must be able to handle the
>>>> caller retrying the realize operation" ?  (I'm not sure why that's
>>>> a useful thing for the caller to be able to do...)>
>>>> I assume we don't mean "even if you successfully realize you must
>>>> handle (and treat as a no-op) a second call to realize", because
>>>> none of our devices do that :-)
>>>
>>> If you take the code literally, device_set_realized() indeed avoids
>>> calling realize after successful realization, but it doesn't report an
>>> error when retrying, so I think this means to allow that.
> 
> Note that device_set_realized() is the setter of device property
> "realized".
> 
> Setting a property to the value it already has is commonly a no-op, not
> an error.

This is about the retrying scenario i.e., "even if you return a failure 
from your realize method you must be able to handle the caller retrying 
the realize operation".

> 
>>> I don't think it's that useful, and it is likely to cause bunch of bugs.
>>> I can also imagine that careful developers have written device code that
>>> preserves this contract, though the added complexity is useless in practice.
>>>
>>> In my opinion, the property should be tristate: initialized, realized,
>>> or retired. Then we would have only the following state transitions:
>>>
>>> Successful realization: initialized -> realized
>>> Failed realization: initialized -> retired
>>> Unrealization: realized -> retired
> 
> Maybe, but this is not the state machine we have.
> 
>>> This is another opportunity for refactoring, but for this particular
>>> patch I'm planning to keep it out of scope.
>>
>> OK. We could make the text clearer then, I think. Maybe
>>
>> "#TypeInfo.instance_init may not fail. #DeviceClass.realize can
>> fail, returning error information to the caller. A device realize
>> method should handle being called again after it has failed once."
>>
>> ?
> 
> In general, a function should either do its job, or fail cleanly,
> i.e. without side effects.
> 
> For .realize() "without side effects" includes:
> 
> * The failed call is invisible to the guest.
> 
> * The device behaves as if the failed call never happened.  This means
>    you can try .realize() again.
> 
> Does the comment need to spell this out?

Practically I think it's irrelevant.

Indeed failing cleanly is a generic good practice and we currently have 
that explicitly spelled it out here. In reality, however, the retrying 
path is never tested and it would break things in interesting ways if 
you exercise it. So I think the tristate I described above is already 
accidentally formed and the realized property is not accurately 
representing it.

Considering that reality of device lifecycle instead of the realized 
property, which is just an extra detail, I regard it as a documented 
invariant not enforced and it is rather misleading.

Regards,
Akihiko Odaki