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

["Alejandro Vallejo" <alejandro.vallejo@xxxxxxxxx>]

On Wed Jul 3, 2024 at 12:58 PM BST, Jan Beulich wrote:
> 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

Sounds good to me.

Cheers,
Alejandro