)]}'
{
  "commit": "707077eafc8986ccb885ede1c82b13ca2a1bd01a",
  "tree": "a7324d6f97f76a06c67f2d7545a21d066ba744a8",
  "parents": [
    "af91171a2f804ed9a8e89861f6ca2f0b93227892"
  ],
  "author": {
    "name": "Akihiko Odaki",
    "email": "odaki@rsg.ci.i.u-tokyo.ac.jp",
    "time": "Mon Sep 14 18:31:49 2026 +0900"
  },
  "committer": {
    "name": "Philippe Mathieu-Daudé",
    "email": "philmd@oss.qualcomm.com",
    "time": "Sun Sep 27 09:30:12 2026 +0200"
  },
  "message": "hw/qdev: Clarify instantiation and realization\n\nThe distinction of instantiation and realization was vague in the old\ndocumentation so this change clarifies it.\n\nThe old documentation said:\n\u003e The former may not fail (and must not abort or exit, since it is\n\u003e called during device introspection already), and the latter may return\n\u003e error information to the caller and must be re-entrant.\n\u003e Trivial field initializations should go into #TypeInfo.instance_init.\n\u003e Operations depending on @props static properties should go into\n\u003e @realize.\n\nThe first problem with the old documentation is that it is unclear what\n\"trivial field initializations\" means and why triviality makes\ninitialization appropriate for #TypeInfo.instance_init. Another problem\nis that the documentation is not comprehensive enough; for example, it\nmentions @props static properties, but it does not say anything about\nthe other properties.\n\nThe keys to distinguish instantiation and realization are instance\nproperty setting and device introspection. The fact that initial\ninstance property setting happens after #TypeInfo.instance_init and\nbefore realization implies that operations depending on properties\nshould go into @realize.\n\nThe fact that instantiation happens during device introspection but\nrealization does not implies:\n- Instance properties may be added in #TypeInfo.instance_init.\n- Instantiation must not have any side effect not contained in the\n  instance.\n- Any operations without special requirements should go into @realize so\n  that they can be skipped during device introspection.\n- Instance properties added during realization will not be configurable\n  or introspectable before realization.\n\nNote these two facts to guide appropriate instantiation and realization.\n\nWe also omit mention of the realized property because it is a QOM\ninterface detail, not part of the device API.\n\nThe statements regarding a future prospect to propagate the realization\nstate change are removed. Device realization is propagated to child\nbuses, but not to the devices on those buses. The proposed recursive\npropagation to child devices has not been achieved after 13 years, has\nbeen questioned [1], and is not relevant with the current API usage.\n\n[1] https://lore.kernel.org/qemu-devel/878syd84s3.fsf@dusky.pond.sub.org/\n\nSigned-off-by: Akihiko Odaki \u003codaki@rsg.ci.i.u-tokyo.ac.jp\u003e\nReviewed-by: Peter Maydell \u003cpeter.maydell@linaro.org\u003e\nMessage-ID: \u003c20260914-qdev-v4-1-93f849b4865c@rsg.ci.i.u-tokyo.ac.jp\u003e\nSigned-off-by: Philippe Mathieu-Daudé \u003cphilmd@oss.qualcomm.com\u003e\n",
  "tree_diff": [
    {
      "type": "modify",
      "old_id": "1f6bf3fc1abf2f3c67aa753d31f5955e77fe312b",
      "old_mode": 33188,
      "old_path": "include/hw/core/qdev.h",
      "new_id": "8e91e2fcb086d9912d332731555a3a658027a492",
      "new_mode": 33188,
      "new_path": "include/hw/core/qdev.h"
    }
  ]
}