Documentation update

[fio.git] / fio.1

diff --git a/fio.1 b/fio.1
index 2eb445578122bb993a5be6569a214e37e7c95743..2bf2c2f77a8fd9e2b7cdd4230776aebd947b1b62 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -187,15 +187,31 @@ 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.
 Example: bssplit=4k/10:64k/50:32k/40 would issue 50% 64k blocks, 10% 4k
 block sizes. The format of the option is bssplit=blocksize/percentage,
 optionally adding as many definitions as needed seperated by a colon.
 Example: bssplit=4k/10:64k/50:32k/40 would issue 50% 64k blocks, 10% 4k

-blocks and 40% 32k blocks.
+blocks and 40% 32k blocks. \fBbssplit\fR also supports giving separate
+splits to reads and writes. The format is identical to what the
+\fBbs\fR option accepts, the read and write parts are separated with a
+comma.

 .TP
 .B blocksize_unaligned\fR,\fP bs_unaligned
 If set, any size in \fBblocksize_range\fR may be used.  This typically won't
 work with direct I/O, as that normally requires sector alignment.
 .TP
 .TP
 .B blocksize_unaligned\fR,\fP bs_unaligned
 If set, any size in \fBblocksize_range\fR may be used.  This typically won't
 work with direct I/O, as that normally requires sector alignment.
 .TP

+.BI blockalign \fR=\fPint[,int] "\fR,\fB ba" \fR=\fPint[,int]
+At what boundary to align random IO offsets. Defaults to the same as 'blocksize'
+the minimum blocksize given.  Minimum alignment is typically 512b
+for using direct IO, though it usually depends on the hardware block size.
+This option is mutually exclusive with using a random map for files, so it
+will turn off that option.
+.TP

 .B zero_buffers
 Initialise buffers with all zeros. Default: fill buffers with random data.
 .TP
 .B zero_buffers
 Initialise buffers with all zeros. Default: fill buffers with random data.
 .TP

+.B 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.
+.TP

 .BI nrfiles \fR=\fPint
 Number of files to use for this job.  Default: 1.
 .TP
 .BI nrfiles \fR=\fPint
 Number of files to use for this job.  Default: 1.
 .TP


@@ -330,8 +346,10 @@ Percentage of a mixed workload that should be reads. Default: 50.
 .TP
 .BI rwmixwrite \fR=\fPint
 Percentage of a mixed workload that should be writes.  If \fBrwmixread\fR and
 .TP
 .BI rwmixwrite \fR=\fPint
 Percentage of a mixed workload that should be writes.  If \fBrwmixread\fR and

-\fBwrmixwrite\fR are given and do not sum to 100%, the latter of the two
-overrides the first.  Default: 50.
+\fBrwmixwrite\fR are given and do not sum to 100%, the latter of the two
+overrides the first. This may interfere with a given rate setting, if fio is
+asked to limit reads or writes to a certain rate. If that is the case, then
+the distribution may be skewed. Default: 50.

 .TP
 .B norandommap
 Normally \fBfio\fR will cover every block of the file when doing random I/O. If
 .TP
 .B norandommap
 Normally \fBfio\fR will cover every block of the file when doing random I/O. If


@@ -360,18 +378,27 @@ Number of blocks to issue before waiting \fBthinktime\fR microseconds.
 Default: 1.
 .TP
 .BI rate \fR=\fPint
 Default: 1.
 .TP
 .BI rate \fR=\fPint

-Cap bandwidth used by this job to this number of KiB/s.
+Cap bandwidth used by this job. The number is in bytes/sec, the normal postfix
+rules apply. You can use \fBrate\fR=500k to limit reads and writes to 500k each,
+or you can specify read and writes separately. Using \fBrate\fR=1m,500k would
+limit reads to 1MB/sec and writes to 500KB/sec. Capping only reads or writes
+can be done with \fBrate\fR=,500k or \fBrate\fR=500k,. The former will only
+limit writes (to 500KB/sec), the latter will only limit reads.

 .TP
 .BI ratemin \fR=\fPint
 Tell \fBfio\fR to do whatever it can to maintain at least the given bandwidth.
 .TP
 .BI ratemin \fR=\fPint
 Tell \fBfio\fR to do whatever it can to maintain at least the given bandwidth.

-Failing to meet this requirement will cause the job to exit.
+Failing to meet this requirement will cause the job to exit. The same format
+as \fBrate\fR is used for read vs write separation.

 .TP
 .BI rate_iops \fR=\fPint
 .TP
 .BI rate_iops \fR=\fPint

-Cap the bandwidth to this number of IOPS.  If \fBblocksize\fR is a range, the
-smallest block size is used as the metric.
+Cap the bandwidth to this number of IOPS. Basically the same as rate, just
+specified independently of bandwidth. The same format as \fBrate\fR is used for
+read vs write seperation. If \fBblocksize\fR is a range, the smallest block
+size is used as the metric.

 .TP
 .BI rate_iops_min \fR=\fPint
 .TP
 .BI rate_iops_min \fR=\fPint

-If this rate of I/O is not met, the job will exit.
+If this rate of I/O is not met, the job will exit. The same format as \fBrate\fR
+is used for read vs write seperation.

 .TP
 .BI ratecycle \fR=\fPint
 Average bandwidth for \fBrate\fR and \fBratemin\fR over this number of
 .TP
 .BI ratecycle \fR=\fPint
 Average bandwidth for \fBrate\fR and \fBratemin\fR over this number of


