From: William Kucharski <william.kucharski@oracle.com>
To: "Matthew Wilcox (Oracle)" <willy@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>,
Linux-Fsdevel <linux-fsdevel@vger.kernel.org>,
"linux-mm@kvack.org" <linux-mm@kvack.org>,
"linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
Jeff Layton <jlayton@kernel.org>
Subject: Re: [PATCH v10 01/33] mm: Introduce struct folio
Date: Sat, 15 May 2021 10:55:19 +0000 [thread overview]
Message-ID: <0FF7A37F-80A8-4B49-909D-6234ADA8A25C@oracle.com> (raw)
In-Reply-To: <20210511214735.1836149-2-willy@infradead.org>
Comment inline:
> On May 11, 2021, at 3:47 PM, Matthew Wilcox (Oracle) <willy@infradead.org> wrote:
>
> A struct folio is a new abstraction to replace the venerable struct page.
> A function which takes a struct folio argument declares that it will
> operate on the entire (possibly compound) page, not just PAGE_SIZE bytes.
> In return, the caller guarantees that the pointer it is passing does
> not point to a tail page.
>
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> Acked-by: Jeff Layton <jlayton@kernel.org>
> ---
> Documentation/core-api/mm-api.rst | 1 +
> include/linux/mm.h | 74 +++++++++++++++++++++++++++++++
> include/linux/mm_types.h | 60 +++++++++++++++++++++++++
> include/linux/page-flags.h | 27 +++++++++++
> 4 files changed, 162 insertions(+)
>
> diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
> index a42f9baddfbf..2a94e6164f80 100644
> --- a/Documentation/core-api/mm-api.rst
> +++ b/Documentation/core-api/mm-api.rst
> @@ -95,6 +95,7 @@ More Memory Management Functions
> .. kernel-doc:: mm/mempolicy.c
> .. kernel-doc:: include/linux/mm_types.h
> :internal:
> +.. kernel-doc:: include/linux/page-flags.h
> .. kernel-doc:: include/linux/mm.h
> :internal:
> .. kernel-doc:: include/linux/mmzone.h
> diff --git a/include/linux/mm.h b/include/linux/mm.h
> index 2327f99b121f..b29c86824e6b 100644
> --- a/include/linux/mm.h
> +++ b/include/linux/mm.h
> @@ -950,6 +950,20 @@ static inline unsigned int compound_order(struct page *page)
> return page[1].compound_order;
> }
>
> +/**
> + * folio_order - The allocation order of a folio.
> + * @folio: The folio.
> + *
> + * A folio is composed of 2^order pages. See get_order() for the definition
> + * of order.
> + *
> + * Return: The order of the folio.
> + */
> +static inline unsigned int folio_order(struct folio *folio)
> +{
> + return compound_order(&folio->page);
> +}
> +
> static inline bool hpage_pincount_available(struct page *page)
> {
> /*
> @@ -1595,6 +1609,65 @@ static inline void set_page_links(struct page *page, enum zone_type zone,
> #endif
> }
>
> +/**
> + * folio_nr_pages - The number of pages in the folio.
> + * @folio: The folio.
> + *
> + * Return: A number which is a power of two.
> + */
> +static inline unsigned long folio_nr_pages(struct folio *folio)
> +{
> + return compound_nr(&folio->page);
> +}
> +
> +/**
> + * folio_next - Move to the next physical folio.
> + * @folio: The folio we're currently operating on.
> + *
> + * If you have physically contiguous memory which may span more than
> + * one folio (eg a &struct bio_vec), use this function to move from one
> + * folio to the next. Do not use it if the memory is only virtually
> + * contiguous as the folios are almost certainly not adjacent to each
> + * other. This is the folio equivalent to writing ``page++``.
> + *
> + * Context: We assume that the folios are refcounted and/or locked at a
> + * higher level and do not adjust the reference counts.
> + * Return: The next struct folio.
> + */
> +static inline struct folio *folio_next(struct folio *folio)
> +{
> + return (struct folio *)folio_page(folio, folio_nr_pages(folio));
> +}
> +
> +/**
> + * folio_shift - The number of bits covered by this folio.
> + * @folio: The folio.
> + *
> + * A folio contains a number of bytes which is a power-of-two in size.
> + * This function tells you which power-of-two the folio is.
> + *
> + * Context: The caller should have a reference on the folio to prevent
> + * it from being split. It is not necessary for the folio to be locked.
> + * Return: The base-2 logarithm of the size of this folio.
> + */
> +static inline unsigned int folio_shift(struct folio *folio)
> +{
> + return PAGE_SHIFT + folio_order(folio);
> +}
> +
> +/**
> + * folio_size - The number of bytes in a folio.
> + * @folio: The folio.
> + *
> + * Context: The caller should have a reference on the folio to prevent
> + * it from being split. It is not necessary for the folio to be locked.
> + * Return: The number of bytes in this folio.
> + */
> +static inline size_t folio_size(struct folio *folio)
> +{
> + return PAGE_SIZE << folio_order(folio);
> +}
> +
> /*
> * Some inline functions in vmstat.h depend on page_zone()
> */
> @@ -1699,6 +1772,7 @@ extern void pagefault_out_of_memory(void);
>
> #define offset_in_page(p) ((unsigned long)(p) & ~PAGE_MASK)
> #define offset_in_thp(page, p) ((unsigned long)(p) & (thp_size(page) - 1))
> +#define offset_in_folio(folio, p) ((unsigned long)(p) & (folio_size(folio) - 1))
>
> /*
> * Flags passed to show_mem() and show_free_areas() to suppress output in
> diff --git a/include/linux/mm_types.h b/include/linux/mm_types.h
> index 5aacc1c10a45..3118ba8b5a4e 100644
> --- a/include/linux/mm_types.h
> +++ b/include/linux/mm_types.h
> @@ -224,6 +224,66 @@ struct page {
> #endif
> } _struct_page_alignment;
>
> +/**
> + * struct folio - Represents a contiguous set of bytes.
> + * @flags: Identical to the page flags.
> + * @lru: Least Recently Used list; tracks how recently this folio was used.
> + * @mapping: The file this page belongs to, or refers to the anon_vma for
> + * anonymous pages.
> + * @index: Offset within the file, in units of pages. For anonymous pages,
> + * this is the index from the beginning of the mmap.
> + * @private: Filesystem per-folio data (see folio_attach_private()).
> + * Used for swp_entry_t if folio_swapcache().
> + * @_mapcount: Do not access this member directly. Use folio_mapcount() to
> + * find out how many times this folio is mapped by userspace.
> + * @_refcount: Do not access this member directly. Use folio_ref_count()
> + * to find how many references there are to this folio.
> + * @memcg_data: Memory Control Group data.
> + *
> + * A folio is a physically, virtually and logically contiguous set
> + * of bytes. It is a power-of-two in size, and it is aligned to that
> + * same power-of-two. It is at least as large as %PAGE_SIZE. If it is
> + * in the page cache, it is at a file offset which is a multiple of that
> + * power-of-two. It may be mapped into userspace at an address which is
> + * at an arbitrary page offset, but its kernel virtual address is aligned
> + * to its size.
> + */
> +struct folio {
> + /* private: don't document the anon union */
> + union {
> + struct {
> + /* public: */
> + unsigned long flags;
> + struct list_head lru;
> + struct address_space *mapping;
> + pgoff_t index;
> + void *private;
> + atomic_t _mapcount;
> + atomic_t _refcount;
> +#ifdef CONFIG_MEMCG
> + unsigned long memcg_data;
> +#endif
> + /* private: the union with struct page is transitional */
> + };
> + struct page page;
> + };
> +};
> +
> +static_assert(sizeof(struct page) == sizeof(struct folio));
> +#define FOLIO_MATCH(pg, fl) \
> + static_assert(offsetof(struct page, pg) == offsetof(struct folio, fl))
> +FOLIO_MATCH(flags, flags);
> +FOLIO_MATCH(lru, lru);
> +FOLIO_MATCH(compound_head, lru);
> +FOLIO_MATCH(index, index);
> +FOLIO_MATCH(private, private);
> +FOLIO_MATCH(_mapcount, _mapcount);
> +FOLIO_MATCH(_refcount, _refcount);
> +#ifdef CONFIG_MEMCG
> +FOLIO_MATCH(memcg_data, memcg_data);
> +#endif
> +#undef FOLIO_MATCH
> +
> static inline atomic_t *compound_mapcount_ptr(struct page *page)
> {
> return &page[1].compound_mapcount;
> diff --git a/include/linux/page-flags.h b/include/linux/page-flags.h
> index d8e26243db25..e069aa8b11b7 100644
> --- a/include/linux/page-flags.h
> +++ b/include/linux/page-flags.h
> @@ -188,6 +188,33 @@ static inline unsigned long _compound_head(const struct page *page)
>
> #define compound_head(page) ((typeof(page))_compound_head(page))
>
> +/**
> + * page_folio - Converts from page to folio.
> + * @p: The page.
> + *
> + * Every page is part of a folio. This function cannot be called on a
> + * NULL pointer.
> + *
> + * Context: No reference, nor lock is required on @page. If the caller
> + * does not hold a reference, this call may race with a folio split, so
> + * it should re-check the folio still contains this page after gaining
> + * a reference on the folio.
> + * Return: The folio which contains this page.
> + */
> +#define page_folio(p) (_Generic((p), \
> + const struct page *: (const struct folio *)_compound_head(p), \
> + struct page *: (struct folio *)_compound_head(p)))
> +
> +/**
> + * folio_page - Return a page from a folio.
> + * @folio: The folio.
> + * @n: The page number to return.
> + *
> + * @n is relative to the start of the folio. It should be between
> + * 0 and folio_nr_pages(@folio) - 1, but this is not checked for.
Please add a statement noting WHY @n isn't checked since you state it
should be. Something like "...but this is not checked for because this is
a hot path."
> + */
> +#define folio_page(folio, n) nth_page(&(folio)->page, n)
> +
> static __always_inline int PageTail(struct page *page)
> {
> return READ_ONCE(page->compound_head) & 1;
> --
> 2.30.2
>
>
Thanks,
Bill
next prev parent reply other threads:[~2021-05-15 10:57 UTC|newest]
Thread overview: 96+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-11 21:47 [PATCH v10 00/33] Memory folios Matthew Wilcox (Oracle)
2021-05-11 21:47 ` [PATCH v10 01/33] mm: Introduce struct folio Matthew Wilcox (Oracle)
2021-05-14 10:34 ` Vlastimil Babka
2021-05-14 10:40 ` Vlastimil Babka
2021-05-14 11:47 ` Matthew Wilcox
2021-05-15 10:55 ` William Kucharski [this message]
2021-05-15 20:14 ` Matthew Wilcox
2021-05-16 19:26 ` William Kucharski
2021-05-27 8:09 ` Christoph Hellwig
2021-05-11 21:47 ` [PATCH v10 02/33] mm: Add folio_pgdat and folio_zone Matthew Wilcox (Oracle)
2021-05-14 10:35 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 03/33] mm/vmstat: Add functions to account folio statistics Matthew Wilcox (Oracle)
2021-05-14 10:36 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 04/33] mm/debug: Add VM_BUG_ON_FOLIO and VM_WARN_ON_ONCE_FOLIO Matthew Wilcox (Oracle)
2021-05-14 10:44 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 05/33] mm: Add folio reference count functions Matthew Wilcox (Oracle)
2021-05-14 11:04 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 06/33] mm: Add folio_put Matthew Wilcox (Oracle)
2021-05-14 11:52 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 07/33] mm: Add folio_get Matthew Wilcox (Oracle)
2021-05-14 11:56 ` Vlastimil Babka
2021-05-14 14:24 ` Matthew Wilcox
2021-05-14 15:39 ` Vlastimil Babka
2021-05-27 8:10 ` Christoph Hellwig
2021-05-27 22:53 ` Andrew Morton
2021-05-11 21:47 ` [PATCH v10 08/33] mm: Add folio_try_get_rcu Matthew Wilcox (Oracle)
2021-05-14 12:11 ` Vlastimil Babka
2021-05-27 8:16 ` Christoph Hellwig
2021-06-05 4:26 ` Matthew Wilcox
2021-06-06 14:13 ` Christoph Hellwig
2021-05-11 21:47 ` [PATCH v10 09/33] mm: Add folio flag manipulation functions Matthew Wilcox (Oracle)
2021-05-14 15:29 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 10/33] mm: Add folio_young and folio_idle Matthew Wilcox (Oracle)
2021-05-14 15:33 ` Vlastimil Babka
2021-05-27 8:17 ` Christoph Hellwig
2021-05-11 21:47 ` [PATCH v10 11/33] mm: Handle per-folio private data Matthew Wilcox (Oracle)
2021-05-14 15:41 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 12/33] mm/filemap: Add folio_index, folio_file_page and folio_contains Matthew Wilcox (Oracle)
2021-05-14 15:55 ` Vlastimil Babka
2021-05-15 15:51 ` Matthew Wilcox
2021-05-11 21:47 ` [PATCH v10 13/33] mm/filemap: Add folio_next_index Matthew Wilcox (Oracle)
2021-05-14 17:07 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 14/33] mm/filemap: Add folio_offset and folio_file_offset Matthew Wilcox (Oracle)
2021-05-14 17:08 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 15/33] mm/util: Add folio_mapping and folio_file_mapping Matthew Wilcox (Oracle)
2021-05-14 17:29 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 16/33] mm: Add folio_mapcount Matthew Wilcox (Oracle)
2021-05-14 17:39 ` Vlastimil Babka
2021-05-18 18:45 ` Matthew Wilcox
2021-05-11 21:47 ` [PATCH v10 17/33] mm/memcg: Add folio wrappers for various functions Matthew Wilcox (Oracle)
2021-05-18 9:57 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 18/33] mm/filemap: Add folio_unlock Matthew Wilcox (Oracle)
2021-05-18 10:06 ` Vlastimil Babka
2021-05-18 11:30 ` Matthew Wilcox
2021-05-11 21:47 ` [PATCH v10 19/33] mm/filemap: Add folio_lock Matthew Wilcox (Oracle)
2021-05-18 10:26 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 20/33] mm/filemap: Add folio_lock_killable Matthew Wilcox (Oracle)
2021-05-18 10:31 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 21/33] mm/filemap: Add __folio_lock_async Matthew Wilcox (Oracle)
2021-05-18 10:34 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 22/33] mm/filemap: Add __folio_lock_or_retry Matthew Wilcox (Oracle)
2021-05-18 10:38 ` Vlastimil Babka
2021-05-18 10:45 ` Vlastimil Babka
2021-05-18 13:35 ` Matthew Wilcox
2021-05-11 21:47 ` [PATCH v10 23/33] mm/filemap: Add folio_wait_locked Matthew Wilcox (Oracle)
2021-05-18 10:41 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 24/33] mm/swap: Add folio_rotate_reclaimable Matthew Wilcox (Oracle)
2021-05-18 10:48 ` Vlastimil Babka
2021-05-27 8:19 ` Christoph Hellwig
2021-05-11 21:47 ` [PATCH v10 25/33] mm/filemap: Add folio_end_writeback Matthew Wilcox (Oracle)
2021-05-18 11:08 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 26/33] mm/writeback: Add folio_wait_writeback Matthew Wilcox (Oracle)
2021-05-18 11:12 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 27/33] mm/writeback: Add folio_wait_stable Matthew Wilcox (Oracle)
2021-05-18 11:42 ` Vlastimil Babka
2021-05-18 13:55 ` Matthew Wilcox
2021-05-11 21:47 ` [PATCH v10 28/33] mm/filemap: Add folio_wait_bit Matthew Wilcox (Oracle)
2021-05-18 11:51 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 29/33] mm/filemap: Add folio_wake_bit Matthew Wilcox (Oracle)
2021-05-18 11:53 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 30/33] mm/filemap: Convert page wait queues to be folios Matthew Wilcox (Oracle)
2021-05-18 12:23 ` Vlastimil Babka
2021-05-11 21:47 ` [PATCH v10 31/33] mm/filemap: Add folio private_2 functions Matthew Wilcox (Oracle)
2021-05-18 12:26 ` Vlastimil Babka
2021-05-27 8:21 ` Christoph Hellwig
2021-05-11 21:47 ` [PATCH v10 32/33] fs/netfs: Add folio fscache functions Matthew Wilcox (Oracle)
2021-05-18 13:48 ` Vlastimil Babka
2021-05-27 8:23 ` Christoph Hellwig
2021-05-11 21:47 ` [PATCH v10 33/33] mm: Add folio_mapped Matthew Wilcox (Oracle)
2021-05-18 14:17 ` Vlastimil Babka
2021-05-27 8:31 ` Christoph Hellwig
2021-05-13 14:50 ` [PATCH v10 00/33] Memory folios Matthew Wilcox
2021-05-15 10:26 ` William Kucharski
2021-06-04 1:07 ` Matteo Croce
2021-06-04 2:13 ` Matthew Wilcox
2021-06-08 14:56 ` Matteo Croce
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=0FF7A37F-80A8-4B49-909D-6234ADA8A25C@oracle.com \
--to=william.kucharski@oracle.com \
--cc=akpm@linux-foundation.org \
--cc=jlayton@kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=willy@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).