Re: [PATCH for-4.19 v2] xen/vmap: Document the vmap header

[Jan Beulich <jbeulich@xxxxxxxx>]

On 03.07.2024 13:19, Alejandro Vallejo wrote:
> +/*
> + * Unmaps a range of virtually contiguous memory from one of the vmap regions
> + *
> + * The system remembers internally how wide the mapping is and unmaps it all.

Seeing this is still taken verbatim ...

> + * It also can determine the vmap region type from the `va`.
> + *
> + * @param va Virtual base address of the range to unmap
> + */
>  void vunmap(const void *va);
>  
> +/*
> + * Allocate `size` octets of possibly non-contiguous physical memory and map
> + * them contiguously in the VMAP_DEFAULT vmap region
> + *
> + * @param size Pointer to the base of an array of mfns
> + * @return Pointer to the mapped area on success; NULL otherwise.
> + */
>  void *vmalloc(size_t size);
> +
> +/* Same as vmalloc(), but for the VMAP_XEN vmap region. */
>  void *vmalloc_xen(size_t size);
>  
> +/* Same as vmalloc(), but set the contents to zero before returning */
>  void *vzalloc(size_t size);
> +
> +/*
> + * Unmap and free memory from vmalloc(), vmalloc_xen() or vzalloc()
> + *
> + * The system remembers internally how wide the mapping is and unmaps it all.
> + *
> + * @param va Virtual base address of the range to free and unmap
> + */
>  void vfree(void *va);

... here (just moved to the proper place now), I further wonder: Why just
"mapping" and "unmap". The function is also (one might even say primarily)
about freeing. IOW perhaps "how wide the allocation is and unmaps/frees it
all"?

Happy to adjust while committing, at which point:
Acked-by: Jan Beulich <jbeulich@xxxxxxxx>

Jan