qemu-devel.nongnu.org archive mirror
 help / color / mirror / Atom feed
* [PATCH] docs/devel: Prohibit calling object_unparent() for memory region
@ 2024-08-29  5:46 Akihiko Odaki
  2024-09-10 17:26 ` Michael S. Tsirkin
  2024-10-08 13:33 ` Peter Maydell
  0 siblings, 2 replies; 5+ messages in thread
From: Akihiko Odaki @ 2024-08-29  5:46 UTC (permalink / raw)
  To: Peter Maydell, Eduardo Habkost, Marcel Apfelbaum,
	Philippe Mathieu-Daudé, Yanan Wang, John Snow,
	BALATON Zoltan, Jiaxun Yang, Nicholas Piggin,
	Daniel Henrique Barboza, David Gibson, Harsh Prateek Bora,
	Alexey Kardashevskiy, Michael S. Tsirkin, Alex Bennée,
	Fabiano Rosas, Paolo Bonzini, David Hildenbrand, Thomas Huth,
	Laurent Vivier, qemu-devel, qemu-block, qemu-ppc
  Cc: Akihiko Odaki

Previously it was allowed to call object_unparent() for a memory region
in instance_finalize() of its parent. However, such a call typically
has no effect because child objects get unparented before
instance_finalize().

Worse, memory regions typically gets finalized when they get unparented
before instance_finalize(). This means calling object_unparent() for
them in instance_finalize() is to call the function for an object
already finalized, which should be avoided.

Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com>
---
 docs/devel/memory.rst | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/devel/memory.rst b/docs/devel/memory.rst
index 69c5e3f914ac..83760279e3db 100644
--- a/docs/devel/memory.rst
+++ b/docs/devel/memory.rst
@@ -168,11 +168,10 @@ 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 do not
+call object_unparent().  The dynamically allocated data structure that contains
+the memory region then should be freed in the instance_finalize callback, which
+is called after it gets unparented.
 
 If you break this rule, the following situation can happen:
 
@@ -199,8 +198,9 @@ 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.
+never called for the machine object, you must never free regions that have no
+owner, unless they are aliases or containers, which you can manually call
+object_unparent() for.
 
 
 Overlapping regions and priority

---
base-commit: 31669121a01a14732f57c49400bc239cf9fd505f
change-id: 20240829-memory-cfd3ee0af44d

Best regards,
-- 
Akihiko Odaki <akihiko.odaki@daynix.com>



^ permalink raw reply related	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2024-10-12  8:08 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-08-29  5:46 [PATCH] docs/devel: Prohibit calling object_unparent() for memory region Akihiko Odaki
2024-09-10 17:26 ` Michael S. Tsirkin
2024-09-10 18:21   ` Peter Maydell
2024-10-08 13:33 ` Peter Maydell
2024-10-12  8:07   ` Akihiko Odaki

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).