.TP
.BI \-\-debug \fR=\fPtype
Enable verbose tracing of various fio actions. May be `all' for all types
-or individual types seperated by a comma (eg --debug=io,file). `help' will
+or individual types separated by a comma (eg \-\-debug=io,file). `help' will
list all available tracing options.
.TP
.B \-\-help
.TP
.I int
SI integer: a whole number, possibly containing a suffix denoting the base unit
-of the value. Accepted suffixes are `k', 'M' and 'G', denoting kilo (1024),
-mega (1024*1024) and giga (1024*1024*1024) respectively. If prefixed with '0x',
-the value is assumed to be base 16 (hexadecimal).
+of the value. Accepted suffixes are `k', 'M', 'G', 'T', and 'P', denoting
+kilo (1024), mega (1024^2), giga (1024^3), tera (1024^4), and peta (1024^5)
+respectively. The suffix is not case sensitive. If prefixed with '0x', the
+value is assumed to be base 16 (hexadecimal). A suffix may include a trailing 'b',
+for instance 'kb' is identical to 'k'. You can specify a base 10 value
+by using 'KiB', 'MiB', 'GiB', etc. This is useful for disk drives where
+values are often given in base 10 values. Specifying '30GiB' will get you
+30*1000^3 bytes.
.TP
.I bool
Boolean: a true or false value. `0' denotes false, `1' denotes true.
Mixed random reads and writes.
.RE
.P
-For mixed I/O, the default split is 50/50. For random I/O, the number of I/Os
-to perform before getting a new offset can be specified by appending
-`:\fIint\fR' to the pattern type. The default is 1.
+For mixed I/O, the default split is 50/50. For certain types of io the result
+may still be skewed a bit, since the speed may be different. It is possible to
+specify a number of IO's to do before getting a new offset, this is one by
+appending a `:\fI<nr>\fR to the end of the string given. For a random read, it
+would look like \fBrw=randread:8\fR for passing in an offset modifier with a
+value of 8. See the \fBrw_sequencer\fR option.
.RE
.TP
+.BI rw_sequencer \fR=\fPstr
+If an offset modifier is given by appending a number to the \fBrw=<str>\fR line,
+then this option controls how that number modifies the IO offset being
+generated. Accepted values are:
+.RS
+.RS
+.TP
+.B sequential
+Generate sequential offset
+.TP
+.B identical
+Generate the same offset
+.RE
+.P
+\fBsequential\fR is only useful for random IO, where fio would normally
+generate a new random offset for every IO. If you append eg 8 to randread, you
+would get a new random offset for every 8 IO's. The result would be a seek for
+only every 8 IO's, instead of for every IO. Use \fBrw=randread:8\fR to specify
+that. As sequential IO is already sequential, setting \fBsequential\fR for that
+would not result in any differences. \fBidentical\fR behaves in a similar
+fashion, except it sends the same offset 8 number of times before generating a
+new offset.
+.RE
+.P
+.TP
+.BI kb_base \fR=\fPint
+The base unit for a kilobyte. The defacto base is 2^10, 1024. Storage
+manufacturers like to use 10^3 or 1000 as a base ten unit instead, for obvious
+reasons. Allow values are 1024 or 1000, with 1024 being the default.
+.TP
.BI randrepeat \fR=\fPbool
Seed the random number generator in a predictable way so results are repeatable
across runs. Default: true.
.TP
+.BI use_os_rand \fR=\fPbool
+Fio can either use the random generator supplied by the OS to generator random
+offsets, or it can use it's own internal generator (based on Tausworthe).
+Default is to use the internal generator, which is often of better quality and
+faster. Default: false.
+.TP
+.BI fallocate \fR=\fPstr
+Whether pre-allocation is performed when laying down files. Accepted values
+are:
+.RS
+.RS
+.TP
+.B none
+Do not pre-allocate space.
+.TP
+.B posix
+Pre-allocate via posix_fallocate().
+.TP
+.B keep
+Pre-allocate via fallocate() with FALLOC_FL_KEEP_SIZE set.
+.TP
+.B 0
+Backward-compatible alias for 'none'.
+.TP
+.B 1
+Backward-compatible alias for 'posix'.
+.RE
+.P
+May not be available on all supported platforms. 'keep' is only
+available on Linux. If using ZFS on Solaris this must be set to 'none'
+because ZFS doesn't support it. Default: 'posix'.
+.RE
+.TP
.BI fadvise_hint \fR=\fPbool
Disable use of \fIposix_fadvise\fR\|(2) to advise the kernel what I/O patterns
are likely to be issued. Default: true.
.BI size \fR=\fPint
Total size of I/O for this job. \fBfio\fR will run until this many bytes have
been transfered, unless limited by other options (\fBruntime\fR, for instance).
-Unless \fBnr_files\fR and \fBfilesize\fR options are given, this amount will be
-divided between the available files for the job.
-.TP
-.BI fill_device \fR=\fPbool
+Unless \fBnrfiles\fR and \fBfilesize\fR options are given, this amount will be
+divided between the available files for the job. If not set, fio will use the
+full size of the given files or devices. If the the files do not exist, size
+must be given. It is also possible to give size as a percentage between 1 and
+100. If size=20% is given, fio will use 20% of the full size of the given files
+or devices.
+.TP
+.BI fill_device \fR=\fPbool "\fR,\fB fill_fs" \fR=\fPbool
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.
For a read workload, the mount point will be filled first then IO started on
-the result.
+the result. This option doesn't make sense if operating on a raw device node,
+since the size of that is already known by the file system. Additionally,
+writing beyond end-of-device will not return ENOSPC there.
.TP
.BI filesize \fR=\fPirange
Individual file sizes. May be a range, in which case \fBfio\fR will select sizes
.TP
.BI blocksize \fR=\fPint[,int] "\fR,\fB bs" \fR=\fPint[,int]
Block size for I/O units. Default: 4k. Values for reads and writes can be
-specified seperately in the format \fIread\fR,\fIwrite\fR, either of
+specified separately in the format \fIread\fR,\fIwrite\fR, either of
which may be empty to leave that value at its default.
.TP
.BI blocksize_range \fR=\fPirange[,irange] "\fR,\fB bsrange" \fR=\fPirange[,irange]
Specify a range of I/O block sizes. The issued I/O unit will always be a
multiple of the minimum size, unless \fBblocksize_unaligned\fR is set. Applies
to both reads and writes if only one range is given, but can be specified
-seperately with a comma seperating the values. Example: bsrange=1k-4k,2k-8k.
+separately with a comma seperating the values. Example: bsrange=1k-4k,2k-8k.
Also (see \fBblocksize\fR).
.TP
.BI bssplit \fR=\fPstr
not just even splits between them. With this option, you can weight various
block sizes for exact control of the issued IO for a job that has mixed
block sizes. The format of the option is bssplit=blocksize/percentage,
-optionally adding as many definitions as needed seperated by a colon.
+optionally adding as many definitions as needed separated by a colon.
Example: bssplit=4k/10:64k/50:32k/40 would issue 50% 64k blocks, 10% 4k
blocks and 40% 32k blocks. \fBbssplit\fR also supports giving separate
splits to reads and writes. The format is identical to what the
Linux native asynchronous I/O.
.TP
.B posixaio
-glibc POSIX asynchronous I/O using \fIaio_read\fR\|(3) and \fIaio_write\fR\|(3).
+POSIX asynchronous I/O using \fIaio_read\fR\|(3) and \fIaio_write\fR\|(3).
+.TP
+.B solarisaio
+Solaris native asynchronous I/O.
+.TP
+.B windowsaio
+Windows native asynchronous I/O.
.TP
.B mmap
File is memory mapped with \fImmap\fR\|(2) and data copied using
.br
See <http://www.xmailserver.org/guasi\-lib.html>.
.TP
+.B rdma
+The RDMA I/O engine supports both RDMA memory semantic(RDMA_WRITE/RDMA_READ)
+and channel semantic(Send/Recv) in InfiniBand, RoCE and iWarp environment.
+.TP
.B external
Loads an external I/O engine object file. Append the engine filename as
`:\fIenginepath\fR'.
.RE
.TP
.BI iodepth \fR=\fPint
-Number of I/O units to keep in flight against the file. Default: 1.
+Number of I/O units to keep in flight against the file. Note that increasing
+iodepth beyond 1 will not affect synchronous ioengines (except for small
+degress when verify_async is in use). Even async engines my impose OS
+restrictions causing the desired depth not to be achieved. This may happen on
+Linux when using libaio and not setting \fBdirect\fR=1, since buffered IO is
+not async on that OS. Keep an eye on the IO depth distribution in the
+fio output to verify that the achieved depth is as expected. Default: 1.
.TP
.BI iodepth_batch \fR=\fPint
Number of I/Os to submit at once. Default: \fBiodepth\fR.
Like \fBfsync\fR, but uses \fBfdatasync\fR\|(2) instead to only sync the
data parts of the file. Default: 0.
.TP
+.BI sync_file_range \fR=\fPstr:int
+Use sync_file_range() for every \fRval\fP number of write operations. Fio will
+track range of writes that have happened since the last sync_file_range() call.
+\fRstr\fP can currently be one or more of:
+.RS
+.TP
+.B wait_before
+SYNC_FILE_RANGE_WAIT_BEFORE
+.TP
+.B write
+SYNC_FILE_RANGE_WRITE
+.TP
+.B wait_after
+SYNC_FILE_RANGE_WRITE
+.TP
+.RE
+.P
+So if you do sync_file_range=wait_before,write:8, fio would use
+\fBSYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE\fP for every 8 writes.
+Also see the sync_file_range(2) man page. This option is Linux specific.
+.TP
.BI overwrite \fR=\fPbool
If writing, setup the file first and do overwrites. Default: false.
.TP
The amount of memory allocated is the maximum allowed \fBblocksize\fR for the
job multiplied by \fBiodepth\fR. For \fBshmhuge\fR or \fBmmaphuge\fR to work,
the system must have free huge pages allocated. \fBmmaphuge\fR also needs to
-have hugetlbfs mounted, and \fIfile\fR must point there.
+have hugetlbfs mounted, and \fIfile\fR must point there. At least on Linux,
+huge pages must be manually allocated. See \fB/proc/sys/vm/nr_hugehages\fR
+and the documentation for that. Normally you just need to echo an appropriate
+number, eg echoing 8 will ensure that the OS has 8 huge pages ready for
+use.
.RE
.TP
-.BI iomem_align \fR=\fPint
+.BI iomem_align \fR=\fPint "\fR,\fP mem_align" \fR=\fPint
This indiciates the memory alignment of the IO memory buffers. Note that the
given alignment is applied to the first IO unit buffer, if using \fBiodepth\fR
the alignment of the following buffers are given by the \fBbs\fR used. In
.TP
.BI hugepage\-size \fR=\fPint
Defines the size of a huge page. Must be at least equal to the system setting.
-Should be a multiple of 1MiB. Default: 4MiB.
+Should be a multiple of 1MB. Default: 4MB.
.TP
.B exitall
Terminate all jobs when one finishes. Default: wait for each job to finish.
.RS
.RS
.TP
-.B md5 crc16 crc32 crc64 crc7 sha256 sha512
-Store appropriate checksum in the header of each block.
+.B md5 crc16 crc32 crc32c crc32c-intel crc64 crc7 sha256 sha512 sha1
+Store appropriate checksum in the header of each block. crc32c-intel is
+hardware accelerated SSE4.2 driven, falls back to regular crc32c if
+not supported by the system.
.TP
.B meta
Write extra information about each I/O (timestamp, block number, etc.). The
-block number is verified.
-.TP
-.B pattern
-Fill I/O buffers with a specific pattern that is used to verify. The pattern is
-specified by appending `:\fIint\fR' to the parameter. \fIint\fR cannot be larger
-than 32-bits.
+block number is verified. See \fBverify_pattern\fR as well.
.TP
.B null
Pretend to verify. Used for testing internals.
.RE
+
+This option can be used for repeated burn-in tests of a system to make sure
+that the written data is also correctly read back. If the data direction given
+is a read or random read, fio will assume that it should verify a previously
+written file. If the data direction includes any form of write, the verify will
+be of the newly written data.
.RE
.TP
.BI verify_sort \fR=\fPbool
Write the verification header for this number of bytes, which should divide
\fBblocksize\fR. Default: \fBblocksize\fR.
.TP
+.BI verify_pattern \fR=\fPstr
+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(it can be either a
+decimal or a hex number). The verify_pattern if larger than a 32-bit quantity
+has to be a hex number that starts with either "0x" or "0X". Use with
+\fBverify\fP=meta.
+.TP
.BI verify_fatal \fR=\fPbool
If true, exit the job on the first observed verification failure. Default:
false.
.TP
+.BI verify_dump \fR=\fPbool
+If set, dump the contents of both the original data block and the data block we
+read off disk to files. This allows later analysis to inspect just what kind of
+data corruption occurred. On by default.
+.TP
.BI verify_async \fR=\fPint
Fio will normally verify IO inline from the submitting thread. This option
takes an integer describing how many async offload threads to create for IO
Tell fio to set the given CPU affinity on the async IO verification threads.
See \fBcpus_allowed\fP for the format used.
.TP
-.B stonewall
-Wait for preceeding jobs in the job file to exit before starting this one.
+.BI verify_backlog \fR=\fPint
+Fio will normally verify the written contents of a job that utilizes verify
+once that job has completed. In other words, everything is written then
+everything is read back and verified. You may want to verify continually
+instead for a variety of reasons. Fio stores the meta data associated with an
+IO block in memory, so for large verify workloads, quite a bit of memory would
+be used up holding this meta data. If this option is enabled, fio will write
+only N blocks before verifying these blocks.
+.TP
+.BI verify_backlog_batch \fR=\fPint
+Control how many blocks fio will verify if verify_backlog is set. If not set,
+will default to the value of \fBverify_backlog\fR (meaning the entire queue is
+read back and verified). If \fBverify_backlog_batch\fR is less than
+\fBverify_backlog\fR then not all blocks will be verified, if
+\fBverify_backlog_batch\fR is larger than \fBverify_backlog\fR, some blocks
+will be verified more than once.
+.TP
+.B stonewall "\fR,\fP wait_for_previous"
+Wait for preceding jobs in the job file to exit before starting this one.
\fBstonewall\fR implies \fBnew_group\fR.
.TP
.B new_group
read.
.TP
.BI write_iolog \fR=\fPstr
-Write the issued I/O patterns to the specified file.
+Write the issued I/O patterns to the specified file. Specify a separate file
+for each job, otherwise the iologs will be interspersed and the file may be
+corrupt.
.TP
.BI read_iolog \fR=\fPstr
Replay the I/O patterns contained in the specified file generated by
\fBwrite_iolog\fR, or may be a \fBblktrace\fR binary file.
.TP
+.BI replay_no_stall \fR=\fPint
+While replaying I/O patterns using \fBread_iolog\fR the default behavior
+attempts to respect timing information between I/Os. Enabling
+\fBreplay_no_stall\fR causes I/Os to be replayed as fast as possible while
+still respecting ordering.
+.TP
+.BI replay_redirect \fR=\fPstr
+While replaying I/O patterns using \fBread_iolog\fR the default behavior
+is to replay the IOPS onto the major/minor device that each IOP was recorded
+from. Setting \fBreplay_redirect\fR causes all IOPS to be replayed onto the
+single specified device regardless of the device it was recorded from.
+.TP
.B write_bw_log \fR=\fPstr
If given, write a bandwidth log of the jobs in this job file. Can be used to
store data of the bandwidth of the jobs in their lifetime. The included
graphs. See \fBwrite_log_log\fR for behaviour of given filename. For this
option, the postfix is _bw.log.
.TP
-.B write_lat_log
+.B write_lat_log \fR=\fPstr
Same as \fBwrite_bw_log\fR, but writes I/O completion latencies. If no
filename is given with this option, the default filename of "jobname_type.log"
is used. Even if the filename is given, fio will still append the type of log.
.TP
-.B disable_clat \fR=\fPbool
-Disable measurements of completion latency numbers. Useful only for cutting
+.B disable_lat \fR=\fPbool
+Disable measurements of total latency numbers. Useful only for cutting
back the number of calls to gettimeofday, as that does impact performance at
really high IOPS rates. Note that to really get rid of a large amount of these
calls, this option must be used with disable_slat and disable_bw as well.
.TP
+.B disable_clat \fR=\fPbool
+Disable measurements of completion latency numbers. See \fBdisable_lat\fR.
+.TP
.B disable_slat \fR=\fPbool
-Disable measurements of submission latency numbers. See \fBdisable_clat\fR.
+Disable measurements of submission latency numbers. See \fBdisable_lat\fR.
.TP
.B disable_bw_measurement \fR=\fPbool
-Disable measurements of throughput/bandwidth numbers. See \fBdisable_clat\fR.
+Disable measurements of throughput/bandwidth numbers. See \fBdisable_lat\fR.
.TP
.BI lockmem \fR=\fPint
Pin the specified amount of memory with \fBmlock\fR\|(2). Can be used to
these time calls will be excluded from other uses. Fio will manually clear it
from the CPU mask of other jobs.
.TP
-.BI continue_on_error \fR=\fPbool
-Normally fio will exit the job on the first observed failure. If this option is
-set, fio will continue the job when there is a 'non-fatal error'
-(\fBEIO\fR or \fBEILSEQ\fR) until the runtime is exceeded or the I/O size
-specified is completed. If this option is used, there are two more stats that
-are appended, the total error count and the first error. The error field given
-in the stats is the first error that was hit during the run.
+.BI cgroup \fR=\fPstr
+Add job to this control group. If it doesn't exist, it will be created.
+The system must have a mounted cgroup blkio mount point for this to work. If
+your system doesn't have it mounted, you can do so with:
+
+# mount \-t cgroup \-o blkio none /cgroup
+.TP
+.BI cgroup_weight \fR=\fPint
+Set the weight of the cgroup to this value. See the documentation that comes
+with the kernel, allowed values are in the range of 100..1000.
+.TP
+.BI cgroup_nodelete \fR=\fPbool
+Normally fio will delete the cgroups it has created after the job completion.
+To override this behavior and to leave cgroups around after the job completion,
+set cgroup_nodelete=1. This can be useful if one wants to inspect various
+cgroup files after job completion. Default: false
+.TP
+.BI uid \fR=\fPint
+Instead of running as the invoking user, set the user ID to this value before
+the thread/process does any work.
+.TP
+.BI gid \fR=\fPint
+Set group ID, see \fBuid\fR.
.SH OUTPUT
While running, \fBfio\fR will display the status of the created jobs. For
example:
.PD
.SH TERSE OUTPUT
If the \fB\-\-minimal\fR option is given, the results will be printed in a
-semicolon-delimited format suitable for scripted use. The fields are:
+semicolon-delimited format suitable for scripted use - a job description
+(if provided) follows on a new line. Note that the first
+number in the line is the version number. If the output has to be changed
+for some reason, this number will be incremented by 1 to signify that
+change. The fields are:
.P
.RS
-.B jobname, groupid, error
+.B version, jobname, groupid, error
.P
Read status:
.RS
-.B KiB I/O, bandwidth \fR(KiB/s)\fP, runtime \fR(ms)\fP
+.B KB I/O, bandwidth \fR(KB/s)\fP, runtime \fR(ms)\fP
.P
Submission latency:
.RS
.RS
.B min, max, mean, standard deviation
.RE
+Total latency:
+.RS
+.B min, max, mean, standard deviation
+.RE
Bandwidth:
.RS
.B min, max, aggregate percentage of total, mean, standard deviation
.P
Write status:
.RS
-.B KiB I/O, bandwidth \fR(KiB/s)\fP, runtime \fR(ms)\fP
+.B KB I/O, bandwidth \fR(KB/s)\fP, runtime \fR(ms)\fP
.P
Submission latency:
.RS
.RS
.B min, max, mean, standard deviation
.RE
+Total latency:
+.RS
+.B min, max, mean, standard deviation
+.RE
Bandwidth:
.RS
.B min, max, aggregate percentage of total, mean, standard deviation
.B <=1, 2, 4, 8, 16, 32, >=64
.RE
.P
-IO latency distribution (ms):
+IO latency distribution:
+.RS
+Microseconds:
+.RS
+.B <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000
+.RE
+Milliseconds:
+.RS
+.B <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000, 2000, >=2000
+.RE
+.RE
+.P
+Error Info (dependent on continue_on_error, default off):
.RS
-.B <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000, >=2000
+.B total # errors, first error code
.RE
.P
-.B text description
+.B text description (if provided in config - appears on newline)
.RE
.SH AUTHORS
.B fio
-was written by Jens Axboe <jens.axboe@oracle.com>.
+was written by Jens Axboe <jens.axboe@oracle.com>,
+now Jens Axboe <jaxboe@fusionio.com>.
.br
This man page was written by Aaron Carroll <aaronc@cse.unsw.edu.au> based
on documentation by Jens Axboe.
projects / fio.git / blobdiff