linux-kernel - Re: [PATCH 2/2] vfree: Update documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Tue, 22 Sep 2020 16:06:03 +0100
From:   Matthew Wilcox <willy@...radead.org>
To:     Christoph Hellwig <hch@....de>
Cc:     Andrew Morton <akpm@...ux-foundation.org>, linux-mm@...ck.org,
        linux-kernel@...r.kernel.org, Uladzislau Rezki <urezki@...il.com>
Subject: Re: [PATCH 2/2] vfree: Update documentation

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.