Re: [PATCH 2/2] vfree: Update documentation

[Matthew Wilcox <willy@infradead.org>]

On Tue, Sep 22, 2020 at 04:35:06PM +0200, Christoph Hellwig wrote:
> >  /**
> > - * vfree - release memory allocated by vmalloc()
> > - * @addr:  memory base address
> > + * vfree - Release memory allocated by vmalloc()
> > + * @addr:  Memory base address
> >   *
> >   * Free the virtually continuous memory area starting at @addr, as
> > + * obtained from vmalloc(), vmalloc_32() or __vmalloc().  If called
> > + * on an @addr obtained from vmap(), it will put one refcount on each
> > + * mapped page, which will free the page if this is the last refcount
> > + * on the page.  If @addr is NULL, no operation is performed.
> 
> This reads a little confusing.  First it only allows vmalloc* and
> then it mentions vmap in the next sentence.  And what about
> vmalloc_32_user, vzalloc_node, vmalloc_node, vmalloc_user, vzalloc and
> __vmalloc_node?

In my defence, I didn't write that sentence; you snipped:

- * obtained from vmalloc(), vmalloc_32() or __vmalloc(). If @addr is
- * NULL, no operation is performed.

I don't think it makes sense to list all vmalloc-style allocators here.
It won't be updated by people who add new variations.  How about this?

 * Free the virtually continuous memory area starting at @addr, as
 * obtained from one of the vmalloc() family of APIs.  This will
 * usually also free the physical memory underlying the virtual
 * allocation, but that memory is reference counted, so it will not
 * be freed until the last user goes away.
 *
 * If @addr is NULL, no operation is performed.

I'm trying to strike a balance between being accurate and not requiring
device driver authors to learn all about struct page.  I may be too
close to the implementation to write good documentation for it.