Fio man page still refers to old mailing list

[fio.git] / fio.1

diff --git a/fio.1 b/fio.1
index adab043b893860b51a1dc97868ca94aae476850a..85304ed57dc1104eb62280fd422d695f905786fe 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -37,9 +37,17 @@ Enable read-only safety checks.
 Specifies when real-time ETA estimate should be printed.  \fIwhen\fR may
 be one of `always', `never' or `auto'.
 .TP
 Specifies when real-time ETA estimate should be printed.  \fIwhen\fR may
 be one of `always', `never' or `auto'.
 .TP

+.BI \-\-section \fR=\fPsec
+Only run section \fIsec\fR from job file.
+.TP

 .BI \-\-cmdhelp \fR=\fPcommand
 Print help information for \fIcommand\fR.  May be `all' for all commands.
 .TP
 .BI \-\-cmdhelp \fR=\fPcommand
 Print help information for \fIcommand\fR.  May be `all' for all commands.
 .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
+list all available tracing options.
+.TP

 .B \-\-help
 Display usage information and exit.
 .TP
 .B \-\-help
 Display usage information and exit.
 .TP


@@ -69,13 +77,10 @@ Some parameters may take arguments of a specific type.  The types used are:
 String: a sequence of alphanumeric characters.
 .TP
 .I int
 String: a sequence of alphanumeric characters.
 .TP
 .I int

-Integer: a whole number, possibly negative.  If prefixed with `0x', the value
-is assumed to be base 16 (hexadecimal).
-.TP
-.I siint

 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),
 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.
+mega (1024*1024) and giga (1024*1024*1024) respectively. If prefixed with '0x',
+the value is assumed to be base 16 (hexadecimal).

 .TP
 .I bool
 Boolean: a true or false value. `0' denotes false, `1' denotes true.
 .TP
 .I bool
 Boolean: a true or false value. `0' denotes false, `1' denotes true.


@@ -151,7 +156,7 @@ across runs.  Default: true.
 Disable use of \fIposix_fadvise\fR\|(2) to advise the kernel what I/O patterns
 are likely to be issued. Default: true.
 .TP
 Disable use of \fIposix_fadvise\fR\|(2) to advise the kernel what I/O patterns
 are likely to be issued. Default: true.
 .TP

-.BI size \fR=\fPsiint
+.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
 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


@@ -163,23 +168,50 @@ for files at random within the given range, limited to \fBsize\fR in total (if
 that is given). If \fBfilesize\fR is not specified, each created file is the
 same size.
 .TP
 that is given). If \fBfilesize\fR is not specified, each created file is the
 same size.
 .TP

-.BI blocksize \fR=\fPsiint "\fR,\fB bs" \fR=\fPsiint
+.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
 which may be empty to leave that value at its default.
 .TP
 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
 which may be empty to leave that value at its default.
 .TP

-.BI blocksize_range \fR=\fPirange "\fR,\fB bsrange" \fR=\fPirange
+.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
 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, but can be specified seperately (see \fBblocksize\fR).
+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.
+Also (see \fBblocksize\fR).
+.TP
+.BI bssplit \fR=\fPstr
+This option allows even finer grained control of the block sizes issued,
+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.
+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
+\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


@@ -196,6 +228,8 @@ Choose a file at random
 .TP
 .B roundrobin
 Round robin over open files (default).
 .TP
 .B roundrobin
 Round robin over open files (default).

+.B sequential
+Do each file in the set sequentially.

 .RE
 .P
 The number of I/Os to issue before switching a new file can be specified by
 .RE
 .P
 The number of I/Os to issue before switching a new file can be specified by


@@ -214,6 +248,10 @@ position the I/O location.
 .B psync
 Basic \fIpread\fR\|(2) or \fIpwrite\fR\|(2) I/O.
 .TP
 .B psync
 Basic \fIpread\fR\|(2) or \fIpwrite\fR\|(2) I/O.
 .TP

+.B vsync
+Basic \fIreadv\fR\|(2) or \fIwritev\fR\|(2) I/O. Will emulate queuing by
+coalescing adjacents IOs into a single submission.
+.TP

 .B libaio
 Linux native asynchronous I/O.
 .TP
 .B libaio
 Linux native asynchronous I/O.
 .TP


