doc: Document atomic command

Now that the atomic command is formally supported, document it.

Signed-off-by: John Garry <john.g.garry@oracle.com>
Link: https://lore.kernel.org/r/20240916165347.2226763-8-john.g.garry@oracle.com
Signed-off-by: Jens Axboe <axboe@kernel.dk>

diff --git a/HOWTO.rst b/HOWTO.rst
index a363206d239af2bfe2310a8c5989212200cf6709..c6c9b3060043f2bb8ac4983d77d3e44c32d6e92b 100644 (file)
--- a/HOWTO.rst
+++ b/HOWTO.rst
@@ -2501,6 +2501,20 @@ with the caveat that when used on the command line, they must come after the
        For direct I/O, requests will only succeed if cache invalidation isn't required,
        file blocks are fully allocated and the disk request could be issued immediately.
 
+.. option:: atomic=bool : [pvsync2] [libaio] [io_uring]
+
+       This option means that writes are issued with torn-write protection, meaning
+       that for a power fail or kernel crash, all or none of the data from the write
+       will be stored, but never a mix of old and new data. Torn-write protection is
+       also known as atomic writes.
+
+       This option sets the RWF_ATOMIC flag (supported from the 6.11 Linux kernel) on
+       a per-IO basis.
+
+       Writes with RWF_ATOMIC set will be rejected by the kernel when the file does
+       not support torn-write protection. To learn a file's torn-write limits, issue
+       statx with STATX_WRITE_ATOMIC.
+
 .. option:: fdp=bool : [io_uring_cmd] [xnvme]
 
        Enable Flexible Data Placement mode for write commands.

diff --git a/fio.1 b/fio.1
index a4ab07ed8fff5d66f27f98f751365d1aa257219d..6e5bed9d0610580bcb99fc2381f6e5a19598ee58 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -2266,6 +2266,19 @@ cached data. Currently the RWF_NOWAIT flag does not supported for cached write.
 For direct I/O, requests will only succeed if cache invalidation isn't required,
 file blocks are fully allocated and the disk request could be issued immediately.
 .TP
+.BI (pvsync2,libaio,io_uring)atomic \fR=\fPbool
+This option means that writes are issued with torn-write protection, meaning
+that for a power fail or kernel crash, all or none of the data from the write
+will be stored, but never a mix of old and new data. Torn-write protection is
+also known as atomic writes.
+
+This option sets the RWF_ATOMIC flag (supported from the 6.11 Linux kernel) on
+a per-IO basis.
+
+Writes with RWF_ATOMIC set will be rejected by the kernel when the file does
+not support torn-write protection. To learn a file's torn-write limits, issue
+statx with STATX_WRITE_ATOMIC.
+.TP
 .BI (io_uring_cmd,xnvme)fdp \fR=\fPbool
 Enable Flexible Data Placement mode for write commands.
 .TP