zbd: Fix zoned_block_device_info.zone_size documentation

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 0a3661684fb4653a1638b30e7d1e204abe6094a9..9e339bb8d0a608a2f83b141197bd1bbbb503804b 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -2040,7 +2040,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 +2097,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 +2282,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 +2572,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


@@ -3342,27 +3375,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