Add option for refilling IO buffers on each submit

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 3e0a31b6767aadb1855471337b50bd8643767c59..36e42aaf6b9defb210d83d0b538284bea7f6a4d6 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -219,13 +219,24 @@ filename=str      Fio normally makes up a filename based on the job name,
 opendir=str    Tell fio to recursively add any file it can find in this
                directory and down the file system tree.
 
 opendir=str    Tell fio to recursively add any file it can find in this
                directory and down the file system tree.
 

-lockfile=bool  If set, fio will lock a file internally before doing IO to it.
-               This makes it safe to share file descriptors across fio
-               jobs that run at the same time.
-
-lockfile_batch=int     Acquiring a semaphore can be quite expensive, so
-               allow a process to complete this number of IOs before releasing
-               the semaphore again. Defaults to 1.
+lockfile=str   Fio defaults to not doing any locking files before it does
+               IO to them. If a file or file descriptor is shared, fio
+               can serialize IO to that file to make the end result
+               consistent. This is usual for emulating real workloads that
+               share files. The lock modes are:
+
+                       none            No locking. The default.
+                       exclusive       Only one thread/process may do IO,
+                                       excluding all others.
+                       readwrite       Read-write locking on the file. Many
+                                       readers may access the file at the
+                                       same time, but writes get exclusive
+                                       access.
+
+               The option may be post-fixed with a lock batch number. If
+               set, then each thread/process may do that amount of IOs to
+               the file before giving up the lock. Since lock acqusition is
+               expensive, batching the lock/unlocks will speed up IO.

 
 readwrite=str
 rw=str         Type of io pattern. Accepted values are:
 
 readwrite=str
 rw=str         Type of io pattern. Accepted values are:


@@ -325,6 +336,11 @@ bs_unaligned       If this option is given, any byte size value within bsrange
 zero_buffers   If this option is given, fio will init the IO buffers to
                all zeroes. The default is to fill them with random data.
 
 zero_buffers   If this option is given, fio will init the IO buffers to
                all zeroes. The default is to fill them with random data.
 

+refill_buffers If this option is given, fio will refill the IO buffers
+               on every submit. The default is to only fill it at init
+               time and reuse that data. Only makes sense if zero_buffers
+               isn't specified, naturally.
+

 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


@@ -443,7 +459,11 @@ fsync=int  If writing to a file, issue a sync of the dirty data
                not sync the file. The exception is the sg io engine, which
                synchronizes the disk cache anyway.
 
                not sync the file. The exception is the sg io engine, which
                synchronizes the disk cache anyway.
 

-overwrite=bool If writing to a file, setup the file first and do overwrites.
+overwrite=bool If true, writes to a file will always overwrite existing
+               data. If the file doesn't already exist, it will be
+               created before the write phase begins. If the file exists
+               and is large enough for the specified write phase, nothing
+               will be done.

 
 end_fsync=bool If true, fsync file contents when the job exits.
 
 
 end_fsync=bool If true, fsync file contents when the job exits.
 


@@ -451,10 +471,6 @@ fsync_on_close=bool        If true, fio will fsync() a dirty file on close.
                This differs from end_fsync in that it will happen on every
                file close, not just at the end of the job.
 
                This differs from end_fsync in that it will happen on every
                file close, not just at the end of the job.
 

-rwmixcycle=int Value in milliseconds describing how often to switch between
-               reads and writes for a mixed workload. The default is
-               500 msecs.
-

 rwmixread=int  How large a percentage of the mix should be reads.
 
 rwmixwrite=int How large a percentage of the mix should be writes. If both
 rwmixread=int  How large a percentage of the mix should be reads.
 
 rwmixwrite=int How large a percentage of the mix should be writes. If both


@@ -471,6 +487,12 @@ norandommap        Normally fio will cover every block of the file when doing
                fio doesn't track potential block rewrites which may alter
                the calculated checksum for that block.
 
                fio doesn't track potential block rewrites which may alter
                the calculated checksum for that block.
 

+softrandommap  See norandommap. If fio runs with the random block map enabled
+               and it fails to allocate the map, if this option is set it
+               will continue without a random block map. As coverage will
+               not be as complete as with random maps, this option is
+               disabled by default.
+

 nice=int       Run the job with the given nice value. See man nice(2).
 
 prio=int       Set the io priority value of this job. Linux limits us to
 nice=int       Run the job with the given nice value. See man nice(2).
 
 prio=int       Set the io priority value of this job. Linux limits us to