doc: add text about possibly verify errors with norandommap

In both the norandommap option section, and the verify option section,
add text warning that norandommap can cause data verification errors
when using async io engines and io depths > 1.

Signed-off-by: Steve Wise <swise@opengridcomputing.com>

diff --git a/HOWTO b/HOWTO
index e1399b4a101925d94527542e4c5f8f696668912b..70eed2805c2d96811d4238afaed645f4f3a10e45 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -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
        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
 
 
 .. option:: softrandommap=bool
 


@@ -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.
 
        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
 .. option:: verify_offset=int
 
        Swap the verification header with data somewhere else in the block before

diff --git a/fio.1 b/fio.1
index c744d1add10f869284127b0261873404ebe2c098..6d2eba67b1419d8d3e60b886c83bde9d87018fa0 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -1120,7 +1120,9 @@ at past I/O history. This means that some blocks may not be read or written,
 and that some blocks may be read/written more than once. If this option is
 used with \fBverify\fR and multiple blocksizes (via \fBbsrange\fR),
 only intact blocks are verified, i.e., partially\-overwritten blocks are
 and that some blocks may be read/written more than once. If this option is
 used with \fBverify\fR and multiple blocksizes (via \fBbsrange\fR),
 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.

 .TP
 .BI softrandommap \fR=\fPbool
 See \fBnorandommap\fR. If fio runs with the random block map enabled and
 .TP
 .BI softrandommap \fR=\fPbool
 See \fBnorandommap\fR. If fio runs with the random block map enabled and


@@ -2370,6 +2372,11 @@ that the written data is also correctly read back. If the data direction
 given is a read or random read, fio will assume that it should verify a
 previously written file. If the data direction includes any form of write,
 the verify will be of the newly written data.
 given is a read or random read, fio will assume that it should verify a
 previously written file. If the data direction includes any form of write,
 the verify will be of the newly written data.

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

 .RE
 .TP
 .BI verify_offset \fR=\fPint
 .RE
 .TP
 .BI verify_offset \fR=\fPint