[chiselsim] Add RunUntilSuccess stimulus

Add new stimulus, `RunUntilSuccess`, which can be used to run a simulation
until a user-specified "success" port asserts.  This is added as a
complementary testing approach to `RunUntilFinished` whish is needed for
some environments where the test harness cannot terminate on its own or
the test harness is re-used in a separate, non-ChiselSim testing context
where it cannot terminate on its own.

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

Author: seldridge

src/main/scala/chisel3/simulator/stimulus/RunUntilFinished.scala

@@ -8,6 +8,8 @@ import chisel3.simulator.Exceptions
 
 /** Stimulus that will run a simulation, expecting a [[chisel3.stop]] (a Verilog
   * `$finish`) to occur before a maximum number of cycles has elapsed.
+  *
+  * @see [[RunUntilSuccess]]
   */
 trait RunUntilFinished[A] extends Stimulus.Type[A] {
 

src/main/scala/chisel3/simulator/stimulus/RunUntilSuccess.scala

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.simulator.stimulus
+
+import chisel3.{Bool, Clock, Module}
+import chisel3.simulator.AnySimulatedModule
+import chisel3.simulator.Exceptions
+
+/** Stimulus that will run a simulation expecting a "success" port to assert.
+  *
+  * If the specified "success" port does not assert, then an
+  * [[Exceptions.Timeout]] will be thrown.
+  *
+  * @see [[RunUntilFinished]]
+  */
+trait RunUntilSuccess[A] extends Stimulus.Type[A] {
+
+  /** The maximum number of cycles. */
+  protected def _maxCycles: Int
+
+  /** A function that returns the clock to tick. */
+  protected def _getClock: (A) => Clock
+
+  /** A function that returns the success port. */
+  protected def _getSuccess: (A) => Bool
+
+  /** Apply stimulus to the unit
+    *
+    * @param the unit to apply stimulus to
+    */
+  override final def apply(dut: A): Unit = {
+    val module = AnySimulatedModule.current
+    val clock = module.port(_getClock(dut))
+    val success = module.port(_getSuccess(dut))
+
+    clock
+      .tick(
+        timestepsPerPhase = 1,
+        maxCycles = _maxCycles,
+        inPhaseValue = 1,
+        outOfPhaseValue = 0,
+        sentinel = Some((success, 1)),
+        checkElapsedCycleCount = (count: BigInt) => {
+          if (count == _maxCycles)
+            throw new Exceptions.Timeout(_maxCycles, "Expected simulation to assert 'success' port")
+        }
+      )
+  }
+
+}
+
+object RunUntilSuccess {
+
+  /** Return stimulus for a [[Module]]
+    *
+    * @param maxCycles the maximum number of cycles to run the unit for before a
+    * timeout
+    * @param getSuccess a function to return a port which asserts when the
+    * simulation has sucessfully finished
+    */
+  def module[A <: Module](maxCycles: Int, getSuccess: A => Bool): RunUntilSuccess[A] = new RunUntilSuccess[A] {
+
+    override protected final val _maxCycles = maxCycles
+
+    override protected final val _getClock = _.clock
+
+    override protected final val _getSuccess = getSuccess
+
+  }
+
+  /** Return stimulus for any type.  This requires the user to specify how to
+    * extract the clock and the success port from the type.
+    *
+    * @param maxCycles the maximum number of cycles to run the unit for before a
+    * timeout
+    * @param getClock a function to return a clock from the unit
+    * @param getSuccess a function to return a port which asserts when the
+    * simulation has sucessfully finished
+    */
+  def any[A](maxCycles: Int, getClock: A => Clock, getSuccess: A => Bool): RunUntilSuccess[A] = new RunUntilSuccess[A] {
+
+    override protected final val _maxCycles = maxCycles
+
+    override protected final val _getClock = getClock
+
+    override protected final val _getSuccess = getSuccess
+
+  }
+
+  /** Return default stimulus.  This is the same as [[module]].
+    *
+    * @param maxCycles the maximum number of cycles to run the unit for before a
+    * timeout
+    * @param getSuccess a function to return a port which asserts when the
+    * simulation has sucessfully finished
+    */
+  def apply[A <: Module](maxCycles: Int, getSuccess: A => Bool): RunUntilSuccess[A] = module(maxCycles, getSuccess)
+
+}

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

@@ -5,8 +5,10 @@ package chiselTests.simulator.scalatest
 import chisel3._
 import chisel3.simulator.PeekPokeAPI.FailedExpectationException
 import chisel3.simulator.{ChiselSim, HasSimulator, MacroText, Settings}
+import chisel3.simulator.stimulus.RunUntilSuccess
 import chisel3.testing.HasTestingDirectory
 import chisel3.testing.scalatest.{FileCheck, TestingDirectory}
+import chisel3.util.Counter
 import chisel3.util.circt.{PlusArgsTest, PlusArgsValue}
 import java.nio.file.FileSystems
 import org.scalatest.funspec.AnyFunSpec
@@ -285,4 +287,23 @@ class ChiselSimSpec extends AnyFunSpec with Matchers with ChiselSim with FileChe
     }
   }
 
+  describe("ChiselSim RunUntilSuccess stimulus") {
+
+    class SuccessAfterFourCycles extends Module {
+      val success = IO(Output(Bool()))
+      success :<= Counter(true.B, 4)._2
+    }
+
+    it("should report success for a passing Module") {
+      simulate(new SuccessAfterFourCycles)(RunUntilSuccess(maxCycles = 8, getSuccess = _.success))
+    }
+
+    it("should throw an exception for a failing Module") {
+      intercept[chisel3.simulator.Exceptions.Timeout] {
+        simulate(new SuccessAfterFourCycles)(RunUntilSuccess(maxCycles = 2, getSuccess = _.success))
+      }
+    }
+
+  }
+
 }