doc: add text about possibly verify errors with norandommap

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 7680f9c7634a7e55044dba0a8ebdc6928fb3bfc0..70eed2805c2d96811d4238afaed645f4f3a10e45 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -163,12 +163,12 @@ Command line options
 
 .. option:: --readonly
 
-       Turn on safety read-only checks, preventing writes.  The ``--readonly``
-       option is an extra safety guard to prevent users from accidentally starting
-       a write workload when that is not desired.  Fio will only write if
-       `rw=write/randwrite/rw/randrw` is given.  This extra safety net can be used
-       as an extra precaution as ``--readonly`` will also enable a write check in
-       the I/O engine core to prevent writes due to unknown user space bug(s).
+       Turn on safety read-only checks, preventing writes and trims.  The
+       ``--readonly`` option is an extra safety guard to prevent users from
+       accidentally starting a write or trim workload when that is not desired.
+       Fio will only modify the device under test if
+       `rw=write/randwrite/rw/randrw/trim/randtrim/trimwrite` is given.  This
+       safety net can be used as an extra precaution.
 
 .. option:: --eta=when
 
@@ -1329,7 +1329,9 @@ I/O type
        and that some blocks may be read/written more than once. If this option is
        used with :option:`verify` and multiple blocksizes (via :option:`bsrange`),
        only intact blocks are verified, i.e., partially-overwritten blocks are
-       ignored.
+       ignored.  With an async I/O engine and an I/O depth > 1, it is possible for
+       the same block to be overwritten, which can cause verification errors.  Either
+       do not use norandommap in this case, or also use the lfsr random generator.
 
 .. option:: softrandommap=bool
 
@@ -1429,7 +1431,7 @@ Block size
        If you want a workload that has 50% 2k reads and 50% 4k reads, while
        having 90% 4k writes and 10% 8k writes, you would specify::
 
-               bssplit=2k/50:4k/50,4k/90,8k/10
+               bssplit=2k/50:4k/50,4k/90:8k/10
 
        Fio supports defining up to 64 different weights for each data
        direction.
@@ -2663,6 +2665,11 @@ Verification
        previously written file. If the data direction includes any form of write,
        the verify will be of the newly written data.
 
+       To avoid false verification errors, do not use the norandommap option when
+       verifying data with async I/O engines and I/O depths > 1.  Or use the
+       norandommap and the lfsr random generator together to avoid writing to the
+       same offset with muliple outstanding I/Os.
+
 .. option:: verify_offset=int
 
        Swap the verification header with data somewhere else in the block before