engines/io_uring: use the atomic load acquire instead of a barrier

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 0a3661684fb4653a1638b30e7d1e204abe6094a9..5dc571f8e55b39d356e8b3fdca57a83604f46af0 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -970,14 +970,15 @@ Target file/device
        Accepted values are:
 
                **none**
        Accepted values are:
 
                **none**

-                               The :option:`zonerange`, :option:`zonesize` and
-                               :option:`zoneskip` parameters are ignored.
+                               The :option:`zonerange`, :option:`zonesize`,
+                               :option `zonecapacity` and option:`zoneskip`
+                               parameters are ignored.

                **strided**
                                I/O happens in a single zone until
                                :option:`zonesize` bytes have been transferred.
                                After that number of bytes has been
                                transferred processing of the next zone
                **strided**
                                I/O happens in a single zone until
                                :option:`zonesize` bytes have been transferred.
                                After that number of bytes has been
                                transferred processing of the next zone

-                               starts.
+                               starts. :option `zonecapacity` is ignored.

                **zbd**
                                Zoned block device mode. I/O happens
                                sequentially in each zone, even if random I/O
                **zbd**
                                Zoned block device mode. I/O happens
                                sequentially in each zone, even if random I/O


@@ -1004,6 +1005,17 @@ Target file/device
        For :option:`zonemode` =zbd, this is the size of a single zone. The
        :option:`zonerange` parameter is ignored in this mode.
 
        For :option:`zonemode` =zbd, this is the size of a single zone. The
        :option:`zonerange` parameter is ignored in this mode.
 

+
+.. option:: zonecapacity=int
+
+       For :option:`zonemode` =zbd, this defines the capacity of a single zone,
+       which is the accessible area starting from the zone start address.
+       This parameter only applies when using :option:`zonemode` =zbd in
+       combination with regular block devices. If not specified it defaults to
+       the zone size. If the target device is a zoned block device, the zone
+       capacity is obtained from the device information and this option is
+       ignored.
+

 .. option:: zoneskip=int
 
        For :option:`zonemode` =strided, the number of bytes to skip after
 .. option:: zoneskip=int
 
        For :option:`zonemode` =strided, the number of bytes to skip after


@@ -2040,7 +2052,8 @@ with the caveat that when used on the command line, they must come after the
     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
     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.
+    enabled and :option:`direct`\=1 option must be used. fio must also be run as
+    the root user.

 
 .. option:: fixedbufs : [io_uring]
 
 
 .. option:: fixedbufs : [io_uring]
 


@@ -2096,6 +2109,26 @@ with the caveat that when used on the command line, they must come after the
        When hipri is set this determines the probability of a pvsync2 I/O being high
        priority. The default is 100%.
 
        When hipri is set this determines the probability of a pvsync2 I/O being high
        priority. The default is 100%.
 

+.. option:: nowait : [pvsync2] [libaio] [io_uring]
+
+       By default if a request cannot be executed immediately (e.g. resource starvation,
+       waiting on locks) it is queued and the initiating process will be blocked until
+       the required resource becomes free.
+
+       This option sets the RWF_NOWAIT flag (supported from the 4.14 Linux kernel) and
+       the call will return instantly with EAGAIN or a partial result rather than waiting.
+
+       It is useful to also use ignore_error=EAGAIN when using this option.
+
+       Note: glibc 2.27, 2.28 have a bug in syscall wrappers preadv2, pwritev2.
+       They return EOPNOTSUP instead of EAGAIN.
+
+       For cached I/O, using this option usually means a request operates only with
+       cached data. Currently the RWF_NOWAIT flag does not supported for cached write.
+
+       For direct I/O, requests will only succeed if cache invalidation isn't required,
+       file blocks are fully allocated and the disk request could be issued immediately.
+

 .. option:: cpuload=int : [cpuio]
 
        Attempt to use the specified percentage of CPU cycles. This is a mandatory
 .. option:: cpuload=int : [cpuio]
 
        Attempt to use the specified percentage of CPU cycles. This is a mandatory


@@ -2261,6 +2294,11 @@ with the caveat that when used on the command line, they must come after the
        multiple paths exist between the client and the server or in certain loopback
        configurations.
 
        multiple paths exist between the client and the server or in certain loopback
        configurations.
 

+.. option:: stat_type=str : [filestat]
+
+       Specify stat system call type to measure lookup/getattr performance.
+       Default is **stat** for :manpage:`stat(2)`.
+

 .. option:: readfua=bool : [sg]
 
        With readfua option set to 1, read operations include
 .. option:: readfua=bool : [sg]
 
        With readfua option set to 1, read operations include


@@ -2546,6 +2584,13 @@ I/O latency
        defaults to 100.0, meaning that all I/Os must be equal or below to the value
        set by :option:`latency_target`.
 
        defaults to 100.0, meaning that all I/Os must be equal or below to the value
        set by :option:`latency_target`.
 

