[v2,05/25] mm: Fix documentation of FGP flags

Message ID	20200212041845.25879-6-willy@infradead.org (mailing list archive)
State	New, archived
Headers	show Return-Path: <SRS0=LM+d=4A=kvack.org=owner-linux-mm@kernel.org> DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 6292821569 From: Matthew Wilcox <willy@infradead.org> To: linux-fsdevel@vger.kernel.org, linux-mm@kvack.org Cc: "Matthew Wilcox (Oracle)" <willy@infradead.org>, linux-kernel@vger.kernel.org Subject: [PATCH v2 05/25] mm: Fix documentation of FGP flags Date: Tue, 11 Feb 2020 20:18:25 -0800 Message-Id: <20200212041845.25879-6-willy@infradead.org> In-Reply-To: <20200212041845.25879-1-willy@infradead.org> References: <20200212041845.25879-1-willy@infradead.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: owner-linux-mm@kvack.org Precedence: bulk
Series	Large pages in the page cache \| expand [v2,00/25] Large pages in the page cache [v2,01/25] mm: Use vm_fault error code directly [v2,02/25] mm: Optimise find_subpage for !THP [v2,03/25] mm: Use VM_BUG_ON_PAGE in clear_page_dirty_for_io [v2,04/25] mm: Unexport find_get_entry [v2,05/25] mm: Fix documentation of FGP flags [v2,06/25] mm: Allow hpages to be arbitrary order [v2,07/25] mm: Introduce thp_size [v2,08/25] mm: Introduce thp_order [v2,09/25] fs: Add a filesystem flag for large pages [v2,10/25] fs: Introduce i_blocks_per_page [v2,11/25] fs: Make page_mkwrite_check_truncate thp-aware [v2,12/25] mm: Add file_offset_of_ helpers [v2,13/25] fs: Add zero_user_large [v2,14/25] iomap: Support arbitrarily many blocks per page [v2,15/25] iomap: Support large pages in iomap_adjust_read_range [v2,16/25] iomap: Support large pages in read paths [v2,17/25] iomap: Support large pages in write paths [v2,18/25] iomap: Inline data shouldn't see large pages [v2,19/25] xfs: Support large pages [v2,20/25] mm: Make prep_transhuge_page return its argument [v2,21/25] mm: Add __page_cache_alloc_order [v2,22/25] mm: Allow large pages to be added to the page cache [v2,23/25] mm: Allow large pages to be removed from the page cache [v2,24/25] mm: Add large page readahead [v2,25/25] mm: Align THP mappings for non-DAX

Matthew Wilcox Feb. 12, 2020, 4:18 a.m. UTC

From: "Matthew Wilcox (Oracle)" <willy@infradead.org>

We never had PCG flags; they've been called FGP flags since their
introduction in 2014.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 mm/filemap.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

Christoph Hellwig Feb. 12, 2020, 7:42 a.m. UTC | #1

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.

Matthew Wilcox Feb. 12, 2020, 7:11 p.m. UTC | #2

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)
 {

Kirill A. Shutemov Feb. 13, 2020, 1:59 p.m. UTC | #3

On Tue, Feb 11, 2020 at 08:18:25PM -0800, Matthew Wilcox wrote:
> From: "Matthew Wilcox (Oracle)" <willy@infradead.org>
> 
> We never had PCG flags

We actually had :P But it's totally different story.

See git log for include/linux/page_cgroup.h.

Kirill A. Shutemov Feb. 13, 2020, 2 p.m. UTC | #4

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@linux.intel.com>

Matthew Wilcox Feb. 13, 2020, 2:34 p.m. UTC | #5

On Thu, Feb 13, 2020 at 04:59:05PM +0300, Kirill A. Shutemov wrote:
> On Tue, Feb 11, 2020 at 08:18:25PM -0800, Matthew Wilcox wrote:
> > From: "Matthew Wilcox (Oracle)" <willy@infradead.org>
> > 
> > We never had PCG flags
> 
> We actually had :P But it's totally different story.
> 
> See git log for include/linux/page_cgroup.h.

Thanks, wording updated.

[v2,05/25] mm: Fix documentation of FGP flags

Commit Message

Comments

Patch