More __must_check annotations

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index f4ebac94348eef97b46b70b80dce8d1e3130dda4..ea98810a211d97328232dfb593f84654cfa2f331 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -49,7 +49,7 @@ bottom, it contains the following basic parameters:
 
        IO engine       How do we issue io? We could be memory mapping the
                        file, we could be using regular read/write, we
-                       could be using splice, async io, or even
+                       could be using splice, async io, syslet, or even
                        SG (SCSI generic sg).
 
        IO depth        If the io engine is async, how large a queuing
@@ -108,8 +108,8 @@ to use any ascii name you want, except 'global' which has special meaning.
 A global section sets defaults for the jobs described in that file. A job
 may override a global section parameter, and a job file may even have
 several global sections if so desired. A job is only affected by a global
-section residing above it. If the first character in a line is a ';', the
-entire line is discarded as a comment.
+section residing above it. If the first character in a line is a ';' or a
+'#', the entire line is discarded as a comment.
 
 So lets look at a really simple job file that define to threads, each
 randomly reading from a 128MiB file.
@@ -203,7 +203,9 @@ directory=str       Prefix filenames with this directory. Used to places files
 filename=str   Fio normally makes up a filename based on the job name,
                thread number, and file number. If you want to share
                files between threads in a job or several jobs, specify
-               a filename for each of them to override the default.
+               a filename for each of them to override the default. If
+               the ioengine used is 'net', the filename is the host and
+               port to connect to in the format of =host:port.
 
 rw=str         Type of io pattern. Accepted values are:
 
@@ -268,6 +270,9 @@ ioengine=str        Defines how the job issues io to the file. The following
                                vmsplice(2) to transfer data from user
                                space to the kernel.
 
+                       syslet-rw Use the syslet system calls to make
+                               regular read/write async.
+
                        sg      SCSI generic sg v3 io. May either be
                                synchronous using the SG_IO ioctl, or if
                                the target is an sg character device
@@ -278,11 +283,24 @@ ioengine=str      Defines how the job issues io to the file. The following
                                to. This is mainly used to exercise fio
                                itself and for debugging/testing purposes.
 
+                       net     Transfer over the network to given host:port.
+                               'filename' must be set appropriately to
+                               filename=host:port regardless of send
+                               or receive, if the latter only the port
+                               argument is used.
+
 iodepth=int    This defines how many io units to keep in flight against
                the file. The default is 1 for each file defined in this
                job, can be overridden with a larger value for higher
                concurrency.
 
+iodepth_low=int        The low water mark indicating when to start filling
+               the queue again. Defaults to the same as iodepth, meaning
+               that fio will attempt to keep the queue full at all times.
+               If iodepth is set to eg 16 and iodepth_low is set to 4, then
+               after fio has filled the queue of 16 requests, it will let
+               the depth drain down to 4 before starting to fill it again.
+
 direct=bool    If value is true, use non-buffered io. This is usually
                O_DIRECT.
 
@@ -332,7 +350,14 @@ prioclass=int      Set the io priority class. See man ionice(1).
 
 thinktime=int  Stall the job x microseconds after an io has completed before
                issuing the next. May be used to simulate processing being
-               done by an application. See thinktime_blocks.
+               done by an application. See thinktime_blocks and
+               thinktime_spin.
+
+thinktime_spin=int
+               Only valid if thinktime is set - pretend to spend CPU time
+               doing something with the data received, before falling back
+               to sleeping for the rest of the period specified by
+               thinktime.
 
 thinktime_blocks
                Only valid if thinktime is set - control how many blocks
@@ -545,6 +570,8 @@ 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%
+     lat (msec): 2=1.6%, 4=0.0%, 8=3.2%, 16=12.8%, 32=38.4%, 64=24.8%, 128=15.2%
+     lat (msec): 256=4.0%, 512=0.0%, 1024=0.0%, >=2048=0.0%
 
 The client number is printed, along with the group id and error of that
 thread. Below is the io statistics, here for writes. In the order listed,
@@ -574,6 +601,12 @@ 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 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,
+               meaning that 2=1.6% means that 1.6% of the IO completed
+               within 2 msecs, 16=12.8% means that 12.8% of the IO
+               took more than 8 msecs, but less than (or equal to) 16 msecs.
 
 After each client has been listed, the group statistics are printed. They
 will look like this: