How to emit vcd file when using chisel3.simulator for testing?

[longfangsong]

I'm using chisel version 6.2.0, and with the following code:

// TopTest.scala
package test

import Serial.Top
import chisel3._
import chisel3.simulator.EphemeralSimulator._
import org.scalatest.flatspec.AnyFlatSpec

class TopSpec extends AnyFlatSpec {
  behavior of "Top"
  it should "do something" in {
    simulate(new Top) { top =>
        top.clock.step(1)
        top.io.rxWire.poke(true.B)
        top.clock.step(1)
        top.io.rxWire.poke(false.B)
        top.clock.step(1)
    }
  }
}

But I cannot find any vcd file generated when sbt run test, and I cannot find out how to generate it.

Is there anything I am missing?

I guess it is related with #3952?

[hakan-demirli]

I was also looking for an answer and here is what I have found:

Currently it is not possible to dump vcd files without extending the existing simulator. Existing one is EphemeralSimulator object which uses a DefaultSimulator class which extends SingleBackendSimulator with a verilator.Backend.
https://github.com/chipsalliance/chisel/blob/ce05462c239deec8aee0704efbd3a71e8b64ec49/src/main/scala/chisel3/simulator/EphemeralSimulator.scala

In the DefaultSimulator class, the backendSpecificCompilationSettings is set to verilator.Backend.CompilationSettings(), which is the default settings. To enable VCD generation, you would need to modify these settings to include:

traceStyle = Some(CompilationSettings.TraceStyle.Vcd(traceUnderscore = true))

However, the DefaultSimulator class is private and its settings are not exposed for modification. Therefore, you might need to create your own simulator class that extends SingleBackendSimulator and allows you to specify your own backendSpecificCompilationSettings.
Here is an example simulator that can emit vcd file: https://github.com/rameloni/tywaves-chisel-demo/blob/main/src/main/scala/tywaves/simulator/BetterEphemeralSimulator.scala

It is unfortunate that chisel-template is using svsim. Mostly new users use the template and they do not know anything about chisel test frameworks. I also assume most users expect at least a traditional testing framework that supports waveforms. So, offering a half-done simulator with a subpar functionality is doing more bad than good for the adoption of Chisel.

[Emin017]

I also find a demo here: https://github.com/rameloni/tywaves-chisel-demo

[seldridge]

The missing thing is an object like EphemeralSimulator which does actual writes to the disk as opposed to putting everything in temporary directories.

[rameloni]

I recently updated BetterEphemeralSimulator and split it into two new simulators.
It made use of both generic features and also features related to my waveform viewer project.

For general usage you can make use of ParametricSimulator now which doesn't have all the additional information used in the viewer and now works for all circuits supported by svsim https://github.com/rameloni/tywaves-chisel-demo/blob/main/src/main/scala/tywaves/simulator/ParametricSimulator.scala

While TywavesSimulator in the demo now has some issues mainly related to the debug information generation. I'm working on that at the moment.

[edwardcwang]

Adding a solution for vanilla Chisel 6.5 if we want to avoid importing any additional libraries beyond just Chisel.

#4246 (comment)

[kazutomo]

Does Chisel 6.x provide a way to dump a VCD file like chiseltest does? Should we import ParametricSimulator or TywavesSimulator, or continue using the hacked EphemeralSimulator?

[seldridge]

There was a software architecture mistake in the design of Chiselsim in Chisel 6 which offloads this onto the user. This is fixed in the soon-to-be-relased Chisel 7.

The software architecture mistake was that Chiselsim was more about providing the pieces to build a simulator as opposed to actually providing that simulator. The expectation was that different users had different testing needs and anybody using this would write their own custom simulator in their src/test/ area. This had some benefits:

1. Different projects and different employers have different environments, simulator defaults, and directory structures.
2. This avoids ChiselSim having to be everything to everyone.

Note 1: This approach has a lot of problems. A default simulator isn't that hard to write, so why not just put it in upstream? The wrangling of different options, environments, etc. isn't that hard, it just needs some thought.

Chisel 6 Example

If you want to do this on Chisel 6, you can do it with a simulator like the one defined below. I'll also accept any PR that adds something like this to the Chisel 6.x branch and the Chisel main branch and deprecates it there. There are much better APIs on Chisel main today that will be made available in Chisel 7 when it is released very soon. (More info in the second example.):