@@ -282,7 +320,7 @@ If true, use non-buffered I/O (usually O_DIRECT).  Default: false.
 If true, use buffered I/O.  This is the opposite of the \fBdirect\fR parameter.
 Default: true.
 .TP
 If true, use buffered I/O.  This is the opposite of the \fBdirect\fR parameter.
 Default: true.
 .TP

-.BI offset \fR=\fPsiint
+.BI offset \fR=\fPint

 Offset in the file to start I/O. Data before the offset will not be touched.
 .TP
 .BI fsync \fR=\fPint
 Offset in the file to start I/O. Data before the offset will not be touched.
 .TP
 .BI fsync \fR=\fPint


@@ -373,6 +411,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 ramp_time 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


@@ -408,7 +453,7 @@ the system must have free huge pages allocated.  \fBmmaphuge\fR also needs to
 have hugetlbfs mounted, and \fIfile\fR must point there.
 .RE
 .TP
 have hugetlbfs mounted, and \fIfile\fR must point there.
 .RE
 .TP

-.BI hugepage\-size \fR=\fPsiint
+.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.
 .TP
 Defines the size of a huge page.  Must be at least equal to the system setting.
 Should be a multiple of 1MiB. Default: 4MiB.
 .TP


@@ -425,6 +470,9 @@ If true, serialize file creation for the jobs.  Default: true.
 .BI create_fsync \fR=\fPbool
 \fIfsync\fR\|(2) data file after creation.  Default: true.
 .TP
 .BI create_fsync \fR=\fPbool
 \fIfsync\fR\|(2) data file after creation.  Default: true.
 .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 unlink \fR=\fPbool
 Unlink job files when done.  Default: false.
 .TP
 .BI unlink \fR=\fPbool
 Unlink job files when done.  Default: false.
 .TP


@@ -463,11 +511,11 @@ Pretend to verify.  Used for testing internals.
 If true, written verify blocks are sorted if \fBfio\fR deems it to be faster to
 read them back in a sorted manner.  Default: true.
 .TP
 If true, written verify blocks are sorted if \fBfio\fR deems it to be faster to
 read them back in a sorted manner.  Default: true.
 .TP

-.BI verify_offset \fR=\fPsiint
+.BI verify_offset \fR=\fPint

 Swap the verification header with data somewhere else in the block before
 writing.  It is swapped back before verifying.
 .TP
 Swap the verification header with data somewhere else in the block before
 writing.  It is swapped back before verifying.
 .TP

-.BI verify_interval \fR=\fPsiint
+.BI verify_interval \fR=\fPint

 Write the verification header for this number of bytes, which should divide
 \fBblocksize\fR.  Default: \fBblocksize\fR.
 .TP
 Write the verification header for this number of bytes, which should divide
 \fBblocksize\fR.  Default: \fBblocksize\fR.
 .TP


@@ -495,10 +543,10 @@ specified.
 Use threads created with \fBpthread_create\fR\|(3) instead of processes created
 with \fBfork\fR\|(2).
 .TP
 Use threads created with \fBpthread_create\fR\|(3) instead of processes created
 with \fBfork\fR\|(2).
 .TP

-.BI zonesize \fR=\fPsiint
+.BI zonesize \fR=\fPint

 Divide file into zones of the specified size in bytes.  See \fBzoneskip\fR.
 .TP
 Divide file into zones of the specified size in bytes.  See \fBzoneskip\fR.
 .TP

-.BI zoneskip \fR=\fPsiint
+.BI zoneskip \fR=\fPint

 Skip the specified number of bytes when \fBzonesize\fR bytes of data have been
 read.
 .TP
 Skip the specified number of bytes when \fBzonesize\fR bytes of data have been
 read.
 .TP


@@ -509,13 +557,31 @@ 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
 .TP

-.BI lockmem \fR=\fPsiint
+.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
 simulate a smaller amount of memory.
 .TP
 Pin the specified amount of memory with \fBmlock\fR\|(2).  Can be used to
 simulate a smaller amount of memory.
 .TP


@@ -538,6 +604,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:


@@ -730,7 +812,7 @@ Bandwidth:
 .P
 CPU usage:
 .RS
 .P
 CPU usage:
 .RS

-.B user, system, context switches
+.B user, system, context switches, major page faults, minor page faults

 .RE
 .P
 IO depth distribution:
 .RE
 .P
 IO depth distribution:


@@ -752,7 +834,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.