+.. option:: latency_run=bool
+
+       Used with :option:`latency_target`. If false (default), fio will find
+       the highest queue depth that meets :option:`latency_target` and exit. If
+       true, fio will continue running and try to meet :option:`latency_target`
+       by adjusting queue depth.
+

 .. option:: max_latency=time
 
        If set, fio will exit the job with an ETIMEDOUT error if it exceeds this
 .. option:: max_latency=time
 
        If set, fio will exit the job with an ETIMEDOUT error if it exceeds this


@@ -2580,6 +2625,9 @@ I/O replay
        character. See the :option:`filename` option for information on how to
        escape ':' characters within the file names. These files will
        be sequentially assigned to job clones created by :option:`numjobs`.
        character. See the :option:`filename` option for information on how to
        escape ':' characters within the file names. These files will
        be sequentially assigned to job clones created by :option:`numjobs`.

+       '-' is a reserved name, meaning read from stdin, notably if
+       :option:`filename` is set to '-' which means stdin as well, then
+       this flag can't be set to '-'.

 
 .. option:: read_iolog_chunked=bool
 
 
 .. option:: read_iolog_chunked=bool
 


@@ -2813,15 +2861,10 @@ Threads, processes and job synchronization
        ``flow=8`` and another job has ``flow=-1``, then there will be a roughly 1:8
        ratio in how much one runs vs the other.
 
        ``flow=8`` and another job has ``flow=-1``, then there will be a roughly 1:8
        ratio in how much one runs vs the other.
 

-.. option:: flow_watermark=int
-
-       The maximum value that the absolute value of the flow counter is allowed to
-       reach before the job must wait for a lower value of the counter.
-

 .. option:: flow_sleep=int
 
 .. option:: flow_sleep=int
 

-       The period of time, in microseconds, to wait after the flow watermark has
-       been exceeded before retrying operations.
+       The period of time, in microseconds, to wait after the flow counter
+       has exceeded its proportion before retrying operations.

 
 .. option:: stonewall, wait_for_previous
 
 
 .. option:: stonewall, wait_for_previous
 


@@ -3342,27 +3385,28 @@ Measurements and reporting
        Disable measurements of throughput/bandwidth numbers. See
        :option:`disable_lat`.
 
        Disable measurements of throughput/bandwidth numbers. See
        :option:`disable_lat`.
 

+.. option:: slat_percentiles=bool
+
+       Report submission latency percentiles. Submission latency is not recorded
+       for synchronous ioengines.
+

 .. option:: clat_percentiles=bool
 
 .. option:: clat_percentiles=bool
 

-       Enable the reporting of percentiles of completion latencies.  This
-       option is mutually exclusive with :option:`lat_percentiles`.
+       Report completion latency percentiles.

 
 .. option:: lat_percentiles=bool
 
 
 .. option:: lat_percentiles=bool
 

-       Enable the reporting of percentiles of I/O latencies. This is similar
-       to :option:`clat_percentiles`, except that this includes the
-       submission latency. This option is mutually exclusive with
-       :option:`clat_percentiles`.
+       Report total latency percentiles. Total latency is the sum of submission
+       latency and completion latency.

 
 .. option:: percentile_list=float_list
 
 
 .. 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
+       Overwrite the default list of percentiles for latencies and the block error
+       histogram.  Each number is a floating point number in the range (0,100], and
+       the maximum length of the list is 20. Use ``:`` to separate the numbers. For

        example, ``--percentile_list=99.5:99.9`` will cause fio to report the
        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.
+       latency durations below which 99.5% and 99.9% of the observed latencies fell,
+       respectively.

 
 .. option:: significant_figures=int
 
 
 .. option:: significant_figures=int
 


@@ -4131,7 +4175,7 @@ Fio supports a variety of log file formats, for logging latencies, bandwidth,
 and IOPS. The logs share a common format, which looks like this:
 
     *time* (`msec`), *value*, *data direction*, *block size* (`bytes`),
 and IOPS. The logs share a common format, which looks like this:
 
     *time* (`msec`), *value*, *data direction*, *block size* (`bytes`),

-    *offset* (`bytes`)
+    *offset* (`bytes`), *command priority*

 
 *Time* for the log entry is always in milliseconds. The *value* logged depends
 on the type of log, it will be one of the following:
 
 *Time* for the log entry is always in milliseconds. The *value* logged depends
 on the type of log, it will be one of the following:


@@ -4156,6 +4200,9 @@ The entry's *block size* is always in bytes. The *offset* is the position in byt
 from the start of the file for that particular I/O. The logging of the offset can be
 toggled with :option:`log_offset`.
 
 from the start of the file for that particular I/O. The logging of the offset can be
 toggled with :option:`log_offset`.
 

+*Command priority* is 0 for normal priority and 1 for high priority. This is controlled
+by the ioengine specific :option:`cmdprio_percentage`.
+

 Fio defaults to logging every individual I/O but when windowed logging is set
 through :option:`log_avg_msec`, either the average (by default) or the maximum
 (:option:`log_max_value` is set) *value* seen over the specified period of time
 Fio defaults to logging every individual I/O but when windowed logging is set
 through :option:`log_avg_msec`, either the average (by default) or the maximum
 (:option:`log_max_value` is set) *value* seen over the specified period of time