Skip to contentSkip to conversation

docs/devel: Prohibit calling object_unparent() for memory region

PATCH In review Akihiko Odaki 3 participants 5 messages Aug 29, 2024 – Oct 12, 2024

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs/devel: Prohibit calling object_unparent() for memory region

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.

---
 docs/devel/memory.rst | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)
docs/devel/memory.rst +7 -7
index 69c5e3f914ac..83760279e3db 100644
@@ -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,

Signature · 1 line
Akihiko Odaki <[email protected]>
Acked-by on v1 1/1
#1 lore raw
Quoted 11 lines · 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.

who's applying this? Paolo?

Quoted 44 lines
---
 docs/devel/memory.rst | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)
docs/devel/memory.rst +7 -8
index 69c5e3f914ac..83760279e3db 100644
@@ -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,

Signature · 1 line
Akihiko Odaki <[email protected]>
#2 lore raw
Quoted 12 lines · Michael S. Tsirkin
Quoted 10 lines · 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.

Quoted 6 lines
Quoted 1 line

who's applying this? Paolo?

It's a docs change to clarify a complex point that's under active discussion in a different patch thread, so it needs review before anybody applies it...

-- PMM

#3 lore raw
In reply to Akihiko Odaki

On Thu, 29 Aug 2024 at 06:46, Akihiko Odaki <[email protected]> wrote:

Hi; sorry it's taken me so long to get back to this patch, but I've now re-read some of the discussion in the other threads. I generally agree with your reasoning and think we do need to update the docs here.

I think we could be more specific in this commit message; I've suggested some expansions of it below. (Partly this is for my own benefit working through what's going on.)

Quoted 4 lines

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().

"because child objects are properties of their owner object, and (since commit 76a6e1cc7cc3a) we delete an object's properties before calling the object's instance_finalize method. Deleting the child property will unparent the child; the later calls to object_unparent() in its owner's instance_finalize will do nothing.".

Quoted 2 lines

Worse, memory regions typically gets finalized when they get unparented before instance_finalize().

"before instance_finalize(), because the only reference to the MemoryRegion is the one we hold because it is a child property of its owner, and so when object_finalize_child_property() calls object_unref(child) the refcount drops to zero and we finalize the MR."

Quoted 3 lines

This means calling object_unparent() for
them in instance_finalize() is to call the function for an object already finalized, which should be avoided.

"This doesn't cause any bad effects in the common case where we know that the memory allocated for the MemoryRegion itself is still valid, such as in the common case where the MR struct is directly embedded in its owner's device state struct. But it could potentially cause a crash if the MemoryRegion struct was somewhere else and was freed.

Update the documentation to explicitly prohibit calling object_unparent() in instance_finalize."

docs/devel/memory.rst and VFIOQuirk in hw/vfio/pci.c.

Quoted 11 lines
---
 docs/devel/memory.rst | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)
docs/devel/memory.rst +0 -0
index 69c5e3f914ac..83760279e3db 100644
@@ -168,11 +168,10 @@ and VFIOQuirk in hw/vfio/pci.c.

Don't we need also to change the paragraph before this, which reads:

Quoted 4 lines

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.

?

Otherwise we have a paragraph that says "you should call object_unparent()" followed by one that says "do not call object_unparent()".

(Also that paragraph's reference to VFIOMSIXInfo is now out of date -- in 2017 we removed the embedded MemoryRegion from that struct.)

docs/devel/memory.rst and VFIOQuirk in hw/vfio/pci.c. · line 174

Quoted 11 lines

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

docs/devel/memory.rst +4 -5
-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.

I think some of these lines are a touch over-length, and should be wrapped a bit earlier.

Also, this now says "don't unparent in finalize", but vfio_bars_finalize() has code which follows the old documentation:

    if (vdev->vga) {
        vfio_vga_quirk_finalize(vdev);
        for (i = 0; i < ARRAY_SIZE(vdev->vga->region); i++) {
            object_unparent(OBJECT(&vdev->vga->region[i].mem));
        }
        g_free(vdev->vga);
    }

Is this wrong and needs changing?

docs/devel/memory.rst but nevertheless it is used in a few places. · line 203

Quoted 11 lines

If you break this rule, the following situation can happen:

docs/devel/memory.rst +3 -2
@@ -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.

thanks
-- PMM

#4 lore raw
Quoted 35 lines · Peter Maydell

On Thu, 29 Aug 2024 at 06:46, Akihiko Odaki <[email protected]> wrote:

Hi; sorry it's taken me so long to get back to this patch, but I've now re-read some of the discussion in the other threads. I generally agree with your reasoning and think we do need to update the docs here.

I think we could be more specific in this commit message; I've suggested some expansions of it below. (Partly this is for my own benefit working through what's going on.)

