Add thread_segments as needed

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index d7634790bf7295d0c10dd8414e52adfb3ac1ad10..386fd12aa7b14b80405a4df2851b3c0f7e967fd0 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


@@ -1665,10 +1677,28 @@ Buffers and memory
        This will be ignored if :option:`pre_read` is also specified for the
        same job.
 
        This will be ignored if :option:`pre_read` is also specified for the
        same job.
 

-.. option:: sync=bool
+.. option:: sync=str
+
+       Whether, and what type, of synchronous I/O to use for writes.  The allowed
+       values are:
+
+               **none**
+                       Do not use synchronous IO, the default.
+
+               **0**
+                       Same as **none**.
+
+               **sync**
+                       Use synchronous file IO. For the majority of I/O engines,
+                       this means using O_SYNC.
+
+               **1**
+                       Same as **sync**.
+
+               **dsync**
+                       Use synchronous data IO. For the majority of I/O engines,
+                       this means using O_DSYNC.

 
 

-       Use synchronous I/O for buffered writes. For the majority of I/O engines,
-       this means using O_SYNC. Default: false.

 
 .. option:: iomem=str, mem=str
 
 
 .. option:: iomem=str, mem=str
 


@@ -1889,14 +1919,6 @@ I/O engine
                        single CPU at the desired rate. A job never finishes unless there is
                        at least one non-cpuio job.
 
                        single CPU at the desired rate. A job never finishes unless there is
                        at least one non-cpuio job.
 

-               **guasi**
-                       The GUASI I/O engine is the Generic Userspace Asynchronous Syscall
-                       Interface approach to async I/O. See
-
-                       http://www.xmailserver.org/guasi-lib.html
-
-                       for more info on GUASI.
-

                **rdma**
                        The RDMA I/O engine supports both RDMA memory semantics
                        (RDMA_WRITE/RDMA_READ) and channel semantics (Send/Recv) for the
                **rdma**
                        The RDMA I/O engine supports both RDMA memory semantics
                        (RDMA_WRITE/RDMA_READ) and channel semantics (Send/Recv) for the


@@ -2040,7 +2062,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 +2119,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,9 +2304,10 @@ 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:: lstat=bool : [filestat]
+.. option:: stat_type=str : [filestat]

 
 

-       Use lstat(2) to measure lookup/getattr performance. Default is 0.
+       Specify stat system call type to measure lookup/getattr performance.
+       Default is **stat** for :manpage:`stat(2)`.

 
 .. option:: readfua=bool : [sg]
 
 
 .. option:: readfua=bool : [sg]
 


@@ -2448,7 +2492,8 @@ I/O depth
        can increase latencies. The benefit is that fio can manage submission rates
        independently of the device completion rates. This avoids skewed latency
        reporting if I/O gets backed up on the device side (the coordinated omission
        can increase latencies. The benefit is that fio can manage submission rates
        independently of the device completion rates. This avoids skewed latency
        reporting if I/O gets backed up on the device side (the coordinated omission

-       problem).
+       problem). Note that this option cannot reliably be used with async IO
+       engines.

 
 
 I/O rate
 
 
 I/O rate


@@ -2550,6 +2595,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


@@ -2584,6 +2636,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
 


@@ -2817,15 +2872,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
 


@@ -4136,7 +4186,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:


@@ -4161,6 +4211,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