Skip to content

RFC btrfs: implement FALLOC_FL_COLLAPSE_RANGE and FALLOC_FL_INSERT_RANGE

Paul Richards linux-btrfs 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 RFC Latest3 patches 7 repliesIn review

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/3btrfs: refactor btrfs_fallocate() ahead of supporting more modesfs/btrfs/file.c+40 -231 reply
2/3btrfs: support for FALLOC_FL_COLLAPSE_RANGE in btrfs_fallocate()fs/btrfs/file.c+300 -01 reply
3/3btrfs: support for FALLOC_FL_INSERT_RANGE in btrfs_fallocate()fs/btrfs/file.c+238 -01 reply

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v1 yet.

Read the v1 thread

Cover letter [RFC PATCH 0/3] btrfs: implement FALLOC_FL_COLLAPSE_RANGE and FALLOC_FL_INSERT_RANGE

This series adds support for FALLOC_FL_COLLAPSE_RANGE and FALLOC_FL_INSERT_RANGE to btrfs_fallocate(). Both operations are already supported by ext4 and xfs. The userspace contract is documented in fallocate(2).

Patch 1 refactors btrfs_fallocate() to dispatch via a switch statement, moving punch_hole into its own function and decoupling locking from the per-operation helpers. This is similar to the implementaitons for ext4 and xfs. The allocate-range and zero-range paths remain coupled since they share some setup logic.

Patches 2 and 3 add COLLAPSE_RANGE and INSERT_RANGE respectively.

== Implementation approach ==

For COLLAPSE_RANGE:
- The removed region [offset, offset+len) is punched out via btrfs_replace_file_extents(), which handles boundary splitting.
- All EXTENT_DATA keys with key.offset >= offset+len are shifted leftward by len in forward order.

For INSERT_RANGE:
- All EXTENT_DATA keys with key.offset >= offset are shifted rightward by len in reverse order (required to avoid key collisions).
- No pre-splitting of straddling extents is needed: the left portion of a straddling extent stays in place, the right portion is shifted; both reference the same physical extent via their existing extent_offset fields.

For each shifted key, the corresponding back-reference in the extent tree is updated via a shared helper btrfs_shift_extent_backref().

After the key-shift loop, btrfs_drop_extent_map_range() is called to invalidate the in-memory extent map cache. This is important for reads after the fallocate operation to ensure they obtain data for the new offsets.

The page cache is flushed and invalidated upfront (before any extent manipulation) following the ext4/xfs pattern. The inode lock (BTRFS_ILOCK_MMAP) is held throughout, preventing new dirty pages from appearing during the operation.

Transaction cycling: the key-shift loop cycles transactions every BTRFS_INSERT_COLLAPSE_TRANSACTION_CYCLE_INTERVAL (32) items to avoid holding a single transaction open across a large number of extents.

Both operations are gated on CONFIG_BTRFS_EXPERIMENTAL.

== Known limitations ==

INSERT_RANGE returns -EOPNOTSUPP for inlined files. Supporting inline files will require promoting the existing inline extent to a regular one, since inline extends are supported only at the very start of a file.

In the opposite direction, COLLAPSE_RANGE will not create inline files like it should if the remaining data is small enough.

I intend to address both of these limitations.

== Testing ==

Tested with a Rust-based functional test suite covering:
- Collapse and insert at the start, middle of a file
- Multiple sequential operations on the same file
- Files with multiple extents (fsync between writes to force separate extent items)
- Files with holes (explicit punch_hole and implicit sparse writes)
- Compressed extents (mount -o compress=zstd)
- Transaction cycling (interval reduced to 4 during testing, verified in dmesg logs)
- Inline files, verified that -EOPNOTSUPP is returned.

The same tests pass on both btrfs and xfs (modulo the inline files).

I have not run fstests which I know contains tests for INSERT_RANGE and COLLAPSE_RANGE. I will do so.

== Questions for reviewers ==

1. Transaction cycling interval: we use 32 items per cycle. Is this the right threshold, or is there an established convention in btrfs for this kind of loop?

2. Extent lock scope for collapse: we hold the extent lock only on [offset, offset+len) during the hole punch, not on the full [offset, i_size) range that the key-shift loop operates on. Is this safe, or should we lock the full affected range?

3. CONFIG_BTRFS_EXPERIMENTAL gate: is this the right gate for these operations, or should they be unconditionally available?

== Notes ==

This is my first kernel contribution. Development was significantly assisted by an LLM (Amazon Q Developer). The implementation, testing, and final review decisions are my own.

Various btrfs_info() print statements, assertions, and comments that were useful during development and testing have been left in place, but will be removed or streamlined in the next revision.

Paul Richards (3):
btrfs: refactor btrfs_fallocate() ahead of supporting more modes
btrfs: support for FALLOC_FL_COLLAPSE_RANGE in btrfs_fallocate()
btrfs: support for FALLOC_FL_INSERT_RANGE in btrfs_fallocate()

 fs/btrfs/file.c | 601 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 578 insertions(+), 23 deletions(-)
Signature · 1 line
2.53.0