X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=0c604a6adb619ac3ed1285185c91b7b141902164;hp=ce3585a43a6660bdda2e45000bea7e9a9825c6ec;hb=0777612739319296ee25047c1bdb56207187c463;hpb=2c3a915064410ac3d8cdd936d835a00b802a495f diff --git a/fio.1 b/fio.1 index ce3585a4..0c604a6a 100644 --- a/fio.1 +++ b/fio.1 @@ -68,12 +68,11 @@ available ioengines. Convert \fIjobfile\fR to a set of command\-line options. .TP .BI \-\-readonly -Turn on safety read\-only checks, preventing writes. The \fB\-\-readonly\fR +Turn on safety read\-only checks, preventing writes and trims. The \fB\-\-readonly\fR option is an extra safety guard to prevent users from accidentally starting -a write workload when that is not desired. Fio will only write if -`rw=write/randwrite/rw/randrw' is given. This extra safety net can be used -as an extra precaution as \fB\-\-readonly\fR will also enable a write check in -the I/O engine core to prevent writes due to unknown user space bug(s). +a write or trim workload when that is not desired. Fio will only modify the +device under test if `rw=write/randwrite/rw/randrw/trim/randtrim/trimwrite' +is given. This safety net can be used as an extra precaution. .TP .BI \-\-eta \fR=\fPwhen Specifies when real\-time ETA estimate should be printed. \fIwhen\fR may @@ -169,7 +168,8 @@ Set this \fIcommand\fR as local trigger. Set this \fIcommand\fR as remote trigger. .TP .BI \-\-aux\-path \fR=\fPpath -Use this \fIpath\fR for fio state generated files. +Use the directory specified by \fIpath\fP for generated state files instead +of the current working directory. .SH "JOB FILE FORMAT" Any parameters following the options will be assumed to be job files, unless they match a job file parameter. Multiple job files can be listed and each job @@ -524,12 +524,15 @@ separating the names with a ':' character. These directories will be assigned equally distributed to job clones created by \fBnumjobs\fR as long as they are using generated filenames. If specific \fBfilename\fR(s) are set fio will use the first listed directory, and thereby matching the -\fBfilename\fR semantic which generates a file each clone if not specified, but -let all clones use the same if set. +\fBfilename\fR semantic (which generates a file for each clone if not +specified, but lets all clones use the same file if set). .RS .P -See the \fBfilename\fR option for information on how to escape ':' and '\' +See the \fBfilename\fR option for information on how to escape ':' and '\\' characters within the directory path itself. +.P +Note: To control the directory fio will use for internal state files +use \fB\-\-aux\-path\fR. .RE .TP .BI filename \fR=\fPstr @@ -546,13 +549,13 @@ by this option will be \fBsize\fR divided by number of files unless an explicit size is specified by \fBfilesize\fR. .RS .P -Each colon and backslash in the wanted path must be escaped with a '\' +Each colon and backslash in the wanted path must be escaped with a '\\' character. For instance, if the path is `/dev/dsk/foo@3,0:c' then you would use `filename=/dev/dsk/foo@3,0\\:c' and if the path is -`F:\\\\filename' then you would use `filename=F\\:\\\\filename'. +`F:\\filename' then you would use `filename=F\\:\\\\filename'. .P -On Windows, disk devices are accessed as `\\\\\\\\.\\\\PhysicalDrive0' for -the first device, `\\\\\\\\.\\\\PhysicalDrive1' for the second etc. +On Windows, disk devices are accessed as `\\\\.\\PhysicalDrive0' for +the first device, `\\\\.\\PhysicalDrive1' for the second etc. Note: Windows and FreeBSD prevent write access to areas of the disk containing in\-use data (e.g. filesystems). .P @@ -758,7 +761,7 @@ Sequential reads. Sequential writes. .TP .B trim -Sequential trims (Linux block devices only). +Sequential trims (Linux block devices and SCSI character devices only). .TP .B randread Random reads. @@ -767,7 +770,7 @@ Random reads. Random writes. .TP .B randtrim -Random trims (Linux block devices only). +Random trims (Linux block devices and SCSI character devices only). .TP .B rw,readwrite Sequential mixed reads and writes. @@ -1121,7 +1124,9 @@ at past I/O history. This means that some blocks may not be read or written, and that some blocks may be read/written more than once. If this option is used with \fBverify\fR and multiple blocksizes (via \fBbsrange\fR), only intact blocks are verified, i.e., partially\-overwritten blocks are -ignored. +ignored. With an async I/O engine and an I/O depth > 1, it is possible for +the same block to be overwritten, which can cause verification errors. Either +do not use norandommap in this case, or also use the lfsr random generator. .TP .BI softrandommap \fR=\fPbool See \fBnorandommap\fR. If fio runs with the random block map enabled and @@ -1227,7 +1232,7 @@ If you want a workload that has 50% 2k reads and 50% 4k reads, while having 90% 4k writes and 10% 8k writes, you would specify: .RS .P -bssplit=2k/50:4k/50,4k/90,8k/10 +bssplit=2k/50:4k/50,4k/90:8k/10 .RE .P Fio supports defining up to 64 different weights for each data direction. @@ -1523,7 +1528,8 @@ SCSI generic sg v3 I/O. May either be synchronous using the SG_IO ioctl, or if the target is an sg character device we use \fBread\fR\|(2) and \fBwrite\fR\|(2) for asynchronous I/O. Requires \fBfilename\fR option to specify either block or -character devices. The sg engine includes engine specific options. +character devices. This engine supports trim operations. The +sg engine includes engine specific options. .TP .B null Doesn't transfer any data, just pretends to. This is mainly used to @@ -2055,6 +2061,11 @@ to replay a workload captured by blktrace. See replay, the file needs to be turned into a blkparse binary data file first (`blkparse \-o /dev/null \-d file_for_fio.bin'). .TP +.BI read_iolog_chunked \fR=\fPbool +Determines how iolog is read. If false (default) entire \fBread_iolog\fR will +be read at once. If selected true, input from iolog will be read gradually. +Useful when iolog is very large, or it is generated. +.TP .BI replay_no_stall \fR=\fPbool When replaying I/O with \fBread_iolog\fR the default behavior is to attempt to respect the timestamps within the log and replay them with the @@ -2371,6 +2382,11 @@ that the written data is also correctly read back. If the data direction given is a read or random read, fio will assume that it should verify a previously written file. If the data direction includes any form of write, the verify will be of the newly written data. +.P +To avoid false verification errors, do not use the norandommap option when +verifying data with async I/O engines and I/O depths > 1. Or use the +norandommap and the lfsr random generator together to avoid writing to the +same offset with muliple outstanding I/Os. .RE .TP .BI verify_offset \fR=\fPint @@ -2596,9 +2612,11 @@ within the file. .TP .BI write_iops_log \fR=\fPstr Same as \fBwrite_bw_log\fR, but writes an IOPS file (e.g. -`name_iops.x.log') instead. See \fBwrite_bw_log\fR for -details about the filename format and the \fBLOG FILE FORMATS\fR section for how data -is structured within the file. +`name_iops.x.log`) instead. Because fio defaults to individual +I/O logging, the value entry in the IOPS log will be 1 unless windowed +logging (see \fBlog_avg_msec\fR) has been enabled. See +\fBwrite_bw_log\fR for details about the filename format and \fBLOG +FILE FORMATS\fR for how data is structured within the file. .TP .BI log_avg_msec \fR=\fPint By default, fio will log an entry in the iops, latency, or bw log for every @@ -3515,17 +3533,16 @@ I/O is a WRITE I/O is a TRIM .RE .P -The entry's `block size' is always in bytes. The `offset' is the offset, in bytes, -from the start of the file, for that particular I/O. The logging of the offset can be +The entry's `block size' is always in bytes. The `offset' is the position in bytes +from the start of the file for that particular I/O. The logging of the offset can be toggled with \fBlog_offset\fR. .P -Fio defaults to logging every individual I/O. When IOPS are logged for individual -I/Os the `value' entry will always be 1. If windowed logging is enabled through -\fBlog_avg_msec\fR, fio logs the average values over the specified period of time. -If windowed logging is enabled and \fBlog_max_value\fR is set, then fio logs -maximum values in that window instead of averages. Since `data direction', `block size' -and `offset' are per\-I/O values, if windowed logging is enabled they -aren't applicable and will be 0. +Fio defaults to logging every individual I/O but when windowed logging is set +through \fBlog_avg_msec\fR, either the average (by default) or the maximum +(\fBlog_max_value\fR is set) `value' seen over the specified period of time +is recorded. Each `data direction' seen within the window period will aggregate +its values in a separate row. Further, when using windowed logging the `block +size' and `offset' entries will always contain 0. .SH CLIENT / SERVER Normally fio is invoked as a stand\-alone application on the machine where the I/O workload should be generated. However, the backend and frontend of fio can