chiseltest

ChiselTest provides a concurrency abstraction for writing testbenches using fork and join. This allows you to spawn threads that run within the simulation cycle without real parallelism.

• fork: Spawns a thread. Child threads run immediately, then return to the parent. On subsequent cycles, child threads run before their parent in the order they were spawned.
• join: Blocks (waits) on a thread.
• Safety: The infrastructure checks for collisions or unexpected behavior when pokes/peeks/expects are performed on wires from different threads.
• Synchronization: You can use fork.withRegion(...) to associate a region with a thread, acting as a synchronization barrier within simulator time steps (useful for monitors).

To use chiseltest as a managed dependency in your Scala project, add it to your build.sbt file.

Important: When using chisel5, ensure you pick a matching major version to avoid linking errors. For older versions, ensure your chisel3 and chiseltest versions match to prevent linking issues.

libraryDependencies += "edu.berkeley.cs" %% "chiseltest" % "5.0-SNAPSHOT"

If migrating from the older chisel-testers or iotesters libraries:

1. Invert Syntax: In chisel-testers, you used tester.poke(wire, value). In chiseltest, use wire.poke(value) where value is a Chisel literal.
2. Test Helpers: Since chiseltest does not require a tester context, you can define test helper functions as standard libraries outside of a test class.
3. PeekPokeTester Compatibility: Use the compatibility layer in chiseltest.iotesters to reuse old tests. Note that while the test logic remains similar, the old Driver is removed and replaced by the new test syntax.
4. Hardware Testers: Synthesizable tests (extending BasicTester) can be run using the runUntilStop function.

When implementing a ScalaBlackBox, you can define dependencies between ports using getDependencies.

Note on Internal State: If your black box has internal state, you may need to specify that inputs depend on outputs to ensure the simulator achieves the correct topological sort during the single-pass assignment of wires. This prevents issues where the simulator attempts to assign a wire before the black box has updated its internal state based on the current inputs.

The VCS simulator supports several waveform formats. To enable waveform dumping, include the corresponding annotation in your circuit state.

Note for FSDB (Verdi): If you use WriteFsdbAnnotation, you must have the VERDI_HOME environment variable set in your system for the simulator to correctly link the Verdi PLI libraries.

// Supported waveform annotations:
// WriteVcdAnnotation
// WriteVpdAnnotation
// WriteFsdbAnnotation

When calling step(n), the simulator returns a StepResult to indicate whether the simulation proceeded normally or was interrupted by a hardware assertion or stop statement.

• StepOk: The simulation completed the requested number of steps without interruption.
• StepInterrupted(after, isFailure, sources): An interrupt occurred.
  • after: The number of steps completed before the interrupt (always $> 0$ and $\le n$).
  • isFailure: true if the interrupt was caused by an assertion/assumption violation or a stop with a non-zero return code; false otherwise.
  • sources: A sequence of hierarchical names identifying which stop/assert/assume statements were triggered.

To remove Chisel3's stacktrace suppression (the at ... () lines) and see the full trace, use the PrintFullStackTraceAnnotation via .withChiselAnnotations.

If you are using ScalaTest via SBT, you must also pass the -oF flag to ScalaTest to prevent it from suppressing the trace. Use -- in SBT to pass arguments directly to ScalaTest.

import chisel3.stage.PrintFullStackTraceAnnotation

test(new MyModule).withChiselAnnotations(Seq(PrintFullStackTraceAnnotation)) {
  c => // test body
}

# Running via SBT
$ sbt
> testOnly <spec name> -- -oF

ChiselTest supports multiple simulator backends. You can switch between them to balance execution speed and waveform quality. Use the appropriate BackendAnnotation to select a simulator.

When using the VCS simulator backend in chiseltest, you can provide specific configuration via annotations. These annotations allow you to pass custom flags to different stages of the VCS compilation and simulation process.

Available VCS options:

• VcsFlags(flags: Seq[String]): Adds flags to the initial vcs invocation (compilation stage).
• VcsCFlags(flags: Seq[String]): Adds flags to the C++ compiler used in the Makefile generated by VCS.
• VcsSimFlags(flags: Seq[String]): Adds flags to the final simulation binary execution.
• VcsBackendAnnotation: Used to explicitly select the VcsSimulator backend.

// Example of using VCS specific flags
val myAnnotations = Seq(
  VcsBackendAnnotation,
  VcsFlags(Seq("-debug_all")),
  VcsCFlags(Seq("-O3")),
  VcsSimFlags(Seq("+extra_sim_arg"))
)

Once simulation recording is complete, use the write method to persist the accumulated changes to a physical file in VCD format.

vcd.write("simulation_output.vcd")