[PATCH] mm: Document the folio refcount a little better

[PATCH] mm: Document the folio refcount a little better

[Matthew Wilcox (Oracle)]

Expand the documentation of folio_ref_count() to talk about expected,
temporary and spurious refcounts as well as the concept of freezing.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 include/linux/page_ref.h | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/include/linux/page_ref.h b/include/linux/page_ref.h
index 94d3f0e71c06..9f5c75d06f76 100644
--- a/include/linux/page_ref.h
+++ b/include/linux/page_ref.h
@@ -71,6 +71,12 @@ static inline int page_ref_count(const struct page *page)
  * folio_ref_count - The reference count on this folio.
  * @folio: The folio.
  *
+ * Folios contain a reference count.  When that reference count reaches
+ * zero, the folio is referred to as frozen.  At this point, it will
+ * usually be returned to the memory allocator, but some parts of the
+ * kernel freeze folios in order to perform unusual operations on them
+ * such as splitting or migration.
+ *
  * The refcount is usually incremented by calls to folio_get() and
  * decremented by calls to folio_put().  Some typical users of the
  * folio refcount:
@@ -82,6 +88,18 @@ static inline int page_ref_count(const struct page *page)
  * - Pipes
  * - Direct IO which references this page in the process address space
  *
+ * The reference count has three components: expected, temporary and
+ * spurious.  The expected reference count of a folio is that which
+ * we would logically expect it to be from just reading the code.
+ * Temporary refcounts are gained by threads which need a temporary
+ * reference to make sure the folio isn't reallocated while they use it.
+ * Spurious refcounts are gained by threads which, thanks to RCU walks
+ * of the page tables or file cache, find a stale pointer to a folio.
+ * These threads will drop the refcount after discoveering the pointer
+ * is stale, but it can surprise other users to see the spurious refcount
+ * on a freshly allocated folio (eg they may see a refcount of 2 instead
+ * of 1).
+ *
  * Return: The number of references to this folio.
  */
 static inline int folio_ref_count(const struct folio *folio)
-- 
2.47.3

Re: [PATCH] mm: Document the folio refcount a little better

[David Hildenbrand (Arm)]

On 5/26/26 22:00, Matthew Wilcox (Oracle) wrote:
> Expand the documentation of folio_ref_count() to talk about expected,
> temporary and spurious refcounts as well as the concept of freezing.
> 
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> ---
>  include/linux/page_ref.h | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 
> diff --git a/include/linux/page_ref.h b/include/linux/page_ref.h
> index 94d3f0e71c06..9f5c75d06f76 100644
> --- a/include/linux/page_ref.h
> +++ b/include/linux/page_ref.h
> @@ -71,6 +71,12 @@ static inline int page_ref_count(const struct page *page)
>   * folio_ref_count - The reference count on this folio.
>   * @folio: The folio.
>   *
> + * Folios contain a reference count.  When that reference count reaches
> + * zero, the folio is referred to as frozen.  At this point, it will
> + * usually be returned to the memory allocator, but some parts of the
> + * kernel freeze folios in order to perform unusual operations on them
> + * such as splitting or migration.
> + *
>   * The refcount is usually incremented by calls to folio_get() and
>   * decremented by calls to folio_put().  Some typical users of the
>   * folio refcount:
> @@ -82,6 +88,18 @@ static inline int page_ref_count(const struct page *page)
>   * - Pipes
>   * - Direct IO which references this page in the process address space
>   *
> + * The reference count has three components: expected, temporary and
> + * spurious.  The expected reference count of a folio is that which
> + * we would logically expect it to be from just reading the code.
> + * Temporary refcounts are gained by threads which need a temporary
> + * reference to make sure the folio isn't reallocated while they use it.
> + * Spurious refcounts are gained by threads which, thanks to RCU walks

I think we often call them "Speculative references".

Not just RCU (GUP-fast doesn't even use RCU for page tables). We also have PFN
walkers that don't involve the pagecache or page tables at all. They don't find
stale pointers.

In essence, all these users use folio_try_get() and friends to grab a reference
speculatively, while the folio might have been freed concurrently, or the
pointer from where they might have obtained the folio could now be stale.

Maybe it's clearer to explain it from that angle.

-- 
Cheers,

David

Re: [PATCH] mm: Document the folio refcount a little better

[Matthew Wilcox]

On Wed, Jun 17, 2026 at 01:22:16PM +0200, David Hildenbrand (Arm) wrote:
> On 5/26/26 22:00, Matthew Wilcox (Oracle) wrote:
> > + * The reference count has three components: expected, temporary and
> > + * spurious.  The expected reference count of a folio is that which
> > + * we would logically expect it to be from just reading the code.
> > + * Temporary refcounts are gained by threads which need a temporary
> > + * reference to make sure the folio isn't reallocated while they use it.
> > + * Spurious refcounts are gained by threads which, thanks to RCU walks
> 
> I think we often call them "Speculative references".
> 
> Not just RCU (GUP-fast doesn't even use RCU for page tables). We also have PFN
> walkers that don't involve the pagecache or page tables at all. They don't find
> stale pointers.
> 
> In essence, all these users use folio_try_get() and friends to grab a reference
> speculatively, while the folio might have been freed concurrently, or the
> pointer from where they might have obtained the folio could now be stale.
> 
> Maybe it's clearer to explain it from that angle.

From the point of view of the reader, they are indeed speculative
references.  But from the view of the owner of the folio, they're
spurious.  If you look at the code flow, this folio hasn't been exposed
to anything yet, and yet someone has already gained a reference to it.

But maybe it's more important to just use one word for this concept.
I can change this to speculative.