Allow ChiselSim to link in prebuilt software libraries #5189

jackkoenig · 2026-01-29T21:27:36Z

I'm wondering if instead of applying this to all chisel tests, we shouldn't add a new test build unit for this. Obviously they aren't harmful, but it feels a bit incongruous

Yeah I was wondering the same thing. I then thought that separating this out into a different build would complicate the whole build for no good practical reason, just aesthetics.

jackkoenig · 2026-01-30T18:33:37Z

I'm not going to block but I don't love this meaning given to the various libs by index--I'd rather we used a case class (or even named tuple, <3 Scala 3) to give names to them, but I'll let it go.

jackkoenig · 2026-01-29T21:03:21Z

This is fine but bonus points if you give an error with the bad input and a carat, e.g.

chisel/src/main/scala/chisel3/stage/ChiselAnnotations.scala

Lines 97 to 111 in fad1f6c

val filters = value.split(",")

filters.toList

// Add accumulating index to each filter for error reporting

.mapAccumulate(0) { case (idx, s) => (idx + 1 + s.length, (idx, s)) } // + 1 for removed ','

._2 // Discard accumulator

.map { case (idx, s) =>

WarningFilter.parse(s) match {

case Right(wf) => wf

case Left((jdx, msg)) =>

val carat = (" " * (idx + jdx)) + "^"

// Note tab before value and carat

throw new Exception(s"Failed to parse configuration: $msg\n $value\n $carat")

}

}

}

jackkoenig · 2026-01-29T21:22:33Z

Usually these things are either or (and also either-or with being passed as arguments).

For example, you can set the CLASSPATH environment variable, but if you set it via -cp <classpath> that wins and the environment variable is ignored.

I'm not sure if we should do that here, but maybe? What do you think?

I didn't know about the classpath behavior. My gut feeling is that since these are lists, we might as well combine them instead of having a single library provided via one mechanism effectively remove the ones provided in the other. That feels somewhat unexpected from a user point of view.

My intuition remains that overriding is more likely to be expected by users, but I'm also not going to sandbag on that because I agree that concatenation also feels reasonable.

jackkoenig · 2026-01-30T18:31:58Z

This is the greatest discovery of my life.

-Original file line number
+Diff line change
@@ Expand Up @@
         override def scalacOptions = Task { super.scalacOptions() :+ "-Wconf:cat=other-implicit-type:s" }
         override def testForkGrouping = discoveredTestClasses().grouped(8).toSeq
