Re: [PATCH] statx.2: document STATX_DIO_READ_ALIGN

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

On Mon, Jan 06, 2025 at 04:19:38PM +0100, Christoph Hellwig wrote:
> Document the new STATX_DIO_READ_ALIGN flag and the new
> stx_dio_read_offset_align field guarded by it.
> 
> Signed-off-by: Christoph Hellwig <hch@lst.de>
> ---
>  man/man2/statx.2 | 27 ++++++++++++++++++++++++++-
>  1 file changed, 26 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man2/statx.2 b/man/man2/statx.2
> index c5b5a28ec2f1..378bf363d93f 100644
> --- a/man/man2/statx.2
> +++ b/man/man2/statx.2
> @@ -76,6 +76,9 @@ struct statx {
>      __u32 stx_atomic_write_unit_min;
>      __u32 stx_atomic_write_unit_max;
>      __u32 stx_atomic_write_segments_max;
> +
> +    /* File offset alignment for direct I/O reads */
> +    __u32   stx_dio_read_offset_align;
>  };
>  .EE
>  .in
> @@ -261,7 +264,7 @@ STATX_BTIME	Want stx_btime
>  STATX_ALL	The same as STATX_BASIC_STATS | STATX_BTIME.
>  	It is deprecated and should not be used.
>  STATX_MNT_ID	Want stx_mnt_id (since Linux 5.8)
> -STATX_DIOALIGN	Want stx_dio_mem_align and stx_dio_offset_align
> +STATX_DIOALIGN	Want stx_dio_mem_align and stx_dio_offset_align.
>  	(since Linux 6.1; support varies by filesystem)
>  STATX_MNT_ID_UNIQUE	Want unique stx_mnt_id (since Linux 6.8)
>  STATX_SUBVOL	Want stx_subvol
> @@ -270,6 +273,8 @@ 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)
> +STATX_DIO_READ_ALIGN	Want stx_dio_read_offset_align.
> +	(since Linux 6.14; support varies by filesystem)
>  .TE
>  .in
>  .P
> @@ -467,6 +472,26 @@ This will only be nonzero if
>  .I stx_dio_mem_align
>  is nonzero, and vice versa.
>  .TP
> +.I stx_dio_read_offset_align
> +The alignment (in bytes) required for file offsets and I/O segment lengths for
> +direct I/O reads
> +.RB ( O_DIRECT )
> +on this file.  If zero the limit in

manpage nit: new sentences should start on a new line.

> +.I
> +stx_dio_offset_align
> +applies for reads as well.  If non-zero this value must be

Here too.

> +smaller than
> +.I
> +stx_dio_offset_align
> +which must be provided by the file system.

I can't imagine a filesystem where dio_read_offset > dio_offset makes
sense, but why do we need to put that in the manpage?

vs. "If non-zero, the filesystem must also provide stx_dio_offset_align."

> +This value does not affect the memory alignent in

                                         alignment

> +.I stx_dio_mem_align .
> +.IP
> +.B STATX_DIO_READ_ALIGN
> +.I ( stx_dio_offset_align )
> +support by filesystem;
> +it is supported by xfs since Linux 6.14.

Aside from those bits, this looks good to me.

--D

> +.TP
>  .I stx_subvol
>  Subvolume number of the current file.
>  .IP
> -- 
> 2.45.2
> 
>