parse: ensure that an option has a category

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 2403a5cd13048fc27e3a89de406cddbba6560aeb..e4614ea8675a0c8b2f958ad8c2d6b04e12181939 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -488,6 +488,22 @@ scramble_buffers=bool      If refill_buffers is too costly and the target is
                block compression attempts, but it will stop naive dedupe of
                blocks. Default: true.
 
                block compression attempts, but it will stop naive dedupe of
                blocks. Default: true.
 

+buffer_compress_percentage=int If this is set, then fio will attempt to
+               provide IO buffer content (on WRITEs) that compress to
+               the specified level. Fio does this by providing a mix of
+               random data and zeroes. Note that this is per block size
+               unit, for file/disk wide compression level that matches
+               this setting, you'll also want to set refill_buffers.
+
+buffer_compress_chunk=int      See buffer_compress_percentage. This
+               setting allows fio to manage how big the ranges of random
+               data and zeroed data is. Without this set, fio will
+               provide buffer_compress_percentage of blocksize random
+               data, followed by the remaining zeroed. With this set
+               to some chunk size smaller than the block size, fio can
+               alternate random and zeroed data throughout the IO
+               buffer.
+

 nrfiles=int    Number of files to use for this job. Defaults to 1.
 
 openfiles=int  Number of files to keep open at the same time. Defaults to
 nrfiles=int    Number of files to use for this job. Defaults to 1.
 
 openfiles=int  Number of files to keep open at the same time. Defaults to


@@ -627,6 +643,7 @@ iodepth_low=int     The low water mark indicating when to start filling
 
 direct=bool    If value is true, use non-buffered io. This is usually
                O_DIRECT. Note that ZFS on Solaris doesn't support direct io.
 
 direct=bool    If value is true, use non-buffered io. This is usually
                O_DIRECT. Note that ZFS on Solaris doesn't support direct io.

+               On Windows the synchronous ioengines don't support direct io.

 
 buffered=bool  If value is true, use buffered io. This is the opposite
                of the 'direct' option. Defaults to true.
 
 buffered=bool  If value is true, use buffered io. This is the opposite
                of the 'direct' option. Defaults to true.


@@ -635,6 +652,13 @@ offset=int Start io at the given offset in the file. The data before
                the given offset will not be touched. This effectively
                caps the file size at real_size - offset.
 
                the given offset will not be touched. This effectively
                caps the file size at real_size - offset.
 

+offset_increment=int   If this is provided, then the real offset becomes
+               the offset + offset_increment * thread_number, where the
+               thread number is a counter that starts at 0 and is incremented
+               for each job. This option is useful if there are several jobs
+               which are intended to operate on a file in parallel in disjoint
+               segments, with even spacing between the starting points.
+

 fsync=int      If writing to a file, issue a sync of the dirty data
                for every number of blocks given. For example, if you give
                32 as a parameter, fio will sync the file for every 32
 fsync=int      If writing to a file, issue a sync of the dirty data
                for every number of blocks given. For example, if you give
                32 as a parameter, fio will sync the file for every 32


@@ -644,7 +668,7 @@ fsync=int   If writing to a file, issue a sync of the dirty data
 
 fdatasync=int  Like fsync= but uses fdatasync() to only sync data and not
                metadata blocks.
 
 fdatasync=int  Like fsync= but uses fdatasync() to only sync data and not
                metadata blocks.

-               In FreeBSD there is no fdatasync(), this falls back to
+               In FreeBSD and Windows there is no fdatasync(), this falls back to

                using fsync()
 
 sync_file_range=str:val        Use sync_file_range() for every 'val' number of
                using fsync()
 
 sync_file_range=str:val        Use sync_file_range() for every 'val' number of


@@ -1101,6 +1125,18 @@ write_lat_log=str Same as write_bw_log, except that this option stores io
 write_bw_log=str If given, write an IOPS log of the jobs in this job
                file. See write_bw_log.
 
 write_bw_log=str If given, write an IOPS log of the jobs in this job
                file. See write_bw_log.
 

