iolog: update man page for version 3

[fio.git] / HOWTO.rst

diff --git a/HOWTO.rst b/HOWTO.rst
index 0e49d8a88e30200288be90bc1d8989271461ce67..a5fa432e4b59caa4838eb24fe5687aa2a13e43c1 100644 (file)
--- a/HOWTO.rst
+++ b/HOWTO.rst
@@ -1443,7 +1443,7 @@ I/O type
        range of possible random values.
        Defaults are: random for **pareto** and **zipf**, and 0.5 for **normal**.
        If you wanted to use **zipf** with a `theta` of 1.2 centered on 1/4 of allowed value range,
-       you would use ``random_distibution=zipf:1.2:0.25``.
+       you would use ``random_distribution=zipf:1.2:0.25``.
 
        For a **zoned** distribution, fio supports specifying percentages of I/O
        access that should fall within what range of the file or device. For
@@ -2277,13 +2277,11 @@ with the caveat that when used on the command line, they must come after the
         by the application. The benefits are more efficient IO for high IOPS
         scenarios, and lower latencies for low queue depth IO.
 
-
    [pvsync2]
 
        Set RWF_HIPRI on I/O, indicating to the kernel that it's of higher priority
        than normal.
 
-
    [sg]
 
        If this option is set, fio will attempt to use polled IO completions.
@@ -2506,11 +2504,17 @@ with the caveat that when used on the command line, they must come after the
 
        Specify the label or UUID of the DAOS container to open.
 
-.. option:: chunk_size=int : [dfs]
+.. option:: chunk_size=int
+
+   [dfs]
 
        Specificy a different chunk size (in bytes) for the dfs file.
        Use DAOS container's chunk size by default.
 
+   [libhdfs]
+
+       The size of the chunk to use for each file.
+
 .. option:: object_class=str : [dfs]
 
        Specificy a different object class for the dfs file.
@@ -2524,10 +2528,6 @@ with the caveat that when used on the command line, they must come after the
 
        libhdfs will create chunk in this HDFS directory.
 
-.. option:: chunk_size : [libhdfs]
-
-       The size of the chunk to use for each file.
-
 .. option:: verb=str : [rdma]
 
        The RDMA verb to use on this side of the RDMA ioengine connection. Valid
@@ -3370,7 +3370,7 @@ Verification
        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.
+       same offset with multiple outstanding I/Os.
 
 .. option:: verify_offset=int
 
@@ -4398,7 +4398,9 @@ given in bytes. The `action` can be one of these:
 
 **wait**
           Wait for `offset` microseconds. Everything below 100 is discarded.
-          The time is relative to the previous `wait` statement.
+          The time is relative to the previous `wait` statement. Note that
+          action `wait` is not allowed as of version 3, as the same behavior
+          can be achieved using timestamps.
 **read**
           Read `length` bytes beginning from `offset`.
 **write**
@@ -4411,6 +4413,31 @@ given in bytes. The `action` can be one of these:
           Trim the given file from the given `offset` for `length` bytes.
 
 
+Trace file format v3
+~~~~~~~~~~~~~~~~~~~~
+
+The third version of the trace file format was added in fio version 3.31. It
+forces each action to have a timestamp associated with it.
+
+The first line of the trace file has to be::
+
+    fio version 3 iolog
+
+Following this can be lines in two different formats, which are described below.
+
+The file management format::
+
+    timestamp filename action
+
+The file I/O action format::
+
+    timestamp filename action offset length
+
+The `timestamp` is relative to the beginning of the run (ie starts at 0). The
+`filename`, `action`, `offset` and `length`  are identical to version 2, except
+that version 3 does not allow the `wait` action.
+
+
 I/O Replay - Merging Traces
 ---------------------------