fio: add serialize_overlap option

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index fc173f02876faab1b0049b4e8f4b6c99acd5b3a5..8a7cb1aac380973900a32884f08c64df3cb41a02 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -2030,6 +2030,21 @@ I/O depth
        16 requests, it will let the depth drain down to 4 before starting to fill
        it again.
 
+.. option:: serialize_overlap=bool
+
+       Serialize in-flight I/Os that might otherwise cause or suffer from data races.
+       When two or more I/Os are submitted simultaneously, there is no guarantee that
+       the I/Os will be processed or completed in the submitted order. Further, if
+       two or more of those I/Os are writes, any overlapping region between them can
+       become indeterminate/undefined on certain storage. These issues can cause
+       verification to fail erratically when at least one of the racing I/Os is
+       changing data and the overlapping region has a non-zero size. Setting
+       ``serialize_overlap`` tells fio to avoid provoking this behavior by explicitly
+       serializing in-flight I/Os that have a non-zero overlap. Note that setting
+       this option can reduce both performance and the `:option:iodepth` achieved.
+       Additionally this option does not work when :option:`io_submit_mode` is set to
+       offload. Default: false.
+
 .. option:: io_submit_mode=str
 
        This option controls how fio submits the I/O to the I/O engine. The default
@@ -2605,7 +2620,6 @@ Verification
 
        Enable experimental verification.
 
-
 Steady state
 ~~~~~~~~~~~~