Re: [PATCH v4 1/3] statx.2: Document STATX_WRITE_ATOMIC

["Darrick J. Wong" <djwong@kernel.org>]

On Wed, Jul 17, 2024 at 09:36:17AM +0000, John Garry wrote:
> From: Himanshu Madhani <himanshu.madhani@oracle.com>
> 
> Add the text to the statx man page.
> 
> Signed-off-by: Himanshu Madhani <himanshu.madhani@oracle.com>
> Signed-off-by: John Garry <john.g.garry@oracle.com>
> ---
>  man/man2/statx.2 | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
> 
> diff --git a/man/man2/statx.2 b/man/man2/statx.2
> index 3d47319c6..a7cdc0097 100644
> --- a/man/man2/statx.2
> +++ b/man/man2/statx.2
> @@ -70,6 +70,11 @@ struct statx {
>      __u32 stx_dio_offset_align;
>  \&
>      __u64 stx_subvol;      /* Subvolume identifier */
> +\&
> +    /* Direct I/O atomic write limits */
> +    __u32 stx_atomic_write_unit_min;
> +    __u32 stx_atomic_write_unit_max;
> +    __u32 stx_atomic_write_segments_max;
>  };
>  .EE
>  .in
> @@ -259,6 +264,9 @@ STATX_DIOALIGN	Want stx_dio_mem_align and stx_dio_offset_align
>  STATX_MNT_ID_UNIQUE	Want unique stx_mnt_id (since Linux 6.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.
> +	(since Linux 6.11; support varies by filesystem)

Congratulations ^^^^^^^^^ on getting this merged!

>  .TE
>  .in
>  .P
> @@ -463,6 +471,22 @@ Subvolumes are fancy directories,
>  i.e. they form a tree structure that may be walked recursively.
>  Support varies by filesystem;
>  it is supported by bcachefs and btrfs since Linux 6.10.
> +.TP
> +.I stx_atomic_write_unit_min
> +.TQ
> +.I stx_atomic_write_unit_max
> +The minimum and maximum sizes (in bytes) supported for direct I/O
> +.RB ( O_DIRECT )
> +on the file to be written with torn-write protection.

I'm tempted to be nitpicky and say "...supported for direct I/O writes
to the the file to have torn-write protection" but... eh.  It's hot out
and I'm not that fussed if you want to ignore that.

Either way,
Reviewed-by: Darrick J. Wong <djwong@kernel.org>

--D


> +These values are each guaranteed to be a power-of-2.
> +.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.
> +See
> +.BR RWF_ATOMIC
> +flag for
> +.BR pwritev2 (2).
>  .P
>  For further information on the above fields, see
>  .BR inode (7).
> @@ -516,6 +540,9 @@ It cannot be written to, and all reads from it will be verified
>  against a cryptographic hash that covers the
>  entire file (e.g., via a Merkle tree).
>  .TP
> +.BR STATX_ATTR_WRITE_ATOMIC " (since Linux 6.11)"
> +The file supports torn-write protection.
> +.TP
>  .BR STATX_ATTR_DAX " (since Linux 5.8)"
>  The file is in the DAX (cpu direct access) state.
>  DAX state attempts to
> -- 
> 2.31.1
>