+write_iops_log=str Same as write_bw_log, but writes IOPS. If no filename is
+               given with this option, the default filename of
+               "jobname_type.log" is used. Even if the filename is given,
+               fio will still append the type of log.
+
+log_avg_msec=int By default, fio will log an entry in the iops, latency,
+               or bw log for every IO that completes. When writing to the
+               disk log, that can quickly grow to a very large size. Setting
+               this option makes fio average the each log entry over the
+               specified period of time, reducing the resolution of the log.
+               Defaults to 0.
+

 lockmem=int    Pin down the specified amount of memory with mlock(2). Can
                potentially be used instead of removing memory or booting
                with less memory to simulate a smaller amount of memory.
 lockmem=int    Pin down the specified amount of memory with mlock(2). Can
                potentially be used instead of removing memory or booting
                with less memory to simulate a smaller amount of memory.


@@ -1170,7 +1206,7 @@ gtod_cpu=int      Sometimes it's cheaper to dedicate a single thread of
                uses. Fio will manually clear it from the CPU mask of other
                jobs.
 
                uses. Fio will manually clear it from the CPU mask of other
                jobs.
 

-continue_on_error=bool Normally fio will exit the job on the first observed
+continue_on_error=str  Normally fio will exit the job on the first observed

                failure. If this option is set, fio will continue the job when
                there is a 'non-fatal error' (EIO or EILSEQ) until the runtime
                is exceeded or the I/O size specified is completed. If this
                failure. If this option is set, fio will continue the job when
                there is a 'non-fatal error' (EIO or EILSEQ) until the runtime
                is exceeded or the I/O size specified is completed. If this


@@ -1179,6 +1215,24 @@ continue_on_error=bool   Normally fio will exit the job on the first observed
                given in the stats is the first error that was hit during the
                run.
 
                given in the stats is the first error that was hit during the
                run.
 

+               The allowed values are:
+
+                       none    Exit on any IO or verify errors.
+
+                       read    Continue on read errors, exit on all others.
+
+                       write   Continue on write errors, exit on all others.
+
+                       io      Continue on any IO error, exit on all others.
+
+                       verify  Continue on verify errors, exit on all others.
+
+                       all     Continue on all errors.
+
+                       0               Backward-compatible alias for 'none'.
+
+                       1               Backward-compatible alias for 'all'.
+

 cgroup=str     Add job to this control group. If it doesn't exist, it will
                be created. The system must have a mounted cgroup blkio
                mount point for this to work. If your system doesn't have it
 cgroup=str     Add job to this control group. If it doesn't exist, it will
                be created. The system must have a mounted cgroup blkio
                mount point for this to work. If your system doesn't have it


@@ -1201,6 +1255,25 @@ uid=int          Instead of running as the invoking user, set the user ID to
 
 gid=int                Set group ID, see uid.
 
 
 gid=int                Set group ID, see uid.
 

+flow_id=int    The ID of the flow. If not specified, it defaults to being a
+               global flow. See flow.
+
+flow=int       Weight in token-based flow control. If this value is used, then
+               there is a 'flow counter' which is used to regulate the
+               proportion of activity between two or more jobs. fio attempts
+               to keep this flow counter near zero. The 'flow' parameter
+               stands for how much should be added or subtracted to the flow
+               counter on each iteration of the main I/O loop. That is, if
+               one job has 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_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.
+
+flow_sleep=int The period of time, in microseconds, to wait after the flow
+               watermark has been exceeded before retrying operations
+

 In addition, there are some parameters which are only valid when a specific
 ioengine is in use. These are used identically to normal parameters, with the
 caveat that when used on the command line, they must come after the ioengine
 In addition, there are some parameters which are only valid when a specific
 ioengine is in use. These are used identically to normal parameters, with the
 caveat that when used on the command line, they must come after the ioengine