[PATCH v2] btrfs: pin folios before dropping the last extent buffer reference

From: Shang En Sim

Date: Fri Nov 20 2026 - 17:05:42 EST


release_extent_buffer() drops the last reference to an extent buffer (eb)
before detaching its folios. For a mapped eb, alloc_extent_buffer() has
dropped its references to the folios since commit 3649833a58b6 ("btrfs: fix
broken drop_caches on extent buffer folios"). The page cache and the
folio's private attachment hold the remaining references.

Consider the following sequence, starting with an order-0 folio F in
btree_inode->i_mapping with F->private == existing_eb, F refcount == 2
(1 for the page cache, 1 for F->private), and existing_eb->refs == 1:

1) Task A drops the last reference to existing_eb:

release_extent_buffer(existing_eb)
refcount_dec_and_test() # existing_eb->refs: 1 -> 0
spin_unlock(&existing_eb->refs_lock)
xa_cmpxchg_irq() # removes existing_eb from buffer_tree
<window before btrfs_release_extent_buffer_folios(existing_eb)>

2) Task B allocates new_eb for the same bytenr, takes over folio F, and
drops its caller reference:

alloc_extent_buffer()
find_extent_buffer() # NULL (existing_eb removed from tree)
btrfs_init_eb_prealloc() # allocates new_eb and new folios
init_extent_buffer() # new_eb->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) -> existing_eb
refcount_inc_not_zero(&existing_eb->refs) -> false
# existing_eb->refs == 0
folio_detach_private(F) # F->private = NULL; refcnt: 3->2
folio_put(new_eb->folios[i]) # drops new_eb's unused new folio
new_eb->folios[i] = F # reuses existing folio F
attach_extent_buffer_folio(new_eb, F)
folio_attach_private(F, new_eb) # F->private = new_eb; refcnt: 2->3
__xa_cmpxchg() # inserts new_eb into buffer_tree
check_buffer_tree_ref(new_eb) # sets TREE_REF; new_eb->refs: 1 -> 2
folio_unlock(F)
folio_put(F) # drops lock ref; F refcnt: 3 -> 2
free_extent_buffer(new_eb)
free_extent_buffer_clear_reading(new_eb, false)
release_extent_buffer(new_eb)
refcount_dec_and_test() # new_eb->refs: 2 -> 1 (TREE_REF)

