docs: update HOWTO and manpage for sg trim support

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index e1399b4a101925d94527542e4c5f8f696668912b..804d93e4c578bfdb7d47058d177cce34420bb380 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -991,13 +991,15 @@ I/O type
                **write**
                                Sequential writes.
                **trim**
                **write**
                                Sequential writes.
                **trim**

-                               Sequential trims (Linux block devices only).
+                               Sequential trims (Linux block devices and SCSI
+                               character devices only).

                **randread**
                                Random reads.
                **randwrite**
                                Random writes.
                **randtrim**
                **randread**
                                Random reads.
                **randwrite**
                                Random writes.
                **randtrim**

-                               Random trims (Linux block devices only).
+                               Random trims (Linux block devices and SCSI
+                               character devices only).

                **rw,readwrite**
                                Sequential mixed reads and writes.
                **randrw**
                **rw,readwrite**
                                Sequential mixed reads and writes.
                **randrw**


@@ -1329,7 +1331,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
 


@@ -1746,7 +1750,7 @@ I/O engine
                        ioctl, or if the target is an sg character device we use
                        :manpage:`read(2)` and :manpage:`write(2)` for asynchronous
                        I/O. Requires :option:`filename` option to specify either block or
                        ioctl, or if the target is an sg character device we use
                        :manpage:`read(2)` and :manpage:`write(2)` for asynchronous
                        I/O. Requires :option:`filename` option to specify either block or

-                       character devices.
+                       character devices. This engine supports trim operations.

                        The sg engine includes engine specific options.
 
                **null**
                        The sg engine includes engine specific options.
 
                **null**


@@ -2080,6 +2084,7 @@ with the caveat that when used on the command line, they must come after the
        the force unit access (fua) flag. Default is 0.
 
 .. option:: sg_write_mode=str : [sg]
        the force unit access (fua) flag. Default is 0.
 
 .. option:: sg_write_mode=str : [sg]

+

        Specify the type of write commands to issue. This option can take three values:
 
        **write**
        Specify the type of write commands to issue. This option can take three values:
 
        **write**


@@ -2663,6 +2668,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