Re: [PATCH v6 1/2] memory: Update inline documentation

[Peter Xu]

On Sun, Jan 05, 2025 at 05:56:18PM +0900, Akihiko Odaki wrote:
> Do not refer to "memory region's reference count"
> -------------------------------------------------
> 
> Now MemoryRegions do have their own reference counts, but they will not
> be used when their owners are not themselves. However, the documentation
> of memory_region_ref() says it adds "1 to a memory region's reference
> count", which is confusing. Avoid referring to "memory region's
> reference count" and just say: "Add a reference to a memory region".
> Make a similar change to memory_region_unref() too.
> 
> Refer to docs/devel/memory.rst for "owner"
> ------------------------------------------
> 
> memory_region_ref() and memory_region_unref() used to have their own
> descriptions of "owner", but they are somewhat out-of-date and
> misleading.
> 
> In particular, they say "whenever memory regions are accessed outside
> the BQL, they need to be preserved against hot-unplug", but protecting
> against hot-unplug is not mandatory if it is known that they will never
> be hot-unplugged. They also say "MemoryRegions actually do not have
> their own reference count", but they actually do. They just will not be
> used unless their owners are not themselves.
> 
> Refer to docs/devel/memory.rst as the single source of truth instead of
> maintaining duplicate descriptions of "owner".
> 
> Clarify that owner may be missing
> 
> ---------------------------------
> A memory region may not have an owner, and memory_region_ref() and
> memory_region_unref() do nothing for such.
> 
> memory: Clarify owner must not call memory_region_ref()
> --------------------------------------------------------
> 
> The owner must not call this function as it results in a circular
> reference.
> 
> Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com>

Reviewed-by: Peter Xu <peterx@redhat.com>

-- 
Peter Xu