lfsr: add HOWTO and man page documentation

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

diff --git a/HOWTO b/HOWTO
index 32e5d668c89e42efec4704b2db8686afc32e17c2..6d541afb412632fdc290b6d5d0b6453b5601be99 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -753,6 +753,23 @@ softrandommap=bool See norandommap. If fio runs with the random block map
                will not be as complete as with random maps, this option is
                disabled by default.
 
+random_generator=str   Fio supports the following engines for generating
+               IO offsets for random IO:
+
+               tausworthe      Strong 2^88 cycle random number generator
+               lfsr            Linear feedback shift register generator
+
+               Tausworthe is a strong random number generator, but it
+               requires tracking on the side if we want to ensure that
+               blocks are only read or written once. LFSR guarantees
+               that we never generate the same offset twice, and it's
+               also less computationally expensive. It's not a true
+               random generator, however, though for IO purposes it's
+               typically good enough. LFSR only works with single
+               block sizes, not with workloads that use multiple block
+               sizes. If used with such a workload, fio may read or write
+               some blocks multiple times.
+               
 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

diff --git a/fio.1 b/fio.1
index 2db9793fac5470f840b95db192f5ed6aad8e7334..7c622938b1360cbd7497c605fa891d5831b26857 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -617,6 +617,26 @@ 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 random_generator \fR=\fPstr
+Fio supports the following engines for generating IO offsets for random IO:
+.RS
+.TP
+.B tausworthe
+Strong 2^88 cycle random number generator
+.TP
+.B lfsr
+Linear feedback shift register generator
+.TP
+.RE
+.P
+Tausworthe is a strong random number generator, but it requires tracking on the
+side if we want to ensure that blocks are only read or written once. LFSR
+guarantees that we never generate the same offset twice, and it's also less
+computationally expensive. It's not a true random generator, however, though
+for IO purposes it's typically good enough. LFSR only works with single block
+sizes, not with workloads that use multiple block sizes. If used with such a
+workload, fio may read or write some blocks multiple times.
+.TP
 .BI nice \fR=\fPint
 Run job with given nice value.  See \fInice\fR\|(2).
 .TP