X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=dc10b4031d9260817618033dc95218c73c96c446;hp=f01bf3a4faa9ef4a50aeb80dac3658c545eb356c;hb=a781480e959e4cad32f27915bdb5dab948aa1c6e;hpb=092f707fea37a4cce592460f15e8aae4609a75e6 diff --git a/fio.1 b/fio.1 index f01bf3a4..dc10b403 100644 --- a/fio.1 +++ b/fio.1 @@ -45,7 +45,7 @@ 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 +or individual types separated by a comma (eg \-\-debug=io,file). `help' will list all available tracing options. .TP .B \-\-help @@ -53,6 +53,9 @@ Display usage information and exit. .TP .B \-\-version Display version information and exit. +.TP +.B \-\-terse\-version\fR=\fPtype +Terse version output format .SH "JOB FILE FORMAT" Job files are in `ini' format. They consist of one or more job definitions, which begin with a job name in square brackets and @@ -81,8 +84,8 @@ SI integer: a whole number, possibly containing a suffix denoting the base unit 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 +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. @@ -96,6 +99,10 @@ Integer range: a range of integers specified in the format \fIupper\fR may contain a suffix as described above. If an option allows two sets of ranges, they are separated with a `,' or `/' character. For example: `8\-8k/8M\-4G'. +.TP +.I float_list +List of floating numbers: A list of floating numbers, separated by +a ':' charcater. .SS "Parameter List" .TP .BI name \fR=\fPstr @@ -177,7 +184,10 @@ 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\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. +value of 8. If the postfix is used with a sequential IO pattern, then the value +specified will be added to the generated offset for each IO. For instance, +using \fBrw=write:4k\fR will skip 4k for every write. It turns sequential IO +into sequential IO with holes. See the \fBrw_sequencer\fR option. .RE .TP .BI rw_sequencer \fR=\fPstr @@ -214,10 +224,38 @@ reasons. Allow values are 1024 or 1000, with 1024 being the default. Seed the random number generator in a predictable way so results are repeatable across runs. Default: true. .TP -.BI fallocate \fR=\fPbool -By default, fio will use fallocate() to advise the system of the size of the -file we are going to write. This can be turned off with fallocate=0. May not -be available on all supported platforms. +.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 @@ -226,16 +264,20 @@ 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 +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. +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 +.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 @@ -260,7 +302,7 @@ 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. +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 @@ -287,6 +329,13 @@ 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 scramble_buffers \fR=\fPbool +If \fBrefill_buffers\fR is too costly and the target is using data +deduplication, then setting this option will slightly modify the IO buffer +contents to defeat normal de-dupe attempts. This is not enough to defeat +more clever block compression attempts, but it will stop naive dedupe +of blocks. Default: true. +.TP .BI nrfiles \fR=\fPint Number of files to use for this job. Default: 1. .TP @@ -328,10 +377,22 @@ 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. +Linux native asynchronous I/O. This engine also has a sub-option, +\fBuserspace_reap\fR. To set it, use \fBioengine=libaio:userspace_reap\fR. +Normally, with the libaio engine in use, fio will use the +\fIio_getevents\fR\|(3) system call to reap newly returned events. With this +flag turned on, the AIO ring will be read directly from user-space to reap +events. The reaping mode is only enabled when polling for a minimum of \fB0\fR +events (eg when \fBiodepth_batch_complete=0\fR). .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 @@ -372,6 +433,10 @@ approach to asycnronous I/O. .br See . .TP +.B rdma +The RDMA I/O engine supports both RDMA memory semantics (RDMA_WRITE/RDMA_READ) +and channel semantics (Send/Recv) for the InfiniBand, RoCE and iWARP protocols. +.TP .B external Loads an external I/O engine object file. Append the engine filename as `:\fIenginepath\fR'. @@ -379,7 +444,13 @@ Loads an external I/O engine object file. Append the engine filename as .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. @@ -464,7 +535,7 @@ Normally \fBfio\fR will cover every block of the file when doing random I/O. If this parameter is given, a new offset will be chosen without looking at past I/O history. This parameter is mutually exclusive with \fBverify\fR. .TP -.B softrandommap +.BI softrandommap \fR=\fPbool See \fBnorandommap\fR. 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 @@ -582,7 +653,7 @@ 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 @@ -680,6 +751,11 @@ has to be a hex number that starts with either "0x" or "0X". Use with 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 @@ -709,8 +785,8 @@ read back and verified). If \fBverify_backlog_batch\fR is less than \fBverify_backlog_batch\fR is larger than \fBverify_backlog\fR, some blocks will be verified more than once. .TP -.B stonewall -Wait for preceeding jobs in the job file to exit before starting this one. +.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 @@ -737,7 +813,9 @@ Skip the specified number of bytes when \fBzonesize\fR bytes of data have been 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 @@ -755,31 +833,31 @@ 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 +.BI 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 \fR=\fPstr +.BI 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_lat \fR=\fPbool +.BI 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 submission latency numbers. See \fBdisable_lat\fR. +.BI disable_clat \fR=\fPbool +Disable measurements of completion latency numbers. See \fBdisable_lat\fR. .TP -.B disable_slat \fR=\fPbool +.BI disable_slat \fR=\fPbool Disable measurements of submission latency numbers. See \fBdisable_lat\fR. .TP -.B disable_bw_measurement \fR=\fPbool +.BI disable_bw_measurement \fR=\fPbool Disable measurements of throughput/bandwidth numbers. See \fBdisable_lat\fR. .TP .BI lockmem \fR=\fPint @@ -827,7 +905,7 @@ 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 +# 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 @@ -845,6 +923,17 @@ the thread/process does any work. .TP .BI gid \fR=\fPint Set group ID, see \fBuid\fR. +.TP +.BI clat_percentiles \fR=\fPbool +Enable the reporting of percentiles of completion latencies. +.TP +.BI percentile_list \fR=\fPfloat_list +Overwrite the default list of percentiles for completion +latencies. Each number is a floating number in the range (0,100], and +the maximum length of the list is 20. Use ':' to separate the +numbers. For example, --percentile_list=99.5:99.9 will cause fio to +report the values of completion latency below which 99.5% and 99.9% of +the observed latencies fell, respectively. .SH OUTPUT While running, \fBfio\fR will display the status of the created jobs. For example: @@ -1005,7 +1094,7 @@ change. The fields are: .P Read status: .RS -.B KB I/O, bandwidth \fR(KB/s)\fP, runtime \fR(ms)\fP +.B Total I/O \fR(KB)\fP, bandwidth \fR(KB/s)\fP, runtime \fR(ms)\fP .P Submission latency: .RS @@ -1027,7 +1116,7 @@ Bandwidth: .P Write status: .RS -.B KB I/O, bandwidth \fR(KB/s)\fP, runtime \fR(ms)\fP +.B Total I/O \fR(KB)\fP, bandwidth \fR(KB/s)\fP, runtime \fR(ms)\fP .P Submission latency: .RS @@ -1069,7 +1158,7 @@ Milliseconds: .RE .RE .P -Error Info (dependant on continue_on_error, default off): +Error Info (dependent on continue_on_error, default off): .RS .B total # errors, first error code .RE