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@xxxxxxxxx>
Reads fine to me now :)
Reviewed-by: "Darrick J. Wong" <djwong@xxxxxxxxxx>
--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
>
>
