t/io_uring: add switch -O for O_DIRECT vs buffered

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index a12bccba826d5c966b438581286e79b43eb8cb6c..297a04851a2bbb747d9c3b8e6df0143be45203a2 100644 (file)
--- 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.
                                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
 
 
 .. 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.
 
        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
 .. option:: zone_reset_threshold=float
 
        A number between zero and one that indicates the ratio of logical


@@ -1960,6 +1968,11 @@ I/O engine
                        character devices. This engine supports trim operations.
                        The sg engine includes engine specific options.
 
                        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.
                **null**
                        Doesn't transfer any data, just pretends to.  This is mainly used to
                        exercise fio itself and for debugging/testing purposes.


@@ -2139,6 +2152,9 @@ I/O engine
                        achieving higher concurrency and thus throughput than is possible
                        via kernel NFS.
 
                        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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 I/O engine specific parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 


@@ -2147,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.
 
 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]
 
 
 .. option:: fixedbufs : [io_uring]
 


@@ -2545,11 +2596,11 @@ with the caveat that when used on the command line, they must come after the
 
 .. option:: pool=str : [dfs]
 
 
 .. 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]
 
 
 .. 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]
 
 
 .. option:: chunk_size=int : [dfs]
 


@@ -2566,6 +2617,28 @@ with the caveat that when used on the command line, they must come after the
        URL in libnfs format, eg nfs://<server|ipv4|ipv6>/path[?arg=val[&arg=val]*]
        Refer to the libnfs README for more details.
 
        URL in libnfs format, eg nfs://<server|ipv4|ipv6>/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
 ~~~~~~~~~
 
 I/O depth
 ~~~~~~~~~
 


@@ -2672,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
        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
 
 
 .. option:: thinktime_spin=time
 


@@ -2697,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_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
 .. option:: rate=int[,int][,int]
 
        Cap the bandwidth used by this job. The number is in bytes/sec, the normal


@@ -2936,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
        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
 
 .. 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
 
 
 .. option:: cpus_allowed=str