X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=0a3351c3f120d5b264f5cca5bcb93e796ed5137b;hp=ef8f9599942bd08e63a96c8f32a24c6f176892e7;hb=5adc2447a8d52322981da4cd364a560bbd9d8351;hpb=3d7cd9b4c2570548bebfae4871c3ca068c5a29fe diff --git a/HOWTO b/HOWTO index ef8f9599..0a3351c3 100644 --- a/HOWTO +++ b/HOWTO @@ -524,16 +524,7 @@ ioengine=str Defines how the job issues io to the file. The following libaio Linux native asynchronous io. Note that Linux may only support queued behaviour with non-buffered IO (set direct=1 or buffered=0). - This engine also has a sub-option, - userspace_reap. To set it, use - ioengine=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). + This engine defines engine specific options. posixaio glibc posix asynchronous io. @@ -562,16 +553,16 @@ ioengine=str Defines how the job issues io to the file. The following itself and for debugging/testing purposes. net Transfer over the network to given host:port. - 'filename' must be set appropriately to - filename=host/port/protocol regardless of send - or receive, if the latter only the port - argument is used. 'host' may be an IP address - or hostname, port is the port number to be used, - and protocol may be 'udp' or 'tcp'. If no - protocol is given, TCP is used. + Depending on the protocol used, the hostname, + port, listen and filename options are used to + specify what sort of connection to make, while + the protocol option determines which protocol + will be used. + This engine defines engine specific options. netsplice Like net, but uses splice/vmsplice to map data and send/receive. + This engine defines engine specific options. cpuio Doesn't transfer any data, but burns CPU cycles according to the cpuload= and @@ -636,6 +627,7 @@ iodepth_low=int The low water mark indicating when to start filling direct=bool If value is true, use non-buffered io. This is usually O_DIRECT. Note that ZFS on Solaris doesn't support direct io. + On Windows the synchronous ioengines don't support direct io. buffered=bool If value is true, use buffered io. This is the opposite of the 'direct' option. Defaults to true. @@ -653,7 +645,7 @@ fsync=int If writing to a file, issue a sync of the dirty data fdatasync=int Like fsync= but uses fdatasync() to only sync data and not metadata blocks. - In FreeBSD there is no fdatasync(), this falls back to + In FreeBSD and Windows there is no fdatasync(), this falls back to using fsync() sync_file_range=str:val Use sync_file_range() for every 'val' number of @@ -981,7 +973,7 @@ verify_fatal=bool Normally fio will keep checking the entire contents verify_dump=bool 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. + corruption occurred. Off by default. verify_async=int Fio will normally verify IO inline from the submitting thread. This option takes an integer describing how many @@ -1110,6 +1102,18 @@ write_lat_log=str Same as write_bw_log, except that this option stores io write_bw_log=str If given, write an IOPS log of the jobs in this job file. See write_bw_log. +write_iops_log=str Same as write_bw_log, 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. + +log_avg_msec=int 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. + lockmem=int Pin down the specified amount of memory with mlock(2). Can potentially be used instead of removing memory or booting with less memory to simulate a smaller amount of memory. @@ -1179,7 +1183,7 @@ gtod_cpu=int Sometimes it's cheaper to dedicate a single thread of uses. Fio will manually clear it from the CPU mask of other jobs. -continue_on_error=bool Normally fio will exit the job on the first observed +continue_on_error=str Normally fio will exit the job on the first observed failure. If this option is set, fio will continue the job when there is a 'non-fatal error' (EIO or EILSEQ) until the runtime is exceeded or the I/O size specified is completed. If this @@ -1188,6 +1192,24 @@ continue_on_error=bool Normally fio will exit the job on the first observed given in the stats is the first error that was hit during the run. + The allowed values are: + + none Exit on any IO or verify errors. + + read Continue on read errors, exit on all others. + + write Continue on write errors, exit on all others. + + io Continue on any IO error, exit on all others. + + verify Continue on verify errors, exit on all others. + + all Continue on all errors. + + 0 Backward-compatible alias for 'none'. + + 1 Backward-compatible alias for 'all'. + cgroup=str 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 @@ -1210,6 +1232,64 @@ uid=int Instead of running as the invoking user, set the user ID to gid=int Set group ID, see uid. +flow_id=int The ID of the flow. If not specified, it defaults to being a + global flow. See flow. + +flow=int Weight in token-based flow control. If this value is used, then + there is a 'flow counter' which is used to regulate the + proportion of activity between two or more jobs. fio attempts + to keep this flow counter near zero. The 'flow' 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 flow=8 and another job has flow=-1, then there + will be a roughly 1:8 ratio in how much one runs vs the other. + +flow_watermark=int 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. + +flow_sleep=int The period of time, in microseconds, to wait after the flow + watermark has been exceeded before retrying operations + +In addition, there are some parameters which 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, they must come after the ioengine +that defines them is selected. + +[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). + +[netsplice] hostname=str +[net] hostname=str 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. + +[netsplice] port=int +[net] port=int The TCP or UDP port to bind to or connect to. + +[netsplice] protocol=str +[netsplice] proto=str +[net] protocol=str +[net] proto=str The network protocol to use. Accepted values are: + + tcp Transmission control protocol + udp Unreliable datagram protocol + unix UNIX domain socket + + 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. + +[net] 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. + + 6.0 Interpreting the output ---------------------------