Add support for 'bssplit' option, fine grained block size contrl
[fio.git] / HOWTO
diff --git a/HOWTO b/HOWTO
index 3bee1a2d70a42622f70f7a00c422246e4eaa2d6c..569b998f215b78d41a36ac71d78f1506a013af4e 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -281,6 +281,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=.
 
+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
@@ -314,6 +338,8 @@ 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.
 
+                       psync   Basic pread(2) or pwrite(2) io.
+
                        libaio  Linux native asynchronous io.
 
                        posixaio glibc posix asynchronous io.
@@ -347,7 +373,7 @@ 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.
 
-                       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
@@ -599,6 +625,15 @@ verify=str If writing to a file, fio can verify the file contents
                                (timestamp, block number etc.). The block
                                number is verified.
 
+                       pattern Fill the IO buffers with a specific pattern,
+                               that we can use to verify. Depending on the
+                               width of the pattern, fio will fill 1/2/3/4
+                               bytes of the buffer at the time. The pattern
+                               cannot be larger than a 32-bit quantity. The
+                               given pattern is given as a postfix to this
+                               option, ala: verify=pattern:0x5a. It accepts
+                               both hex and dec values.
+
                        null    Only pretend to verify. Useful for testing
                                internals with ioengine=null, not for much
                                else.
@@ -624,14 +659,6 @@ verify_interval=siint      Write the verification header at a finer granularity
                        size of header_interval. blocksize should divide this
                        evenly.
 
-verify_pattern=int     If set, fio will fill the io buffers with this
-               pattern. Fio defaults to filling with totally random
-               bytes, but sometimes it's interesting to fill with a known
-               pattern for io verification purposes. Depending on the
-               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
@@ -755,7 +782,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
-  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%,
@@ -786,7 +813,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
-               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
@@ -856,7 +885,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
-       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