X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=b54eeadb045016c0c970a4d11deb93faaf030e79;hp=d42516a912bb0ad3bbc7a772317d9ac57918a58f;hb=8ff749cca16845a3172e22323489d20d8f99f9dd;hpb=3d7174e3c4b8aa4daa36261a8e638b702fac5aba diff --git a/fio.1 b/fio.1 index d42516a9..b54eeadb 100644 --- a/fio.1 +++ b/fio.1 @@ -50,13 +50,16 @@ List all commands defined by \fIioengine\fR, or print help for \fIcommand\fR def .BI \-\-showcmd \fR=\fPjobfile Convert \fIjobfile\fR to a set of command-line options. .TP -.B \-\-readonly -Enable read-only safety checks. -.TP .BI \-\-eta \fR=\fPwhen Specifies when real-time ETA estimate should be printed. \fIwhen\fR may be one of `always', `never' or `auto'. .TP +.BI \-\-eta\-newline \fR=\fPtime +Force an ETA newline for every `time` period passed. +.TP +.BI \-\-status\-interval \fR=\fPtime +Report full output status every `time` period passed. +.TP .BI \-\-readonly Turn on safety read-only checks, preventing any attempted write. .TP @@ -80,6 +83,9 @@ Background a fio server, writing the pid to the given pid file. .TP .BI \-\-client \fR=\fPhost Instead of running the jobs locally, send and run them on the given host. +.TP +.BI \-\-idle\-prof \fR=\fPoption +Report cpu idleness on a system or percpu basis (\fIoption\fP=system,percpu) or run unit work calibration only (\fIoption\fP=calibrate). .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 @@ -151,6 +157,34 @@ a number of files by separating the names with a `:' character. `\-' is a reserved name, meaning stdin or stdout, depending on the read/write direction set. .TP +.BI filename_format \fR=\fPstr +If sharing multiple files between jobs, it is usually necessary to have +fio generate the exact names that you want. By default, fio will name a file +based on the default file format specification of +\fBjobname.jobnumber.filenumber\fP. With this option, that can be +customized. Fio will recognize and replace the following keywords in this +string: +.RS +.RS +.TP +.B $jobname +The name of the worker thread or process. +.TP +.B $jobnum +The incremental number of the worker thread or process. +.TP +.B $filenum +The incremental number of the file for that worker thread or process. +.RE +.P +To have dependent jobs share a set of files, this option can be set to +have fio generate filenames that are shared between the two. For instance, +if \fBtestfiles.$filenum\fR is specified, file number 4 for any job will +be named \fBtestfiles.4\fR. The default of \fB$jobname.$jobnum.$filenum\fR +will be used if no other format specifier is given. +.RE +.P +.TP .BI lockfile \fR=\fPstr Fio defaults to not locking any files before it does IO to them. If a file or file descriptor is shared, fio can serialize IO to that file to make the end @@ -169,10 +203,6 @@ Only one thread or process may do IO at the time, excluding all others. Read-write locking on the file. Many readers may access the file at the same time, but writes get exclusive access. .RE -.P -The option may be post-fixed with a lock batch number. If set, then each -thread/process may do that amount of IOs to the file before giving up the lock. -Since lock acquisition is expensive, batching the lock/unlocks will speed up IO. .RE .P .BI opendir \fR=\fPstr @@ -243,6 +273,11 @@ 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 reasons. Allow values are 1024 or 1000, with 1024 being the default. .TP +.BI unified_rw_reporting \fR=\fPbool +Fio normally reports statistics on a per data direction basis, meaning that +read, write, and trim are accounted and reported separately. If this option is +set, the fio will sum the results and report them as "mixed" instead. +.TP .BI randrepeat \fR=\fPbool Seed the random number generator in a predictable way so results are repeatable across runs. Default: true. @@ -309,9 +344,10 @@ that is given). If \fBfilesize\fR is not specified, each created file is the same size. .TP .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 separately in the format \fIread\fR,\fIwrite\fR, either of -which may be empty to leave that value at its default. +Block size for I/O units. Default: 4k. Values for reads, writes, and trims +can be specified separately in the format \fIread\fR,\fIwrite\fR,\fItrim\fR +either of which may be empty to leave that value at its default. If a trailing +comma isn't given, the remainder will inherit the last value set. .TP .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 @@ -343,6 +379,12 @@ 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 +.BI bs_is_seq_rand \fR=\fPbool +If this option is set, fio will use the normal read,write blocksize settings as +sequential,random instead. Any random read or write will use the WRITE +blocksize settings, and any sequential read or write will use the READ +blocksize setting. +.TP .B zero_buffers Initialise buffers with all zeros. Default: fill buffers with random data. .TP @@ -413,6 +455,9 @@ Basic \fIpread\fR\|(2) or \fIpwrite\fR\|(2) I/O. Basic \fIreadv\fR\|(2) or \fIwritev\fR\|(2) I/O. Will emulate queuing by coalescing adjacents IOs into a single submission. .TP +.B pvsync +Basic \fIpreadv\fR\|(2) or \fIpwritev\fR\|(2) I/O. +.TP .B libaio Linux native asynchronous I/O. This ioengine defines engine specific options. .TP @@ -486,8 +531,8 @@ transfer as fio ioengine .B e4defrag IO engine that does regular EXT4_IOC_MOVE_EXT ioctls to simulate defragment activity request to DDIR_WRITE event -.TP .RE +.P .RE .TP .BI iodepth \fR=\fPint @@ -564,7 +609,7 @@ Also see the sync_file_range(2) man page. This option is Linux specific. If writing, setup the file first and do overwrites. Default: false. .TP .BI end_fsync \fR=\fPbool -Sync file contents when job exits. Default: false. +Sync file contents when a write stage has completed. Default: false. .TP .BI fsync_on_close \fR=\fPbool If true, sync file contents on close. This differs from \fBend_fsync\fR in that @@ -580,6 +625,39 @@ 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 +.BI random_distribution \fR=\fPstr:float +By default, fio will use a completely uniform random distribution when asked +to perform random IO. Sometimes it is useful to skew the distribution in +specific ways, ensuring that some parts of the data is more hot than others. +Fio includes the following distribution models: +.RS +.TP +.B random +Uniform random distribution +.TP +.B zipf +Zipf distribution +.TP +.B pareto +Pareto distribution +.TP +.RE +.P +When using a zipf or pareto distribution, an input value is also needed to +define the access pattern. For zipf, this is the zipf theta. For pareto, +it's the pareto power. Fio includes a test program, genzipf, that can be +used visualize what the given input values will yield in terms of hit rates. +If you wanted to use zipf with a theta of 1.2, you would use +random_distribution=zipf:1.2 as the option. If a non-uniform model is used, +fio will disable use of the random map. +.TP +.BI percentage_random \fR=\fPint +For a random workload, set how big a percentage should be random. This defaults +to 100%, in which case the workload is fully random. It can be set from +anywhere from 0 to 100. Setting it to 0 would make the workload fully +sequential. It is possible to set different values for reads, writes, and +trim. To do so, simply use a comma separated list. See \fBblocksize\fR. +.TP .B norandommap 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 @@ -591,6 +669,26 @@ 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 option is disabled by default. .TP +.BI random_generator \fR=\fPstr +Fio supports the following engines for generating IO offsets for random IO: +.RS +.TP +.B tausworthe +Strong 2^88 cycle random number generator +.TP +.B lfsr +Linear feedback shift register generator +.TP +.RE +.P +Tausworthe is a strong random number generator, but it requires tracking on the +side if we want to ensure that blocks are only read or written once. LFSR +guarantees that we never generate the same offset twice, and it's also less +computationally expensive. It's not a true random generator, however, though +for IO purposes it's typically good enough. LFSR only works with single block +sizes, not with workloads that use multiple block sizes. If used with such a +workload, fio may read or write some blocks multiple times. +.TP .BI nice \fR=\fPint Run job with given nice value. See \fInice\fR\|(2). .TP @@ -609,7 +707,12 @@ Pretend to spend CPU time for given number of microseconds, sleeping the rest of the time specified by \fBthinktime\fR. Only valid if \fBthinktime\fR is set. .TP .BI thinktime_blocks \fR=\fPint -Number of blocks to issue before waiting \fBthinktime\fR microseconds. +Only valid if thinktime is set - control how many blocks to issue, before +waiting \fBthinktime\fR microseconds. If not set, defaults to 1 which will +make fio wait \fBthinktime\fR microseconds after every block. This +effectively makes any queue depth setting redundant, since no more than 1 IO +will be queued before we have to complete it and do our thinktime. In other +words, this setting effectively caps the queue depth if the latter is larger. Default: 1. .TP .BI rate \fR=\fPint @@ -639,6 +742,10 @@ is used for read vs write seperation. Average bandwidth for \fBrate\fR and \fBratemin\fR over this number of milliseconds. Default: 1000ms. .TP +.BI max_latency \fR=\fPint +If set, fio will exit the job if it exceeds this maximum latency. It will exit +with an ETIME error. +.TP .BI cpumask \fR=\fPint Set CPU affinity for this job. \fIint\fR is a bitmask of allowed CPUs the job may run on. See \fBsched_setaffinity\fR\|(2). @@ -646,6 +753,28 @@ may run on. See \fBsched_setaffinity\fR\|(2). .BI cpus_allowed \fR=\fPstr Same as \fBcpumask\fR, but allows a comma-delimited list of CPU numbers. .TP +.BI numa_cpu_nodes \fR=\fPstr +Set this job running on spcified NUMA nodes' CPUs. The arguments allow +comma delimited list of cpu numbers, A-B ranges, or 'all'. +.TP +.BI numa_mem_policy \fR=\fPstr +Set this job's memory policy and corresponding NUMA nodes. Format of +the argements: +.RS +.TP +.B [:] +.TP +.B mode +is one of the following memory policy: +.TP +.B default, prefer, bind, interleave, local +.TP +.RE +For \fBdefault\fR and \fBlocal\fR memory policy, no \fBnodelist\fR is +needed to be specified. For \fBprefer\fR, only one node is +allowed. For \fBbind\fR and \fBinterleave\fR, \fBnodelist\fR allows +comma delimited list of numbers, A-B ranges, or 'all'. +.TP .BI startdelay \fR=\fPint Delay start of job for the specified number of seconds. .TP @@ -933,13 +1062,19 @@ Disable measurements of throughput/bandwidth numbers. See \fBdisable_lat\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. +simulate a smaller amount of memory. The amount specified is per worker. .TP .BI exec_prerun \fR=\fPstr Before running the job, execute the specified command with \fBsystem\fR\|(3). +.RS +Output is redirected in a file called \fBjobname.prerun.txt\fR +.RE .TP .BI exec_postrun \fR=\fPstr Same as \fBexec_prerun\fR, but the command is executed after the job completes. +.RS +Output is redirected in a file called \fBjobname.postrun.txt\fR +.RE .TP .BI ioscheduler \fR=\fPstr Attempt to switch the device hosting the file to the specified I/O scheduler. @@ -955,6 +1090,27 @@ given time in milliseconds. .BI disk_util \fR=\fPbool Generate disk utilization statistics if the platform supports it. Default: true. .TP +.BI clocksource \fR=\fPstr +Use the given clocksource as the base of timing. The supported options are: +.RS +.TP +.B gettimeofday +gettimeofday(2) +.TP +.B clock_gettime +clock_gettime(2) +.TP +.B cpu +Internal CPU clock source +.TP +.RE +.P +\fBcpu\fR is the preferred clocksource if it is reliable, as it is very fast +(and fio is heavy on time calls). Fio will automatically use this clocksource +if it's supported and considered reliable on the system it is running on, +unless another clocksource is specifically set. For x86/x86-64 CPUs, this +means supporting TSC Invariant. +.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 @@ -1065,11 +1221,21 @@ iodepth_batch_complete=0). .BI (net,netsplice)hostname \fR=\fPstr The host name or IP address to use for TCP or UDP based IO. If the job is a TCP listener or UDP reader, the hostname is not -used and must be omitted. +used and must be omitted unless it is a valid UDP multicast address. .TP .BI (net,netsplice)port \fR=\fPint The TCP or UDP port to bind to or connect to. .TP +.BI (net,netsplice)interface \fR=\fPstr +The IP address of the network interface used to send or receive UDP multicast +packets. +.TP +.BI (net,netsplice)ttl \fR=\fPint +Time-to-live value for outgoing UDP multicast packets. Default: 1 +.TP +.BI (net,netsplice)nodelay \fR=\fPbool +Set TCP_NODELAY on TCP connections. +.TP .BI (net,netsplice)protocol \fR=\fPstr "\fR,\fP proto" \fR=\fPstr The network protocol to use. Accepted values are: .RS @@ -1079,7 +1245,7 @@ The network protocol to use. Accepted values are: Transmission control protocol .TP .B udp -Unreliable datagram protocol +User datagram protocol .TP .B unix UNIX domain socket @@ -1096,6 +1262,16 @@ For TCP network connections, tell fio to listen for incoming connections rather than initiating an outgoing connection. The hostname must be omitted if this option is used. .TP +.BI (net, pingpong) \fR=\fPbool +Normaly a network writer will just continue writing data, and a network reader +will just consume packages. If pingpong=1 is set, a writer will send its normal +payload to the reader, then wait for the reader to send the same payload back. +This allows fio to measure network latencies. The submission and completion +latencies then measure local time spent sending or receiving, and the +completion latency measures how long it took for the other end to receive and +send back. For UDP multicast traffic pingpong=1 should only be set for a single +reader when multiple readers are listening to the same address. +.TP .BI (e4defrag,donorname) \fR=\fPstr File will be used as a block donor (swap extents between files) .TP