//> using scala "2.13.16"
//> using repository sonatype-s01:snapshots
//> using dep "org.chipsalliance::chisel::6.7.0"
//> using plugin "org.chipsalliance:::chisel-plugin::6.7.0"
//> using options "-unchecked", "-deprecation", "-language:reflectiveCalls", "-feature", "-Xcheckinit", "-Xfatal-warnings", "-Ywarn-dead-code", "-Ywarn-unused", "-Ymacro-annotations"

import chisel3._
import chisel3.simulator.{PeekPokeAPI, SingleBackendSimulator}
import chisel3.util.Counter
import svsim.{CommonCompilationSettings, verilator}

class Foo extends Module {

  val (count, done) = Counter(true.B, 8)

  when(done) {
    stop()
  }

  printf("%d\n", count)
}

object DefaultSimulator extends PeekPokeAPI {

  def simulate[T <: RawModule](
      module: => T,
      buildDir: String,
      enableWaves: Boolean = false
  )(body: (T) => Unit): Unit = {
    makeSimulator(buildDir, enableWaves)
      .simulate(module) { module =>
        module.controller.setTraceEnabled(enableWaves)
        body(module.wrapped)
      }
      .result
  }

  private class DefaultSimulator(
      val workspacePath: String,
      enableWaves: Boolean = false
  ) extends SingleBackendSimulator[verilator.Backend] {
    val backend = verilator.Backend.initializeFromProcessEnvironment()
    val tag = "default"
    val commonCompilationSettings = CommonCompilationSettings()
    val backendSpecificCompilationSettings = {
      val settings = verilator.Backend.CompilationSettings()
      if (enableWaves) {
        settings.copy(
          traceStyle = Some(verilator.Backend.CompilationSettings.TraceStyle.Vcd(traceUnderscore = false))
        )
      } else {
        settings
      }
    }
  }

  private def makeSimulator(
      buildDir: String,
      enableWaves: Boolean
  ): DefaultSimulator = {
    new DefaultSimulator(buildDir, enableWaves)
  }

}

import DefaultSimulator._

object Main extends App {

  simulate(new Foo, buildDir = "build", enableWaves = true) { dut =>
    dut.clock.step(10)
  }

}

If you run this, you get the following output and directory structure:

# scala-cli Waves6x.scala
0
1
2
3
4
5
6
7
0
1
# tree build
build
├── generated-sources
│   ├── c-dpi-bridge.cpp
│   ├── simulation-driver.cpp
│   └── testbench.sv
├── primary-sources
│   └── Foo.sv
├── support-artifacts
│   └── filelist.f
└── workdir-default
    ├── Makefile
    ├── compilation-log.txt
    ├── execution-script.txt
    ├── simulation
    ├── simulation-log.txt
    ├── trace.vcd
    └── verilated-sources
        ├── VsvsimTestbench.cpp
        ├── VsvsimTestbench.h
        ├── VsvsimTestbench.mk
        ├── VsvsimTestbench__ALL.a
        ├── VsvsimTestbench__ALL.cpp
        ├── VsvsimTestbench__ALL.d
        ├── VsvsimTestbench__ALL.o
        ├── VsvsimTestbench__Dpi.cpp
        ├── VsvsimTestbench__Dpi.h
        ├── VsvsimTestbench__Dpi_Export__0.cpp
        ├── VsvsimTestbench__Syms.cpp
        ├── VsvsimTestbench__Syms.h
        ├── VsvsimTestbench__TraceDecls__0__Slow.cpp
        ├── VsvsimTestbench__Trace__0.cpp
        ├── VsvsimTestbench__Trace__0__Slow.cpp
        ├── VsvsimTestbench___024root.h
        ├── VsvsimTestbench___024root__DepSet_h06920d97__0.cpp
        ├── VsvsimTestbench___024root__DepSet_h06920d97__0__Slow.cpp
        ├── VsvsimTestbench___024root__DepSet_h1687f531__0.cpp
        ├── VsvsimTestbench___024root__DepSet_h1687f531__0__Slow.cpp
        ├── VsvsimTestbench___024root__Slow.cpp
        ├── VsvsimTestbench__pch.h
        ├── VsvsimTestbench__ver.d
        ├── VsvsimTestbench__verFiles.dat
        ├── VsvsimTestbench_classes.mk
        ├── c-dpi-bridge.d
        ├── c-dpi-bridge.o
        ├── simulation-driver.d
        ├── simulation-driver.o
        ├── verilated.d
        ├── verilated.o
        ├── verilated_dpi.d
        ├── verilated_dpi.o
        ├── verilated_threads.d
        ├── verilated_threads.o
        ├── verilated_vcd_c.d
        └── verilated_vcd_c.o

