Add write barriers
[fio.git] / HOWTO
diff --git a/HOWTO b/HOWTO
index 4d103c8..12974f3 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -170,7 +170,8 @@ Some parameters take an option of a given type, such as an integer or
 a string. The following types are used:
 
 str    String. This is a sequence of alpha characters.
-int    Integer. A whole number value, can be negative.
+int    Integer. A whole number value, can be negative. If prefixed with
+       0x, the integer is assumed to be of base 16 (hexidecimal).
 siint  SI integer. A whole number value, which may contain a postfix
        describing the base of the number. Accepted postfixes are k/m/g,
        meaning kilo, mega, and giga. So if you want to specify 4096,
@@ -218,6 +219,25 @@ filename=str       Fio normally makes up a filename based on the job name,
 opendir=str    Tell fio to recursively add any file it can find in this
                directory and down the file system tree.
 
+lockfile=str   Fio defaults to not doing any locking files before it does
+               IO to them. If a file or file descriptor is shared, fio
+               can serialize IO to that file to make the end result
+               consistent. This is usual for emulating real workloads that
+               share files. The lock modes are:
+
+                       none            No locking. The default.
+                       exclusive       Only one thread/process may do IO,
+                                       excluding all others.
+                       readwrite       Read-write locking on the file. Many
+                                       readers may access the file at the
+                                       same time, but writes get exclusive
+                                       access.
+
+               The option may be post-fixed with a lock batch number. If
+               set, then each thread/process may do that amount of IOs to
+               the file before giving up the lock. Since lock acqusition is
+               expensive, batching the lock/unlocks will speed up IO.
+
 readwrite=str
 rw=str         Type of io pattern. Accepted values are:
 
@@ -261,6 +281,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.
 
+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
@@ -280,6 +304,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
@@ -288,6 +336,12 @@ bs_unaligned       If this option is given, any byte size value within bsrange
 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.
 
+refill_buffers If this option is given, fio will refill the IO buffers
+               on every submit. The default is to only fill it at init
+               time and reuse that data. Only makes sense if zero_buffers
+               isn't specified, naturally. If data verification is enabled,
+               refill_buffers is also automatically enabled.
+
 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
@@ -313,10 +367,16 @@ 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.
+
+                       vsync   Basic readv(2) or writev(2) IO.
+
                        libaio  Linux native asynchronous io.
 
                        posixaio glibc posix asynchronous io.
 
+                       solarisaio Solaris native asynchronous io.
+
                        mmap    File is memory mapped and data copied
                                to/from using memcpy(3).
 
@@ -343,11 +403,17 @@ ioengine=str      Defines how the job issues io to the file. The following
                                or receive, if the latter only the port
                                argument is used.
 
-                       cpu     Doesn't transfer any data, but burns CPU
+                       netsplice Like net, but uses splice/vmsplice to
+                               map data and send/receive.
+
+                       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
-                               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
@@ -368,8 +434,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.
-               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
@@ -395,7 +462,11 @@ fsync=int  If writing to a file, issue a sync of the dirty data
                not sync the file. The exception is the sg io engine, which
                synchronizes the disk cache anyway.
 
-overwrite=bool If writing to a file, setup the file first and do overwrites.
+overwrite=bool If true, writes to a file will always overwrite existing
+               data. If the file doesn't already exist, it will be
+               created before the write phase begins. If the file exists
+               and is large enough for the specified write phase, nothing
+               will be done.
 
 end_fsync=bool If true, fsync file contents when the job exits.
 
@@ -403,10 +474,6 @@ fsync_on_close=bool        If true, fio will fsync() a dirty file on close.
                This differs from end_fsync in that it will happen on every
                file close, not just at the end of the job.
 
-rwmixcycle=int Value in milliseconds describing how often to switch between
-               reads and writes for a mixed workload. The default is
-               500 msecs.
-
 rwmixread=int  How large a percentage of the mix should be reads.
 
 rwmixwrite=int How large a percentage of the mix should be writes. If both
@@ -423,6 +490,12 @@ norandommap        Normally fio will cover every block of the file when doing
                fio doesn't track potential block rewrites which may alter
                the calculated checksum for that block.
 
+softrandommap  See norandommap. If fio runs with the random block map enabled
+               and it fails to allocate the map, if this option is set it
+               will continue without a random block map. As coverage will
+               not be as complete as with random maps, this option is
+               disabled by default.
+
 nice=int       Run the job with the given nice value. See man nice(2).
 
 prio=int       Set the io priority value of this job. Linux limits us to
@@ -565,15 +638,36 @@ 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.
 
+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
                after each iteration of the job. The allowed values are:
 
                        md5     Use an md5 sum of the data area and store
                                it in the header of each block.
 
+                       crc64   Use an experimental crc64 sum of the data
+                               area and store it in the header of each
+                               block.
+
                        crc32   Use a crc32 sum of the data area and store
                                it in the header of each block.
 
+                       crc16   Use a crc16 sum of the data area and store
+                               it in the header of each block.
+
+                       crc7    Use a crc7 sum of the data area and store
+                               it in the header of each block.
+
+                       sha512  Use sha512 as the checksum function.
+
+                       sha256  Use sha256 as the checksum function.
+
+                       meta    Write extra information about each io
+                               (timestamp, block number etc.). The block
+                               number is verified.
+
                        null    Only pretend to verify. Useful for testing
                                internals with ioengine=null, not for much
                                else.
@@ -589,6 +683,28 @@ verifysort=bool    If set, fio will sort written verify blocks when it deems
                can ignore this option unless doing huge amounts of really
                fast IO where the red-black tree sorting CPU time becomes
                significant.
+
+verify_offset=siint    Swap the verification header with data somewhere else
+                       in the block before writing. Its swapped back before
+                       verifying.
+
+verify_interval=siint  Write the verification header at a finer granularity
+                       than the blocksize. It will be written for chunks the
+                       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
+               failure.
                
 stonewall      Wait for preceeding jobs in the job file to exit, before
                starting this one. Can be used to insert serialization
@@ -694,9 +810,10 @@ E          Thread exited, not reaped by main thread yet.
 _              Thread reaped.
 
 The other values are fairly self explanatory - number of threads
-currently running and doing io, rate of io since last check, and the estimated
-completion percentage and time for the running group. It's impossible to
-estimate runtime of the following groups (if any).
+currently running and doing io, rate of io since last check (read speed
+listed first, then write speed), and the estimated completion percentage
+and time for the running group. It's impossible to estimate runtime of
+the following groups (if any).
 
 When fio is done (or interrupted by ctrl-c), it will show the data for
 each thread, group of threads, and disks in that order. For each data
@@ -707,8 +824,10 @@ 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%
+     submit    : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0%
+     complete  : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=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%
@@ -738,12 +857,19 @@ 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
                than the previous entry. In other words, it covers the
                range from 16 to 31.
+IO submit=     How many pieces of IO were submitting in a single submit
+               call. Each entry denotes that amount and below, until
+               the previous entry - eg, 8=100% mean that we submitted
+               anywhere in between 5-8 ios per submit call.
+IO complete=   Like the above submit number, but for completions instead.
 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
@@ -808,7 +934,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