[svsim] Add -j, --build-jobs, and --verilate-jobs (#5051)

seldridge · web-flow · commit 78ba535b7464 · 2025-10-10T05:52:01.000Z
Add Verilator compilation-time options to the Verilator svsim backend.
This is added to workaround an issue observed internally where Verilator
can crash when running with full parallelism, i.e., the default `-j 0`
that was previously hard-coded in the Verilator backend.

The default behavior is preserved, but users can now set `-j` OR
`--build-jobs`/`--verilate-jobs` individually.

Signed-off-by: Schuyler Eldridge &lt;schuyler.eldridge@sifive.com&gt;
diff --git a/src/main/scala/chisel3/simulator/HasSimulator.scala b/src/main/scala/chisel3/simulator/HasSimulator.scala
@@ -42,7 +42,8 @@ object HasSimulator {
     /** A [[HasSimulator]] implementation for a Verilator simulator. */
     def verilator(
       compilationSettings: svsim.CommonCompilationSettings = svsim.CommonCompilationSettings(),
-      verilatorSettings:   svsim.verilator.Backend.CompilationSettings = svsim.verilator.Backend.CompilationSettings()
+      verilatorSettings: svsim.verilator.Backend.CompilationSettings =
+        svsim.verilator.Backend.CompilationSettings.default
     ): HasSimulator = new HasSimulator {
       override def getSimulator(implicit testingDirectory: HasTestingDirectory): Simulator[svsim.verilator.Backend] =
         new Simulator[svsim.verilator.Backend] {
diff --git a/src/main/scala/chisel3/simulator/scalatest/Cli.scala b/src/main/scala/chisel3/simulator/scalatest/Cli.scala
@@ -129,8 +129,8 @@ object Cli {
                   traceSettings = options.traceSettings.copy(enableVcd = true)
                 )
               case options: svsim.verilator.Backend.CompilationSettings =>
-                options.copy(
-                  traceStyle = options.traceStyle match {
+                options.withTraceStyle(
+                  options.traceStyle match {
                     case None =>
                       Some(
                         svsim.verilator.Backend.CompilationSettings
diff --git a/src/test/scala-2/chiselTests/MultiClockSpec.scala b/src/test/scala-2/chiselTests/MultiClockSpec.scala
@@ -125,7 +125,9 @@ class MultiClockSpec extends AnyFlatSpec with Matchers with LogUtils with Chisel
 
   it should "scope ports of memories" in {
     implicit val verilator = simulators
-      .verilator(verilatorSettings = svsim.verilator.Backend.CompilationSettings(disabledWarnings = Seq("MULTIDRIVEN")))
+      .verilator(verilatorSettings =
+        svsim.verilator.Backend.CompilationSettings.default.withDisabledWarnings(Seq("MULTIDRIVEN"))
+      )
     simulate(new MultiClockMemTest)(RunUntilFinished(21))
   }
 
diff --git a/src/test/scala-2/chiselTests/simulator/HasSimulatorSpec.scala b/src/test/scala-2/chiselTests/simulator/HasSimulatorSpec.scala
@@ -28,7 +28,7 @@ class HasSimulatorSpec extends AnyFunSpec with Matchers {
             override val backend = svsim.verilator.Backend.initializeFromProcessEnvironment()
             override val tag = "still-verilator"
             override val commonCompilationSettings = svsim.CommonCompilationSettings()
-            override val backendSpecificCompilationSettings = svsim.verilator.Backend.CompilationSettings()
+            override val backendSpecificCompilationSettings = svsim.verilator.Backend.CompilationSettings.default
             override val workspacePath = ""
           }
       }
diff --git a/src/test/scala-2/chiselTests/simulator/SimulatorSpec.scala b/src/test/scala-2/chiselTests/simulator/SimulatorSpec.scala
@@ -14,7 +14,7 @@ class VerilatorSimulator(val workspacePath: String) extends Simulator[verilator.
   val backend = verilator.Backend.initializeFromProcessEnvironment()
   val tag = "verilator"
   val commonCompilationSettings = CommonCompilationSettings()
-  val backendSpecificCompilationSettings = verilator.Backend.CompilationSettings()
+  val backendSpecificCompilationSettings = verilator.Backend.CompilationSettings.default
 }
 
 class SimulatorSpec extends AnyFunSpec with Matchers {
diff --git a/src/test/scala-2/chiselTests/simulator/scalatest/ChiselSimSpec.scala b/src/test/scala-2/chiselTests/simulator/scalatest/ChiselSimSpec.scala
@@ -212,8 +212,8 @@ class ChiselSimSpec extends AnyFunSpec with Matchers with ChiselSim with FileChe
     // Return a Verilator `HasSimulator` that will dump waves to `trace.vcd`.
     def verilatorWithVcd = HasSimulator.simulators
       .verilator(verilatorSettings =
-        svsim.verilator.Backend.CompilationSettings(
-          traceStyle = Some(
+        svsim.verilator.Backend.CompilationSettings.default.withTraceStyle(
+          Some(
             svsim.verilator.Backend.CompilationSettings
               .TraceStyle(
                 svsim.verilator.Backend.CompilationSettings.TraceKind.Vcd,
@@ -229,8 +229,8 @@ class ChiselSimSpec extends AnyFunSpec with Matchers with ChiselSim with FileChe
     // Return a Verilator `HasSimulator` that will dump waves to `trace.fst`.
     def verilatorWithFst = HasSimulator.simulators
       .verilator(verilatorSettings =
-        svsim.verilator.Backend.CompilationSettings(
-          traceStyle = Some(
+        svsim.verilator.Backend.CompilationSettings.default.withTraceStyle(
+          Some(
             svsim.verilator.Backend.CompilationSettings
               .TraceStyle(
                 svsim.verilator.Backend.CompilationSettings.TraceKind.Fst(Some(2)),
diff --git a/svsim/src/main/scala/verilator/Backend.scala b/svsim/src/main/scala/verilator/Backend.scala
@@ -22,7 +22,7 @@ object Backend {
       }
 
       /** FST tracing
-        * 
+        *
         * @param traceThreads Enable FST waveform creation using `traceThreads` separate threads
         */
       case class Fst(traceThreads: Option[Int] = None) extends Type {
@@ -66,17 +66,217 @@ object Backend {
       case object TimingEnabled extends Type
       case object TimingDisabled extends Type
     }
+
+    /** Control job parallelism in verilator */
+    object Parallelism {
+      sealed trait Type {
+        def toCompileFlags: Seq[String]
+      }
+
+      /** Apply uniform parallelism to Verilation.  This maps to `-j`. */
+      class Uniform private (num: Int) extends Type {
+        override def toCompileFlags = Seq("-j", num.toString)
+
+        private def copy(num: Int): Uniform = new Uniform(num = num)
+
+        def withNum(num: Int): Uniform = copy(num = num)
+      }
+
+      object Uniform {
+        def default: Uniform = new Uniform(num = 0)
+      }
+
+      /** Apply non-uniform parallelism to Verilation.  This allows control of
+        * `--build-jobs` and `--verilate-jobs` separately.
+        */
+      class Different private (build: Option[Int], verilate: Option[Int]) extends Type {
+        override def toCompileFlags: Seq[String] = {
+          val buildJobs:    Seq[String] = build.map(num => Seq("--build-jobs", num.toString)).toSeq.flatten
+          val verilateJobs: Seq[String] = verilate.map(num => Seq("--verilate-jobs", num.toString)).toSeq.flatten
+          buildJobs ++ verilateJobs
+        }
+
+        private def copy(build: Option[Int] = this.build, verilate: Option[Int] = this.verilate): Different =
+          new Different(
+            build = build,
+            verilate = verilate
+          )
+
+        def withBuild(build: Option[Int]): Different = copy(build = build)
+
+        def withVerilate(verilate: Option[Int]): Different = copy(verilate = verilate)
+      }
+
+      object Different {
+        def default = new Different(build = None, verilate = None)
+      }
+    }
+
+    @deprecated("use 'CompilationSettings.default' and 'with<name>' helpers", "Chisel 7.1.0")
+    def apply(
+      traceStyle:                 Option[CompilationSettings.TraceStyle] = None,
+      outputSplit:                Option[Int] = None,
+      outputSplitCFuncs:          Option[Int] = None,
+      disabledWarnings:           Seq[String] = Seq(),
+      disableFatalExitOnWarnings: Boolean = false,
+      enableAllAssertions:        Boolean = false,
+      timing:                     Option[CompilationSettings.Timing.Type] = None
+    ): CompilationSettings = CompilationSettings(
+      traceStyle,
+      outputSplit,
+      outputSplitCFuncs,
+      disabledWarnings,
+      disableFatalExitOnWarnings,
+      enableAllAssertions,
+      timing,
+      Some(CompilationSettings.Parallelism.Uniform.default)
+    )
+
+    @deprecated("avoid use of unapply", "Chisel 7.1.0")
+    def unapply(compilationSettings: CompilationSettings): Option[
+      (
+        Option[CompilationSettings.TraceStyle],
+        Option[Int],
+        Option[Int],
+        Seq[String],
+        Boolean,
+        Boolean,
+        Option[CompilationSettings.Timing.Type]
+      )
+    ] = Some(
+      (
+        compilationSettings.traceStyle,
+        compilationSettings.outputSplit,
+        compilationSettings.outputSplitCFuncs,
+        compilationSettings.disabledWarnings,
+        compilationSettings.disableFatalExitOnWarnings,
+        compilationSettings.enableAllAssertions,
+        compilationSettings.timing
+      )
+    )
+
+    def default: CompilationSettings = new CompilationSettings(
+      traceStyle = None,
+      outputSplit = None,
+      outputSplitCFuncs = None,
+      disabledWarnings = Seq(),
+      disableFatalExitOnWarnings = false,
+      enableAllAssertions = false,
+      timing = None,
+      parallelism = Some(CompilationSettings.Parallelism.Uniform.default)
+    )
+
   }
 
-  case class CompilationSettings(
-    traceStyle:                 Option[CompilationSettings.TraceStyle] = None,
-    outputSplit:                Option[Int] = None,
-    outputSplitCFuncs:          Option[Int] = None,
-    disabledWarnings:           Seq[String] = Seq(),
-    disableFatalExitOnWarnings: Boolean = false,
-    enableAllAssertions:        Boolean = false,
-    timing:                     Option[CompilationSettings.Timing.Type] = None
-  ) extends svsim.Backend.Settings
+  case class CompilationSettings private (
+    traceStyle:                 Option[CompilationSettings.TraceStyle],
+    outputSplit:                Option[Int],
+    outputSplitCFuncs:          Option[Int],
+    disabledWarnings:           Seq[String],
+    disableFatalExitOnWarnings: Boolean,
+    enableAllAssertions:        Boolean,
+    timing:                     Option[CompilationSettings.Timing.Type],
+    parallelism:                Option[CompilationSettings.Parallelism.Type]
+  ) extends svsim.Backend.Settings {
+
+    @deprecated("use 'CompilationSettings.default' and 'with<name>' helpers", "Chisel 7.1.0")
+    def this(
+      traceStyle:                 Option[CompilationSettings.TraceStyle] = None,
+      outputSplit:                Option[Int] = None,
+      outputSplitCFuncs:          Option[Int] = None,
+      disabledWarnings:           Seq[String] = Seq(),
+      disableFatalExitOnWarnings: Boolean = false,
+      enableAllAssertions:        Boolean = false,
+      timing:                     Option[CompilationSettings.Timing.Type] = None
+    ) = this(
+      traceStyle,
+      outputSplit,
+      outputSplitCFuncs,
+      disabledWarnings,
+      disableFatalExitOnWarnings,
+      enableAllAssertions,
+      timing,
+      Some(CompilationSettings.Parallelism.Uniform.default)
+    )
+
+    def _copy(
+      traceStyle:                 Option[CompilationSettings.TraceStyle] = this.traceStyle,
+      outputSplit:                Option[Int] = this.outputSplit,
+      outputSplitCFuncs:          Option[Int] = this.outputSplitCFuncs,
+      disabledWarnings:           Seq[String] = this.disabledWarnings,
+      disableFatalExitOnWarnings: Boolean = this.disableFatalExitOnWarnings,
+      enableAllAssertions:        Boolean = this.enableAllAssertions,
+      timing:                     Option[CompilationSettings.Timing.Type] = this.timing,
+      parallelism:                Option[CompilationSettings.Parallelism.Type] = this.parallelism
+    ): CompilationSettings = CompilationSettings(
+      traceStyle = traceStyle,
+      outputSplit = outputSplit,
+      outputSplitCFuncs = outputSplitCFuncs,
+      disabledWarnings = disabledWarnings,
+      disableFatalExitOnWarnings = disableFatalExitOnWarnings,
+      enableAllAssertions = enableAllAssertions,
+      timing = timing,
+      parallelism = parallelism
+    )
+
+    @deprecated("don't use the copy method, use 'with<name>' single setters", "Chisel 7.1.0")
+    def copy(
+      traceStyle:                 Option[CompilationSettings.TraceStyle] = this.traceStyle,
+      outputSplit:                Option[Int] = this.outputSplit,
+      outputSplitCFuncs:          Option[Int] = this.outputSplitCFuncs,
+      disabledWarnings:           Seq[String] = this.disabledWarnings,
+      disableFatalExitOnWarnings: Boolean = this.disableFatalExitOnWarnings,
+      enableAllAssertions:        Boolean = this.enableAllAssertions,
+      timing:                     Option[CompilationSettings.Timing.Type] = this.timing
+    ): CompilationSettings = _copy(
+      traceStyle = traceStyle,
+      outputSplit = outputSplit,
+      outputSplitCFuncs = outputSplitCFuncs,
+      disabledWarnings = disabledWarnings,
+      disableFatalExitOnWarnings = disableFatalExitOnWarnings,
+      enableAllAssertions = enableAllAssertions,
+      timing = timing,
+      parallelism = this.parallelism
+    )
+
+    // Suppress generation of private copy with default arguments by Scala 3
+    private def copy(
+      traceStyle:                 Option[CompilationSettings.TraceStyle],
+      outputSplit:                Option[Int],
+      outputSplitCFuncs:          Option[Int],
+      disabledWarnings:           Seq[String],
+      disableFatalExitOnWarnings: Boolean,
+      enableAllAssertions:        Boolean,
+      timing:                     Option[CompilationSettings.Timing.Type],
+      parallelism:                Option[CompilationSettings.Parallelism.Type]
+    ): CompilationSettings = _copy(
+      traceStyle = traceStyle,
+      outputSplit = outputSplit,
+      outputSplitCFuncs = outputSplitCFuncs,
+      disabledWarnings = disabledWarnings,
+      disableFatalExitOnWarnings = disableFatalExitOnWarnings,
+      enableAllAssertions = enableAllAssertions,
+      timing = timing,
+      parallelism = Some(CompilationSettings.Parallelism.Uniform.default)
+    )
+
+    def withTraceStyle(traceStyle: Option[CompilationSettings.TraceStyle]) = _copy(traceStyle = traceStyle)
+
+    def withOutputSplit(outputSplit: Option[Int]) = _copy(outputSplit = outputSplit)
+
+    def withOutputSplitCFuncs(outputSplitCFuncs: Option[Int]) = _copy(outputSplitCFuncs = outputSplitCFuncs)
+
+    def withDisabledWarnings(disabledWarnings: Seq[String]) = _copy(disabledWarnings = disabledWarnings)
+
+    def withDisableFatalExitOnWarnings(disableFatalExitOnWarnings: Boolean) =
+      _copy(disableFatalExitOnWarnings = disableFatalExitOnWarnings)
+
+    def withEnableAllAssertions(enableAllAssertions: Boolean) = _copy(enableAllAssertions = enableAllAssertions)
+
+    def withTiming(timing: Option[CompilationSettings.Timing.Type]) = _copy(timing = timing)
+
+    def withParallelism(parallelism: Option[CompilationSettings.Parallelism.Type]) = _copy(parallelism = parallelism)
+  }
 
   def initializeFromProcessEnvironment() = {
     val output = mutable.ArrayBuffer.empty[String]
@@ -114,13 +314,17 @@ final class Backend(executablePath: String) extends svsim.Backend {
       "--cc",
       "--exe",
       "--build",
-      "-j", "0",
       "-o", s"../$outputBinaryName",
       "--top-module", topModuleName,
       "--Mdir", "verilated-sources",
       "--assert"
     ))
 
+    backendSpecificSettings.parallelism match {
+      case Some(parallelism) => addArg(parallelism.toCompileFlags)
+      case None => ()
+    }
+
     commonSettings.libraryExtensions.foreach { extensions =>
       addArg(Seq((Seq("+libext") ++ extensions).mkString("+")))
     }
diff --git a/svsim/src/test/scala/BackendSpec.scala b/svsim/src/test/scala/BackendSpec.scala
@@ -155,8 +155,8 @@ class VerilatorSpec extends BackendSpec {
 
   import verilator.Backend.CompilationSettings._
   val backend = CustomVerilatorBackend(verilator.Backend.initializeFromProcessEnvironment())
-  val compilationSettings = verilator.Backend.CompilationSettings(
-    traceStyle = Some(TraceStyle(TraceKind.Vcd, traceUnderscore = false))
+  val compilationSettings = verilator.Backend.CompilationSettings.default.withTraceStyle(
+    Some(TraceStyle(TraceKind.Vcd, traceUnderscore = false))
   )
   test("verilator", backend)(compilationSettings)
 
@@ -174,7 +174,7 @@ class VerilatorSpec extends BackendSpec {
       )(
         workingDirectoryTag = "verilator",
         commonSettings = CommonCompilationSettings(),
-        backendSpecificSettings = compilationSettings.copy(traceStyle = None),
+        backendSpecificSettings = compilationSettings.withTraceStyle(None),
         customSimulationWorkingDirectory = None,
         verbose = false
       )
@@ -197,8 +197,8 @@ class VerilatorFstTraceSpec extends BackendSpec {
 
   import verilator.Backend.CompilationSettings._
   val backend = CustomVerilatorBackend(verilator.Backend.initializeFromProcessEnvironment())
-  val compilationSettings = verilator.Backend.CompilationSettings(
-    traceStyle = Some(TraceStyle(TraceKind.Fst(), traceUnderscore = true))
+  val compilationSettings = verilator.Backend.CompilationSettings.default.withTraceStyle(
+    Some(TraceStyle(TraceKind.Fst(), traceUnderscore = true))
   )
   test("verilator", backend)(compilationSettings)
 
diff --git a/svsim/src/test/scala/CommandLineSpec.scala b/svsim/src/test/scala/CommandLineSpec.scala

Original file line number	Diff line number	Diff line change
`@@ -125,7 +125,9 @@ class MultiClockSpec extends AnyFlatSpec with Matchers with LogUtils with Chisel`
`125`	`125`
`126`	`126`	`it should "scope ports of memories" in {`
`127`	`127`	`implicit val verilator = simulators`
`128`		`- .verilator(verilatorSettings = svsim.verilator.Backend.CompilationSettings(disabledWarnings = Seq("MULTIDRIVEN")))`
	`128`	`+ .verilator(verilatorSettings =`
	`129`	`+ svsim.verilator.Backend.CompilationSettings.default.withDisabledWarnings(Seq("MULTIDRIVEN"))`
	`130`	`+ )`
`129`	`131`	`simulate(new MultiClockMemTest)(RunUntilFinished(21))`
`130`	`132`	`}`
`131`	`133`
Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ class HasSimulatorSpec extends AnyFunSpec with Matchers {`
`28`	`28`	`override val backend = svsim.verilator.Backend.initializeFromProcessEnvironment()`
`29`	`29`	`override val tag = "still-verilator"`
`30`	`30`	`override val commonCompilationSettings = svsim.CommonCompilationSettings()`
`31`		`- override val backendSpecificCompilationSettings = svsim.verilator.Backend.CompilationSettings()`
	`31`	`+ override val backendSpecificCompilationSettings = svsim.verilator.Backend.CompilationSettings.default`
`32`	`32`	`override val workspacePath = ""`
`33`	`33`	`}`
`34`	`34`	`}`
Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,7 @@ class VerilatorSimulator(val workspacePath: String) extends Simulator[verilator.`
`14`	`14`	`val backend = verilator.Backend.initializeFromProcessEnvironment()`
`15`	`15`	`val tag = "verilator"`
`16`	`16`	`val commonCompilationSettings = CommonCompilationSettings()`
`17`		`- val backendSpecificCompilationSettings = verilator.Backend.CompilationSettings()`
	`17`	`+ val backendSpecificCompilationSettings = verilator.Backend.CompilationSettings.default`
`18`	`18`	`}`
`19`	`19`
`20`	`20`	`class SimulatorSpec extends AnyFunSpec with Matchers {`