X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=297a04851a2bbb747d9c3b8e6df0143be45203a2;hp=86fb296445f006e2f3416abe559bd5f0dc57ce19;hb=a87ea1a869595ca57052e7645431a397d3c7d5ac;hpb=3fd60780bc5984639b568e85d31ede7a50f4e1e5 diff --git a/HOWTO b/HOWTO index 86fb2964..297a0485 100644 --- a/HOWTO +++ b/HOWTO @@ -992,6 +992,9 @@ Target file/device single zone. The :option:`zoneskip` parameter is ignored. :option:`zonerange` and :option:`zonesize` must be identical. + Trim is handled using a zone reset operation. + Trim only considers non-empty sequential write + required and sequential write preferred zones. .. option:: zonerange=int @@ -1055,6 +1058,11 @@ Target file/device number of open zones is defined as the number of zones to which write commands are issued. +.. option:: job_max_open_zones=int + + Limit on the number of simultaneously opened zones per single + thread/process. + .. option:: zone_reset_threshold=float A number between zero and one that indicates the ratio of logical @@ -1705,6 +1713,36 @@ Buffers and memory this option will also enable :option:`refill_buffers` to prevent every buffer being identical. +.. option:: dedupe_mode=str + + If ``dedupe_percentage=`` is given, then this option controls how fio + generates the dedupe buffers. + + **repeat** + Generate dedupe buffers by repeating previous writes + **working_set** + Generate dedupe buffers from working set + + ``repeat`` is the default option for fio. Dedupe buffers are generated + by repeating previous unique write. + + ``working_set`` is a more realistic workload. + With ``working_set``, ``dedupe_working_set_percentage=`` should be provided. + Given that, fio will use the initial unique write buffers as its working set. + Upon deciding to dedupe, fio will randomly choose a buffer from the working set. + Note that by using ``working_set`` the dedupe percentage will converge + to the desired over time while ``repeat`` maintains the desired percentage + throughout the job. + +.. option:: dedupe_working_set_percentage=int + + If ``dedupe_mode=`` is set to ``working_set``, then this controls + the percentage of size of the file or device used as the buffers + fio will choose to generate the dedupe buffers from + + Note that size needs to be explicitly provided and only 1 file per + job is supported + .. option:: invalidate=bool Invalidate the buffer/page cache parts of the files to be used prior to @@ -1930,6 +1968,11 @@ I/O engine character devices. This engine supports trim operations. The sg engine includes engine specific options. + **libzbc** + Read, write, trim and ZBC/ZAC operations to a zoned + block device using libzbc library. The target can be + either an SG character device or a block device file. + **null** Doesn't transfer any data, just pretends to. This is mainly used to exercise fio itself and for debugging/testing purposes. @@ -2109,6 +2152,9 @@ I/O engine achieving higher concurrency and thus throughput than is possible via kernel NFS. + **exec** + Execute 3rd party tools. Could be used to perform monitoring during jobs runtime. + I/O engine specific parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2117,14 +2163,49 @@ In addition, there are some parameters which are only valid when a specific with the caveat that when used on the command line, they must come after the :option:`ioengine` that defines them is selected. -.. option:: cmdprio_percentage=int : [io_uring] [libaio] - - 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:: cmdprio_percentage=int[,int] : [io_uring] [libaio] + + Set the percentage of I/O that will be issued with the highest priority. + Default: 0. A single value applies to reads and writes. Comma-separated + values may be specified for reads and writes. This option cannot be used + with the :option:`prio` or :option:`prioclass` options. For this option + to be effective, NCQ priority must be supported and enabled, and `direct=1' + option must be used. fio must also be run as the root user. + +.. option:: cmdprio_class=int[,int] : [io_uring] [libaio] + + Set the I/O priority class to use for I/Os that must be issued with + a priority when :option:`cmdprio_percentage` or + :option:`cmdprio_bssplit` is set. If not specified when + :option:`cmdprio_percentage` or :option:`cmdprio_bssplit` is set, + this defaults to the highest priority class. A single value applies + to reads and writes. Comma-separated values may be specified for + reads and writes. See :manpage:`ionice(1)`. See also the + :option:`prioclass` option. + +.. option:: cmdprio=int[,int] : [io_uring] [libaio] + + Set the I/O priority value to use for I/Os that must be issued with + a priority when :option:`cmdprio_percentage` or + :option:`cmdprio_bssplit` is set. If not specified when + :option:`cmdprio_percentage` or :option:`cmdprio_bssplit` is set, + this defaults to 0. + Linux limits us to a positive value between 0 and 7, with 0 being the + highest. A single value applies to reads and writes. Comma-separated + values may be specified for reads and writes. See :manpage:`ionice(1)`. + Refer to an appropriate manpage for other operating systems since + meaning of priority may differ. See also the :option:`prio` option. + +.. option:: cmdprio_bssplit=str[,str] : [io_uring] [libaio] + To get a finer control over I/O priority, this option allows + specifying the percentage of IOs that must have a priority set + depending on the block size of the IO. This option is useful only + when used together with the :option:`bssplit` option, that is, + multiple different block sizes are used for reads and writes. + The format for this option is the same as the format of the + :option:`bssplit` option, with the exception that values for + trim IOs are ignored. This option is mutually exclusive with the + :option:`cmdprio_percentage` option. .. option:: fixedbufs : [io_uring] @@ -2515,11 +2596,11 @@ with the caveat that when used on the command line, they must come after the .. option:: pool=str : [dfs] - Specify the UUID of the DAOS pool to connect to. + Specify the label or UUID of the DAOS pool to connect to. .. option:: cont=str : [dfs] - Specify the UUID of the DAOS container to open. + Specify the label or UUID of the DAOS container to open. .. option:: chunk_size=int : [dfs] @@ -2536,6 +2617,28 @@ with the caveat that when used on the command line, they must come after the URL in libnfs format, eg nfs:///path[?arg=val[&arg=val]*] Refer to the libnfs README for more details. +.. option:: program=str : [exec] + + Specify the program to execute. + +.. option:: arguments=str : [exec] + + Specify arguments to pass to program. + Some special variables can be expanded to pass fio's job details to the program. + + **%r** + Replaced by the duration of the job in seconds. + **%n** + Replaced by the name of the job. + +.. option:: grace_time=int : [exec] + + Specify the time between the SIGTERM and SIGKILL signals. Default is 1 second. + +.. option:: std_redirect=bool : [exec] + + If set, stdout and stderr streams are redirected to files named from the job name. Default is true. + I/O depth ~~~~~~~~~ @@ -2642,7 +2745,7 @@ I/O rate Stall the job for the specified period of time after an I/O has completed before issuing the next. May be used to simulate processing being done by an application. When the unit is omitted, the value is interpreted in microseconds. See - :option:`thinktime_blocks` and :option:`thinktime_spin`. + :option:`thinktime_blocks`, :option:`thinktime_iotime` and :option:`thinktime_spin`. .. option:: thinktime_spin=time @@ -2667,6 +2770,18 @@ I/O rate :option:`thinktime_blocks` blocks. If this is set to `issue`, then the trigger happens at the issue side. +.. option:: thinktime_iotime=time + + Only valid if :option:`thinktime` is set - control :option:`thinktime` + interval by time. The :option:`thinktime` stall is repeated after IOs + are executed for :option:`thinktime_iotime`. For example, + ``--thinktime_iotime=9s --thinktime=1s`` repeat 10-second cycle with IOs + for 9 seconds and stall for 1 second. When the unit is omitted, + :option:`thinktime_iotime` is interpreted as a number of seconds. If + this option is used together with :option:`thinktime_blocks`, the + :option:`thinktime` stall is repeated after :option:`thinktime_iotime` + or after :option:`thinktime_blocks` IOs, whichever happens first. + .. option:: rate=int[,int][,int] Cap the bandwidth used by this job. The number is in bytes/sec, the normal @@ -2906,14 +3021,14 @@ Threads, processes and job synchronization 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. For per-command priority - setting, see I/O engine specific `cmdprio_percentage` and `hipri_percentage` - options. + setting, see I/O engine specific :option:`cmdprio_percentage` and + :option:`cmdprio` options. .. option:: prioclass=int 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. + priority setting, see I/O engine specific :option:`cmdprio_percentage` + and :option:`cmdprio_class` options. .. option:: cpus_allowed=str