| Message ID | 20220722074229.148925-1-ebiggers@kernel.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [man-pages,RFC,v2] statx.2, open.2: document STATX_DIOALIGN | expand |
On Fri, Jul 22, 2022 at 12:42:28AM -0700, Eric Biggers wrote: > From: Eric Biggers <ebiggers@google.com> > > Document the proposed STATX_DIOALIGN support for statx() > (https://lore.kernel.org/linux-fsdevel/20220722071228.146690-1-ebiggers@kernel.org/T/#u). > > Signed-off-by: Eric Biggers <ebiggers@google.com> > --- > > v2: rebased onto man-pages master branch, mentioned xfs, and updated > link to patchset > > man2/open.2 | 43 ++++++++++++++++++++++++++++++++----------- > man2/statx.2 | 29 +++++++++++++++++++++++++++++ > 2 files changed, 61 insertions(+), 11 deletions(-) > > diff --git a/man2/open.2 b/man2/open.2 > index d1485999f..ef29847c3 100644 > --- a/man2/open.2 > +++ b/man2/open.2 > @@ -1732,21 +1732,42 @@ of user-space buffers and the file offset of I/Os. > In Linux alignment > restrictions vary by filesystem and kernel version and might be > absent entirely. > -However there is currently no filesystem\-independent > -interface for an application to discover these restrictions for a given > -file or filesystem. > -Some filesystems provide their own interfaces > -for doing so, for example the > +The handling of misaligned > +.B O_DIRECT > +I/Os also varies; they can either fail with > +.B EINVAL > +or fall back to buffered I/O. > +.PP > +Since Linux 5.20, > +.B O_DIRECT > +support and alignment restrictions for a file can be queried using > +.BR statx (2), > +using the > +.B STATX_DIOALIGN > +flag. > +Support for > +.B STATX_DIOALIGN > +varies by filesystem; see > +.BR statx (2). > +.PP > +Some filesystems provide their own interfaces for querying > +.B O_DIRECT > +alignment restrictions, for example the > .B XFS_IOC_DIOINFO > operation in > .BR xfsctl (3). > +.B STATX_DIOALIGN > +should be used instead when it is available. > .PP > -Under Linux 2.4, transfer sizes, the alignment of the user buffer, > -and the file offset must all be multiples of the logical block size > -of the filesystem. > -Since Linux 2.6.0, alignment to the logical block size of the > -underlying storage (typically 512 bytes) suffices. > -The logical block size can be determined using the > +If none of the above is available, then direct I/O support and alignment > +restrictions can only be assumed from known characteristics of the filesystem, > +the individual file, the underlying storage device(s), and the kernel version. > +In Linux 2.4, most block device based filesystems require that the file offset > +and the length and memory address of all I/O segments be multiples of the > +filesystem block size (typically 4096 bytes). > +In Linux 2.6.0, this was relaxed to the logical block size of the block device > +(typically 512 bytes). > +A block device's logical block size can be determined using the > .BR ioctl (2) > .B BLKSSZGET > operation or from the shell using the command: > diff --git a/man2/statx.2 b/man2/statx.2 > index 0326e9af0..ea38ec829 100644 > --- a/man2/statx.2 > +++ b/man2/statx.2 > @@ -61,7 +61,12 @@ struct statx { > containing the filesystem where the file resides */ > __u32 stx_dev_major; /* Major ID */ > __u32 stx_dev_minor; /* Minor ID */ > + > __u64 stx_mnt_id; /* Mount ID */ > + > + /* Direct I/O alignment restrictions */ > + __u32 stx_dio_mem_align; > + __u32 stx_dio_offset_align; > }; > .EE > .in > @@ -247,6 +252,8 @@ 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 > + (since Linux 5.20; support varies by filesystem) > .TE > .in > .PP > @@ -407,6 +414,28 @@ This is the same number reported by > .BR name_to_handle_at (2) > and corresponds to the number in the first field in one of the records in > .IR /proc/self/mountinfo . > +.TP > +.I stx_dio_mem_align > +The alignment (in bytes) required for user memory buffers for direct I/O > +.BR "" ( O_DIRECT ) > +on this file. or 0 if direct I/O is not supported on this file. Nit: "..on this file, or 0 if direct..." > +.IP > +.B STATX_DIOALIGN > +.IR "" ( stx_dio_mem_align > +and > +.IR stx_dio_offset_align ) > +is supported on block devices since Linux 5.20. > +The support on regular files varies by filesystem; it is supported by ext4, > +f2fs, and xfs since Linux 5.20. > +.TP > +.I stx_dio_offset_align > +The alignment (in bytes) required for file offsets and I/O segment lengths for > +direct I/O > +.BR "" ( O_DIRECT ) > +on this file, or 0 if direct I/O is not supported on this file. On this last part -- userspace can only conclude that directio is not supported on the file if ((STATX_DIOALIGN & stx_mask) && stx_dio_offset_align == 0), right? IOWs, if (STATX_DIOALIGN & stx_mask)==0 then userspace can't draw any conclusions from stx_dio_offset_align, correct? If the answers are yes and yes, then I think I've understood all this and can say Reviewed-by: Darrick J. Wong <djwong@kernel.org> --D > +This will only be nonzero if > +.I stx_dio_mem_align > +is nonzero, and vice versa. > .PP > For further information on the above fields, see > .BR inode (7). > > base-commit: f9f25914e4ed393ac284ab921876e8a78722c504 > -- > 2.37.0 >
diff --git a/man2/open.2 b/man2/open.2 index d1485999f..ef29847c3 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -1732,21 +1732,42 @@ of user-space buffers and the file offset of I/Os. In Linux alignment restrictions vary by filesystem and kernel version and might be absent entirely. -However there is currently no filesystem\-independent -interface for an application to discover these restrictions for a given -file or filesystem. -Some filesystems provide their own interfaces -for doing so, for example the +The handling of misaligned +.B O_DIRECT +I/Os also varies; they can either fail with +.B EINVAL +or fall back to buffered I/O. +.PP +Since Linux 5.20, +.B O_DIRECT +support and alignment restrictions for a file can be queried using +.BR statx (2), +using the +.B STATX_DIOALIGN +flag. +Support for +.B STATX_DIOALIGN +varies by filesystem; see +.BR statx (2). +.PP +Some filesystems provide their own interfaces for querying +.B O_DIRECT +alignment restrictions, for example the .B XFS_IOC_DIOINFO operation in .BR xfsctl (3). +.B STATX_DIOALIGN +should be used instead when it is available. .PP -Under Linux 2.4, transfer sizes, the alignment of the user buffer, -and the file offset must all be multiples of the logical block size -of the filesystem. -Since Linux 2.6.0, alignment to the logical block size of the -underlying storage (typically 512 bytes) suffices. -The logical block size can be determined using the +If none of the above is available, then direct I/O support and alignment +restrictions can only be assumed from known characteristics of the filesystem, +the individual file, the underlying storage device(s), and the kernel version. +In Linux 2.4, most block device based filesystems require that the file offset +and the length and memory address of all I/O segments be multiples of the +filesystem block size (typically 4096 bytes). +In Linux 2.6.0, this was relaxed to the logical block size of the block device +(typically 512 bytes). +A block device's logical block size can be determined using the .BR ioctl (2) .B BLKSSZGET operation or from the shell using the command: diff --git a/man2/statx.2 b/man2/statx.2 index 0326e9af0..ea38ec829 100644 --- a/man2/statx.2 +++ b/man2/statx.2 @@ -61,7 +61,12 @@ struct statx { containing the filesystem where the file resides */ __u32 stx_dev_major; /* Major ID */ __u32 stx_dev_minor; /* Minor ID */ + __u64 stx_mnt_id; /* Mount ID */ + + /* Direct I/O alignment restrictions */ + __u32 stx_dio_mem_align; + __u32 stx_dio_offset_align; }; .EE .in @@ -247,6 +252,8 @@ 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 + (since Linux 5.20; support varies by filesystem) .TE .in .PP @@ -407,6 +414,28 @@ This is the same number reported by .BR name_to_handle_at (2) and corresponds to the number in the first field in one of the records in .IR /proc/self/mountinfo . +.TP +.I stx_dio_mem_align +The alignment (in bytes) required for user memory buffers for direct I/O +.BR "" ( O_DIRECT ) +on this file. or 0 if direct I/O is not supported on this file. +.IP +.B STATX_DIOALIGN +.IR "" ( stx_dio_mem_align +and +.IR stx_dio_offset_align ) +is supported on block devices since Linux 5.20. +The support on regular files varies by filesystem; it is supported by ext4, +f2fs, and xfs since Linux 5.20. +.TP +.I stx_dio_offset_align +The alignment (in bytes) required for file offsets and I/O segment lengths for +direct I/O +.BR "" ( O_DIRECT ) +on this file, or 0 if direct I/O is not supported on this file. +This will only be nonzero if +.I stx_dio_mem_align +is nonzero, and vice versa. .PP For further information on the above fields, see .BR inode (7).