Accepted values are:
**none**
- The :option:`zonerange`, :option:`zonesize` and
- :option:`zoneskip` parameters are ignored.
+ The :option:`zonerange`, :option:`zonesize`,
+ :option `zonecapacity` and option:`zoneskip`
+ parameters are ignored.
**strided**
I/O happens in a single zone until
:option:`zonesize` bytes have been transferred.
After that number of bytes has been
transferred processing of the next zone
- starts.
+ starts. :option `zonecapacity` is ignored.
**zbd**
Zoned block device mode. I/O happens
sequentially in each zone, even if random I/O
For :option:`zonemode` =zbd, this is the size of a single zone. The
:option:`zonerange` parameter is ignored in this mode.
+
+.. option:: zonecapacity=int
+
+ For :option:`zonemode` =zbd, this defines the capacity of a single zone,
+ which is the accessible area starting from the zone start address.
+ This parameter only applies when using :option:`zonemode` =zbd in
+ combination with regular block devices. If not specified it defaults to
+ the zone size. If the target device is a zoned block device, the zone
+ capacity is obtained from the device information and this option is
+ ignored.
+
.. option:: zoneskip=int
For :option:`zonemode` =strided, the number of bytes to skip after
This will be ignored if :option:`pre_read` is also specified for the
same job.
-.. option:: sync=bool
+.. option:: sync=str
+
+ Whether, and what type, of synchronous I/O to use for writes. The allowed
+ values are:
+
+ **none**
+ Do not use synchronous IO, the default.
+
+ **0**
+ Same as **none**.
+
+ **sync**
+ Use synchronous file IO. For the majority of I/O engines,
+ this means using O_SYNC.
+
+ **1**
+ Same as **sync**.
+
+ **dsync**
+ Use synchronous data IO. For the majority of I/O engines,
+ this means using O_DSYNC.
- Use synchronous I/O for buffered writes. For the majority of I/O engines,
- this means using O_SYNC. Default: false.
.. option:: iomem=str, mem=str
single CPU at the desired rate. A job never finishes unless there is
at least one non-cpuio job.
- **guasi**
- The GUASI I/O engine is the Generic Userspace Asynchronous Syscall
- Interface approach to async I/O. See
-
- http://www.xmailserver.org/guasi-lib.html
-
- for more info on GUASI.
-
**rdma**
The RDMA I/O engine supports both RDMA memory semantics
(RDMA_WRITE/RDMA_READ) and channel semantics (Send/Recv) for the
set `filesize` so that all the accounting still occurs, but no
actual I/O will be done other than creating the file.
+ **filestat**
+ Simply do stat() and do no I/O to the file. You need to set 'filesize'
+ and 'nrfiles', so that files will be created.
+ This engine is to measure file lookup and meta data access.
+
**libpmem**
Read and write using mmap I/O to a file on a filesystem
mounted with DAX on a persistent memory device through the PMDK
with the caveat that when used on the command line, they must come after the
:option:`ioengine` that defines them is selected.
-.. option:: hipri : [io_uring]
+.. option:: cmdprio_percentage=int : [io_uring] [libaio]
- If this option is set, fio will attempt to use polled IO completions.
- Normal IO completions generate interrupts to signal the completion of
- IO, polled completions do not. Hence they are require active reaping
- by the application. The benefits are more efficient IO for high IOPS
- scenarios, and lower latencies for low queue depth IO.
+ Set the percentage of I/O that will be issued with higher priority by setting
+ the priority bit. Non-read I/O is likely unaffected by ``cmdprio_percentage``.
+ This option cannot be used with the `prio` or `prioclass` options. For this
+ option to set the priority bit properly, NCQ priority must be supported and
+ enabled and :option:`direct`\=1 option must be used. fio must also be run as
+ the root user.
.. option:: fixedbufs : [io_uring]
- If fio is asked to do direct IO, then Linux will map pages for each
- IO call, and release them when IO is done. If this option is set, the
- pages are pre-mapped before IO is started. This eliminates the need to
- map and release for each IO. This is more efficient, and reduces the
- IO latency as well.
+ If fio is asked to do direct IO, then Linux will map pages for each
+ IO call, and release them when IO is done. If this option is set, the
+ pages are pre-mapped before IO is started. This eliminates the need to
+ map and release for each IO. This is more efficient, and reduces the
+ IO latency as well.
+
+.. option:: hipri : [io_uring]
+
+ If this option is set, fio will attempt to use polled IO completions.
+ Normal IO completions generate interrupts to signal the completion of
+ IO, polled completions do not. Hence they are require active reaping
+ by the application. The benefits are more efficient IO for high IOPS
+ scenarios, and lower latencies for low queue depth IO.
.. option:: registerfiles : [io_uring]
When hipri is set this determines the probability of a pvsync2 I/O being high
priority. The default is 100%.
+.. option:: nowait : [pvsync2] [libaio] [io_uring]
+
+ By default if a request cannot be executed immediately (e.g. resource starvation,
+ waiting on locks) it is queued and the initiating process will be blocked until
+ the required resource becomes free.
+
+ This option sets the RWF_NOWAIT flag (supported from the 4.14 Linux kernel) and
+ the call will return instantly with EAGAIN or a partial result rather than waiting.
+
+ It is useful to also use ignore_error=EAGAIN when using this option.
+
+ Note: glibc 2.27, 2.28 have a bug in syscall wrappers preadv2, pwritev2.
+ They return EOPNOTSUP instead of EAGAIN.
+
+ For cached I/O, using this option usually means a request operates only with
+ cached data. Currently the RWF_NOWAIT flag does not supported for cached write.
+
+ For direct I/O, requests will only succeed if cache invalidation isn't required,
+ file blocks are fully allocated and the disk request could be issued immediately.
+
.. option:: cpuload=int : [cpuio]
Attempt to use the specified percentage of CPU cycles. This is a mandatory
multiple paths exist between the client and the server or in certain loopback
configurations.
+.. option:: stat_type=str : [filestat]
+
+ Specify stat system call type to measure lookup/getattr performance.
+ Default is **stat** for :manpage:`stat(2)`.
+
.. option:: readfua=bool : [sg]
With readfua option set to 1, read operations include
can increase latencies. The benefit is that fio can manage submission rates
independently of the device completion rates. This avoids skewed latency
reporting if I/O gets backed up on the device side (the coordinated omission
- problem).
+ problem). Note that this option cannot reliably be used with async IO
+ engines.
I/O rate
defaults to 100.0, meaning that all I/Os must be equal or below to the value
set by :option:`latency_target`.
+.. option:: latency_run=bool
+
+ Used with :option:`latency_target`. If false (default), fio will find
+ the highest queue depth that meets :option:`latency_target` and exit. If
+ true, fio will continue running and try to meet :option:`latency_target`
+ by adjusting queue depth.
+
.. option:: max_latency=time
If set, fio will exit the job with an ETIMEDOUT error if it exceeds this
character. See the :option:`filename` option for information on how to
escape ':' characters within the file names. These files will
be sequentially assigned to job clones created by :option:`numjobs`.
+ '-' is a reserved name, meaning read from stdin, notably if
+ :option:`filename` is set to '-' which means stdin as well, then
+ this flag can't be set to '-'.
.. option:: read_iolog_chunked=bool
Set the I/O priority value of this job. Linux limits us to a positive value
between 0 and 7, with 0 being the highest. See man
:manpage:`ionice(1)`. Refer to an appropriate manpage for other operating
- systems since meaning of priority may differ.
+ systems since meaning of priority may differ. For per-command priority
+ setting, see I/O engine specific `cmdprio_percentage` and `hipri_percentage`
+ options.
.. option:: prioclass=int
- Set the I/O priority class. See man :manpage:`ionice(1)`.
+ Set the I/O priority class. See man :manpage:`ionice(1)`. For per-command
+ priority setting, see I/O engine specific `cmdprio_percentage` and
+ `hipri_percentage` options.
.. option:: cpus_allowed=str
``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.
-.. option:: 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.
-
.. option:: flow_sleep=int
- The period of time, in microseconds, to wait after the flow watermark has
- been exceeded before retrying operations.
+ The period of time, in microseconds, to wait after the flow counter
+ has exceeded its proportion before retrying operations.
.. option:: stonewall, wait_for_previous
Disable measurements of throughput/bandwidth numbers. See
:option:`disable_lat`.
+.. option:: slat_percentiles=bool
+
+ Report submission latency percentiles. Submission latency is not recorded
+ for synchronous ioengines.
+
.. option:: clat_percentiles=bool
- Enable the reporting of percentiles of completion latencies. This
- option is mutually exclusive with :option:`lat_percentiles`.
+ Report completion latency percentiles.
.. option:: lat_percentiles=bool
- Enable the reporting of percentiles of I/O latencies. This is similar
- to :option:`clat_percentiles`, except that this includes the
- submission latency. This option is mutually exclusive with
- :option:`clat_percentiles`.
+ Report total latency percentiles. Total latency is the sum of submission
+ latency and completion latency.
.. option:: percentile_list=float_list
- Overwrite the default list of percentiles for completion latencies and
- the block error histogram. Each number is a floating number in the
- range (0,100], and the maximum length of the list is 20. Use ``:`` to
- separate the numbers, and list the numbers in ascending order. For
+ Overwrite the default list of percentiles for latencies and the block error
+ histogram. Each number is a floating point number in the range (0,100], and
+ 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.
+ latency durations below which 99.5% and 99.9% of the observed latencies fell,
+ respectively.
.. option:: significant_figures=int
and IOPS. The logs share a common format, which looks like this:
*time* (`msec`), *value*, *data direction*, *block size* (`bytes`),
- *offset* (`bytes`)
+ *offset* (`bytes`), *command priority*
*Time* for the log entry is always in milliseconds. The *value* logged depends
on the type of log, it will be one of the following:
from the start of the file for that particular I/O. The logging of the offset can be
toggled with :option:`log_offset`.
+*Command priority* is 0 for normal priority and 1 for high priority. This is controlled
+by the ioengine specific :option:`cmdprio_percentage`.
+
Fio defaults to logging every individual I/O but when windowed logging is set
through :option:`log_avg_msec`, either the average (by default) or the maximum
(:option:`log_max_value` is set) *value* seen over the specified period of time
projects / fio.git / blobdiff