X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=78fa6ccf4a61e623a44c0e1137f46cc416382ee8;hp=4d3a8c8cec73c8c46d8a608e948810a5adf0a5f6;hb=7f3ecee2f6dd2aa40c0404a40d0406d9efc765f2;hpb=725927803e15a56fafc4952a78c6810efae6cebb diff --git a/HOWTO b/HOWTO index 4d3a8c8c..78fa6ccf 100644 --- a/HOWTO +++ b/HOWTO @@ -173,7 +173,16 @@ Command line options .. option:: --eta=when Specifies when real-time ETA estimate should be printed. `when` may be - `always`, `never` or `auto`. + `always`, `never` or `auto`. `auto` is the default, it prints ETA + when requested if the output is a TTY. `always` disregards the output + type, and prints ETA when requested. `never` never prints ETA. + +.. option:: --eta-interval=time + + By default, fio requests client ETA status roughly every second. With + this option, the interval is configurable. Fio imposes a minimum + allowed time to avoid flooding the console, less than 250 msec is + not supported. .. option:: --eta-newline=time @@ -1254,6 +1263,9 @@ I/O type **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 @@ -1278,10 +1290,26 @@ I/O type 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] @@ -1372,34 +1400,39 @@ Block size .. 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 @@ -1751,7 +1784,8 @@ I/O engine **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 @@ -1893,10 +1927,15 @@ with the caveat that when used on the command line, they must come after the 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] @@ -2002,6 +2041,21 @@ with the caveat that when used on the command line, they must come after the 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 ~~~~~~~~~ @@ -2163,6 +2217,13 @@ I/O rate (https://en.wikipedia.org/wiki/Poisson_point_process). The lambda will be 10^6 / IOPS for the given workload. +.. option:: rate_ignore_thinktime=bool + + By default, fio will attempt to catch up to the specified rate setting, + if any kind of thinktime setting was used. If this option is set, then + fio will ignore the thinktime and continue doing IO at the specified + rate, instead of entering a catch-up mode after thinktime is done. + I/O latency ~~~~~~~~~~~ @@ -2913,20 +2974,20 @@ Measurements and reporting .. 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. + 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