From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 39EAECCA47C for ; Thu, 23 Jun 2022 16:02:41 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232081AbiFWQCk (ORCPT ); Thu, 23 Jun 2022 12:02:40 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38350 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231160AbiFWQCj (ORCPT ); Thu, 23 Jun 2022 12:02:39 -0400 Received: from ams.source.kernel.org (ams.source.kernel.org [IPv6:2604:1380:4601:e00::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id ADE3A37A9E; Thu, 23 Jun 2022 09:02:38 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id 70774B81370; Thu, 23 Jun 2022 16:02:37 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2B909C3411B; Thu, 23 Jun 2022 16:02:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1656000156; bh=KDZro067hOs54V5FFK7xSXNOUbG2XQbnl6krjTY23Ck=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=aFKuyHxI8O+khgn74cZXUbdL6rLFZn2OzWcLNJ4jb5lz+ls5l93I8W279wmcNAWUc /oVyf141lxp/6Jb1TUiAkAHyMnnEMWCbiv7An9MDsHG+5fY830R3mcnDWxeLNdS0Wz A2SJc9YiOWxYeV9667xlg4B5EdPahTWnJY9tmk5Q2Sfg094lTbv2XpJUhJqaOCMAhw kGHGl1ZHDgNFmb0GXHDUt7S38X37aLh9l3Kut5/3WXv346eraEciXK5bb0Y9FPU55z i1HMd9dcdEjUnB23t0tf2NDJ0AfTIOWEbhjNCnRB4H8+YgU1uweiDYVlQGpvfOl2u+ zrRmIFUgR6VEA== Date: Thu, 23 Jun 2022 09:02:35 -0700 From: "Darrick J. Wong" To: Eric Biggers Cc: linux-fsdevel@vger.kernel.org, linux-man@vger.kernel.org, linux-ext4@vger.kernel.org, linux-f2fs-devel@lists.sourceforge.net, linux-xfs@vger.kernel.org, linux-api@vger.kernel.org, linux-fscrypt@vger.kernel.org, linux-block@vger.kernel.org, linux-kernel@vger.kernel.org, Keith Busch Subject: Re: [man-pages RFC PATCH] statx.2, open.2: document STATX_DIOALIGN Message-ID: References: <20220616202141.125079-1-ebiggers@kernel.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20220616202141.125079-1-ebiggers@kernel.org> Precedence: bulk List-ID: X-Mailing-List: linux-api@vger.kernel.org On Thu, Jun 16, 2022 at 01:21:41PM -0700, Eric Biggers wrote: > From: Eric Biggers > > Document the proposed STATX_DIOALIGN support for statx() > (https://lore.kernel.org/linux-fsdevel/20220616201506.124209-1-ebiggers@kernel.org). > > Signed-off-by: Eric Biggers > --- > man2/open.2 | 43 ++++++++++++++++++++++++++++++++----------- > man2/statx.2 | 32 +++++++++++++++++++++++++++++++- > 2 files changed, 63 insertions(+), 12 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 a8620be6f..fff0a63ec 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 > @@ -244,8 +249,11 @@ STATX_SIZE Want stx_size > STATX_BLOCKS Want stx_blocks > STATX_BASIC_STATS [All of the above] > STATX_BTIME Want stx_btime > +STATX_ALL The same as STATX_BASIC_STATS | STATX_BTIME. > + This is deprecated and should not be used. STATX_ALL is deprecated?? I was under the impression that _ALL meant all the known bits for that kernel release, but... > STATX_MNT_ID Want stx_mnt_id (since Linux 5.8) ...I guess that is not correct. > -STATX_ALL [All currently available fields] > +STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align > + (since Linux 5.20; support varies by filesystem) > .TE > .in > .PP > @@ -406,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. "...on this file, or 0 if..." > +.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 and > +f2fs since Linux 5.20. If the VFS changes don't provoke further bikeshedding, I'll contribute an XFS patch to go with your series. --D > +.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). > -- > 2.36.1 >