On 2026/07/13 22:20, Markus Armbruster wrote:
Peter Maydell <[email protected]> writes:
On Mon, 13 Jul 2026 at 12:21, Akihiko Odaki
<[email protected]> wrote:
On 2026/07/13 18:13, Peter Maydell wrote:
On Mon, 29 Jun 2026 at 09:18, Akihiko Odaki
<[email protected]> 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 <[email protected]>
* 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
