Re: [PATCH v6 3/7] fs: iomap: Atomic write support

From: John Garry
Date: Tue Oct 01 2024 - 04:05:55 EST




This new flag needs a documentation update. What do you think of this?

diff --git a/Documentation/filesystems/iomap/operations.rst b/Documentation/filesystems/iomap/operations.rst
index 8e6c721d23301..279db993be7fa 100644
--- a/Documentation/filesystems/iomap/operations.rst
+++ b/Documentation/filesystems/iomap/operations.rst
@@ -513,6 +513,16 @@ IOMAP_WRITE`` with any combination of the following enhancements:
if the mapping is unwritten and the filesystem cannot handle zeroing
the unaligned regions without exposing stale contents.
+ * ``IOMAP_ATOMIC``: This write must be persisted in its entirety or
+ not at all.
+ The write must not be split into multiple I/O requests.
+ The file range to write must be aligned to satisfy the requirements
+ of both the filesystem and the underlying block device's atomic
+ commit capabilities.
+ If filesystem metadata updates are required (e.g. unwritten extent
+ conversion or copy on write), all updates for the entire file range
+ must be committed atomically as well.
+
Callers commonly hold ``i_rwsem`` in shared or exclusive mode before
calling this function.

Sure, but I would make a couple of tweaks to the beginning:

* ``IOMAP_ATOMIC``: This write is to be be issued with torn-write
protection. Only a single bio can be created for the write, and the
bio must not be split into multiple I/O requests, i.e. flag
REQ_ATOMIC must be set.
The file range to write must be aligned to satisfy the requirements
of both the filesystem and the underlying block device's atomic
commit capabilities.
If filesystem metadata updates are required (e.g. unwritten extent
conversion or copy on write), all updates for the entire file range
must be committed atomically as well.

ok?

Thanks,
John