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

[Ritesh Harjani (IBM) <ritesh.list@gmail.com>]

"Darrick J. Wong" <djwong@kernel.org> writes:

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

Sure.

>>     * **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.
>

Thanks Darrick, for the clarification and the review comments on this
patch. Once the remaining tracing patch is reviewed, I will incorporate
these comments in v2.

-ritesh