Re: [PATCH 1/2] Documentation: iomap: Add missing flags description

["Darrick J. Wong" <djwong@kernel.org>]

On Thu, Apr 03, 2025 at 11:52:27PM +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 ioends
>   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
> 
> Signed-off-by: Ritesh Harjani (IBM) <ritesh.list@gmail.com>
> ---
>  Documentation/filesystems/iomap/design.rst | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/Documentation/filesystems/iomap/design.rst b/Documentation/filesystems/iomap/design.rst
> index e29651a42eec..b916e85bc930 100644
> --- a/Documentation/filesystems/iomap/design.rst
> +++ b/Documentation/filesystems/iomap/design.rst
> @@ -243,6 +243,11 @@ The fields are as follows:
>       regular file data.
>       This is only useful for FIEMAP.
>  
> +   * **IOMAP_F_BOUNDARY**: This indicates that I/O and I/O completions
> +     for this iomap must never be merged with the mapping before it.
> +     Currently XFS uses this to prevent merging of ioends across RTG
> +     (realtime group) boundaries.

Hrm, ok.  Based on hch's comment about not mentioning specific fs
behavior, I think I'll suggest something more like:

IOMAP_F_BOUNDARY: This 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**: Starting with this value, the upper bits can
>       be set by the filesystem for its own purposes.
>  
> @@ -250,6 +255,11 @@ The fields are as follows:
>       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**: Indicates that 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.

--D

> +
>     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
> 
>