3) Task C runs drop_caches, releases new_eb, 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) -> new_eb
new_eb->refs == 1 # check passes
test_and_clear_bit(EXTENT_BUFFER_TREE_REF) -> true
release_extent_buffer(new_eb)
refcount_dec_and_test() # new_eb->refs: 1 -> 0
spin_unlock(&new_eb->refs_lock)
xa_cmpxchg_irq() # removes new_eb from buffer_tree
btrfs_release_extent_buffer_folios(new_eb)
detach_extent_buffer_folio(new_eb, 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
# (existing_eb 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 existing_eb's folios:

btrfs_release_extent_buffer_folios(existing_eb)
detach_extent_buffer_folio(existing_eb, F)
mapping = F->mapping # NULL (F refcnt is 0, freed/reused)
spin_lock(&mapping->i_private_lock) # NULL dereference

If new_eb was already fully freed and detached before task C runs, e.g.
via free_extent_buffer_stale(), F has no private attachment and
filemap_release_folio() returns true immediately, with the same result.

With a delay added in the window, this reproduces as:

BUG: kernel NULL pointer dereference, address: 0000000000000074
RIP: 0010:_raw_spin_lock+0x18/0x30
Call Trace:
detach_extent_buffer_folio+0x68/0x140
release_extent_buffer+0xac/0x120
btrfs_release_path+0x17/0x80
btrfs_free_path+0x17/0x30
btrfs_getxattr+0xe2/0x110
...

Compaction can also hit this window, since it calls
release_extent_buffer() through btree_migrate_folio() ->
filemap_release_folio() -> btree_release_folio().

Even without the NULL mapping, the folio can already be freed and
reused when detach_extent_buffer_folio() looks at it.

This race requires nodesize >= PAGE_SIZE. With subpage metadata,
grab_extent_buffer() never takes over folios, and a shared folio keeps
folio->private set until every eb on it is detached, so
try_release_subpage_extent_buffer() does not release it while an eb is
in this window.

Fix this in two parts:

- In release_extent_buffer(), when refs is 1 and the eb is mapped, take
a reference on each folio before dropping the eb reference, and drop
those references after the folios are detached. This keeps the folios
alive across the window, as the eb's own folio reference did before
the commit above.
Checking refs == 1 under refs_lock is enough: free_extent_buffer()
only decrements a mapped eb's refs without refs_lock while refs is
above 3, so no one else can drop it to 0 under us.

- In detach_extent_buffer_folio(), take i_private_lock from the btree
inode instead of from folio->mapping. A pinned folio can still be
removed from the page cache. All folios of a mapped eb belong to the
btree inode, so this is the same lock in every other case.

Fixes: 3649833a58b6 ("btrfs: fix broken drop_caches on extent buffer folios")
Cc: stable@xxxxxxxxxxxxxxx # 6.16+
Signed-off-by: Shang En Sim <sim@xxxxxxxxxxx>
---
I reproduced the oops with a test-only delay.

v1 testing on btrfs for-next 6f4bbde7e036, 8 vCPUs, 2 NUMA nodes, 120 s
per run of the reproducer:

- delay only: oops in 3 of 4 runs (at 61 s, 83 s, 46 s), trace as in
the commit message
- delay + this patch: no oops in 3 runs

Subpage, arm64 with 64K pages, nodesize 16K, emulated in QEMU:

- delay only: no oops in 3 runs (expected: grab_extent_buffer() does
not take over folios for subpage)
- delay + this patch: no oops in 3 runs

v1 built with W=1 with no new warnings in fs/btrfs/.
On the v2 base, fs/btrfs/extent_io.o built with W=1 on x86-64.
---
Changes in v2:
- Drop "mapped" from the first sentence, release_extent_buffer() handles
both mapped and unmapped buffers (Filipe).
- Replace the race diagram with the full step-by-step sequence from the
v1 discussion, using existing_eb and new_eb (Filipe).
- Rebase onto btrfs for-next.
- Link to v1: https://patch.msgid.link/20261117-my-btrfs-patch-v1-1-4b934a7ff69a@xxxxxxxxxxx
---
fs/btrfs/extent_io.c | 33 ++++++++++++++++++++++++++++++---
1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/fs/btrfs/extent_io.c b/fs/btrfs/extent_io.c
index b2739838c646..ce6880b1d64e 100644
--- a/fs/btrfs/extent_io.c
+++ b/fs/btrfs/extent_io.c
@@ -3155,15 +3155,18 @@ static bool folio_range_has_eb(struct folio *folio)
static void detach_extent_buffer_folio(const struct extent_buffer *eb, struct folio *folio)
{
struct btrfs_fs_info *fs_info = eb->fs_info;
- struct address_space *mapping = folio->mapping;
+ struct address_space *mapping = NULL;
const bool mapped = !test_bit(EXTENT_BUFFER_UNMAPPED, &eb->bflags);

/*
* For mapped eb, we're going to change the folio private, which should
- * be done under the i_private_lock.
+ * be done under the i_private_lock. Do not use folio->mapping, the
+ * folio may have left the page cache, see release_extent_buffer().
*/
- if (mapped)
+ if (mapped) {
+ mapping = fs_info->btree_inode->i_mapping;
spin_lock(&mapping->i_private_lock);
+ }

if (!folio_test_private(folio)) {
if (mapped)
@@ -4011,8 +4014,27 @@ static inline void btrfs_release_extent_buffer_rcu(struct rcu_head *head)
static int release_extent_buffer(struct extent_buffer *eb)
__releases(&eb->refs_lock)
{
+ struct folio *pinned[INLINE_EXTENT_BUFFER_PAGES];
+ int nr_pinned = 0;
+
lockdep_assert_held(&eb->refs_lock);

+ /*
+ * Once refs drops to 0 our folios can be taken over and freed, so pin
+ * them until they are detached. refs only drops below 3 under
+ * refs_lock, so checking for 1 is enough. Keep the folios in a local
+ * array: if refs does not hit 0, another holder may free the eb.
+ */
+ if (refcount_read(&eb->refs) == 1 &&
+ !test_bit(EXTENT_BUFFER_UNMAPPED, &eb->bflags)) {
+ for (int i = 0; i < INLINE_EXTENT_BUFFER_PAGES; i++) {
+ if (!eb->folios[i])
+ continue;
+ folio_get(eb->folios[i]);
+ pinned[nr_pinned++] = eb->folios[i];
+ }
+ }
+
if (refcount_dec_and_test(&eb->refs)) {
struct btrfs_fs_info *fs_info = eb->fs_info;

@@ -4039,6 +4061,8 @@ static int release_extent_buffer(struct extent_buffer *eb)
btrfs_leak_debug_del_eb(eb);
/* Should be safe to release folios at this point. */
btrfs_release_extent_buffer_folios(eb);
+ for (int i = 0; i < nr_pinned; i++)
+ folio_put(pinned[i]);
#ifdef CONFIG_BTRFS_FS_RUN_SANITY_TESTS
if (unlikely(test_bit(EXTENT_BUFFER_UNMAPPED, &eb->bflags))) {
kmem_cache_free(extent_buffer_cache, eb);
@@ -4050,6 +4074,9 @@ static int release_extent_buffer(struct extent_buffer *eb)
}
spin_unlock(&eb->refs_lock);

+ for (int i = 0; i < nr_pinned; i++)
+ folio_put(pinned[i]);
+
return 0;
}


---
base-commit: 184fa2c40f5c50afb1d8bf900eafadf450db392e
change-id: 20261117-my-btrfs-patch-984742ed64b0

Best regards,
--
Shang En Sim <sim@xxxxxxxxxxx>