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
is "trivial" field initializations and why fields being trivial makes
them 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 property setting happens
after instantiation and before realization implies that operations
depending on properties should go into @realize.

The fact that initialization happens for device introspection but
realization implies:
- Properties should be added during instantiation.
- Instantiation must not have any side effect not contained in the
  instance.
- Any operations without special requirements should go @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>
---
 include/hw/qdev-core.h | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/include/hw/qdev-core.h b/include/hw/qdev-core.h
index 530f3da70218..58f831a198ba 100644
--- a/include/hw/qdev-core.h
+++ b/include/hw/qdev-core.h
@@ -21,16 +21,19 @@
  * Realization
  * -----------
  *
- * Devices are constructed in two stages:
+ * Devices are constructed in three stages:
  *
- * 1) object instantiation via object_initialize() and
- * 2) device realization via the #DeviceState.realized property
+ * 1) object instantiation via object_initialize()
+ * 2) initial property value setting
+ * 3) 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
+ * Instantiation may not fail, and realization 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.
+ * Instantiation should add 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

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

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