Util doc lsfr (#1021)

* Update documentation for LSFR16
- Moved bulk of comments to object.
- Added an example
- Added functional test
- example based on section of test

* Update documentation for LSFR16
- Moved bulk of comments to object.
- Added an example
- Added functional test
- example based on section of test

* Update documentation for LSFR16
- Fixed typos in LFSR
- Reduce trials a little
- Add test of LFSR period

* Update documentation for LSFR16
- Fixed remaining LSFR, arrgh
- Removed intellij specific warning suppressor
- Fixed comments/scaladoc wording and case.

* Update documentation for LSFR16
- Use printable interpolator as example of printing out a Vec

1 files changed, 45 insertions, 29 deletions

diff --git a/src/test/scala/chiselTests/LFSR16.scala b/src/test/scala/chiselTests/LFSR16.scala
index 7b798518..54a3591f 100644
--- a/src/test/scala/chiselTests/LFSR16.scala
+++ b/src/test/scala/chiselTests/LFSR16.scala
@@ -6,43 +6,59 @@ import chisel3._
 import chisel3.testers.BasicTester
 import chisel3.util._
 
-class LFSR16 extends Module {
-  val io = IO(new Bundle {
-    val inc = Input(Bool())
-    val out = Output(UInt(16.W))
-  })
-  val res = RegInit(1.U(16.W))
-  when (io.inc) {
-    val nxt_res = Cat(res(0)^res(2)^res(3)^res(5), res(15,1))
-    res := nxt_res
+/**
+  * This test creates two 4 sided dice.
+  * Each cycle it adds them together and adds a count to the bin corresponding to that value
+  * The asserts check that the bins show the correct distribution.
+  */
+//scalastyle:off magic.number
+class LFSRTester extends BasicTester {
+  val bins = Reg(Vec(8, UInt(32.W)))
+
+  // Use tap points on each LFSR so values are more independent
+  val die0 = Cat(Seq.tabulate(2) { i => LFSR16()(i) })
+  val die1 = Cat(Seq.tabulate(2) { i => LFSR16()(i + 2) })
+
+  val (trial, done) = Counter(true.B, 10000)
+
+  val rollValue = die0 +& die1  // Note +& is critical because sum will need an extra bit.
+
+  bins(rollValue) := bins(rollValue) + 1.U
+
+  when(done) {
+    printf(p"bins: $bins\n") // Note using the printable interpolator p"" to print out a Vec
+
+    // test that the distribution feels right.
+    assert(bins(1) > bins(0))
+    assert(bins(2) > bins(1))
+    assert(bins(3) > bins(2))
+    assert(bins(4) < bins(3))
+    assert(bins(5) < bins(4))
+    assert(bins(6) < bins(5))
+    assert(bins(7) === 0.U)
+
+    stop()
   }
-  io.out := res
 }
 
+class LFSR16MaxPeriod extends BasicTester {
+
+  val lfsr16 = LFSR16()
+  val started = RegNext(true.B, false.B)
 
-/*
-class LFSR16Tester(c: LFSR16) extends Tester(c) {
-  var res = 1
-  for (t <- 0 until 16) {
-    val inc = rnd.nextInt(2)
-    poke(c.io.inc, inc)
-    step(1)
-    if (inc == 1) {
-      val bit = ((res >> 0) ^ (res >> 2) ^ (res >> 3) ^ (res >> 5) ) & 1;
-      res = (res >> 1) | (bit << 15);
-    }
-    expect(c.io.out, res)
+  val (_, wrap) = Counter(started, math.pow(2.0, 16).toInt - 1)
+  when (lfsr16 === 1.U && started) {
+    chisel3.assert(wrap)
+    stop()
   }
 }
-*/
-
-//TODO: Use chisel3.util version instead?
 
 class LFSRSpec extends ChiselPropSpec {
-
-  property("LFSR16 should elaborate") {
-    elaborate { new LFSR16 }
+  property("LFSR16 can be used to produce pseudo-random numbers, this tests the distribution") {
+    assertTesterPasses{ new LFSRTester }
   }
 
-  ignore("LFSR16 should return the correct result") { }
+  property("LFSR16 period tester, Period should 2^16 - 1") {
+    assertTesterPasses { new LFSR16MaxPeriod }
+  }
 }