posixaio engine: residual data count

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index f61b4c1daab6b54831d5195dc36000be502461ab..06408e40e16a91fadeea2dce399efc444845b6e5 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -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.
@@ -253,6 +253,14 @@ bs_unaligned       If this option is given, any byte size value within bsrange
 
 nrfiles=int    Number of files to use for this job. Defaults to 1.
 
+file_service_type=str  Defines how fio decides which file from a job to
+               service next. The following types are defined:
+
+                       random  Just choose a file at random.
+
+                       roundrobin  Round robin over open files. This
+                               is the default.
+
 ioengine=str   Defines how the job issues io to the file. The following
                types are defined:
 
@@ -289,11 +297,27 @@ ioengine=str      Defines how the job issues io to the file. The following
                                or receive, if the latter only the port
                                argument is used.
 
+                       external Prefix to specify loading an external
+                               IO engine object file. Append the engine
+                               filename, eg ioengine=external:/tmp/foo.o
+                               to load ioengine foo.o in /tmp.
+
 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_batch=int This defines how many pieces of IO to submit at once.
+               It defaults to the same as iodepth, but can be set lower
+               if one so desires.
+
+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.
 
@@ -343,7 +367,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
@@ -556,8 +587,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%
+     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%
 
 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,
@@ -591,8 +622,8 @@ 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.
+               within 2 msecs, 20=12.8% means that 12.8% of the IO
+               took more than 10 msecs, but less than (or equal to) 20 msecs.
 
 After each client has been listed, the group statistics are printed. They
 will look like this: