X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=34669665bfdbe59fbd00c22fbeb9dbdcfc4d13e5;hp=bacc634ebc3b519b9465b5e523ed94b433e8f162;hb=5c9323fb6e381ba6bd6adc1b69ce28975d463333;hpb=1d360ffbcd58d32d6b5ec33f325f36b40efb3e6c diff --git a/fio.1 b/fio.1 index bacc634e..34669665 100644 --- a/fio.1 +++ b/fio.1 @@ -54,6 +54,12 @@ Convert \fIjobfile\fR to a set of command-line options. 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 @@ -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 @@ -241,7 +271,7 @@ new offset. .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 -reasons. Allow values are 1024 or 1000, with 1024 being the default. +reasons. Allowed 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 @@ -291,7 +321,7 @@ are likely to be issued. Default: true. .TP .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). +been transferred, unless limited by other options (\fBruntime\fR, for instance). 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 @@ -314,15 +344,16 @@ 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 multiple of the minimum size, unless \fBblocksize_unaligned\fR is set. Applies to both reads and writes if only one range is given, but can be specified -separately with a comma seperating the values. Example: bsrange=1k-4k,2k-8k. +separately with a comma separating the values. Example: bsrange=1k-4k,2k-8k. Also (see \fBblocksize\fR). .TP .BI bssplit \fR=\fPstr @@ -348,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 @@ -390,10 +427,11 @@ Defines how files to service are selected. The following types are defined: .RS .TP .B random -Choose a file at random +Choose a file at random. .TP .B roundrobin Round robin over open files (default). +.TP .B sequential Do each file in the set sequentially. .RE @@ -418,6 +456,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 @@ -536,6 +577,13 @@ that starts at 0 and is incremented for each job. This option is useful if there are several jobs which are intended to operate on a file in parallel in disjoint segments, with even spacing between the starting points. .TP +.BI number_ios \fR=\fPint +Fio will normally perform IOs until it has exhausted the size of the region +set by \fBsize\fR, or if it exhaust the allocated time (or hits an error +condition). With this setting, the range/size can be set independently of +the number of IOs to perform. When fio reaches this number, it will exit +normally and report status. +.TP .BI fsync \fR=\fPint How many I/Os to perform before issuing an \fBfsync\fR\|(2) of dirty data. If 0, don't sync. Default: 0. @@ -611,6 +659,13 @@ 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 @@ -660,7 +715,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 @@ -679,12 +739,12 @@ as \fBrate\fR is used for read vs write separation. .BI rate_iops \fR=\fPint Cap the bandwidth to this number of IOPS. Basically the same as rate, just specified independently of bandwidth. The same format as \fBrate\fR is used for -read vs write seperation. If \fBblocksize\fR is a range, the smallest block +read vs write separation. If \fBblocksize\fR is a range, the smallest block size is used as the metric. .TP .BI rate_iops_min \fR=\fPint If this rate of I/O is not met, the job will exit. The same format as \fBrate\fR -is used for read vs write seperation. +is used for read vs write separation. .TP .BI ratecycle \fR=\fPint Average bandwidth for \fBrate\fR and \fBratemin\fR over this number of @@ -862,7 +922,7 @@ written file. If the data direction includes any form of write, the verify will be of the newly written data. .RE .TP -.BI verify_sort \fR=\fPbool +.BI verifysort \fR=\fPbool 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 @@ -1010,13 +1070,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. @@ -1146,6 +1212,12 @@ Some parameters are only valid when a specific ioengine is in use. These are used identically to normal parameters, with the caveat that when used on the command line, the must come after the ioengine that defines them is selected. .TP +.BI (cpu)cpuload \fR=\fPint +Attempt to use the specified percentage of CPU cycles. +.TP +.BI (cpu)cpuchunks \fR=\fPint +Split the load into cycles of the given time. In microseconds. +.TP .BI (libaio)userspace_reap Normally, with the libaio engine in use, fio will use the io_getevents system call to reap newly returned events. @@ -1157,11 +1229,18 @@ 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 @@ -1192,13 +1271,14 @@ connections rather than initiating an outgoing connection. The hostname must be omitted if this option is used. .TP .BI (net, pingpong) \fR=\fPbool -Normal a network writer will just continue writing data, and a network reader +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. +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)