fio: HOWTO update

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index cdfe80aa9fc4f1908ecf504a9ba5dae1b7a11071..d8c6b9414eef85be48779d7018682cf2bbd07470 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -262,6 +262,10 @@ filesize=siint     Individual file sizes. May be a range, in which case fio
                and limited to 'size' in total (if that is given). If not
                given, each created file is the same size.
 
                and limited to 'size' in total (if that is given). If not
                given, each created file is the same size.
 

+fill_device=bool Sets size to something really large and waits for ENOSPC (no
+               space left on device) as the terminating condition. Only makes
+                sense with sequential write.
+

 blocksize=siint
 bs=siint       The block size used for the io units. Defaults to 4k. Values
                can be given for both read and writes. If a single siint is
 blocksize=siint
 bs=siint       The block size used for the io units. Defaults to 4k. Values
                can be given for both read and writes. If a single siint is


@@ -281,6 +285,30 @@ bsrange=irange     Instead of giving a single block size, specify a range
                writes, however a second range can be given after a comma.
                See bs=.
 
                writes, however a second range can be given after a comma.
                See bs=.
 

+bssplit=str    Sometimes you want even finer grained control of the
+               block sizes issued, not just an even split between them.
+               This option allows you to weight various block sizes,
+               so that you are able to define a specific amount of
+               block sizes issued. The format for this option is:
+
+                       bssplit=blocksize/percentage:blocksize/percentage
+
+               for as many block sizes as needed. So if you want to define
+               a workload that has 50% 64k blocks, 10% 4k blocks, and
+               40% 32k blocks, you would write:
+
+                       bssplit=4k/10:64k/50:32k/40
+
+               Ordering does not matter. If the percentage is left blank,
+               fio will fill in the remaining values evenly. So a bssplit
+               option like this one:
+
+                       bssplit=4k/50:1k/:32k/
+
+               would have 50% 4k ios, and 25% 1k and 32k ios. The percentages
+               always add up to 100, if bssplit is given a range that adds
+               up to more, it will error out.
+

 blocksize_unaligned
 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
 blocksize_unaligned
 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


@@ -314,6 +342,10 @@ ioengine=str       Defines how the job issues io to the file. The following
                        sync    Basic read(2) or write(2) io. lseek(2) is
                                used to position the io location.
 
                        sync    Basic read(2) or write(2) io. lseek(2) is
                                used to position the io location.
 

+                       psync   Basic pread(2) or pwrite(2) io.
+
+                       vsync   Basic readv(2) or writev(2) IO.
+

                        libaio  Linux native asynchronous io.
 
                        posixaio glibc posix asynchronous io.
                        libaio  Linux native asynchronous io.
 
                        posixaio glibc posix asynchronous io.


@@ -347,11 +379,14 @@ ioengine=str      Defines how the job issues io to the file. The following
                        netsplice Like net, but uses splice/vmsplice to
                                map data and send/receive.
 
                        netsplice Like net, but uses splice/vmsplice to
                                map data and send/receive.
 

-                       cpu     Doesn't transfer any data, but burns CPU
+                       cpuio   Doesn't transfer any data, but burns CPU

                                cycles according to the cpuload= and
                                cpucycle= options. Setting cpuload=85
                                will cause that job to do nothing but burn
                                cycles according to the cpuload= and
                                cpucycle= options. Setting cpuload=85
                                will cause that job to do nothing but burn

-                               85% of the CPU.
+                               85% of the CPU. In case of SMP machines,
+                               use numjobs=<no_of_cpu> to get desired CPU
+                               usage, as the cpuload only loads a single
+                               CPU at the desired rate.

 
                        guasi   The GUASI IO engine is the Generic Userspace
                                Asyncronous Syscall Interface approach
 
                        guasi   The GUASI IO engine is the Generic Userspace
                                Asyncronous Syscall Interface approach


@@ -372,8 +407,9 @@ iodepth=int This defines how many io units to keep in flight against
                concurrency.
 
 iodepth_batch=int This defines how many pieces of IO to submit at once.
                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.
