.TP
.BI \-\-debug \fR=\fPtype
Enable verbose tracing of various fio actions. May be `all' for all types
-or individual types seperated by a comma (eg --debug=io,file). `help' will
+or individual types seperated by a comma (eg \-\-debug=io,file). `help' will
list all available tracing options.
.TP
.B \-\-help
.TP
.I int
SI integer: a whole number, possibly containing a suffix denoting the base unit
-of the value. Accepted suffixes are `k', 'M' and 'G', denoting kilo (1024),
-mega (1024*1024) and giga (1024*1024*1024) respectively. If prefixed with '0x',
-the value is assumed to be base 16 (hexadecimal).
+of the value. Accepted suffixes are `k', 'M', 'G', 'T', and 'P', denoting
+kilo (1024), mega (1024^2), giga (1024^3), tera (1024^4), and peta (1024^5)
+respectively. The suffix is not case sensitive. If prefixed with '0x', the
+value is assumed to be base 16 (hexadecimal).
.TP
.I bool
Boolean: a true or false value. `0' denotes false, `1' denotes true.
reserved name, meaning stdin or stdout, depending on the read/write direction
set.
.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
+result consistent. This is usual for emulating real workloads that share files.
+The lock modes are:
+.RS
+.RS
+.TP
+.B none
+No locking. This is the default.
+.TP
+.B exclusive
+Only one thread or process may do IO at the time, excluding all others.
+.TP
+.B readwrite
+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
Recursively open any files below directory \fIstr\fR.
.TP
`:\fIint\fR' to the pattern type. The default is 1.
.RE
.TP
+.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.
+.TP
.BI randrepeat \fR=\fPbool
Seed the random number generator in a predictable way so results are repeatable
across runs. Default: true.
Unless \fBnr_files\fR and \fBfilesize\fR options are given, this amount will be
divided between the available files for the job.
.TP
+.BI fill_device \fR=\fPbool
+Sets size to something really large and waits for ENOSPC (no space left on
+device) as the terminating condition. Only makes sense with sequential write.
+For a read workload, the mount point will be filled first then IO started on
+the result.
+.TP
.BI filesize \fR=\fPirange
Individual file sizes. May be a range, in which case \fBfio\fR will select sizes
for files at random within the given range, limited to \fBsize\fR in total (if
.BI iodepth_batch \fR=\fPint
Number of I/Os to submit at once. Default: \fBiodepth\fR.
.TP
+.BI iodepth_batch_complete \fR=\fPint
+This defines how many pieces of IO to retrieve at once. It defaults to 1 which
+ means that we'll ask for a minimum of 1 IO in the retrieval process from the
+kernel. The IO retrieval will go on until we hit the limit set by
+\fBiodepth_low\fR. If this variable is set to 0, then fio will always check for
+completed events before queuing more IO. This helps reduce IO latency, at the
+cost of more retrieval system calls.
+.TP
.BI iodepth_low \fR=\fPint
Low watermark indicating when to start filling the queue again. Default:
\fBiodepth\fR.
How many I/Os to perform before issuing an \fBfsync\fR\|(2) of dirty data. If
0, don't sync. Default: 0.
.TP
+.BI fdatasync \fR=\fPint
+Like \fBfsync\fR, but uses \fBfdatasync\fR\|(2) instead to only sync the
+data parts of the file. Default: 0.
+.TP
.BI overwrite \fR=\fPbool
If writing, setup the file first and do overwrites. Default: false.
.TP
this parameter is given, a new offset will be chosen without looking at past
I/O history. This parameter is mutually exclusive with \fBverify\fR.
.TP
+.B softrandommap
+See \fBnorandommap\fR. If fio runs with the random block map enabled and it
+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 nice \fR=\fPint
Run job with given nice value. See \fInice\fR\|(2).
.TP
The amount of memory allocated is the maximum allowed \fBblocksize\fR for the
job multiplied by \fBiodepth\fR. For \fBshmhuge\fR or \fBmmaphuge\fR to work,
the system must have free huge pages allocated. \fBmmaphuge\fR also needs to
-have hugetlbfs mounted, and \fIfile\fR must point there.
+have hugetlbfs mounted, and \fIfile\fR must point there. At least on Linux,
+huge pages must be manually allocated. See \fB/proc/sys/vm/nr_hugehages\fR
+and the documentation for that. Normally you just need to echo an appropriate
+number, eg echoing 8 will ensure that the OS has 8 huge pages ready for
+use.
.RE
.TP
+.BI iomem_align \fR=\fPint
+This indiciates the memory alignment of the IO memory buffers. Note that the
+given alignment is applied to the first IO unit buffer, if using \fBiodepth\fR
+the alignment of the following buffers are given by the \fBbs\fR used. In
+other words, if using a \fBbs\fR that is a multiple of the page sized in the
+system, all buffers will be aligned to this value. If using a \fBbs\fR that
+is not page aligned, the alignment of subsequent IO memory buffers is the
+sum of the \fBiomem_align\fR and \fBbs\fR used.
+.TP
.BI hugepage\-size \fR=\fPint
Defines the size of a huge page. Must be at least equal to the system setting.
-Should be a multiple of 1MiB. Default: 4MiB.
+Should be a multiple of 1MB. Default: 4MB.
.TP
.B exitall
Terminate all jobs when one finishes. Default: wait for each job to finish.
.BI pre_read \fR=\fPbool
If this is given, files will be pre-read into memory before starting the given
IO operation. This will also clear the \fR \fBinvalidate\fR flag, since it is
-pointless to pre-read and then drop the cache.
+pointless to pre-read and then drop the cache. This will only work for IO
+engines that are seekable, since they allow you to read the same data
+multiple times. Thus it will not work on eg network or splice IO.
.TP
.BI unlink \fR=\fPbool
Unlink job files when done. Default: false.
.RS
.RS
.TP
-.B md5 crc16 crc32 crc64 crc7 sha256 sha512
+.B md5 crc16 crc32 crc32c crc32c-intel crc64 crc7 sha256 sha512 sha1
Store appropriate checksum in the header of each block.
.TP
.B meta
block number is verified.
.TP
.B pattern
-Fill I/O buffers with a specific pattern that is used to verify. The pattern is
-specified by appending `:\fIint\fR' to the parameter. \fIint\fR cannot be larger
-than 32-bits.
+Fill I/O buffers with a specific pattern that is used to verify. If the pattern
+is < 4bytes, it can either be a decimal or a hexadecimal number. If the pattern
+is > 4bytes, currently, it can only be a hexadecimal pattern starting with
+either "0x" or "0X".
.TP
.B null
Pretend to verify. Used for testing internals.
.RE
+
+This option can be used for repeated burn-in tests of a system to make sure
+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.
.RE
.TP
.BI verify_sort \fR=\fPbool
If true, exit the job on the first observed verification failure. Default:
false.
.TP
+.BI verify_async \fR=\fPint
+Fio will normally verify IO inline from the submitting thread. This option
+takes an integer describing how many async offload threads to create for IO
+verification instead, causing fio to offload the duty of verifying IO contents
+to one or more separate threads. If using this offload option, even sync IO
+engines can benefit from using an \fBiodepth\fR setting higher than 1, as it
+allows them to have IO in flight while verifies are running.
+.TP
+.BI verify_async_cpus \fR=\fPstr
+Tell fio to set the given CPU affinity on the async IO verification threads.
+See \fBcpus_allowed\fP for the format used.
+.TP
.B stonewall
Wait for preceeding jobs in the job file to exit before starting this one.
\fBstonewall\fR implies \fBnew_group\fR.
entering the kernel with a gettimeofday() call. The CPU set aside for doing
these time calls will be excluded from other uses. Fio will manually clear it
from the CPU mask of other jobs.
+.TP
+.BI cgroup \fR=\fPstr
+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 mounted, you can do so with:
+
+# mount -t cgroup -o blkio none /cgroup
+.TP
+.BI cgroup_weight \fR=\fPint
+Set the weight of the cgroup to this value. See the documentation that comes
+with the kernel, allowed values are in the range of 100..1000.
.SH OUTPUT
While running, \fBfio\fR will display the status of the created jobs. For
example:
.P
Read status:
.RS
-.B KiB I/O, bandwidth \fR(KiB/s)\fP, runtime \fR(ms)\fP
+.B KB I/O, bandwidth \fR(KB/s)\fP, runtime \fR(ms)\fP
.P
Submission latency:
.RS
.P
Write status:
.RS
-.B KiB I/O, bandwidth \fR(KiB/s)\fP, runtime \fR(ms)\fP
+.B KB I/O, bandwidth \fR(KB/s)\fP, runtime \fR(ms)\fP
.P
Submission latency:
.RS
projects / fio.git / blobdiff