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

[Oleksii <oleksii.kurochko@xxxxxxxxx>]

On Wed, 2024-07-03 at 13:58 +0200, 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>
Release-Acked-by: Oleksii Kurochko <oleksii.kurochko@xxxxxxxxx>

~ Oleskii