qdev currently represents a device's realization state with a single
boolean. This cannot distinguish a device that has never been realized
from one whose realization has failed or that has been unrealized, nor
can it represent realization in progress. Consequently, the same device
can enter DeviceClass::realize() reentrantly or more than once.
Supporting that complicates device implementations, and the behavior is
untested and likely broken.

The accessor conversions, const qualification of qdev_is_realized(), and
QOM-parenting fix from earlier revisions have already been merged. This
revision contains the four remaining patches.

The first patch clarifies the division of work between
TypeInfo.instance_init, pre-realize property setting, and
DeviceClass::realize, including the implications of device introspection
and property-dependent child creation.

The other three patches replace DeviceState::realized and the QOM
realized property with four explicit phases: initialized, realizing,
realized, and retired. Entering the realizing phase before invoking
callbacks prevents reentrant realization. A failure after realization
starts, or the start of unrealization, moves the device to the terminal
retired phase, so a device's realize method is invoked at most once.

Signed-off-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>
---
Changes in v4:
- Dropped the merged accessor conversions, const qualification, and
  QOM-parenting fix.
- Split the phase conversion into three patches.
- Clarified automatic child-bus realization and explicit child-device
  realization, and removed the obsolete plan for recursive realization
  propagation.
- Documented that properties added during realization are neither
  configurable nor introspectable beforehand.
- Initialized DeviceState::phase explicitly.
- Updated the DevicePhase introduction version to 11.2.
- Link to v3: https://lore.kernel.org/qemu-devel/20260721-qdev-v3-0-d2e226fa002e@rsg.ci.i.u-tokyo.ac.jp

Changes in v3:
- Ensured devices are QOM-parented before attaching them to a bus,
  avoiding unparentable bus children when realization fails.
- Clarified property-dependent child creation.
- Removed documentation references to the QOM realized property.
- Replaced DeviceState::realized and the QOM realized property with
  device phases. The realizing phase prevents reentrant realization, and
  the terminal retired phase prevents another attempt after realization
  fails or unrealization begins.
- Link to v2: https://lore.kernel.org/qemu-devel/20260629-qdev-v2-1-8cd1d9be0d8d@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

---
Akihiko Odaki (4):
      qdev: Clarify instantiation and realization
      hw/qdev: Introduce DevicePhase
      hw/qdev: Introduce the initialized and retired phases
      hw/qdev: Introduce the realizing phase

 qapi/common.json          |  19 ++++++++
 include/hw/core/qdev.h    |  50 ++++++++++-----------
 hw/core/qdev-clock.c      |   4 +-
 hw/core/qdev-properties.c |   4 +-
 hw/core/qdev.c            |  99 ++++++++++++++++++++++++++--------------
 hw/scsi/scsi-bus.c        |   4 +-
 qom/qom-qmp-cmds.c        |   2 +-
 system/qdev-monitor.c     |   5 ++-
 tests/unit/test-qdev.c    | 112 +++++++++++++++++++++++++++++++++++++++++++++-
 9 files changed, 231 insertions(+), 68 deletions(-)
---
base-commit: 209b2afaface001c7d4d981e38f186afe7b24a50
change-id: 20250906-qdev-9e5cb7c06ffa

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