Quoted 4 lines

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().

"because child objects are properties of their owner object, and (since commit 76a6e1cc7cc3a) we delete an object's properties before calling the object's instance_finalize method. Deleting the child property will unparent the child; the later calls to object_unparent() in its owner's instance_finalize will do nothing.".

Quoted 2 lines

Worse, memory regions typically gets finalized when they get unparented before instance_finalize().

"before instance_finalize(), because the only reference to the MemoryRegion is the one we hold because it is a child property of its owner, and so when object_finalize_child_property() calls object_unref(child) the refcount drops to zero and we finalize the MR."

Quoted 3 lines

This means calling object_unparent() for
them in instance_finalize() is to call the function for an object already finalized, which should be avoided.

Quoted 6 lines

"This doesn't cause any bad effects in the common case where we know that the memory allocated for the MemoryRegion itself is still valid, such as in the common case where the MR struct is directly embedded in its owner's device state struct. But it could potentially cause a crash if the MemoryRegion struct was somewhere else and was freed.

It won't cause a crash even if the MR struct is not embedded as long as the data structure is freed in the instance_finalize callback. I suggest the following:

"This doesn't cause any bad effects in the common case where the data structure is managed by the owner because the memory allocated for the MemoryRegion itself is valid until the owner is also finalized. However, it is still semantically wrong to touch the MemoryRegion after its finalization and confusing."

Your other suggestions look good so I'll apply them with v2.

Quoted 24 lines

Update the documentation to explicitly prohibit calling object_unparent() in instance_finalize."

docs/devel/memory.rst and VFIOQuirk in hw/vfio/pci.c.

Quoted 11 lines
---
  docs/devel/memory.rst | 14 +++++++-------
  1 file changed, 7 insertions(+), 7 deletions(-)
docs/devel/memory.rst +0 -0
index 69c5e3f914ac..83760279e3db 100644
@@ -168,11 +168,10 @@ and VFIOQuirk in hw/vfio/pci.c.

Don't we need also to change the paragraph before this, which reads:

Quoted 4 lines

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.

Quoted 5 lines

?

Otherwise we have a paragraph that says "you should call object_unparent()" followed by one that says "do not call object_unparent()".

You are right. I'll remove the statement.

Quoted 5 lines

(Also that paragraph's reference to VFIOMSIXInfo is now out of date -- in 2017 we removed the embedded MemoryRegion from that struct.)

Quoted 14 lines

docs/devel/memory.rst and VFIOQuirk in hw/vfio/pci.c. · line 174

Quoted 11 lines

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

docs/devel/memory.rst +4 -5
-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.

I think some of these lines are a touch over-length, and should be wrapped a bit earlier.

I'll wrap them by 72 columns.

Quoted 12 lines

Also, this now says "don't unparent in finalize", but vfio_bars_finalize() has code which follows the old documentation:

     if (vdev->vga) {
         vfio_vga_quirk_finalize(vdev);
         for (i = 0; i < ARRAY_SIZE(vdev->vga->region); i++) {
             object_unparent(OBJECT(&vdev->vga->region[i].mem));
         }
         g_free(vdev->vga);
     }
Quoted 1 line

Is this wrong and needs changing?

I'll add a patch to remove object_unparent() calls from hw/vfio/pci.c with v2.

Regards,
Akihiko Odaki

Quoted 15 lines

docs/devel/memory.rst but nevertheless it is used in a few places. · line 203

Quoted 12 lines

If you break this rule, the following situation can happen:

docs/devel/memory.rst +3 -2
@@ -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.

thanks
-- PMM