[chiselsim] Add subdirectory to SimulatorAPI fns (#4815)

Add a subdirectory parameter to `simulate` and `simulateRaw` methods.
This is intended for a bit of a corner case where a user wants to run
simulate multiple times within a single test or they want to customize the
test directory based on Cli arguments.

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

Author: seldridge

src/main/scala/chisel3/simulator/SimulatorAPI.scala

@@ -21,6 +21,8 @@ trait SimulatorAPI {
     * @param chiselOpts command line options to pass to Chisel
     * @param firtoolOpts command line options to pass to firtool
     * @param settings ChiselSim-related settings used for simulation
+    * @param subdirectory an optional subdirectory for the test.  This will be a
+    * subdirectory under what is provided by `testingDirectory`.
     * @param stimulus directed stimulus to use
     * @param testingDirectory a type class implementation that can be used to
     * change the behavior of where files will be created
@@ -29,10 +31,11 @@ trait SimulatorAPI {
     * by default and if you set incompatible options, the simulation will fail.
     */
   def simulateRaw[T <: RawModule](
-    module:      => T,
-    chiselOpts:  Array[String] = Array.empty,
-    firtoolOpts: Array[String] = Array.empty,
-    settings:    Settings[T] = Settings.defaultRaw[T]
+    module:       => T,
+    chiselOpts:   Array[String] = Array.empty,
+    firtoolOpts:  Array[String] = Array.empty,
+    settings:     Settings[T] = Settings.defaultRaw[T],
+    subdirectory: Option[String] = None
   )(stimulus: (T) => Unit)(
     implicit hasSimulator:        HasSimulator,
     testingDirectory:             HasTestingDirectory,
@@ -42,7 +45,13 @@ trait SimulatorAPI {
     backendSettingsModifications: svsim.BackendSettingsModifications
   ): Unit = {
 
-    hasSimulator.getSimulator
+    val modifiedTestingDirectory = subdirectory match {
+      case Some(subdir) => testingDirectory.withSubdirectory(subdir)
+      case None         => testingDirectory
+    }
+
+    hasSimulator
+      .getSimulator(modifiedTestingDirectory)
       .simulate(module = module, chiselOpts = chiselOpts, firtoolOpts = firtoolOpts, settings = settings) { module =>
         stimulus(module.wrapped)
       }
@@ -59,6 +68,8 @@ trait SimulatorAPI {
     * @param settings ChiselSim-related settings used for simulation
     * @param additionalResetCycles a number of _additional_ cycles to assert
     * reset for
+    * @param subdirectory an optional subdirectory for the test.  This will be a
+    * subdirectory under what is provided by `testingDirectory`.
     * @param stimulus directed stimulus to use
     * @param testingDirectory a type class implementation that can be used to
     * change the behavior of where files will be created
@@ -71,7 +82,8 @@ trait SimulatorAPI {
     chiselOpts:            Array[String] = Array.empty,
     firtoolOpts:           Array[String] = Array.empty,
     settings:              Settings[T] = Settings.default[T],
-    additionalResetCycles: Int = 0
+    additionalResetCycles: Int = 0,
+    subdirectory:          Option[String] = None
   )(stimulus: (T) => Unit)(
     implicit hasSimulator:        HasSimulator,
     testingDirectory:             HasTestingDirectory,
@@ -83,7 +95,8 @@ trait SimulatorAPI {
     module = module,
     chiselOpts = chiselOpts,
     firtoolOpts = firtoolOpts,
-    settings = settings
+    settings = settings,
+    subdirectory = subdirectory
   ) { dut =>
     ResetProcedure.module(additionalResetCycles)(dut)
     stimulus(dut)

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

@@ -182,6 +182,30 @@ class ChiselSimSpec extends AnyFunSpec with Matchers with ChiselSim with FileChe
       }
     }
 
+    it("should allow the user to change the subdirectory on SimulatorAPI methods") {
+      class Foo extends Module {
+        stop()
+      }
+
+      var file = FileSystems
+        .getDefault()
+        .getPath(implicitly[HasTestingDirectory].getDirectory.toString, "foo", "workdir-verilator", "Makefile")
+        .toFile
+      file.delete()
+      simulate(new Foo, subdirectory = Some("foo")) { _ => }
+      info(s"$file exists")
+      file should (exist)
+
+      file = FileSystems
+        .getDefault()
+        .getPath(implicitly[HasTestingDirectory].getDirectory.toString, "bar", "workdir-verilator", "Makefile")
+        .toFile
+      file.delete()
+      simulateRaw(new Foo, subdirectory = Some("bar")) { _ => }
+      info(s"$file exists")
+      file should (exist)
+    }
+
     // Return a Verilator `HasSimulator` that will dump waves to `trace.vcd`.
     def verilatorWithWaves = HasSimulator.simulators
       .verilator(verilatorSettings =