All of lore.kernel.org
 help / color / mirror / Atom feed
From: Matthew Wilcox <willy@infradead.org>
To: linux-mm@kvack.org
Cc: akpm@linuxfoundation.org, Matthew Wilcox <mawilcox@microsoft.com>
Subject: [PATCH v2 7/8] mm: Document how to use struct page
Date: Wed, 20 Dec 2017 07:55:51 -0800	[thread overview]
Message-ID: <20171220155552.15884-8-willy@infradead.org> (raw)
In-Reply-To: <20171220155552.15884-1-willy@infradead.org>

From: Matthew Wilcox <mawilcox@microsoft.com>

Be really explicit about what bits / bytes are reserved for users that
want to store extra information about the pages they allocate.

Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Acked-by: Kirill A. Shutemov <kirill.shutemov@linux.intel.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Michal Hocko <mhocko@suse.com>
---
 include/linux/mm_types.h | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/include/linux/mm_types.h b/include/linux/mm_types.h
index 1a3ba1f1605d..ef35ea524c26 100644
--- a/include/linux/mm_types.h
+++ b/include/linux/mm_types.h
@@ -31,7 +31,29 @@ struct hmm;
  * it to keep track of whatever it is we are using the page for at the
  * moment. Note that we have no way to track which tasks are using
  * a page, though if it is a pagecache page, rmap structures can tell us
- * who is mapping it.
+ * who is mapping it. If you allocate the page using alloc_pages(), you
+ * can use some of the space in struct page for your own purposes.
+ *
+ * Pages that were once in the page cache may be found under the RCU lock
+ * even after they have been recycled to a different purpose.  The page
+ * cache reads and writes some of the fields in struct page to pin the
+ * page before checking that it's still in the page cache.  It is vital
+ * that all users of struct page:
+ * 1. Use the first word as PageFlags.
+ * 2. Clear or preserve bit 0 of page->compound_head.  It is used as
+ *    PageTail for compound pages, and the page cache must not see false
+ *    positives.  Some users put a pointer here (guaranteed to be at least
+ *    4-byte aligned), other users avoid using the field altogether.
+ * 3. page->_refcount must either not be used, or must be used in such a
+ *    way that other CPUs temporarily incrementing and then decrementing the
+ *    refcount does not cause problems.  On receiving the page from
+ *    alloc_pages(), the refcount will be positive.
+ * 4. Either preserve page->_mapcount or restore it to -1 before freeing it.
+ *
+ * If you allocate pages of order > 0, you can use the fields in the struct
+ * page associated with each page, but bear in mind that the pages may have
+ * been inserted individually into the page cache, so you must use the above
+ * four fields in a compatible way for each struct page.
  *
  * SLUB uses cmpxchg_double() to atomically update its freelist and
  * counters.  That requires that freelist & counters be adjacent and
-- 
2.15.1

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

  parent reply	other threads:[~2017-12-20 15:56 UTC|newest]

Thread overview: 11+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-12-20 15:55 [PATCH v2 0/8] Restructure " Matthew Wilcox
2017-12-20 15:55 ` [PATCH v2 1/8] mm: Align struct page more aesthetically Matthew Wilcox
2017-12-20 15:55 ` [PATCH v2 2/8] mm: De-indent struct page Matthew Wilcox
2017-12-20 15:55 ` [PATCH v2 3/8] mm: Remove misleading alignment claims Matthew Wilcox
2017-12-20 15:55 ` [PATCH v2 4/8] mm: Improve comment on page->mapping Matthew Wilcox
2017-12-20 15:55 ` [PATCH v2 5/8] mm: Introduce _slub_counter_t Matthew Wilcox
2017-12-20 15:55 ` [PATCH v2 6/8] mm: Store compound_dtor / compound_order as bytes Matthew Wilcox
2017-12-20 23:39   ` Andrew Morton
2017-12-21  0:01     ` Matthew Wilcox
2017-12-20 15:55 ` Matthew Wilcox [this message]
2017-12-20 15:55 ` [PATCH v2 8/8] mm: Remove reference to PG_buddy Matthew Wilcox

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=20171220155552.15884-8-willy@infradead.org \
    --to=willy@infradead.org \
    --cc=akpm@linuxfoundation.org \
    --cc=linux-mm@kvack.org \
    --cc=mawilcox@microsoft.com \
    --subject='Re: [PATCH v2 7/8] mm: Document how to use struct page' \
    /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

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.