iolog: update man page for version 3

[fio.git] / HOWTO.rst

diff --git a/HOWTO.rst b/HOWTO.rst
index 0978879ce693a6c28527497c1739bd3dfcf72158..a5fa432e4b59caa4838eb24fe5687aa2a13e43c1 100644 (file)
--- a/HOWTO.rst
+++ b/HOWTO.rst
@@ -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
 ---------------------------