@@ -395,6 +422,13 @@ If given, run for the specified \fBruntime\fR duration even if the files are
 completely read or written. The same workload will be repeated as many times
 as \fBruntime\fR allows.
 .TP
 completely read or written. The same workload will be repeated as many times
 as \fBruntime\fR allows.
 .TP

+.BI ramp_time \fR=\fPint
+If set, fio will run the specified workload for this amount of time before
+logging any performance numbers. Useful for letting performance settle before
+logging results, thus minimizing the runtime required for stable results. Note
+that the \fBramp_time\fR is considered lead in time for a job, thus it will
+increase the total runtime if a special timeout or runtime is specified.
+.TP

 .BI invalidate \fR=\fPbool
 Invalidate buffer-cache for the file prior to starting I/O.  Default: true.
 .TP
 .BI invalidate \fR=\fPbool
 Invalidate buffer-cache for the file prior to starting I/O.  Default: true.
 .TP


@@ -450,6 +484,11 @@ If true, serialize file creation for the jobs.  Default: true.
 .BI create_on_open \fR=\fPbool
 If true, the files are not created until they are opened for IO by the job.
 .TP
 .BI create_on_open \fR=\fPbool
 If true, the files are not created until they are opened for IO by the job.
 .TP

+.BI pre_read \fR=\fPbool
+If this is given, files will be pre-read into memory before starting the given
+IO operation. This will also clear the \fR \fBinvalidate\fR flag, since it is
+pointless to pre-read and then drop the cache.
+.TP

 .BI unlink \fR=\fPbool
 Unlink job files when done.  Default: false.
 .TP
 .BI unlink \fR=\fPbool
 Unlink job files when done.  Default: false.
 .TP


@@ -534,11 +573,29 @@ Write the issued I/O patterns to the specified file.
 Replay the I/O patterns contained in the specified file generated by
 \fBwrite_iolog\fR, or may be a \fBblktrace\fR binary file.
 .TP
 Replay the I/O patterns contained in the specified file generated by
 \fBwrite_iolog\fR, or may be a \fBblktrace\fR binary file.
 .TP

-.B write_bw_log
-If given, write bandwidth logs of the jobs in this file.
+.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
+fio_generate_plots script uses gnuplot to turn these text files into nice
+graphs. See \fBwrite_log_log\fR for behaviour of given filename. For this
+option, the postfix is _bw.log.

 .TP
 .B write_lat_log
 .TP
 .B write_lat_log

-Same as \fBwrite_bw_log\fR, but writes I/O completion latencies.
+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
+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_slat \fR=\fPbool
+Disable measurements of submission latency numbers. See \fBdisable_clat\fR.
+.TP
+.B disable_bw_measurement \fR=\fPbool
+Disable measurements of throughput/bandwidth numbers. See \fBdisable_clat\fR.

 .TP
 .BI lockmem \fR=\fPint
 Pin the specified amount of memory with \fBmlock\fR\|(2).  Can be used to
 .TP
 .BI lockmem \fR=\fPint
 Pin the specified amount of memory with \fBmlock\fR\|(2).  Can be used to


@@ -563,6 +620,22 @@ given time in milliseconds.
 .TP
 .BI disk_util \fR=\fPbool
 Generate disk utilization statistics if the platform supports it. Default: true.
 .TP
 .BI disk_util \fR=\fPbool
 Generate disk utilization statistics if the platform supports it. Default: true.

+.TP
+.BI gtod_reduce \fR=\fPbool
+Enable all of the gettimeofday() reducing options (disable_clat, disable_slat,
+disable_bw) plus reduce precision of the timeout somewhat to really shrink the
+gettimeofday() call count. With this option enabled, we only do about 0.4% of
+the gtod() calls we would have done if all time keeping was enabled.
+.TP
+.BI gtod_cpu \fR=\fPint
+Sometimes it's cheaper to dedicate a single thread of execution to just getting
+the current time. Fio (and databases, for instance) are very intensive on
+gettimeofday() calls. With this option, you can set one CPU aside for doing
+nothing but logging current time to a shared memory location. Then the other
+threads/processes that run IO workloads need only copy that segment, instead of
+entering the kernel with a gettimeofday() call. The CPU set aside for doing
+these time calls will be excluded from other uses. Fio will manually clear it
+from the CPU mask of other jobs.

 .SH OUTPUT
 While running, \fBfio\fR will display the status of the created jobs.  For
 example:
 .SH OUTPUT
 While running, \fBfio\fR will display the status of the created jobs.  For
 example:


@@ -777,7 +850,7 @@ was written by Jens Axboe <jens.axboe@oracle.com>.
 This man page was written by Aaron Carroll <aaronc@cse.unsw.edu.au> based
 on documentation by Jens Axboe.
 .SH "REPORTING BUGS"
 This man page was written by Aaron Carroll <aaronc@cse.unsw.edu.au> based
 on documentation by Jens Axboe.
 .SH "REPORTING BUGS"

-Report bugs to the \fBfio\fR mailing list <fio-devel@kernel.dk>.
+Report bugs to the \fBfio\fR mailing list <fio@vger.kernel.org>.

 See \fBREADME\fR.
 .SH "SEE ALSO"
 For further documentation see \fBHOWTO\fR and \fBREADME\fR.
 See \fBREADME\fR.
 .SH "SEE ALSO"
 For further documentation see \fBHOWTO\fR and \fBREADME\fR.