From: Akihiko Odaki Date: Wed, 24 Sep 2025 04:37:20 +0000 (+0900) Subject: docs/devel: Do not unparent in instance_finalize() X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=62e82053fc676e9493dc2c2072352634b8cd655d;p=thirdparty%2Fqemu.git docs/devel: Do not unparent in instance_finalize() 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 Reviewed-by: Daniel P. Berrangé Link: https://lore.kernel.org/r/20250924-use-v4-1-07c6c598f53d@rsg.ci.i.u-tokyo.ac.jp Signed-off-by: Paolo Bonzini --- diff --git a/docs/devel/memory.rst b/docs/devel/memory.rst index 42d3ca29c43..f22146e56ce 100644 --- a/docs/devel/memory.rst +++ b/docs/devel/memory.rst @@ -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