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.
 
                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
 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
 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
 .BI nice \fR=\fPint
 Run job with given nice value.  See \fInice\fR\|(2).
 .TP