linux-kernel - Re: [PATCH v2 05/25] mm: Fix documentation of FGP flags

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]

Message-ID: <20200213140018.fv2uj7knrd3chdgz@box>
Date:   Thu, 13 Feb 2020 17:00:18 +0300
From:   "Kirill A. Shutemov" <kirill@...temov.name>
To:     Matthew Wilcox <willy@...radead.org>
Cc:     Christoph Hellwig <hch@...radead.org>,
        linux-fsdevel@...r.kernel.org, linux-mm@...ck.org,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 05/25] mm: Fix documentation of FGP flags

On Wed, Feb 12, 2020 at 11:11:45AM -0800, Matthew Wilcox wrote:
> On Tue, Feb 11, 2020 at 11:42:15PM -0800, Christoph Hellwig wrote:
> > On Tue, Feb 11, 2020 at 08:18:25PM -0800, Matthew Wilcox wrote:
> > > - * @fgp_flags: PCG flags
> > > + * @fgp_flags: FGP flags
> > >   * @gfp_mask: gfp mask to use for the page cache data page allocation
> > >   *
> > >   * Looks up the page cache slot at @mapping & @offset.
> > >   *
> > > - * PCG flags modify how the page is returned.
> > > + * FGP flags modify how the page is returned.
> > 
> > This still looks weird.  Why not just a single line:
> > 
> > 	* @fgp_flags: FGP_* flags that control how the page is returned.
> 
> Well, now you got me reading the entire comment for this function, and
> looking at the html output, so I ended up rewriting it entirely.
> 
> +++ b/mm/filemap.c
> @@ -1574,37 +1574,34 @@ struct page *find_lock_entry(struct address_space *mapping, pgoff_t offset)
>  EXPORT_SYMBOL(find_lock_entry);
>  
>  /**
> - * pagecache_get_page - find and get a page reference
> - * @mapping: the address_space to search
> - * @offset: the page index
> - * @fgp_flags: FGP flags
> - * @gfp_mask: gfp mask to use for the page cache data page allocation
> - *
> - * Looks up the page cache slot at @mapping & @offset.
> + * pagecache_get_page - Find and get a reference to a page.
> + * @mapping: The address_space to search.
> + * @offset: The page index.
> + * @fgp_flags: %FGP flags modify how the page is returned.
> + * @gfp_mask: Memory allocation flags to use if %FGP_CREAT is specified.
>   *
> - * FGP flags modify how the page is returned.
> + * Looks up the page cache entry at @mapping & @offset.
>   *
> - * @fgp_flags can be:
> + * @fgp_flags can be zero or more of these flags:
>   *
> - * - FGP_ACCESSED: the page will be marked accessed
> - * - FGP_LOCK: Page is return locked
> - * - FGP_CREAT: If page is not present then a new page is allocated using
> - *   @gfp_mask and added to the page cache and the VM's LRU
> - *   list. The page is returned locked and with an increased
> - *   refcount.
> - * - FGP_FOR_MMAP: Similar to FGP_CREAT, only we want to allow the caller to do
> - *   its own locking dance if the page is already in cache, or unlock the page
> - *   before returning if we had to add the page to pagecache.
> + * * %FGP_ACCESSED - The page will be marked accessed.
> + * * %FGP_LOCK - The page is returned locked.
> + * * %FGP_CREAT - If no page is present then a new page is allocated using
> + *   @gfp_mask and added to the page cache and the VM's LRU list.
> + *   The page is returned locked and with an increased refcount.
> + * * %FGP_FOR_MMAP - The caller wants to do its own locking dance if the
> + *   page is already in cache.  If the page was allocated, unlock it before
> + *   returning so the caller can do the same dance.
>   *
> - * If FGP_LOCK or FGP_CREAT are specified then the function may sleep even
> - * if the GFP flags specified for FGP_CREAT are atomic.
> + * If %FGP_LOCK or %FGP_CREAT are specified then the function may sleep even
> + * if the %GFP flags specified for %FGP_CREAT are atomic.
>   *
>   * If there is a page cache page, it is returned with an increased refcount.
>   *
> - * Return: the found page or %NULL otherwise.
> + * Return: The found page or %NULL otherwise.
>   */
>  struct page *pagecache_get_page(struct address_space *mapping, pgoff_t offset,
> -       int fgp_flags, gfp_t gfp_mask)
> +               int fgp_flags, gfp_t gfp_mask)
>  {

LGTM:

Acked-by: Kirill A. Shutemov <kirill.shutemov@...ux.intel.com>

-- 
 Kirill A. Shutemov