X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=85304ed57dc1104eb62280fd422d695f905786fe;hp=adab043b893860b51a1dc97868ca94aae476850a;hb=482900c94face8e1891a181148b2f8a01e905aa5;hpb=d9956b64373522fcbe5acb5015fef6d315f252da diff --git a/fio.1 b/fio.1 index adab043b..85304ed5 100644 --- 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 +.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 \-\-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 @@ -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 -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), -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. @@ -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 -.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 @@ -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 -.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 -.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 -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 +.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 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 @@ -196,6 +228,8 @@ Choose a file at random .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 @@ -214,6 +248,10 @@ position the I/O location. .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 @@ -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 -.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 @@ -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 +.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 @@ -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 -.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 @@ -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_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 @@ -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 -.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 -.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 @@ -495,10 +543,10 @@ specified. 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 -.BI zoneskip \fR=\fPsiint +.BI zoneskip \fR=\fPint 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 -.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 -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 -.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 @@ -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 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: @@ -730,7 +812,7 @@ Bandwidth: .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: @@ -752,7 +834,7 @@ was written by Jens Axboe . This man page was written by Aaron Carroll based on documentation by Jens Axboe. .SH "REPORTING BUGS" -Report bugs to the \fBfio\fR mailing list . +Report bugs to the \fBfio\fR mailing list . See \fBREADME\fR. .SH "SEE ALSO" For further documentation see \fBHOWTO\fR and \fBREADME\fR.