man/man2/statx.2: Add stx_atomic_write_unit_max_opt

XFS supports atomic writes - or untorn writes - based on two different
methods:
- HW offload in the disk
- FS method based on out-of-place writes

The value reported in stx_atomic_write_unit_max will be the max size of the
FS-based method.

The max atomic write unit size of the FS-based atomic writes will
typically be much larger than what is capable from the HW offload. However,
FS-based atomic writes will also be typically much slower.

Advertise this HW offload size 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 in
stx_atomic_write_unit_max_opt means that stx_atomic_write_unit_max holds
this optimised limit.

Linux will zero unused statx members, so stx_atomic_write_unit_max_opt
will always hold 0 for older kernel versions which do not support
this FS-based atomic write method (for XFS).

Signed-off-by: John Garry <john.g.garry@oracle.com>
Message-ID: <20250619154455.321848-3-john.g.garry@oracle.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man2/statx.2 b/man/man2/statx.2
index 273d80711aa51a48b72dba344cadb7e64e70b9df..07ac60b3c5d61d919fa790fe2d5c2ba33a771f75 100644 (file)
--- a/man/man2/statx.2
+++ b/man/man2/statx.2
@@ -74,6 +74,9 @@ struct statx {
 \&
     /* File offset alignment for direct I/O reads */
     __u32 stx_dio_read_offset_align;
+\&
+    /* Direct I/O atomic write max opt limit */
+    __u32 stx_atomic_write_unit_max_opt;
 };
 .EE
 .in
@@ -266,7 +269,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)
@@ -514,6 +518,21 @@ 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 writes issued with torn-write protection.
+If non-zero,
+this value will not exceed the value in
+.I stx_atomic_write_unit_max
+and will not be less than the value in
+.IR stx_atomic_write_unit_min .
+A value of zero indicates that
+.I stx_atomic_write_unit_max
+is the optimised limit.
+Slower writes may be experienced when the size of the write exceeds
+.I stx_atomic_write_unit_max_opt
+(when non-zero).
+.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.