Fio 1.16.2

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 8312d9315ae3a591b7a85cdd0822c86626ace840..5156adbe1e39c6ae738392e04467d155ee2abe57 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -211,7 +211,9 @@ filename=str        Fio normally makes up a filename based on the job name,
                ioengine is file based, you can specify a number of files
                by seperating the names with a ':' colon. So if you wanted
                a job to open /dev/sda and /dev/sdb as the two working files,
-               you would use filename=/dev/sda:/dev/sdb
+               you would use filename=/dev/sda:/dev/sdb. '-' is a reserved
+               name, meaning stdin or stdout. Which of the two depends
+               on the read/write direction set.
 
 opendir=str    Tell fio to recursively add any file it can find in this
                directory and down the file system tree.
@@ -283,6 +285,9 @@ bs_unaligned        If this option is given, any byte size value within bsrange
                may be used as a block range. This typically wont work with
                direct IO, as that normally requires sector alignment.
 
+zero_buffers   If this option is given, fio will init the IO buffers to
+               all zeroes. The default is to fill them with random data.
+
 nrfiles=int    Number of files to use for this job. Defaults to 1.
 
 openfiles=int  Number of files to keep open at the same time. Defaults to
@@ -460,7 +465,8 @@ ratecycle=int       Average bandwidth for 'rate' and 'ratemin' over this number
 
 cpumask=int    Set the CPU affinity of this job. The parameter given is a
                bitmask of allowed CPU's the job may run on. See man
-               sched_setaffinity(2).
+               sched_setaffinity(2). This may not work on all supported
+               operating systems or kernel versions.
 
 startdelay=int Start this job the specified number of seconds after fio
                has started. Only useful if the job file contains several
@@ -472,6 +478,11 @@ runtime=int        Tell fio to terminate processing after the specified number
                a specified job will run, so this parameter is handy to
                cap the total runtime to a given time.
 
+time_based     If set, fio will run for the duration of the runtime
+               specified even if the file(s) are completey read or
+               written. It will simply loop over the same workload
+               as many times as the runtime allows.
+
 invalidate=bool        Invalidate the buffer/page cache parts for this file prior
                to starting io. Defaults to true.
 
@@ -555,10 +566,22 @@ verify=str        If writing to a file, fio can verify the file contents
                        crc32   Use a crc32 sum of the data area and store
                                it in the header of each block.
 
+                       null    Only pretend to verify. Useful for testing
+                               internals with ioengine=null, not for much
+                               else.
+
                This option can be used for repeated burn-in tests of a
                system to make sure that the written data is also
                correctly read back.
 
+verifysort=bool        If set, fio will sort written verify blocks when it deems
+               it faster to read them back in a sorted manner. This is
+               often the case when overwriting an existing file, since
+               the blocks are already laid out in the file system. You
+               can ignore this option unless doing huge amounts of really
+               fast IO where the red-black tree sorting CPU time becomes
+               significant.
+               
 stonewall      Wait for preceeding jobs in the job file to exit, before
                starting this one. Can be used to insert serialization
                points in the job file. A stone wall also implies starting
@@ -596,7 +619,12 @@ write_iolog=str    Write the issued io patterns to the specified file. See
 
 read_iolog=str Open an iolog with the specified file name and replay the
                io patterns it contains. This can be used to store a
-               workload and replay it sometime later.
+               workload and replay it sometime later. The iolog given
+               may also be a blktrace binary file, which allows fio
+               to replay a workload captured by blktrace. See blktrace
+               for how to capture such logging data. For blktrace replay,
+               the file needs to be turned into a blkparse binary data
+               file first (blktrace <device> -d file_for_fio.bin).
 
 write_bw_log   If given, write a bandwidth log of the jobs in this job
                file. Can be used to store data of the bandwidth of the
@@ -626,6 +654,9 @@ cpuload=int If the job is a CPU cycle eater, attempt to use the specified
 cpuchunks=int  If the job is a CPU cycle eater, split the load into
                cycles of the given time. In milliseconds.
 
+disk_util=bool Generate disk utilization statistics, if the platform
+               supports it. Defaults to on.
+
 
 6.0 Interpreting the output
 ---------------------------
@@ -670,6 +701,7 @@ Client1 (g=0): err= 0:
     bw (KiB/s) : min=    0, max= 1196, per=51.00%, avg=664.02, stdev=681.68
   cpu        : usr=1.49%, sys=0.25%, ctx=7969
   IO depths    : 1=0.1%, 2=0.3%, 4=0.5%, 8=99.0%, 16=0.0%, 32=0.0%, >32=0.0%
+     issued r/w: total=0/32768, short=0/0
      lat (msec): 2=1.6%, 4=0.0%, 10=3.2%, 20=12.8%, 50=38.4%, 100=24.8%,
      lat (msec): 250=15.2%, 500=0.0%, 750=0.0%, 1000=0.0%, >=2048=0.0%
 
@@ -701,6 +733,8 @@ IO depths=  The distribution of io depths over the job life time. The
                16= entries includes depths up to that value but higher
                than the previous entry. In other words, it covers the
                range from 16 to 31.
+IO issued=     The number of read/write requests issued, and how many
+               of them were short.
 IO latencies=  The distribution of IO completion latencies. This is the
                time from when IO leaves fio and when it gets completed.
                The numbers follow the same pattern as the IO depths,