fridtjof/qemu-cr16
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs/devel: Do not unparent in instance_finalize()

Browse source 
Children are automatically unparented so manually unparenting is
unnecessary.

Worse, automatic unparenting happens before the instance_finalize()
callback of the parent gets called, so object_unparent() calls in
the callback will refer to objects that are already unparented, which
is semantically incorrect.

Remove the instruction to call object_unparent(), and the exception
of the "do not call object_unparent()" rule for instance_finalize().

Signed-off-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Link: https://lore.kernel.org/r/20250924-use-v4-1-07c6c598f53d@rsg.ci.i.u-tokyo.ac.jp
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
This commit is contained in:
Akihiko Odaki 2025-09-24 13:37:20 +09:00 • committed by Paolo Bonzini
parent db05b0d21e
commit 62e82053fc
1 changed files with 6 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

17
docs/devel/memory.rst
View file

@ -165,17 +165,14 @@ and finalized one by one. The order in which memory regions will be
finalized is not guaranteed.
If however the memory region is part of a dynamically allocated data
structure, you should call object_unparent() to destroy the memory region
before the data structure is freed. For an example see VFIOMSIXInfo
and VFIOQuirk in hw/vfio/pci.c.
structure, you should free the memory region in the instance_finalize
callback. For an example see VFIOMSIXInfo and VFIOQuirk in
hw/vfio/pci.c.
You must not destroy a memory region as long as it may be in use by a
device or CPU. In order to do this, as a general rule do not create or
destroy memory regions dynamically during a device's lifetime, and only
call object_unparent() in the memory region owner's instance_finalize
callback. The dynamically allocated data structure that contains the
memory region then should obviously be freed in the instance_finalize
callback as well.
destroy memory regions dynamically during a device's lifetime, and never
call object_unparent().
If you break this rule, the following situation can happen:
@ -201,9 +198,7 @@ this exception is rarely necessary, and therefore it is discouraged,
but nevertheless it is used in a few places.
For regions that "have no owner" (NULL is passed at creation time), the
machine object is actually used as the owner. Since instance_finalize is
never called for the machine object, you must never call object_unparent
on regions that have no owner, unless they are aliases or containers.
machine object is actually used as the owner.
Overlapping regions and priority