Merge branch 'master' of ssh://router/data/git/fio

diff --git a/HOWTO b/HOWTO
index 8f7320835c914ea54820a4b35330a8cb2d06205d..536e370ba03f0c5f3c9d3d8fc03ddd559c0cc95b 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -314,7 +314,8 @@ filesize=int        Individual file sizes. May be a range, in which case fio
 
 fill_device=bool Sets size to something really large and waits for ENOSPC (no
                space left on device) as the terminating condition. Only makes
-                sense with sequential write.
+                sense with sequential write. For a read workload, the mount
+               point will be filled first then IO started on the result.
 
 blocksize=int
 bs=int         The block size used for the io units. Defaults to 4k. Values
@@ -546,7 +547,9 @@ 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 and rwmixwrite is given and the values do not add
                up to 100%, the latter of the two will be used to override
-               the first.
+               the first. This may interfere with a given rate setting,
+               if fio is asked to limit reads or writes to a certain rate.
+               If that is the case, then the distribution may be skewed.
 
 norandommap    Normally fio will cover every block of the file when doing
                random IO. If this option is given, fio will just get a

diff --git a/fio.1 b/fio.1
index a897d27981a9b1de289121cd0ac58f48ada276ca..b984a8cbd5e17c9156c4bfd0c773480adc0e66d1 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -116,6 +116,30 @@ a number of files by separating the names with a `:' character. `\-' is a
 reserved name, meaning stdin or stdout, depending on the read/write direction
 set.
 .TP
+.BI lockfile \fR=\fPstr
+Fio defaults to not locking any 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:
+.RS
+.RS
+.TP
+.B none
+No locking. This is the default.
+.TP
+.B exclusive
+Only one thread or process may do IO at the time, excluding all others.
+.TP
+.B readwrite
+Read-write locking on the file. Many readers may access the file at the same
+time, but writes get exclusive access.
+.RE
+.P
+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 acquisition is expensive, batching the lock/unlocks will speed up IO.
+.RE
+.P
 .BI opendir \fR=\fPstr
 Recursively open any files below directory \fIstr\fR.
 .TP
@@ -162,6 +186,12 @@ been transfered, unless limited by other options (\fBruntime\fR, for instance).
 Unless \fBnr_files\fR and \fBfilesize\fR options are given, this amount will be
 divided between the available files for the job.
 .TP
+.BI fill_device \fR=\fPbool
+Sets size to something really large and waits for ENOSPC (no space left on
+device) as the terminating condition. Only makes sense with sequential write.
+For a read workload, the mount point will be filled first then IO started on
+the result.
+.TP
 .BI filesize \fR=\fPirange
 Individual file sizes. May be a range, in which case \fBfio\fR will select sizes
 for files at random within the given range, limited to \fBsize\fR in total (if
@@ -309,6 +339,14 @@ Number of I/O units to keep in flight against the file.  Default: 1.
 .BI iodepth_batch \fR=\fPint
 Number of I/Os to submit at once.  Default: \fBiodepth\fR.
 .TP
+.BI iodepth_batch_complete \fR=\fPint
+This defines how many pieces of IO to retrieve at once. It defaults to 1 which
+ means that we'll ask for a minimum of 1 IO in the retrieval process from the
+kernel. The IO retrieval will go on until we hit the limit set by
+\fBiodepth_low\fR. If this variable is set to 0, then fio will always check for
+completed events before queuing more IO. This helps reduce IO latency, at the
+cost of more retrieval system calls.
+.TP
 .BI iodepth_low \fR=\fPint
 Low watermark indicating when to start filling the queue again.  Default:
 \fBiodepth\fR. 
@@ -346,14 +384,22 @@ Percentage of a mixed workload that should be reads. Default: 50.
 .TP
 .BI rwmixwrite \fR=\fPint
 Percentage of a mixed workload that should be writes.  If \fBrwmixread\fR and
-\fBwrmixwrite\fR are given and do not sum to 100%, the latter of the two
-overrides the first.  Default: 50.
+\fBrwmixwrite\fR are given and do not sum to 100%, the latter of the two
+overrides the first. This may interfere with a given rate setting, if fio is
+asked to limit reads or writes to a certain rate. If that is the case, then
+the distribution may be skewed. Default: 50.
 .TP
 .B norandommap
 Normally \fBfio\fR will cover every block of the file when doing random I/O. If
 this parameter is given, a new offset will be chosen without looking at past
 I/O history.  This parameter is mutually exclusive with \fBverify\fR.
 .TP
+.B softrandommap
+See \fBnorandommap\fR. 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.
+.TP
 .BI nice \fR=\fPint
 Run job with given nice value.  See \fInice\fR\|(2).
 .TP
@@ -376,18 +422,27 @@ Number of blocks to issue before waiting \fBthinktime\fR microseconds.
 Default: 1.
 .TP
 .BI rate \fR=\fPint
-Cap bandwidth used by this job to this number of KiB/s.
+Cap bandwidth used by this job. The number is in bytes/sec, the normal postfix
+rules apply. You can use \fBrate\fR=500k to limit reads and writes to 500k each,
+or you can specify read and writes separately. Using \fBrate\fR=1m,500k would
+limit reads to 1MB/sec and writes to 500KB/sec. Capping only reads or writes
+can be done with \fBrate\fR=,500k or \fBrate\fR=500k,. The former will only
+limit writes (to 500KB/sec), the latter will only limit reads.
 .TP
 .BI ratemin \fR=\fPint
 Tell \fBfio\fR to do whatever it can to maintain at least the given bandwidth.
-Failing to meet this requirement will cause the job to exit.
+Failing to meet this requirement will cause the job to exit. The same format
+as \fBrate\fR is used for read vs write separation.
 .TP
 .BI rate_iops \fR=\fPint
-Cap the bandwidth to this number of IOPS.  If \fBblocksize\fR is a range, the
-smallest block size is used as the metric.
+Cap the bandwidth to this number of IOPS. Basically the same as rate, just
+specified independently of bandwidth. The same format as \fBrate\fR is used for
+read vs write seperation. If \fBblocksize\fR is a range, the smallest block
+size is used as the metric.
 .TP
 .BI rate_iops_min \fR=\fPint
-If this rate of I/O is not met, the job will exit.
+If this rate of I/O is not met, the job will exit. The same format as \fBrate\fR
+is used for read vs write seperation.
 .TP
 .BI ratecycle \fR=\fPint
 Average bandwidth for \fBrate\fR and \fBratemin\fR over this number of
@@ -415,8 +470,8 @@ as \fBruntime\fR allows.
 If set, fio will run the specified workload for this amount of time before
 logging any performance numbers. Useful for letting performance settle before
 logging results, thus minimizing the runtime required for stable results. Note
-that the ramp_time is considered lead in time for a job, thus it will increase
-the total runtime if a special timeout or runtime is specified.
+that the \fBramp_time\fR is considered lead in time for a job, thus it will
+increase the total runtime if a special timeout or runtime is specified.
 .TP
 .BI invalidate \fR=\fPbool
 Invalidate buffer-cache for the file prior to starting I/O.  Default: true.