X-Git-Url: https://git.kernel.dk/?a=blobdiff_plain;f=fio.1;h=938038e4f0a0a61a98a7423ce5c6f175a302eb9f;hb=d0db819d9c5abe904f85a3b21a95023fef007f20;hp=aae7657281a893f97b8cede4f4b5e59b23d3a5d8;hpb=ef71e317e6e1e96a4776610035cd67711603e1f8;p=fio.git diff --git a/fio.1 b/fio.1 index aae76572..938038e4 100644 --- a/fio.1 +++ b/fio.1 @@ -44,6 +44,9 @@ Display usage information and exit. .BI \-\-cmdhelp \fR=\fPcommand Print help information for \fIcommand\fR. May be `all' for all commands. .TP +.BI \-\-enghelp \fR=\fPioengine[,command] +List all commands defined by \fIioengine\fR, or print help for \fIcommand\fR defined by \fIioengine\fR. +.TP .BI \-\-showcmd \fR=\fPjobfile Convert \fIjobfile\fR to a set of command-line options. .TP @@ -142,9 +145,8 @@ than `./'. .B fio normally makes up a file name based on the job name, thread number, and file number. If you want to share files between threads in a job or several jobs, -specify a \fIfilename\fR for each of them to override the default. If the I/O -engine used is `net', \fIfilename\fR is the host and port to connect to in the -format \fIhost\fR/\fIport\fR. If the I/O engine is file-based, you can specify +specify a \fIfilename\fR for each of them to override the default. +If the I/O engine is file-based, you can specify 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. @@ -279,7 +281,7 @@ 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 +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=\fPint @@ -357,6 +359,20 @@ 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 buffer_compress_percentage \fR=\fPint +If this is set, then fio will attempt to provide IO buffer content (on WRITEs) +that compress to the specified level. Fio does this by providing a mix of +random data and zeroes. Note that this is per block size unit, for file/disk +wide compression level that matches this setting, you'll also want to set +\fBrefill_buffers\fR. +.TP +.BI buffer_compress_chunk \fR=\fPint +See \fBbuffer_compress_percentage\fR. This setting allows fio to manage how +big the ranges of random data and zeroed data is. Without this set, fio will +provide \fBbuffer_compress_percentage\fR of blocksize random data, followed by +the remaining zeroed. With this set to some chunk size smaller than the block +size, fio can alternate random and zeroed data throughout the IO buffer. +.TP .BI nrfiles \fR=\fPint Number of files to use for this job. Default: 1. .TP @@ -398,13 +414,7 @@ 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. 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). +Linux native asynchronous I/O. This ioengine defines engine specific options. .TP .B posixaio POSIX asynchronous I/O using \fIaio_read\fR\|(3) and \fIaio_write\fR\|(3). @@ -436,14 +446,14 @@ Doesn't transfer any data, just pretends to. Mainly used to exercise \fBfio\fR itself and for debugging and testing purposes. .TP .B net -Transfer over the network. \fBfilename\fR must be set appropriately to -`\fIhost\fR,\fIport\fR,\fItype\fR' regardless of data direction. \fItype\fR -is one of \fBtcp\fR, \fBudp\fR, or \fBunix\fR. For UNIX domain sockets, -the \fIhost\fR parameter is a file system path. +Transfer over the network. The protocol to be used can be defined with the +\fBprotocol\fR parameter. Depending on the protocol, \fBfilename\fR, +\fBhostname\fR, \fBport\fR, or \fBlisten\fR must be specified. +This ioengine defines engine specific options. .TP .B netsplice Like \fBnet\fR, but uses \fIsplice\fR\|(2) and \fIvmsplice\fR\|(2) to map data -and send/receive. +and send/receive. This ioengine defines engine specific options. .TP .B cpuio Doesn't transfer any data, but burns CPU cycles according to \fBcpuload\fR and @@ -499,6 +509,13 @@ Default: true. .BI offset \fR=\fPint Offset in the file to start I/O. Data before the offset will not be touched. .TP +.BI offset_increment \fR=\fPint +If this is provided, then the real offset becomes the +offset + offset_increment * thread_number, where the thread number is a counter +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 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. @@ -876,6 +893,13 @@ Same as \fBwrite_bw_log\fR, but writes IOPS. 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 +.BI log_avg_msec \fR=\fPint +By default, fio will log an entry in the iops, latency, or bw log for every +IO that completes. When writing to the disk log, that can quickly grow to a +very large size. Setting this option makes fio average the each log entry +over the specified period of time, reducing the resolution of the log. +Defaults to 0. +.TP .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 @@ -955,6 +979,27 @@ the thread/process does any work. .BI gid \fR=\fPint Set group ID, see \fBuid\fR. .TP +.BI flow_id \fR=\fPint +The ID of the flow. If not specified, it defaults to being a global flow. See +\fBflow\fR. +.TP +.BI flow \fR=\fPint +Weight in token-based flow control. If this value is used, then there is a +\fBflow counter\fR which is used to regulate the proportion of activity between +two or more jobs. fio attempts to keep this flow counter near zero. The +\fBflow\fR parameter stands for how much should be added or subtracted to the +flow counter on each iteration of the main I/O loop. That is, if one job has +\fBflow=8\fR and another job has \fBflow=-1\fR, then there will be a roughly +1:8 ratio in how much one runs vs the other. +.TP +.BI flow_watermark \fR=\fPint +The maximum value that the absolute value of the flow counter is allowed to +reach before the job must wait for a lower value of the counter. +.TP +.BI flow_sleep \fR=\fPint +The period of time, in microseconds, to wait after the flow watermark has been +exceeded before retrying operations +.TP .BI clat_percentiles \fR=\fPbool Enable the reporting of percentiles of completion latencies. .TP @@ -965,6 +1010,58 @@ 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. +.SS "Ioengine Parameters List" +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. +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 0 events (eg when +iodepth_batch_complete=0). +.TP +.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. +.TP +.BI (net,netsplice)port \fR=\fPint +The TCP or UDP port to bind to or connect to. +.TP +.BI (net,netsplice)protocol \fR=\fPstr "\fR,\fP proto" \fR=\fPstr +The network protocol to use. Accepted values are: +.RS +.RS +.TP +.B tcp +Transmission control protocol +.TP +.B udp +Unreliable datagram protocol +.TP +.B unix +UNIX domain socket +.RE +.P +When the protocol is TCP or UDP, the port must also be given, +as well as the hostname if the job is a TCP listener or UDP +reader. For unix sockets, the normal filename option should be +used and the port is invalid. +.RE +.TP +.BI (net,netsplice)listen +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. .SH OUTPUT While running, \fBfio\fR will display the status of the created jobs. For example: