[chiselsim] Add randomization to settings (#4835)

Add the ability to control the existing FIRRTL randomization settings via
an additional parameter to `chisel3.simulator.Settings`.  Set the default
behavior for this to always randomize.  This is a reasonable default for
Verilator or any other 2-state simulator.  For 4-state simulators, users
may want to deviate and use the provided `uniniitialized` randomization.

This commit intentionally does not try to struggle with setting
per-simulator settings that are different from each other.  While I think
this could make sense (you would like to use randomization for Verilator
and uninitialized w/ x-prop for VCS), I think that the logic necessary to
handling this is going to be too opaque for most users.  I would rather
keep this as a single setting on simulate and any simulator you use will
then simulate the same thing.  If you want to do something different, then
it is on the user.

Note: I don't expect most users to care about running different
simulators, in spite of the fact that we provide the `Cli.Simulator`
trait (and intentionally do not mix it into `ChiselSim`).  If users _do_
care about running different simulators, then they would be better served
by enumerating these as explicit tests.  I.e., I am not super concerned
about the use case of writing a test with one randomization mode and then
expecting the randomization mode to morph if the user changes the
simulator on the command line.

Signed-off-by: Schuyler Eldridge <[email protected]>

Author: seldridge

src/main/scala/chisel3/simulator/Randomization.scala

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.simulator
+
+import svsim.CommonCompilationSettings.VerilogPreprocessorDefine
+
+/** A description of how a Chisel circuit should be randomized
+  *
+  * @param registers if true, randomize the initial state of registers
+  * @param memories if true, randomize the initial state of memories
+  * @param garbageAssign
+  * @param invalidAssign
+  * @param delay an optional delay value to apply to the randomization.  This
+  * will cause the randomization to be applied this many Verilog time units
+  * after the simulation starts.
+  * @throws IllegalArgumentException if register and memory randomization are
+  * both disabled and delay or randomValue are non-empty
+  */
+final class Randomization(
+  val registers:   Boolean,
+  val memories:    Boolean,
+  val delay:       Option[Int],
+  val randomValue: Option[String]
+) {
+
+  require(
+    registers || memories || (delay.isEmpty && randomValue.isEmpty),
+    "when register and memory randomization is disabled, then `delay` and `randomValue` should be empty as they have no effect"
+  )
+
+  require(
+    delay.isEmpty || delay.get != 0,
+    "a delay of zero is illegal as this can conflict with initial blocks and simulator-specific time-zero behavior"
+  )
+
+  /** Create a copy of this [[Randomization]] changing some parameters */
+  def copy(
+    registers:   Boolean = registers,
+    memories:    Boolean = memories,
+    delay:       Option[Int] = delay,
+    randomValue: Option[String] = randomValue
+  ) = new Randomization(registers, memories, delay, randomValue)
+
+  /** Convert this to Verilog preprocessor defines */
+  private[simulator] def toPreprocessorDefines: Seq[VerilogPreprocessorDefine] = {
+    Option.when(registers)(VerilogPreprocessorDefine("RANDOMIZE_REG_INIT")).toSeq ++
+      Option.when(memories)(VerilogPreprocessorDefine("RANDOMIZE_MEM_INIT")) ++
+      delay.map(d => VerilogPreprocessorDefine("RANDOMIZE_DELAY", d.toString)) ++
+      randomValue.map(VerilogPreprocessorDefine("RANDOM", _))
+  }
+
+}
+
+object Randomization {
+
+  /** Randomize nothing
+    *
+    * This will cause the simulation to be brought up in whatever state the
+    * simulator brings up a simulation in.  If the simulator supports `x`, then
+    * uninitialized hardware will be brought up in `x`.  However, if the
+    * simulator is two-state (e.g., Verilator), then it will be brought up in a
+    * simulator-dependent state.
+    */
+  def uninitialized = new Randomization(
+    registers = false,
+    memories = false,
+    delay = None,
+    randomValue = None
+  )
+
+  /** Randomize everything
+    *
+    * This will randomize everything that the FIRRTL/Verilog ABI allows.  All
+    * Verilog that Chisel produces will have a random two-state value.  Verilog
+    * that Chisel does not have control of (e.g., blackboxes) will be brought up
+    * in a different state unless they opt-in to the FIRRTL/Verilog ABI.
+    *
+    * Non-two-state values (i.e., `x`)
+    *
+    * @note The FIRRTL/Verilog ABI for randomization is undocumented in the
+    * FIRRTL ABI specification.
+    */
+  def random = new Randomization(
+    registers = true,
+    memories = true,
+    delay = Some(1),
+    randomValue = Some("$urandom")
+  )
+
+}

src/main/scala/chisel3/simulator/Settings.scala

@@ -80,6 +80,7 @@ object MacroText {
   * simulation runtime.
   * @param enableWavesAtTimeZero enable waveform dumping at time zero. This
   * requires a simulator capable of dumping waves.
+  * @param randomization random initialization settings to use
   */
 final class Settings[A <: RawModule] private[simulator] (
   /** Layers to turn on/off during Verilog elaboration */
@@ -88,7 +89,8 @@ final class Settings[A <: RawModule] private[simulator] (
   val printfCond:            Option[MacroText.Type[A]],
   val stopCond:              Option[MacroText.Type[A]],
   val plusArgs:              Seq[svsim.PlusArg],
-  val enableWavesAtTimeZero: Boolean
+  val enableWavesAtTimeZero: Boolean,
+  val randomization:         Randomization
 ) {
 
   def copy(
@@ -97,9 +99,10 @@ final class Settings[A <: RawModule] private[simulator] (
     printfCond:            Option[MacroText.Type[A]] = printfCond,
     stopCond:              Option[MacroText.Type[A]] = stopCond,
     plusArgs:              Seq[svsim.PlusArg] = plusArgs,
-    enableWavesAtTimeZero: Boolean = enableWavesAtTimeZero
+    enableWavesAtTimeZero: Boolean = enableWavesAtTimeZero,
+    randomization:         Randomization = randomization
   ) =
-    new Settings(verilogLayers, assertVerboseCond, printfCond, stopCond, plusArgs, enableWavesAtTimeZero)
+    new Settings(verilogLayers, assertVerboseCond, printfCond, stopCond, plusArgs, enableWavesAtTimeZero, randomization)
 
   private[simulator] def preprocessorDefines(
     elaboratedModule: ElaboratedModule[A]
@@ -112,7 +115,7 @@ final class Settings[A <: RawModule] private[simulator] (
     ).flatMap {
       case (Some(a), macroName) => Some(a.toPreprocessorDefine(macroName, elaboratedModule))
       case (None, _)            => None
-    } ++ verilogLayers.preprocessorDefines(elaboratedModule)
+    } ++ verilogLayers.preprocessorDefines(elaboratedModule) ++ randomization.toPreprocessorDefines
 
   }
 
@@ -146,7 +149,8 @@ object Settings {
     printfCond = Some(MacroText.NotSignal(get = _.reset)),
     stopCond = Some(MacroText.NotSignal(get = _.reset)),
     plusArgs = Seq.empty,
-    enableWavesAtTimeZero = false
+    enableWavesAtTimeZero = false,
+    randomization = Randomization.random
   )
 
   /** Retun a default [[Settings]] for a [[RawModule]].
@@ -174,7 +178,8 @@ object Settings {
     printfCond = None,
     stopCond = None,
     plusArgs = Seq.empty,
-    enableWavesAtTimeZero = false
+    enableWavesAtTimeZero = false,
+    randomization = Randomization.random
   )
 
   /** Simple factory for construcing a [[Settings]] from arguments.
@@ -196,14 +201,16 @@ object Settings {
     printfCond:            Option[MacroText.Type[A]],
     stopCond:              Option[MacroText.Type[A]],
     plusArgs:              Seq[svsim.PlusArg],
-    enableWavesAtTimeZero: Boolean
+    enableWavesAtTimeZero: Boolean,
+    randomization:         Randomization
   ): Settings[A] = new Settings(
     verilogLayers = verilogLayers,
     assertVerboseCond = assertVerboseCond,
     printfCond = printfCond,
     stopCond = stopCond,
     plusArgs = plusArgs,
-    enableWavesAtTimeZero = enableWavesAtTimeZero
+    enableWavesAtTimeZero = enableWavesAtTimeZero,
+    randomization = randomization
   )
 
 }

src/test/scala-2/chiselTests/RecordSpec.scala

@@ -16,12 +16,12 @@ import scala.collection.immutable.{ListMap, SeqMap, VectorMap}
 
 object RecordSpec {
   class MyBundle extends Bundle {
-    val foo = UInt(32.W)
-    val bar = UInt(32.W)
+    val foo = UInt(16.W)
+    val bar = UInt(16.W)
   }
   // Useful for constructing types from CustomBundle
   // This is a def because each call to this needs to return a new instance
-  def fooBarType: CustomBundle = new CustomBundle("foo" -> UInt(32.W), "bar" -> UInt(32.W))
+  def fooBarType: CustomBundle = new CustomBundle("foo" -> UInt(16.W), "bar" -> UInt(16.W))
 
   class MyModule(output: => Record, input: => Record) extends Module {
     val io = IO(new Bundle {

src/test/scala-2/chiselTests/simulator/scalatest/ChiselSimSpec.scala

@@ -4,7 +4,8 @@ package chiselTests.simulator.scalatest
 
 import chisel3._
 import chisel3.simulator.PeekPokeAPI.FailedExpectationException
-import chisel3.simulator.{ChiselSim, HasSimulator, MacroText, Settings}
+import chisel3.simulator.{HasSimulator, MacroText, Randomization, Settings}
+import chisel3.simulator.scalatest.ChiselSim
 import chisel3.simulator.stimulus.RunUntilSuccess
 import chisel3.testing.HasTestingDirectory
 import chisel3.testing.scalatest.{FileCheck, TestingDirectory}
@@ -15,7 +16,7 @@ import org.scalatest.funspec.AnyFunSpec
 import org.scalatest.matchers.should.Matchers
 import scala.reflect.io.Directory
 
-class ChiselSimSpec extends AnyFunSpec with Matchers with ChiselSim with FileCheck with TestingDirectory {
+class ChiselSimSpec extends AnyFunSpec with Matchers with ChiselSim with FileCheck {
 
   describe("scalatest.ChiselSim") {
 
@@ -285,6 +286,95 @@ class ChiselSimSpec extends AnyFunSpec with Matchers with ChiselSim with FileChe
       }
 
     }
+
+    class RandomizationTest extends Module {
+      val in = IO(Input(UInt(32.W)))
+      val addr = IO(Input(UInt(1.W)))
+      val we = IO(Input(Bool()))
+
+      val r = IO(Output(UInt(32.W)))
+      val cm = IO(Output(UInt(32.W)))
+      val sm = IO(Output(UInt(32.W)))
+
+      private val reg = Reg(UInt(32.W))
+      private val cmem = Mem(2, UInt(32.W))
+      private val smem = SyncReadMem(2, UInt(32.W))
+
+      when(we) {
+        reg :<= in
+        cmem.write(addr, in)
+        smem.write(addr, in)
+      }
+
+      r :<= reg
+      cm :<= cmem.read(addr)
+      sm :<= smem.read(addr)
+    }
+
+    it("should have randomization on by default") {
+
+      simulate(new RandomizationTest) { dut =>
+        dut.clock.step(2)
+
+        val regValue = dut.r.peekValue().asBigInt
+        info(s"register is not zero, has value $regValue")
+        regValue should not be (0)
+
+        val cmemValue = dut.cm.peekValue().asBigInt
+        info(s"combinational read memory index zero is not zero, has value $cmemValue")
+        cmemValue should not be (0)
+
+        val smemValue = dut.sm.peekValue().asBigInt
+        info(s"sequential read memory index zero is not zero, has value $smemValue")
+        cmemValue should not be (0)
+      }
+
+    }
+
+    it("uninitialized randomization should result in zeros (for Verilator)") {
+
+      simulate(new RandomizationTest, settings = Settings.default.copy(randomization = Randomization.uninitialized)) {
+        dut =>
+          dut.clock.step(2)
+
+          val regValue = dut.r.peekValue().asBigInt
+          info(s"register is zero")
+          regValue should be(0)
+
+          val cmemValue = dut.cm.peekValue().asBigInt
+          info(s"combinational read memory index zero is zero")
+          cmemValue should be(0)
+
+          val smemValue = dut.sm.peekValue().asBigInt
+          info(s"sequential read memory index zero is zero")
+          cmemValue should be(0)
+      }
+
+    }
+
+    it("the randomization value should be user-overridable") {
+
+      simulate(
+        new RandomizationTest,
+        settings = Settings.default.copy(randomization = Randomization.random.copy(randomValue = Some("{32'd42}")))
+      ) { dut =>
+        dut.clock.step(2)
+
+        val regValue = dut.r.peekValue().asBigInt
+        info(s"register is 42")
+        regValue should be(42)
+
+        val cmemValue = dut.cm.peekValue().asBigInt
+        info(s"combinational read memory index zero is 42")
+        cmemValue should be(42)
+
+        val smemValue = dut.sm.peekValue().asBigInt
+        info(s"sequential read memory index zero is 42")
+        cmemValue should be(42)
+      }
+
+    }
+
   }
 
   describe("ChiselSim RunUntilSuccess stimulus") {