| Message ID | 8d8534a704c4f162f347a84830710db32a927b2e.1744432270.git.ritesh.list@gmail.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | [v2,1/2] Documentation: iomap: Add missing flags description | expand |
On Sat, Apr 12, 2025 at 10:06:34AM +0530, Ritesh Harjani (IBM) wrote: > Let's document the use of these flags in iomap design doc where other > flags are defined too - > > - IOMAP_F_BOUNDARY was added by XFS to prevent merging of I/O and I/O > completions across RTG boundaries. > - IOMAP_F_ATOMIC_BIO was added for supporting atomic I/O operations > for filesystems to inform the iomap that it needs HW-offload based > mechanism for torn-write protection. > > While we are at it, let's also fix the description of IOMAP_F_PRIVATE > flag after a recent: > commit 923936efeb74b3 ("iomap: Fix conflicting values of iomap flags") > > Signed-off-by: Ritesh Harjani (IBM) <ritesh.list@gmail.com> Reads fine to me now :) Reviewed-by: "Darrick J. Wong" <djwong@kernel.org> --D > --- > Documentation/filesystems/iomap/design.rst | 16 ++++++++++++++-- > 1 file changed, 14 insertions(+), 2 deletions(-) > > diff --git a/Documentation/filesystems/iomap/design.rst b/Documentation/filesystems/iomap/design.rst > index e29651a42eec..f2df9b6df988 100644 > --- a/Documentation/filesystems/iomap/design.rst > +++ b/Documentation/filesystems/iomap/design.rst > @@ -243,13 +243,25 @@ The fields are as follows: > regular file data. > This is only useful for FIEMAP. > > - * **IOMAP_F_PRIVATE**: Starting with this value, the upper bits can > - be set by the filesystem for its own purposes. > + * **IOMAP_F_BOUNDARY**: This indicates I/O and its completion must not be > + merged with any other I/O or completion. Filesystems must use this when > + submitting I/O to devices that cannot handle I/O crossing certain LBAs > + (e.g. ZNS devices). This flag applies only to buffered I/O writeback; all > + other functions ignore it. > + > + * **IOMAP_F_PRIVATE**: This flag is reserved for filesystem private use. > > * **IOMAP_F_ANON_WRITE**: Indicates that (write) I/O does not have a target > block assigned to it yet and the file system will do that in the bio > submission handler, splitting the I/O as needed. > > + * **IOMAP_F_ATOMIC_BIO**: This indicates write I/O must be submitted with the > + ``REQ_ATOMIC`` flag set in the bio. Filesystems need to set this flag to > + inform iomap that the write I/O operation requires torn-write protection > + based on HW-offload mechanism. They must also ensure that mapping updates > + upon the completion of the I/O must be performed in a single metadata > + update. > + > These flags can be set by iomap itself during file operations. > The filesystem should supply an ``->iomap_end`` function if it needs > to observe these flags: > -- > 2.48.1 > >
On Sat, 12 Apr 2025 10:06:34 +0530, Ritesh Harjani (IBM) wrote: > Let's document the use of these flags in iomap design doc where other > flags are defined too - > > - IOMAP_F_BOUNDARY was added by XFS to prevent merging of I/O and I/O > completions across RTG boundaries. > - IOMAP_F_ATOMIC_BIO was added for supporting atomic I/O operations > for filesystems to inform the iomap that it needs HW-offload based > mechanism for torn-write protection. > > [...] Applied to the vfs-6.16.iomap branch of the vfs/vfs.git tree. Patches in the vfs-6.16.iomap branch should appear in linux-next soon. Please report any outstanding bugs that were missed during review in a new review to the original patch series allowing us to drop it. It's encouraged to provide Acked-bys and Reviewed-bys even though the patch has now been applied. If possible patch trailers will be updated. Note that commit hashes shown below are subject to change due to rebase, trailer updates or similar. If in doubt, please check the listed branch. tree: https://git.kernel.org/pub/scm/linux/kernel/git/vfs/vfs.git branch: vfs-6.16.iomap [1/2] Documentation: iomap: Add missing flags description https://git.kernel.org/vfs/vfs/c/336bac5e0892 [2/2] iomap: trace: Add missing flags to [IOMAP_|IOMAP_F_]FLAGS_STRINGS https://git.kernel.org/vfs/vfs/c/d1253c677b8f
diff --git a/Documentation/filesystems/iomap/design.rst b/Documentation/filesystems/iomap/design.rst index e29651a42eec..f2df9b6df988 100644 --- a/Documentation/filesystems/iomap/design.rst +++ b/Documentation/filesystems/iomap/design.rst @@ -243,13 +243,25 @@ The fields are as follows: regular file data. This is only useful for FIEMAP. - * **IOMAP_F_PRIVATE**: Starting with this value, the upper bits can - be set by the filesystem for its own purposes. + * **IOMAP_F_BOUNDARY**: This indicates I/O and its completion must not be + merged with any other I/O or completion. Filesystems must use this when + submitting I/O to devices that cannot handle I/O crossing certain LBAs + (e.g. ZNS devices). This flag applies only to buffered I/O writeback; all + other functions ignore it. + + * **IOMAP_F_PRIVATE**: This flag is reserved for filesystem private use. * **IOMAP_F_ANON_WRITE**: Indicates that (write) I/O does not have a target block assigned to it yet and the file system will do that in the bio submission handler, splitting the I/O as needed. + * **IOMAP_F_ATOMIC_BIO**: This indicates write I/O must be submitted with the + ``REQ_ATOMIC`` flag set in the bio. Filesystems need to set this flag to + inform iomap that the write I/O operation requires torn-write protection + based on HW-offload mechanism. They must also ensure that mapping updates + upon the completion of the I/O must be performed in a single metadata + update. + These flags can be set by iomap itself during file operations. The filesystem should supply an ``->iomap_end`` function if it needs to observe these flags:
Let's document the use of these flags in iomap design doc where other flags are defined too - - IOMAP_F_BOUNDARY was added by XFS to prevent merging of I/O and I/O completions across RTG boundaries. - IOMAP_F_ATOMIC_BIO was added for supporting atomic I/O operations for filesystems to inform the iomap that it needs HW-offload based mechanism for torn-write protection. While we are at it, let's also fix the description of IOMAP_F_PRIVATE flag after a recent: commit 923936efeb74b3 ("iomap: Fix conflicting values of iomap flags") Signed-off-by: Ritesh Harjani (IBM) <ritesh.list@gmail.com> --- Documentation/filesystems/iomap/design.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) -- 2.48.1