Document random distribution

Signed-off-by: Jens Axboe <axboe@kernel.dk>

diff --git a/HOWTO b/HOWTO
index 40fe65fe9bc6d65cfc14cbe2e5565189fee2ae9d..6391b82a9c79b31fe3e3b0f2fac2dd0b6caf57ae 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -716,6 +716,25 @@ rwmixwrite=int     How large a percentage of the mix should be writes. If both
                if fio is asked to limit reads or writes to a certain rate.
                If that is the case, then the distribution may be skewed.
 
+random_distribution=str:float  By default, fio will use a completely uniform
+               random distribution when asked to perform random IO. Sometimes
+               it is useful to skew the distribution in specific ways,
+               ensuring that some parts of the data is more hot than others.
+               fio includes the following distribution models:
+
+               random          Uniform random distribution
+               zipf            Zipf distribution
+               pareto          Pareto distribution
+
+               When using a zipf or pareto distribution, an input value
+               is also needed to define the access pattern. For zipf, this
+               is the zipf theta. For pareto, it's the pareto power. Fio
+               includes a test program, genzipf, that can be used visualize
+               what the given input values will yield in terms of hit rates.
+               If you wanted to use zipf with a theta of 1.2, you would use
+               random_distribution=zipf:1.2 as the option. If a non-uniform
+               model is used, fio will disable use of the random map.
+
 norandommap    Normally fio will cover every block of the file when doing
                random IO. If this option is given, fio will just get a
                new random offset without looking at past io history. This

diff --git a/fio.1 b/fio.1
index 08d6c0f4ba3da66191ba855de21f60a4ed0b838c..2db9793fac5470f840b95db192f5ed6aad8e7334 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -580,6 +580,32 @@ 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
+.BI random_distribution \fR=\fPstr:float
+By default, fio will use a completely uniform random distribution when asked
+to perform random IO. Sometimes it is useful to skew the distribution in
+specific ways, ensuring that some parts of the data is more hot than others.
+Fio includes the following distribution models:
+.RS
+.TP
+.B random
+Uniform random distribution
+.TP
+.B zipf
+Zipf distribution
+.TP
+.B pareto
+Pareto distribution
+.TP
+.RE
+.P
+When using a zipf or pareto distribution, an input value is also needed to
+define the access pattern. For zipf, this is the zipf theta. For pareto,
+it's the pareto power. Fio includes a test program, genzipf, that can be
+used visualize what the given input values will yield in terms of hit rates.
+If you wanted to use zipf with a theta of 1.2, you would use
+random_distribution=zipf:1.2 as the option. If a non-uniform model is used,
+fio will disable use of the random map.
+.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