hw/qdev: Clarify instantiation and realization

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 instance
property setting and device introspection. The fact that initial
instance 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 may 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.
- Instance properties added during realization will not be configurable
  or introspectable before realization.

Note these two facts to guide appropriate instantiation and realization.

We also omit mention of the realized property because it is a QOM
interface detail, not part of the device API.

The statements regarding a future prospect to propagate the realization
state change are removed. Device realization is propagated to child
buses, but not to the devices on those buses. The proposed recursive
propagation to child devices has not been achieved after 13 years, has
been questioned [1], and is not relevant with the current API usage.

[1] https://lore.kernel.org/qemu-devel/878syd84s3.fsf@dusky.pond.sub.org/

Signed-off-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Message-ID: <20260914-qdev-v4-1-93f849b4865c@rsg.ci.i.u-tokyo.ac.jp>
Signed-off-by: Philippe Mathieu-Daudé <philmd@oss.qualcomm.com>