+        // Compile shared libraries for the simulator link library tests.
+        def sharedTestLibs: T[Seq[os.Path]] = Task(persistent = true) {
+          val srcDir = this.moduleDir / "src" / "test" / "resources" / "chisel3" / "simulator"
+          val cc = sys.env.getOrElse("CC", "cc")
+          val shared = if (scala.util.Properties.isMac) "-dynamiclib" else "-shared"
+          val srcFiles = Seq("linkLibA.c", "linkLibB.c", "linkLibC.c")
+          val libFiles = srcFiles.map { src =>
+            val lib = Task.dest / (src.stripSuffix(".c") + ".so")
+            os.proc(cc, shared, "-fPIC", srcDir / src, "-o", lib).call()
+            lib
+          }
+          libFiles
+        }
+        // Pass some of the pre-compiled shared libraries to the simulator via
+        // environment variables.
+        override def forkEnv = Task {
+          val libs = sharedTestLibs()
+          super.forkEnv() ++ Map(
+            // CHISELSIM_LIBS lets ChiselSim resolve libraries by name:
+            "CHISELSIM_LIBS" -> s"linkLibA=${libs(0)}",
+            // Also pass in a full path to test the `libraryPaths` setting:
+            "LINKLIBC_FULL_PATH" -> libs(2).toString
+          )
+        }
+        // Pass one of the pre-compiled shared libraries to the simulator via a JVM
+        // property.
+        override def forkArgs = Task {
+          val libs = sharedTestLibs()
+          super.forkArgs() :+ s"-Dchiselsim.libraries=linkLibB=${libs(1)}"
+        }
       }
       def unitTest(
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -81,6 +81,12 @@ object MacroText { @@
       * @param enableWavesAtTimeZero enable waveform dumping at time zero. This
       * requires a simulator capable of dumping waves.
       * @param randomization random initialization settings to use
+      * @param libraries Names of libraries to include in simulation. Use this to
+      * provide implementations for DPI functions, for example. The simulator will
+      * resolve these libraries to concrete files using the `CHISELSIM_LIBS`
+      * environment variable and `chiselsim.libraries` Java property.
+      * @param libraryPaths Paths to libraries to include in simulation. Use this to
+      * provide implementations for DPI functions, for example.
       */
     final class Settings[A <: RawModule] private[simulator] (
       /** Layers to turn on/off during Verilog elaboration */
@@ Expand All / @@ -90,7 +96,9 @@ final class Settings[A <: RawModule] private[simulator] ( @@
       val stopCond:              Option[MacroText.Type[A]],
       val plusArgs:              Seq[svsim.PlusArg],
       val enableWavesAtTimeZero: Boolean,
-      val randomization:         Randomization
+      val randomization:         Randomization,
+      val libraries:             Seq[String],
+      val libraryPaths:          Seq[String]
     ) {
       def copy(
@@ Expand All / @@ -102,7 +110,43 @@ final class Settings[A <: RawModule] private[simulator] ( @@
         enableWavesAtTimeZero: Boolean = enableWavesAtTimeZero,
         randomization:         Randomization = randomization
       ) =
-        new Settings(verilogLayers, assertVerboseCond, printfCond, stopCond, plusArgs, enableWavesAtTimeZero, randomization)
+        new Settings(
+          verilogLayers,
+          assertVerboseCond,
+          printfCond,
+          stopCond,
+          plusArgs,
+          enableWavesAtTimeZero,
+          randomization,
+          libraries,
+          libraryPaths
+        )
+      def withLibraries(libraries: Seq[String]): Settings[A] =
+        new Settings(
+          verilogLayers,
+          assertVerboseCond,
+          printfCond,
+          stopCond,
+          plusArgs,
+          enableWavesAtTimeZero,
+          randomization,
+          libraries,
+          libraryPaths
+        )
+      def withLibraryPaths(libraryPaths: Seq[String]): Settings[A] =
+        new Settings(
+          verilogLayers,
+          assertVerboseCond,
+          printfCond,
+          stopCond,
+          plusArgs,
+          enableWavesAtTimeZero,
+          randomization,
+          libraries,
+          libraryPaths
+        )
       private[simulator] def preprocessorDefines(
         elaboratedModule: ElaboratedModule[A]
@@ Expand Down Expand Up / @@ -150,7 +194,9 @@ object Settings { @@
         stopCond = Some(MacroText.NotSignal(get = _.reset)),
         plusArgs = Seq.empty,
         enableWavesAtTimeZero = false,
-        randomization = Randomization.random
+        randomization = Randomization.random,
+        libraries = Seq.empty,
+        libraryPaths = Seq.empty
       )
       /** Retun a default [[Settings]] for a [[RawModule]].
@@ Expand Down Expand Up / @@ -179,7 +225,9 @@ object Settings { @@
         stopCond = None,
         plusArgs = Seq.empty,
         enableWavesAtTimeZero = false,
-        randomization = Randomization.random
+        randomization = Randomization.random,
+        libraries = Seq.empty,
+        libraryPaths = Seq.empty
       )
       /** Simple factory for construcing a [[Settings]] from arguments.
@@ Expand All / @@ -193,6 +241,12 @@ object Settings { @@
         * @param printfCond a condition that guards printing of [[chisel3.printf]]s
         * @param stopCond a condition that guards terminating the simulation (via
         * `$fatal`) for asserts created from `circt_chisel_ifelsefatal` intrinsics
+        * @param libraries Names of libraries to include in simulation. Use this to
+        * provide implementations for DPI functions, for example. The simulator will
+        * resolve these libraries to concrete files using the `CHISELSIM_LIBS`
+        * environment variable and `chiselsim.libraries` Java property.
+        * @param libraryPaths Paths to libraries to include in simulation. Use this
+        * to provide implementations for DPI functions, for example.
         * @return a [[Settings]] with the provided parameters set
         */
       def apply[A <: RawModule](
@@ Expand All / @@ -210,7 +264,9 @@ object Settings { @@
         stopCond = stopCond,
         plusArgs = plusArgs,
         enableWavesAtTimeZero = enableWavesAtTimeZero,
-        randomization = randomization
+        randomization = randomization,
+        libraries = Seq.empty,
+        libraryPaths = Seq.empty
       )
     }

Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		void magicFuncA(int result) { result = 42; }

Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		void magicFuncB(int result) { result = 1337; }

Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		void magicFuncC(int result) { result = 9001; }

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow ChiselSim to link in prebuilt software libraries #5189

Diff view

Diff view

There are no files selected for viewing

jackkoenig Jan 29, 2026

Uh oh!

fabianschuiki Jan 29, 2026

Uh oh!

jackkoenig Jan 30, 2026

Uh oh!

Uh oh!

jackkoenig Jan 29, 2026

Uh oh!

jackkoenig Jan 29, 2026

Uh oh!

fabianschuiki Jan 29, 2026

Uh oh!

jackkoenig Jan 30, 2026

Uh oh!

jackkoenig Jan 30, 2026

Uh oh!

-Original file line number
+Diff line change
@@ Expand Up / @@ -3,6 +3,7 @@ package chiselTests.simulator @@
     import chisel3._
     import chisel3.layer.{block, Convention, Layer, LayerConfig}
     import chisel3.simulator._
+    import chisel3.util.circt.dpi._
     import org.scalatest.funspec.AnyFunSpec
     import org.scalatest.matchers.must.Matchers
     import org.scalatest.matchers.should.Matchers.convertToAnyShouldWrapper
@@ Expand All @@
       val backendSpecificCompilationSettings = verilator.Backend.CompilationSettings.default
     }
+    object SimulatorSpec {
+      class LinkLibraryTest extends RawModule {
+        val a = IO(Output(UInt(32.W)))
+        val b = IO(Output(UInt(32.W)))
+        val c = IO(Output(UInt(32.W)))
+        // The following DPI functions are implemented in
+        // `src/test/resources/chisel3/simulator/linkLib*.c`. The build system
+        // compiles these into shared libraries and makes them available to be linked
+        // into the simulator above.
+        a := RawUnclockedNonVoidFunctionCall("magicFuncA", UInt(32.W))(true.B)
+        b := RawUnclockedNonVoidFunctionCall("magicFuncB", UInt(32.W))(true.B)
+        c := RawUnclockedNonVoidFunctionCall("magicFuncC", UInt(32.W))(true.B)
+      }
+    }
     class SimulatorSpec extends AnyFunSpec with Matchers {
       describe("Chisel Simulator") {
         it("runs GCD correctly") {
@@ Expand Down Expand Up / @@ -333,5 +349,21 @@ class SimulatorSpec extends AnyFunSpec with Matchers { @@
             .result
         }
+        it("supports link libraries provided by the build system") {
+          val simulator = new VerilatorSimulator("test_run_dir/simulator/LinkLibrary")
+          val settings = Settings
+            .defaultRaw[SimulatorSpec.LinkLibraryTest]
+            .withLibraries(Seq("linkLibA", "linkLibB"))
+            .withLibraryPaths(Seq(sys.env("LINKLIBC_FULL_PATH")))
+          val result = simulator
+            .simulate(new SimulatorSpec.LinkLibraryTest(), settings = settings) { module =>
+              import PeekPokeAPI._
+              val dut = module.wrapped
+              (dut.a.peek().litValue, dut.b.peek().litValue, dut.c.peek().litValue)
+            }
+            .result
+          assert(result === (42, 1337, 9001))
+        }
       }
     }

-Original file line number
+Diff line change
@@ -1,5 +1,6 @@
     package svsim
+    import com.lihaoyi.unroll
     import java.io.File
     import scala.util.matching.Regex
@@ Expand Down Expand Up / @@ -68,7 +69,9 @@ case class CommonCompilationSettings( @@
       includeDirs:        Option[Seq[String]] = None,
       fileFilter:         PartialFunction[File, Boolean] = PartialFunction.empty,
       directoryFilter:    PartialFunction[File, Boolean] = PartialFunction.empty,
-      simulationSettings: CommonSimulationSettings = CommonSimulationSettings.default
+      simulationSettings: CommonSimulationSettings = CommonSimulationSettings.default,
+      // @unroll is required to maintain binary compatibility
+      @unroll linkLibraryPaths: Seq[String] = Seq.empty
     )
     object CommonCompilationSettings {
       object VerilogPreprocessorDefine {
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -351,6 +351,8 @@ final class Backend( @@
                 case Some(paths) => paths.flatMap(Seq("-y", _))
               },
+              commonSettings.linkLibraryPaths.flatMap(lib => Seq("-sv_lib", lib)),
               commonSettings.includeDirs match {
                 case None => Seq()
                 case Some(dirs) => dirs.map(dir => s"+incdir+$dir")
@@ Expand Down @@

Allow ChiselSim to link in prebuilt software libraries #5189

Allow ChiselSim to link in prebuilt software libraries #5189

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!