+               It defaults to 1 which means that we submit each IO
+               as soon as it is available, but can be raised to submit
+               bigger batches of IO at the time.

 
 iodepth_low=int        The low water mark indicating when to start filling
                the queue again. Defaults to the same as iodepth, meaning
 
 iodepth_low=int        The low water mark indicating when to start filling
                the queue again. Defaults to the same as iodepth, meaning


@@ -569,7 +605,7 @@ loops=int   Run the specified number of iterations of this job. Used
                to repeat the same workload a given number of times. Defaults
                to 1.
 
                to repeat the same workload a given number of times. Defaults
                to 1.
 

-do_verify=int  Run the verify phase after a write phase. Only makes sense if
+do_verify=bool Run the verify phase after a write phase. Only makes sense if

                verify is set. Defaults to 1.
 
 verify=str     If writing to a file, fio can verify the file contents
                verify is set. Defaults to 1.
 
 verify=str     If writing to a file, fio can verify the file contents


@@ -631,6 +667,11 @@ verify_pattern=int If set, fio will fill the io buffers with this
                width of the pattern, fio will fill 1/2/3/4 bytes of the
                buffer at the time. The verify_pattern cannot be larger than
                a 32-bit quantity.
                width of the pattern, fio will fill 1/2/3/4 bytes of the
                buffer at the time. The verify_pattern cannot be larger than
                a 32-bit quantity.

+
+verify_fatal=bool      Normally fio will keep checking the entire contents
+               before quitting on a block verification failure. If this
+               option is set, fio will exit the job on the first observed
+               failure.

                
 stonewall      Wait for preceeding jobs in the job file to exit, before
                starting this one. Can be used to insert serialization
                
 stonewall      Wait for preceeding jobs in the job file to exit, before
                starting this one. Can be used to insert serialization


@@ -750,7 +791,7 @@ Client1 (g=0): err= 0:
     slat (msec): min=    0, max=  136, avg= 0.03, stdev= 1.92
     clat (msec): min=    0, max=  631, avg=48.50, stdev=86.82
     bw (KiB/s) : min=    0, max= 1196, per=51.00%, avg=664.02, stdev=681.68
     slat (msec): min=    0, max=  136, avg= 0.03, stdev= 1.92
     clat (msec): min=    0, max=  631, avg=48.50, stdev=86.82
     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
+  cpu        : usr=1.49%, sys=0.25%, ctx=7969, majf=0, minf=17

   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%,
   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%,


@@ -781,7 +822,9 @@ runt=               The runtime of that thread
                only really useful if the threads in this group are on the
                same disk, since they are then competing for disk access.
 cpu=           CPU usage. User and system time, along with the number
                only really useful if the threads in this group are on the
                same disk, since they are then competing for disk access.
 cpu=           CPU usage. User and system time, along with the number

-               of context switches this thread went through.
+               of context switches this thread went through, usage of
+               system and user time, and finally the number of major
+               and minor page faults.

 IO depths=     The distribution of io depths over the job life time. The
                numbers are divided into powers of 2, so for example the
                16= entries includes depths up to that value but higher
 IO depths=     The distribution of io depths over the job life time. The
                numbers are divided into powers of 2, so for example the
                16= entries includes depths up to that value but higher


@@ -851,7 +894,7 @@ Split up, the format is as follows:
                Submission latency: min, max, mean, deviation
                Completion latency: min, max, mean, deviation
                Bw: min, max, aggregate percentage of total, mean, deviation
                Submission latency: min, max, mean, deviation
                Completion latency: min, max, mean, deviation
                Bw: min, max, aggregate percentage of total, mean, deviation

-       CPU usage: user, system, context switches
+       CPU usage: user, system, context switches, major faults, minor faults

        IO depths: <=1, 2, 4, 8, 16, 32, >=64
        IO latencies: <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000, >=2000
        Text description
        IO depths: <=1, 2, 4, 8, 16, 32, >=64
        IO latencies: <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000, >=2000
        Text description