6 directories, 48 files

Note 2: you get both test directory permanence and a trace.vcd which you can feed to surfer or your favorite waveform viewer. You can customize the directory however you want.

Note 3: The simulation doesn't actually terminate. This is a longstanding bug in ChiselSim that was not understood at the time. A simulation is supposed to terminate when it hits a $finish. However, the way ChiselSim drove the simulation in Verilator didn't properly handle this (and you can drive a Verilator simulation such that it won't immediately exit on a $finish). This is fixed on Chisel main.

Note 4: You don't need any external libraries or hacks to Chisel internals to do this.

Chisel 7

Using a recent snapshot release you can use the following:

//> using scala "2.13.16"
//> using repository sonatype-s01:snapshots
//> using dep "org.chipsalliance::chisel::7.0.0-M2+588-cf353ccf-SNAPSHOT"
//> using plugin "org.chipsalliance:::chisel-plugin::7.0.0-M2+588-cf353ccf-SNAPSHOT"
//> using options "-unchecked", "-deprecation", "-language:reflectiveCalls", "-feature", "-Xcheckinit", "-Xfatal-warnings", "-Ywarn-dead-code", "-Ywarn-unused", "-Ymacro-annotations"

import chisel3._
import chisel3.simulator.ChiselSim
import chisel3.simulator.HasSimulator
import chisel3.simulator.stimulus.{ResetProcedure, RunUntilFinished}
import chisel3.util.Counter

class Foo extends Module {

  val (count, done) = Counter(true.B, 8)

  when(done) {
    stop()
  }

  printf("%d\n", count)
}

object Main extends App with ChiselSim {

  implicit val verilator: HasSimulator = HasSimulator.simulators
    .verilator(verilatorSettings =
      svsim.verilator.Backend.CompilationSettings(
        traceStyle = Some(
          svsim.verilator.Backend.CompilationSettings.TraceStyle
            .Vcd(traceUnderscore = true, "trace.vcd")
        )
      )
    )

  simulateRaw(new Foo) { dut =>
    enableWaves()
    ResetProcedure.module()(dut)
    RunUntilFinished(10)(dut)
  }

}

If you run this you get the output below and the following directory structure:

# scala-cli Waves7x.scala
0
1
2
3
4
5
6
7
# tree build
build
└── chiselsim
    └── 2025-03-16T15-33-39.876784
        ├── generated-sources
        │   ├── c-dpi-bridge.cpp
        │   ├── simulation-driver.cpp
        │   └── testbench.sv
        ├── primary-sources
        │   ├── Foo.sv
        │   └── verification
        │       ├── Foo_Verification.sv
        │       ├── assert
        │       │   └── layers-Foo-Verification-Assert.sv
        │       ├── assume
        │       │   └── layers-Foo-Verification-Assume.sv
        │       ├── cover
        │       │   └── layers-Foo-Verification-Cover.sv
        │       └── layers-Foo-Verification.sv
        ├── support-artifacts
        │   ├── filelist.f
        │   └── verification
        │       ├── assert
        │       ├── assume
        │       └── cover
        └── workdir-verilator
            ├── Makefile
            ├── compilation-log.txt
            ├── execution-script.txt
            ├── simulation
            ├── simulation-log.txt
            ├── trace.vcd
            └── verilated-sources
                ├── VsvsimTestbench.cpp
                ├── VsvsimTestbench.h
                ├── VsvsimTestbench.mk
                ├── VsvsimTestbench__ALL.a
                ├── VsvsimTestbench__ALL.cpp
                ├── VsvsimTestbench__ALL.d
                ├── VsvsimTestbench__ALL.o
                ├── VsvsimTestbench__Dpi.cpp
                ├── VsvsimTestbench__Dpi.h
                ├── VsvsimTestbench__Dpi_Export__0.cpp
                ├── VsvsimTestbench__Syms.cpp
                ├── VsvsimTestbench__Syms.h
                ├── VsvsimTestbench__TraceDecls__0__Slow.cpp
                ├── VsvsimTestbench__Trace__0.cpp
                ├── VsvsimTestbench__Trace__0__Slow.cpp
                ├── VsvsimTestbench___024root.h
                ├── VsvsimTestbench___024root__DepSet_h06920d97__0.cpp
                ├── VsvsimTestbench___024root__DepSet_h06920d97__0__Slow.cpp
                ├── VsvsimTestbench___024root__DepSet_h1687f531__0.cpp
                ├── VsvsimTestbench___024root__DepSet_h1687f531__0__Slow.cpp
                ├── VsvsimTestbench___024root__Slow.cpp
                ├── VsvsimTestbench___024unit.h
                ├── VsvsimTestbench___024unit__DepSet_hb827a8aa__0__Slow.cpp
                ├── VsvsimTestbench___024unit__Slow.cpp
                ├── VsvsimTestbench__pch.h
                ├── VsvsimTestbench__ver.d
                ├── VsvsimTestbench__verFiles.dat
                ├── VsvsimTestbench_classes.mk
                ├── c-dpi-bridge.d
                ├── c-dpi-bridge.o
                ├── simulation-driver.d
                ├── simulation-driver.o
                ├── verilated.d
                ├── verilated.o
                ├── verilated_dpi.d
                ├── verilated_dpi.o
                ├── verilated_threads.d
                ├── verilated_threads.o
                ├── verilated_vcd_c.d
                └── verilated_vcd_c.o

16 directories, 56 files

Note 5: This is using one of two ChiselSim APIs. This is using the generic one that is not tied to Scalatest: chisel3.simulator.ChiselSim. This one will default to using timestamp-based permanent output directories. There is a second one that is more closely integrated with Scalatest: chisel3.simulator.scalatest.ChiselSim. The Scalatest-specific version will use directories derived from the test name. There is more information in the documentation here: https://www.chisel-lang.org/docs/explanations/testing#chiselsim (Also, the testing directory is implemented with a typeclass pattern and you can customize it however you'd like! The timestamp-based and scalatest-based are just two implementations of this typeclass.)

Note 6: The simulation actually terminates correctly on a stop/$finish. Many bugs were fixed in ChiselSim as part of the forthcoming Chisel 7. Much of this is related to throwing good exceptions on failures. Previously, many ChiselSim failures would get bundled as an svsim error, EndOfMessagesException, which would require interpretation by a user-implemented simulator. (When you implement something like DefaultSimulator above, the expectation is that you would watch for these exceptions. 😬)

If you are working in the Scalatest-specific version of ChiselSim, there will be additional APIs that allow you to turn on waveforms from the Scalatest command line. E.g., you can do ./mill <scalatest> -- -DemitVcd=1. This is part of a larger API to add Scalatest CLI options in an extensible, safe way. Hence, a more standard Scalatest-based flow would only write:

behavior of "Foo"
it should "finish before 10 cycles" in {
  simulate(new Foo) { dut =>
    RunUntilFinished(10)(dut)
  }
}

Then, if there was a failure, a user would run ./mill 'FooProject[2.13.16].test.testOnly' FooSpec -- -DemitVcd=1 to debug it. However, the user wouldn't be manually turning waves on/off in the test itself.

Note 7: The difference between simulate and simulateRaw is that the former automatically applies the reset initialization procedure for you.

Note 8: It's safe to use a snapshot version of Chisel and bump more frequently. We always use snapshot releases in order to get the newest features. As long as you can deal with less API stability (e.g., things which have not made it into a publicly released API may break while they are under heavy development), this may be a good option for you. We are aiming to get onto a faster release cycle for Chisel 7+ so that major releases come out more frequently.

[kazutomo]

Thanks a lot for the detailed response; I really appreciate the time and effort you put into this!

Regarding the software architecture, I like the idea of a customizable simulator like your DefaultSimulator example; it's powerful. I was also hoping for a simple way to specify options, similar to how chiseltest does it.

It's great to have a way to override the simulator setting, like in your Chisel 7 example, without having to manually construct a simulator. It might be even better if Chisel provided a helper function that returns a HasSimulator, for example:

implicit val verilator = enableVerilatorVcd("trace.vcd")

By the way, I confirmed that loadMemoryFromFileInline() works with Chisel 7, whereas it didn’t work with Chisel 6.