On Wed, Sep 17, 2025 at 07:13:26PM +0900, Akihiko Odaki wrote: > 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 <od...@rsg.ci.i.u-tokyo.ac.jp> > --- > docs/devel/memory.rst | 19 ++++++------------- > 1 file changed, 6 insertions(+), 13 deletions(-) > > diff --git a/docs/devel/memory.rst b/docs/devel/memory.rst > index 57fb2aec76e0..749f11d8a4dd 100644 > --- a/docs/devel/memory.rst > +++ b/docs/devel/memory.rst > @@ -161,18 +161,11 @@ or never. > Destruction of a memory region happens automatically when the owner > object dies. > > -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.
Should we still keep some of these examples? After the series they'll be doing the right things. Dynamic MRs are still slightly tricky, I think it's still good to have some references. > - > 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. > +The dynamically allocated data structure that contains the > +memory region should be freed in the instance_finalize callback. > > If you break this rule, the following situation can happen: > > @@ -198,9 +191,9 @@ 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. You must never call > +object_unparent on regions that have no owner, unless they are aliases > +or containers. This looks like a completely separate change. So we start to allow machines to be finalized now? I'm not familiar with machine object lifecycles. Maybe split it out even if it's true? -- Peter Xu
