Re: [PATCH] btrfs: pin folios before dropping the last extent buffer reference
From: Filipe Manana
Date: Fri Nov 20 2026 - 10:07:54 EST
On Fri, Nov 20, 2026 at 12:48 AM Shang En Sim <sim@xxxxxxxxxxx> wrote:
>
> On Thu Nov 19, 2026 at 11:24 AM CST, Filipe Manana wrote:
> > On Wed, Nov 18, 2026 at 12:20 AM Shang En Sim <sim@xxxxxxxxxxx> wrote:
> >>
> >> release_extent_buffer() drops the last reference to a mapped extent
> >> buffer (eb) before detaching its folios.
> >
> > To mapped and unmapped extent buffers, so remove the "mapped" part.
>
> I will remove "mapped" in v2.
>
> >> task A task B task C
> >> release_extent_buffer(eb)
> >> refs: 1 -> 0
> >> remove eb from buffer_tree
> >> alloc_extent_buffer()
> >> attach_eb_folio_to_filemap()
> >> grab_extent_buffer()
> >> refs is 0, take over
> >> the folios
> >> ... new eb released ...
> >
> > It's not "new eb released", it's the new folio that is released and we
> > take the existing folio into the new eb.
>
> My bad, that diagram was misleading.
>
> Inside attach_eb_folio_to_filemap(), task B drops its newly allocated
> folio and reuses the existing folio for the new eb (eb2), attaching eb2
> as folio->private after grab_extent_buffer() detaches eb1. After
> alloc_extent_buffer() completes, task B finishes using eb2 and calls
> free_extent_buffer(eb2), dropping eb2->refs from 2 to 1 (leaving only
> EXTENT_BUFFER_TREE_REF).
Ok, now I see it. Those are all important details for the changelog.
To make it clear, avoid using eb1 and eb2, just call them new_eb and
existing_eb (the later matches the name we use in
attach_eb_folio_to_filemap(), which make it clearer).
>
> >> drop_caches
> >> folio->mapping
> >> = NULL
> >
> > And where does this happens?
> > Please be detailed, add the call chain triggered by drop_caches that
> > results in setting the folio's mapping to NULL.
> >
> > I don't see how that is happening, because when we end up in
> > try_release_extent_buffer(), eb->refs is 0 and that
> > makes us return immediately with 0:
> >
> > spin_lock(&eb->refs_lock);
> > if (refcount_read(&eb->refs) != 1 || extent_buffer_under_io(eb)) {
> > spin_unlock(&eb->refs_lock);
> > spin_unlock(&folio->mapping->i_private_lock);
> > return 0;
> > }
> > spin_unlock(&folio->mapping->i_private_lock);
>
> When task C enters try_release_extent_buffer(), folio->private no longer
> points to task A's eb (eb1, with refs == 0). Task B's
> grab_extent_buffer() detached eb1 and attach_extent_buffer_folio()
> attached eb2 to folio->private. Once task B drops its caller reference
> on eb2, eb2->refs is 1 (with EXTENT_BUFFER_TREE_REF set), so
> try_release_extent_buffer() inspects eb2, clears EXTENT_BUFFER_TREE_REF,
> releases eb2 (detaching folio->private), and returns 1.
> mapping_evict_folio() then calls remove_mapping() ->
> __remove_mapping_unfreeze() -> __remove_mapping() ->
> __filemap_remove_folio() -> page_cache_delete(), which sets
> folio->mapping = NULL.
>
> (If eb2 was already fully freed and detached before task C runs, e.g.
> via free_extent_buffer_stale(), try_release_extent_buffer() sees
> !folio_test_private(folio) and returns 1 immediately.)
>
> Here is the full sequence, starting with a 0-order folio F in
> btree_inode->i_mapping with F->private == eb1, F refcount == 2 (1 for
> the page cache, 1 for F->private), and eb1->refs == 1:
>
> 1) Task A drops the last reference to eb1:
>
> release_extent_buffer(eb1)
> refcount_dec_and_test() # eb1->refs: 1 -> 0
> spin_unlock(&eb1->refs_lock)
> xa_cmpxchg_irq() # removes eb1 from buffer_tree
> <window before btrfs_release_extent_buffer_folios(eb1)>
>
> 2) Task B allocates eb2 for the same bytenr, takes over folio F, and
> drops its caller reference:
>
> alloc_extent_buffer()
> find_extent_buffer() # NULL (eb1 removed from tree)
> btrfs_init_eb_prealloc() # allocates eb2 and new folios
> init_extent_buffer() # eb2->refs = 1
> attach_eb_folio_to_filemap()
> filemap_add_folio() -> -EEXIST
> filemap_lock_folio() -> F # locks F; F refcnt: 2 -> 3
> grab_extent_buffer(F)
> folio_get_private(F) -> eb1
> refcount_inc_not_zero(&eb1->refs) -> false (eb1->refs == 0)
> folio_detach_private(F) # F->private = NULL; refcnt: 3->2
> folio_put(eb2->folios[i]) # drops eb2's unused new folio
> eb2->folios[i] = F # reuses existing folio F
> attach_extent_buffer_folio(eb2, F)
> folio_attach_private(F, eb2) # F->private = eb2; refcnt: 2->3
> __xa_cmpxchg() # inserts eb2 into buffer_tree
> check_buffer_tree_ref(eb2) # sets TREE_REF; eb2->refs: 1 -> 2
> folio_unlock(F)
> folio_put(F) # drops lock ref; F refcnt: 3 -> 2
> free_extent_buffer(eb2)
> free_extent_buffer_clear_reading(eb2, false)
> release_extent_buffer(eb2)
> refcount_dec_and_test() # eb2->refs: 2 -> 1 (TREE_REF)
>
> 3) Task C runs drop_caches, releases eb2, and evicts folio F:
>
> drop_caches_sysctl_handler()
> iterate_supers()
> __iterate_supers()
> drop_pagecache_sb()
> invalidate_mapping_pages()
> mapping_try_invalidate()
> find_lock_entries() # locks F, fbatch ref: F refcnt 2->3
> mapping_evict_folio(mapping, F)
> folio_ref_count check # 3 <= 1 + 1 + 1 (passes)
> filemap_release_folio(F, 0)
> btree_release_folio(F, 0)
> try_release_extent_buffer(F)
> folio_get_private(F) -> eb2
> eb2->refs == 1 # check passes
> test_and_clear_bit(EXTENT_BUFFER_TREE_REF) -> true
> release_extent_buffer(eb2)
> refcount_dec_and_test() # eb2->refs: 1 -> 0
> spin_unlock(&eb2->refs_lock)
> xa_cmpxchg_irq() # removes eb2 from buffer_tree
> btrfs_release_extent_buffer_folios(eb2)
> detach_extent_buffer_folio(eb2, F)
> folio_detach_private(F) # F->private=NULL; refcnt 3->2
> returns 1
> remove_mapping(mapping, F)
> __remove_mapping_unfreeze()
> __remove_mapping()
> folio_ref_freeze(F, 2) # F refcnt: 2 -> 0 (eb1 holds no ref)
> __filemap_remove_folio(F, NULL)
> page_cache_delete()
> xas_store(NULL) # removes F from i_pages
> F->mapping = NULL
> returns 1
> folio_ref_unfreeze(F, 1) # drops page cache ref; refcnt 0->1
> folio_unlock(F)
> folio_batch_release() # drops fbatch ref; refcnt 1->0, free
>
> 4) Task A resumes and detaches eb1's folios:
>
> btrfs_release_extent_buffer_folios(eb1)
> detach_extent_buffer_folio(eb1, F)
> mapping = F->mapping # NULL (F refcnt is 0, freed/reused)
> spin_lock(&mapping->i_private_lock) # NULL dereference
This detailed breakdown removes any potential confusion and should be
in the changelog.
>
> I validated this exact sequence with bpftrace probes during the
> reproducer run and observed try_release_extent_buffer() seeing
> folio->private == eb2 with refs == 1, returning 1,
> __filemap_remove_folio() running from drop_caches_sysctl_handler(), and
> task A subsequently entering detach_extent_buffer_folio(eb1, F) with
> F->mapping == NULL and refcount == 0.
>
> I will replace the diagram with this fuller breakdown (and remove
> "mapped") in v2 once you have had a chance to look at the rest of the
> patch.
The code part of the change looks good, thanks!
>
> Thanks,
> Shang En Sim