Re: [PATCH v2 3/3] softmmu/physmem: Fixup qemu_ram_block_from_host() documentation

[Igor Mammedov <imammedo@redhat.com>]

On Thu, 16 Mar 2023 16:36:58 +0100
David Hildenbrand <david@redhat.com> wrote:

> Let's fixup the documentation (e.g., removing traces of the ram_addr_t
                                                               ^^^^^^^^^
_t typo?

> parameter that no longer exists) and move it to the header file while at
> it.
> 
> Suggested-by: Igor Mammedov <imammedo@redhat.com>
> Signed-off-by: David Hildenbrand <david@redhat.com>
> ---
>  include/exec/cpu-common.h | 15 +++++++++++++++
>  softmmu/physmem.c         | 17 -----------------
>  2 files changed, 15 insertions(+), 17 deletions(-)
> 
> diff --git a/include/exec/cpu-common.h b/include/exec/cpu-common.h
> index 6feaa40ca7..edef5bee21 100644
> --- a/include/exec/cpu-common.h
> +++ b/include/exec/cpu-common.h
> @@ -75,6 +75,21 @@ void qemu_ram_remap(ram_addr_t addr, ram_addr_t length);
>  ram_addr_t qemu_ram_addr_from_host(void *ptr);
>  ram_addr_t qemu_ram_addr_from_host_nofail(void *ptr);
>  RAMBlock *qemu_ram_block_by_name(const char *name);
> +
> +/*
> + * Translates a host ptr back to a RAMBlock and an offset in that RAMBlock.
> + *
> + * @ptr: The host pointer to transalte.
> + * @round_offset: Whether to round the result offset down to a target page
> + * @offset: Will be set to the offset within the returned RAMBlock.
> + *
> + * Returns: RAMBlock (or NULL if not found)
> + *
> + * By the time this function returns, the returned pointer is not protected
> + * by RCU anymore.  If the caller is not within an RCU critical section and
> + * does not hold the iothread lock, it must have other means of protecting the
> + * pointer, such as a reference to the memory region that owns the RAMBlock.
> + */
>  RAMBlock *qemu_ram_block_from_host(void *ptr, bool round_offset,
>                                     ram_addr_t *offset);
>  ram_addr_t qemu_ram_block_host_offset(RAMBlock *rb, void *host);
> diff --git a/softmmu/physmem.c b/softmmu/physmem.c
> index fb412a56e1..36b33786fd 100644
> --- a/softmmu/physmem.c
> +++ b/softmmu/physmem.c
> @@ -2169,23 +2169,6 @@ ram_addr_t qemu_ram_block_host_offset(RAMBlock *rb, void *host)
>      return res;
>  }
>  
> -/*
> - * Translates a host ptr back to a RAMBlock, a ram_addr and an offset
> - * in that RAMBlock.
> - *
> - * ptr: Host pointer to look up
> - * round_offset: If true round the result offset down to a page boundary
> - * *ram_addr: set to result ram_addr
> - * *offset: set to result offset within the RAMBlock
> - *
> - * Returns: RAMBlock (or NULL if not found)
> - *
> - * By the time this function returns, the returned pointer is not protected
> - * by RCU anymore.  If the caller is not within an RCU critical section and
> - * does not hold the iothread lock, it must have other means of protecting the
> - * pointer, such as a reference to the region that includes the incoming
> - * ram_addr_t.
> - */
>  RAMBlock *qemu_ram_block_from_host(void *ptr, bool round_offset,
>                                     ram_addr_t *offset)
>  {