X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=ad5040b37372e93415b7783db9924934211213cf;hp=77773a0cb42db641fc1fd713b8a4130ba6b6a908;hb=a596f047e2b3d447ccca76bd075f05473a1f8d1c;hpb=525c2bfabdb7e0093a8775a09ad3e772d962760e diff --git a/fio.1 b/fio.1 index 77773a0c..ad5040b3 100644 --- a/fio.1 +++ b/fio.1 @@ -172,11 +172,39 @@ Mixed sequential reads and writes. 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\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=\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 @@ -186,10 +214,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 @@ -198,16 +254,18 @@ 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. .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 @@ -303,7 +361,13 @@ coalescing adjacents IOs into a single submission. 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 @@ -351,7 +415,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. @@ -652,6 +722,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 @@ -670,13 +745,16 @@ 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 verify -the previously written blocks before continuing to write new ones. +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). +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 Wait for preceeding jobs in the job file to exit before starting this one. @@ -706,12 +784,26 @@ 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 \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 @@ -719,7 +811,7 @@ 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 +.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. @@ -951,7 +1043,8 @@ Disk utilization. .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. Note that the first +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: @@ -1013,12 +1106,24 @@ IO depth distribution: .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 (dependant 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