[PATCH v3 0/2] statx.2: Add stx_atomic_write_unit_max_opt

[PATCH v3 0/2] statx.2: Add stx_atomic_write_unit_max_opt

[John Garry]

This adds the man page update for stx_atomic_write_unit_max_opt.

Differences to v2:
- properly align stx_dio_read_offset_align
- update formatting according to Alex's recommendations

John Garry (2):
  statx.2: properly align stx_dio_read_offset_align
  statx.2: Add stx_atomic_write_unit_max_opt

 man/man2/statx.2 | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

-- 
2.31.1

[PATCH v3 1/2] statx.2: properly align stx_dio_read_offset_align

[John Garry]

Align this member in struct statx with the members above it.

Signed-off-by: John Garry <john.g.garry@oracle.com>
---
 man/man2/statx.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man2/statx.2 b/man/man2/statx.2
index ef7dbbcf9..273d80711 100644
--- a/man/man2/statx.2
+++ b/man/man2/statx.2
@@ -73,7 +73,7 @@ struct statx {
     __u32 stx_atomic_write_segments_max;
 \&
     /* File offset alignment for direct I/O reads */
-    __u32   stx_dio_read_offset_align;
+    __u32 stx_dio_read_offset_align;
 };
 .EE
 .in
-- 
2.31.1

[PATCH v3 2/2] statx.2: Add stx_atomic_write_unit_max_opt

[John Garry]

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>
---
 man/man2/statx.2 | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/man/man2/statx.2 b/man/man2/statx.2
index 273d80711..07ac60b3c 100644
--- 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.
-- 
2.31.1

Re: [PATCH v3 1/2] statx.2: properly align stx_dio_read_offset_align

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 947 bytes --]

Hi John,

On Thu, Jun 19, 2025 at 03:44:54PM +0000, John Garry wrote:
> Align this member in struct statx with the members above it.
> 
> Signed-off-by: John Garry <john.g.garry@oracle.com>

Thanks!  I've applied the patch.
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=6006fe8bf74e400e060ff70f62ac03d911af13c5>


Have a lovely day!
Alex

> ---
>  man/man2/statx.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man/man2/statx.2 b/man/man2/statx.2
> index ef7dbbcf9..273d80711 100644
> --- a/man/man2/statx.2
> +++ b/man/man2/statx.2
> @@ -73,7 +73,7 @@ struct statx {
>      __u32 stx_atomic_write_segments_max;
>  \&
>      /* File offset alignment for direct I/O reads */
> -    __u32   stx_dio_read_offset_align;
> +    __u32 stx_dio_read_offset_align;
>  };
>  .EE
>  .in
> -- 
> 2.31.1
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3 2/2] statx.2: Add stx_atomic_write_unit_max_opt

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3277 bytes --]

Hi John,

On Thu, Jun 19, 2025 at 03:44:55PM +0000, John Garry wrote:
> 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>

Thanks!  Patch applied.
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=6dd3ceed42a94815ae41f0a7ec2e946a12a8f4be>


Cheers,
Alex

> ---
>  man/man2/statx.2 | 21 ++++++++++++++++++++-
>  1 file changed, 20 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man2/statx.2 b/man/man2/statx.2
> index 273d80711..07ac60b3c 100644
> --- 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.
> -- 
> 2.31.1
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]