[PATCH RFC] statx.2: Add stx_atomic_write_unit_max_opt

John Garry
2025-03-19T11:45:04Z

XFS supports atomic writes - or untorn writes - based on different methods:
- HW offload in the disk
- Software emulation

The value reported in stx_atomic_write_unit_max will be the max of the
software emulation method.

The max atomic write unit size of the software emulated atomic writes will
generally be much larger than the HW offload. However, software emulated
atomic writes will also be typically much slower.

The filesystem will transparently support both methods, specifically
HW offload is the preferred method when possible, e.g. if write size is
small enough then HW offload will be used.

Advertise this HW offload limit to the user in a new statx member,
stx_atomic_write_unit_max_opt.

We want STATX_WRITE_ATOMIC to get this new member in addition to the
already-existing members, so mention that a value of 0 means that
stx_atomic_write_unit_max holds this limit.

Signed-off-by: John Garry <john.g.garry@oracle.com>
---
I'm sending as an RFC as I am not sure if we need bother with this.

Maybe it's better to update the man page to mention that software
emulated atomic writes are available, and the user should check the
mounted bdev atomic write limits instead to know this opt limit.
diff --git a/man/man2/statx.2 b/man/man2/statx.2
index 0abac75c1..c3872f05d 100644
--- a/man/man2/statx.2
+++ b/man/man2/statx.2
@@ -79,6 +79,9 @@ struct statx {
\&
/* File offset alignment for direct I/O reads */
__u32 stx_dio_read_offset_align;
+\&
+ /* Direct I/O atomic write opt max limit */
+ __u32 stx_atomic_write_unit_max_opt;
};
.EE
.in
@@ -271,7 +274,8 @@ STATX_SUBVOL Want stx_subvol
(since Linux 6.10; support varies by filesystem)
STATX_WRITE_ATOMIC Want stx_atomic_write_unit_min,
stx_atomic_write_unit_max,
- and stx_atomic_write_segments_max.
+ stx_atomic_write_segments_max,
+ and stx_atomic_write_unit_max_opt.
(since Linux 6.11; support varies by filesystem)
STATX_DIO_READ_ALIGN Want stx_dio_read_offset_align.
(since Linux 6.14; support varies by filesystem)
@@ -519,6 +523,15 @@ is supported on block devices since Linux 6.11.
The support on regular files varies by filesystem;
it is supported by xfs and ext4 since Linux 6.13.
.TP
+.I stx_atomic_write_unit_max_opt
+The maximum size (in bytes) which is optimised for fast
+untorn writes.
+This value must not exceed the value in
+.I stx_atomic_write_unit_max.
+A value of 0 indicates that
+.I stx_atomic_write_unit_max
+is the optimised limit.
+.TP
.I stx_atomic_write_segments_max
The maximum number of elements in an array of vectors
for a write with torn-write protection enabled.
--
2.31.1