thread/process.
.. option:: ignore_zone_limits=bool
+
If this option is used, fio will ignore the maximum number of open
zones limit of the zoned block device in use, thus allowing the
option :option:`max_open_zones` value to be larger than the device
range of possible random values.
Defaults are: random for **pareto** and **zipf**, and 0.5 for **normal**.
If you wanted to use **zipf** with a `theta` of 1.2 centered on 1/4 of allowed value range,
- you would use ``random_distibution=zipf:1.2:0.25``.
+ you would use ``random_distribution=zipf:1.2:0.25``.
For a **zoned** distribution, fio supports specifying percentages of I/O
access that should fall within what range of the file or device. For
Note that size needs to be explicitly provided and only 1 file per
job is supported
+.. option:: dedupe_global=bool
+
+ This controls whether the deduplication buffers will be shared amongst
+ all jobs that have this option set. The buffers are spread evenly between
+ participating jobs.
+
.. option:: invalidate=bool
Invalidate the buffer/page cache parts of the files to be used prior to
**mmaphuge** to work, the system must have free huge pages allocated. This
can normally be checked and set by reading/writing
:file:`/proc/sys/vm/nr_hugepages` on a Linux system. Fio assumes a huge page
- is 4MiB in size. So to calculate the number of huge pages you need for a
- given job file, add up the I/O depth of all jobs (normally one unless
- :option:`iodepth` is used) and multiply by the maximum bs set. Then divide
- that number by the huge page size. You can see the size of the huge pages in
- :file:`/proc/meminfo`. If no huge pages are allocated by having a non-zero
- number in `nr_hugepages`, using **mmaphuge** or **shmhuge** will fail. Also
- see :option:`hugepage-size`.
+ is 2 or 4MiB in size depending on the platform. So to calculate the
+ number of huge pages you need for a given job file, add up the I/O
+ depth of all jobs (normally one unless :option:`iodepth` is used) and
+ multiply by the maximum bs set. Then divide that number by the huge
+ page size. You can see the size of the huge pages in
+ :file:`/proc/meminfo`. If no huge pages are allocated by having a
+ non-zero number in `nr_hugepages`, using **mmaphuge** or **shmhuge**
+ will fail. Also see :option:`hugepage-size`.
**mmaphuge** also needs to have hugetlbfs mounted and the file location
should point there. So if it's mounted in :file:`/huge`, you would use
.. option:: hugepage-size=int
- Defines the size of a huge page. Must at least be equal to the system
- setting, see :file:`/proc/meminfo`. Defaults to 4MiB. Should probably
- always be a multiple of megabytes, so using ``hugepage-size=Xm`` is the
- preferred way to set this to avoid setting a non-pow-2 bad value.
+ Defines the size of a huge page. Must at least be equal to the system
+ setting, see :file:`/proc/meminfo` and
+ :file:`/sys/kernel/mm/hugepages/`. Defaults to 2 or 4MiB depending on
+ the platform. Should probably always be a multiple of megabytes, so
+ using ``hugepage-size=Xm`` is the preferred way to set this to avoid
+ setting a non-pow-2 bad value.
.. option:: lockmem=int
for both direct and buffered IO.
This engine defines engine specific options.
+ **io_uring_cmd**
+ Fast Linux native asynchronous I/O for pass through commands.
+ This engine defines engine specific options.
+
**libaio**
Linux native asynchronous I/O. Note that Linux may only support
queued behavior with non-buffered I/O (set ``direct=1`` or
**exec**
Execute 3rd party tools. Could be used to perform monitoring during jobs runtime.
+ **xnvme**
+ I/O engine using the xNVMe C API, for NVMe devices. The xnvme engine provides
+ flexibility to access GNU/Linux Kernel NVMe driver via libaio, IOCTLs, io_uring,
+ the SPDK NVMe driver, or your own custom NVMe driver. The xnvme engine includes
+ engine specific options. (See https://xnvme.io).
+
I/O engine specific parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
values for trim IOs are ignored. This option is mutually exclusive with
the :option:`cmdprio_percentage` option.
-.. option:: fixedbufs : [io_uring]
+.. option:: fixedbufs : [io_uring] [io_uring_cmd]
- 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]
+.. option:: nonvectored : [io_uring] [io_uring_cmd]
- 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.
+ With this option, fio will use non-vectored read/write commands, where
+ address must contain the address directly. Default is -1.
-.. option:: registerfiles : [io_uring]
+.. option:: force_async=int : [io_uring] [io_uring_cmd]
+
+ Normal operation for io_uring is to try and issue an sqe as
+ non-blocking first, and if that fails, execute it in an async manner.
+ With this option set to N, then every N request fio will ask sqe to
+ be issued in an async manner. Default is 0.
+
+.. option:: registerfiles : [io_uring] [io_uring_cmd]
With this option, fio registers the set of files being used with the
kernel. This avoids the overhead of managing file counts in the kernel,
making the submission and completion part more lightweight. Required
for the below :option:`sqthread_poll` option.
-.. option:: sqthread_poll : [io_uring]
+.. option:: sqthread_poll : [io_uring] [io_uring_cmd] [xnvme]
Normally fio will submit IO by issuing a system call to notify the
kernel of available items in the SQ ring. If this option is set, the
This frees up cycles for fio, at the cost of using more CPU in the
system.
-.. option:: sqthread_poll_cpu : [io_uring]
+.. option:: sqthread_poll_cpu : [io_uring] [io_uring_cmd]
When :option:`sqthread_poll` is set, this option provides a way to
define which CPU should be used for the polling thread.
+.. option:: cmd_type=str : [io_uring_cmd]
+
+ Specifies the type of uring passthrough command to be used. Supported
+ value is nvme. Default is nvme.
+
+.. option:: hipri
+
+ [io_uring] [io_uring_cmd] [xnvme]
+
+ 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.
+
+ [pvsync2]
+
+ Set RWF_HIPRI on I/O, indicating to the kernel that it's of higher priority
+ than normal.
+
+ [sg]
+
+ If this option is set, fio will attempt to use polled IO completions.
+ This will have a similar effect as (io_uring)hipri. Only SCSI READ and
+ WRITE commands will have the SGV4_FLAG_HIPRI set (not UNMAP (trim) nor
+ VERIFY). Older versions of the Linux sg driver that do not support
+ hipri will simply ignore this flag and do normal IO. The Linux SCSI
+ Low Level Driver (LLD) that "owns" the device also needs to support
+ hipri (also known as iopoll and mq_poll). The MegaRAID driver is an
+ example of a SCSI LLD. Default: clear (0) which does normal
+ (interrupted based) IO.
+
.. option:: userspace_reap : [libaio]
Normally, with the libaio engine in use, fio will use the
reap events. The reaping mode is only enabled when polling for a minimum of
0 events (e.g. when :option:`iodepth_batch_complete` `=0`).
-.. option:: hipri : [pvsync2]
-
- Set RWF_HIPRI on I/O, indicating to the kernel that it's of higher priority
- than normal.
-
.. option:: hipri_percentage : [pvsync2]
When hipri is set this determines the probability of a pvsync2 I/O being high
the full *type.id* string. If no type. prefix is given, fio will add
'client.' by default.
+.. option:: conf=str : [rados]
+
+ Specifies the configuration path of ceph cluster, so conf file does not
+ have to be /etc/ceph/ceph.conf.
+
.. option:: busy_poll=bool : [rbd,rados]
Poll store instead of waiting for completion. Usually this provides better
Specify the label or UUID of the DAOS container to open.
-.. option:: chunk_size=int : [dfs]
+.. option:: chunk_size=int
+
+ [dfs]
Specificy a different chunk size (in bytes) for the dfs file.
Use DAOS container's chunk size by default.
+ [libhdfs]
+
+ The size of the chunk to use for each file.
+
.. option:: object_class=str : [dfs]
Specificy a different object class for the dfs file.
libhdfs will create chunk in this HDFS directory.
-.. option:: chunk_size : [libhdfs]
-
- The size of the chunk to use for each file.
-
.. option:: verb=str : [rdma]
The RDMA verb to use on this side of the RDMA ioengine connection. Valid
a valid stream identifier) fio will open a stream and then close it when done. Default
is 0.
-.. option:: hipri : [sg]
-
- If this option is set, fio will attempt to use polled IO completions.
- This will have a similar effect as (io_uring)hipri. Only SCSI READ and
- WRITE commands will have the SGV4_FLAG_HIPRI set (not UNMAP (trim) nor
- VERIFY). Older versions of the Linux sg driver that do not support
- hipri will simply ignore this flag and do normal IO. The Linux SCSI
- Low Level Driver (LLD) that "owns" the device also needs to support
- hipri (also known as iopoll and mq_poll). The MegaRAID driver is an
- example of a SCSI LLD. Default: clear (0) which does normal
- (interrupted based) IO.
-
.. option:: http_host=str : [http]
Hostname to connect to. For S3, this could be the bucket hostname.
If set, stdout and stderr streams are redirected to files named from the job name. Default is true.
+.. option:: xnvme_async=str : [xnvme]
+
+ Select the xnvme async command interface. This can take these values.
+
+ **emu**
+ This is default and used to emulate asynchronous I/O.
+ **thrpool**
+ Use thread pool for Asynchronous I/O.
+ **io_uring**
+ Use Linux io_uring/liburing for Asynchronous I/O.
+ **libaio**
+ Use Linux aio for Asynchronous I/O.
+ **posix**
+ Use POSIX aio for Asynchronous I/O.
+ **nil**
+ Use nil-io; For introspective perf. evaluation
+
+.. option:: xnvme_sync=str : [xnvme]
+
+ Select the xnvme synchronous command interface. This can take these values.
+
+ **nvme**
+ This is default and uses Linux NVMe Driver ioctl() for synchronous I/O.
+ **psync**
+ Use pread()/write() for synchronous I/O.
+
+.. option:: xnvme_admin=str : [xnvme]
+
+ Select the xnvme admin command interface. This can take these values.
+
+ **nvme**
+ This is default and uses linux NVMe Driver ioctl() for admin commands.
+ **block**
+ Use Linux Block Layer ioctl() and sysfs for admin commands.
+ **file_as_ns**
+ Use file-stat to construct NVMe idfy responses.
+
+.. option:: xnvme_dev_nsid=int : [xnvme]
+
+ xnvme namespace identifier, for userspace NVMe driver.
+
+.. option:: xnvme_iovec=int : [xnvme]
+
+ If this option is set. xnvme will use vectored read/write commands.
+
I/O depth
~~~~~~~~~
Write the issued I/O patterns to the specified file. See
:option:`read_iolog`. Specify a separate file for each job, otherwise the
- iologs will be interspersed and the file may be corrupt.
+ iologs will be interspersed and the file may be corrupt. This file will
+ be opened in append mode.
.. option:: read_iolog=str
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.
+ same offset with multiple outstanding I/Os.
.. option:: verify_offset=int
**slat**
Submission latency (**min** being the minimum, **max** being the
maximum, **avg** being the average, **stdev** being the standard
- deviation). This is the time it took to submit the I/O. For
- sync I/O this row is not displayed as the slat is really the
- completion latency (since queue/complete is one operation there).
- This value can be in nanoseconds, microseconds or milliseconds ---
- fio will choose the most appropriate base and print that (in the
- example above nanoseconds was the best scale). Note: in :option:`--minimal` mode
- latencies are always expressed in microseconds.
+ deviation). This is the time from when fio initialized the I/O
+ to submission. For synchronous ioengines this includes the time
+ up until just before the ioengine's queue function is called.
+ For asynchronous ioengines this includes the time up through the
+ completion of the ioengine's queue function (and commit function
+ if it is defined). For sync I/O this row is not displayed as the
+ slat is negligible. This value can be in nanoseconds,
+ microseconds or milliseconds --- fio will choose the most
+ appropriate base and print that (in the example above
+ nanoseconds was the best scale). Note: in :option:`--minimal`
+ mode latencies are always expressed in microseconds.
**clat**
Completion latency. Same names as slat, this denotes the time from
- submission to completion of the I/O pieces. For sync I/O, clat will
- usually be equal (or very close) to 0, as the time from submit to
- complete is basically just CPU time (I/O has already been done, see slat
- explanation).
+ submission to completion of the I/O pieces. For sync I/O, this
+ represents the time from when the I/O was submitted to the
+ operating system to when it was completed. For asynchronous
+ ioengines this is the time from when the ioengine's queue (and
+ commit if available) functions were completed to when the I/O's
+ completion was reaped by fio.
**lat**
Total latency. Same names as slat and clat, this denotes the time from
when fio created the I/O unit to completion of the I/O operation.
+ It is the sum of submission and completion latency.
**bw**
Bandwidth statistics based on samples. Same names as the xlat stats,
**wait**
Wait for `offset` microseconds. Everything below 100 is discarded.
- The time is relative to the previous `wait` statement.
+ The time is relative to the previous `wait` statement. Note that
+ action `wait` is not allowed as of version 3, as the same behavior
+ can be achieved using timestamps.
**read**
Read `length` bytes beginning from `offset`.
**write**
Trim the given file from the given `offset` for `length` bytes.
+Trace file format v3
+~~~~~~~~~~~~~~~~~~~~
+
+The third version of the trace file format was added in fio version 3.31. It
+forces each action to have a timestamp associated with it.
+
+The first line of the trace file has to be::
+
+ fio version 3 iolog
+
+Following this can be lines in two different formats, which are described below.
+
+The file management format::
+
+ timestamp filename action
+
+The file I/O action format::
+
+ timestamp filename action offset length
+
+The `timestamp` is relative to the beginning of the run (ie starts at 0). The
+`filename`, `action`, `offset` and `length` are identical to version 2, except
+that version 3 does not allow the `wait` action.
+
+
I/O Replay - Merging Traces
---------------------------
projects / fio.git / blobdiff