| Message ID | 20250106151938.GA27324@lst.de (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | statx.2: document STATX_DIO_READ_ALIGN | expand |
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 > >
On Mon, Jan 06, 2025 at 09:40:07AM -0800, Darrick J. Wong wrote: > > +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? Well, to be backwards compatible to older userspace the value put into stx_dio_offset_align also needs to work for reads. Given that there were questions about this in the RFC round I thought I'd mention it.
On Mon, Jan 06, 2025 at 07:09:58PM +0100, Christoph Hellwig wrote: > On Mon, Jan 06, 2025 at 09:40:07AM -0800, Darrick J. Wong wrote: > > > +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? > > Well, to be backwards compatible to older userspace the value put into > stx_dio_offset_align also needs to work for reads. Given that there > were questions about this in the RFC round I thought I'd mention it. Ah ok then. :) With the other formatting nits fixed, Reviewed-by: "Darrick J. Wong" <djwong@kernel.org> --D
Hi Christoph, 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> Thanks for the patch! Please see some minor comments below. Have a lovely night! Alex > --- > 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 Please write poems, not prose. :) In other words, new sentence, new line. See man-pages(7). $ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p' Use semantic newlines In the source of a manual page, new sentences should be started on new lines, long sentences should be split into lines at clause breaks (commas, semicolons, colons, and so on), and long clauses should be split at phrase boundaries. This convention, sometimes known as "semantic newlines", makes it easier to see the effect of patches, which often operate at the level of individual sentences, clauses, or phrases. > +.I > +stx_dio_offset_align We put the italics word in the same line as the .I. > +applies for reads as well. If non-zero this value must be > +smaller than > +.I > +stx_dio_offset_align > +which must be provided by the file system. > +This value does not affect the memory alignent in > +.I stx_dio_mem_align . > +.IP > +.B STATX_DIO_READ_ALIGN > +.I ( stx_dio_offset_align ) You probably meant .RI (roman-italics alternating). > +support by filesystem; > +it is supported by xfs since Linux 6.14. > +.TP > .I stx_subvol > Subvolume number of the current file. > .IP > -- > 2.45.2 > >
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 +.I +stx_dio_offset_align +applies for reads as well. If non-zero this value must be +smaller than +.I +stx_dio_offset_align +which must be provided by the file system. +This value does not affect the memory alignent in +.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. +.TP .I stx_subvol Subvolume number of the current file. .IP
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(-)