error out if ENOSPC during file layout

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 9e339bb8d0a608a2f83b141197bd1bbbb503804b..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


@@ -2470,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


@@ -2613,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
 


@@ -2846,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
 


@@ -4165,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:


@@ -4190,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