**zoned**
Zoned random distribution
+ **zoned_abs**
+ Zone absolute random distribution
+
When using a **zipf** or **pareto** distribution, an input value is also
needed to define the access pattern. For **zipf**, this is the `Zipf
theta`. For **pareto**, it's the `Pareto power`. Fio includes a test
random_distribution=zoned:60/10:30/20:8/30:2/40
- similarly to how :option:`bssplit` works for setting ranges and percentages
- of block sizes. Like :option:`bssplit`, it's possible to specify separate
- zones for reads, writes, and trims. If just one set is given, it'll apply to
- all of them.
+ A **zoned_abs** distribution works exactly like the **zoned**, except
+ that it takes absolute sizes. For example, let's say you wanted to
+ define access according to the following criteria:
+
+ * 60% of accesses should be to the first 20G
+ * 30% of accesses should be to the next 100G
+ * 10% of accesses should be to the next 500G
+
+ we can define an absolute zoning distribution with:
+
+ random_distribution=zoned_abs=60/20G:30/100G:10/500g
+
+ For both **zoned** and **zoned_abs**, fio supports defining up to
+ 256 separate zones.
+
+ Similarly to how :option:`bssplit` works for setting ranges and
+ percentages of block sizes. Like :option:`bssplit`, it's possible to
+ specify separate zones for reads, writes, and trims. If just one set
+ is given, it'll apply to all of them. This goes for both **zoned**
+ **zoned_abs** distributions.
.. option:: percentage_random=int[,int][,int]
.. option:: bssplit=str[,str][,str]
- Sometimes you want even finer grained control of the block sizes issued, not
- just an even split between them. This option allows you to weight various
- block sizes, so that you are able to define a specific amount of block sizes
- issued. The format for this option is::
+ Sometimes you want even finer grained control of the block sizes
+ issued, not just an even split between them. This option allows you to
+ weight various block sizes, so that you are able to define a specific
+ amount of block sizes issued. The format for this option is::
bssplit=blocksize/percentage:blocksize/percentage
- for as many block sizes as needed. So if you want to define a workload that
- has 50% 64k blocks, 10% 4k blocks, and 40% 32k blocks, you would write::
+ for as many block sizes as needed. So if you want to define a workload
+ that has 50% 64k blocks, 10% 4k blocks, and 40% 32k blocks, you would
+ write::
bssplit=4k/10:64k/50:32k/40
- Ordering does not matter. If the percentage is left blank, fio will fill in
- the remaining values evenly. So a bssplit option like this one::
+ Ordering does not matter. If the percentage is left blank, fio will
+ fill in the remaining values evenly. So a bssplit option like this one::
bssplit=4k/50:1k/:32k/
- would have 50% 4k ios, and 25% 1k and 32k ios. The percentages always add up
- to 100, if bssplit is given a range that adds up to more, it will error out.
+ would have 50% 4k ios, and 25% 1k and 32k ios. The percentages always
+ add up to 100, if bssplit is given a range that adds up to more, it
+ will error out.
Comma-separated values may be specified for reads, writes, and trims as
described in :option:`blocksize`.
- 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::
+ 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::
bssplit=2k/50:4k/50,4k/90,8k/10
+ Fio supports defining up to 64 different weights for each data
+ direction.
+
.. option:: blocksize_unaligned, bs_unaligned
If set, fio will issue I/O units with any size within
.. option:: refill_buffers
If this option is given, fio will refill the I/O buffers on every
- submit. The default is to only fill it at init time and reuse that
- data. Only makes sense if zero_buffers isn't specified, naturally. If data
- verification is enabled, `refill_buffers` is also automatically enabled.
+ submit. Only makes sense if :option:`zero_buffers` isn't specified,
+ naturally. Defaults to being unset i.e., the buffer is only filled at
+ init time and the data in it is reused when possible but if any of
+ :option:`verify`, :option:`buffer_compress_percentage` or
+ :option:`dedupe_percentage` are enabled then `refill_buffers` is also
+ automatically enabled.
.. option:: scramble_buffers=bool
.. option:: buffer_compress_percentage=int
- If this is set, then fio will attempt to provide I/O buffer content (on
- WRITEs) that compresses to the specified level. Fio does this by providing a
- mix of random data and a fixed pattern. The fixed pattern is either zeros,
- or the pattern specified by :option:`buffer_pattern`. If the pattern option
- is used, it might skew the compression ratio slightly. Note that this is per
- block size unit, see :option:`buffer_compress_chunk` for setting a finer
- granularity of compression regions.
+ If this is set, then fio will attempt to provide I/O buffer content
+ (on WRITEs) that compresses to the specified level. Fio does this by
+ providing a mix of random data followed by fixed pattern data. The
+ fixed pattern is either zeros, or the pattern specified by
+ :option:`buffer_pattern`. If the `buffer_pattern` option is used, it
+ might skew the compression ratio slightly. Setting
+ `buffer_compress_percentage` to a value other than 100 will also
+ enable :option:`refill_buffers` in order to reduce the likelihood that
+ adjacent blocks are so similar that they over compress when seen
+ together. See :option:`buffer_compress_chunk` for how to set a finer or
+ coarser granularity for the random/fixed data region. Defaults to unset
+ i.e., buffer data will not adhere to any compression level.
.. option:: buffer_compress_chunk=int
- See :option:`buffer_compress_percentage`. This setting allows fio to manage
- how big the ranges of random data and zeroed data is. Without this set, fio
- will provide :option:`buffer_compress_percentage` of blocksize random data,
- followed by the remaining zeroed. With this set to some chunk size smaller
- than the block size, fio can alternate random and zeroed data throughout the
- I/O buffer. This is particularly useful when bigger block sizes are used
- for a job.
+ This setting allows fio to manage how big the random/fixed data region
+ is when using :option:`buffer_compress_percentage`. When
+ `buffer_compress_chunk` is set to some non-zero value smaller than the
+ block size, fio can repeat the random/fixed region throughout the I/O
+ buffer at the specified interval (which particularly useful when
+ bigger block sizes are used for a job). When set to 0, fio will use a
+ chunk size that matches the block size resulting in a single
+ random/fixed region within the I/O buffer. Defaults to 512. When the
+ unit is omitted, the value is interpreted in bytes.
.. option:: buffer_pattern=str
writing. These buffers will be naturally dedupable. The contents of the
buffers depend on what other buffer compression settings have been set. It's
possible to have the individual buffers either fully compressible, or not at
- all. This option only controls the distribution of unique buffers.
+ all -- this option only controls the distribution of unique buffers. Setting
+ this option will also enable :option:`refill_buffers` to prevent every buffer
+ being identical.
.. option:: invalidate=bool
**rdma**
The RDMA I/O engine supports both RDMA memory semantics
(RDMA_WRITE/RDMA_READ) and channel semantics (Send/Recv) for the
- InfiniBand, RoCE and iWARP protocols.
+ InfiniBand, RoCE and iWARP protocols. This engine defines engine
+ specific options.
**falloc**
I/O engine that does regular fallocate to simulate data transfer as
set `filesize` so that all the accounting still occurs, but no
actual I/O will be done other than creating the file.
+ **libpmem**
+ Read and write using mmap I/O to a file on a filesystem
+ mounted with DAX on a persistent memory device through the NVML
+ libpmem library.
+
I/O engine specific parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
this will be the starting port number since fio will use a range of
ports.
-.. option:: hostname=str : [netsplice] [net]
+ [rdma]
+
+ The port to use for RDMA-CM communication. This should be the same value
+ on the client and the server side.
- The hostname or IP address to use for TCP or UDP based I/O. If the job is
- a TCP listener or UDP reader, the hostname is not used and must be omitted
+.. option:: hostname=str : [netsplice] [net] [rdma]
+
+ The hostname or IP address to use for TCP, UDP or RDMA-CM based I/O. If the job
+ is a TCP listener or UDP reader, the hostname is not used and must be omitted
unless it is a valid UDP multicast address.
.. option:: interface=str : [netsplice] [net]
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
+ values are write, read, send and recv. These correspond to the equivalent
+ RDMA verbs (e.g. write = rdma_write etc.). Note that this only needs to be
+ specified on the client side of the connection. See the examples folder.
+
+.. option:: bindname=str : [rdma]
+
+ The name to use to bind the local RDMA-CM connection to a local RDMA device.
+ This could be a hostname or an IPv4 or IPv6 address. On the server side this
+ will be passed into the rdma_bind_addr() function and on the client site it
+ will be used in the rdma_resolve_add() function. This can be useful when
+ multiple paths exist between the client and the server or in certain loopback
+ configurations.
I/O depth
~~~~~~~~~
.. option:: write_lat_log=str
Same as :option:`write_bw_log`, except this option creates I/O
- submission (e.g., `file:`name_slat.x.log`), completion (e.g.,
- `file:`name_clat.x.log`), and total (e.g., `file:`name_lat.x.log`)
+ submission (e.g., :file:`name_slat.x.log`), completion (e.g.,
+ :file:`name_clat.x.log`), and total (e.g., :file:`name_lat.x.log`)
latency files instead. See :option:`write_bw_log` for details about
the filename format and `Log File Formats`_ for how data is structured
within the files.
.. option:: write_hist_log=str
Same as :option:`write_bw_log` but writes an I/O completion latency
- histogram file (e.g., `file:`name_hist.x.log`) instead. Note that this
+ histogram file (e.g., :file:`name_hist.x.log`) instead. Note that this
file will be empty unless :option:`log_hist_msec` has also been set.
See :option:`write_bw_log` for details about the filename format and
`Log File Formats`_ for how data is structured within the file.
.. option:: write_iops_log=str
Same as :option:`write_bw_log`, but writes an IOPS file (e.g.
- `file:`name_iops.x.log`) instead. See :option:`write_bw_log` for
+ :file:`name_iops.x.log`) instead. See :option:`write_bw_log` for
details about the filename format and `Log File Formats`_ for how data
is structured within the file.
.. 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 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.
+ 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
+ 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.
+
+.. option:: significant_figures=int
+
+ If using :option:`--output-format` of `normal`, set the significant
+ figures to this value. Higher values will yield more precise IOPS and
+ throughput units, while lower values will round. Requires a minimum
+ value of 1 and a maximum value of 10. Defaults to 4.
Error handling
projects / fio.git / blobdiff