Tywaves internals
In order to create a typed waveform viewer, I first needed to figure out how the values of signals stored in a trace file could be associated with their respective Chisel representation. In other words, how a Chisel circuit is simulated and how it is compiled to Verilog.
Starting from version 5, Chisel replaced its hardware compiler with firtool (implemented in the LLVM CIRCT project) to generate Verilog. ChiselTest, the chisel 3's testing library, is built around the Scala FIRRTL Compiler (SFC), which made difficult the support in Chisel 5 and future versions. For this reason, ChiselSim has been created as a replacement for ChiselTest and is officially maintained and supported.
ChiselSim is composed of 2 core components: svsim and the PeekPoke API. Respectively, a low-level library for compiling and controlling SystemVerilog simulators with maximal portability and backend-independent test harness and simulation, and an API that provides basic control operations for a testbench in scala (peek, poke, expect, and step).
Since svsim is not a testing framework like ChiselTest, it should be used together with the API to implement higher-level simulators with more advanced functionality.
The figure below shows a high-level diagram of the architecture of ChiselSim and its integration with firtool and existing Verilog simulators.
 |
|---|
| Fig. 1 - Chisel simulation diagram (relationship between user code, chisel library, the firtool compiler and external Verilog simulators) |
As shown in the figure the user can run tests using high-level simulators as interfaces between the testbench code and ChiselSim. The simulator should expose the PeekPoke API and, in turn, invoke svsim for the actual low-level simulation.
Svsim internally uses ChiselStage to link chisel with the firrtl-verilog compilation, then passes the emitted SystemVerilog circuit to an existing hardware backend simulator (currently, Verilator and VCS are the 2 supported backends).
An example of such a higher-level testing simulator can be found in the chisel library itself and it is called EphemeralSimulator.
This simulator simply exposes the PeekPoke API and invokes svsim to control the testbench, simplifying the underlying complexity.
However, it does not support more advanced functions and options for getting extra output information from the simulation.
While Verilator and svsim support emitting trace files for waveform viewers like VCD (TraceStyle), users cannot access this feature through the EphemeralSimulator.
The previous section introduced the architecture of ChiselSim and a summary of how it works internally. Chisel inherently lacks a proper waveform visualization. While attempting to load a trace file emitted by a ChiselTest simulation in GTKWave, the signals displayed correspond to the final compiled Verilog logic rather than the original Chisel. This is not ideal for debugging, as the compiler-generated code is often not always understandable. Besides, Chisel users might not want to engage with the underlying Verilog at all. On the other hand, this version of ChiselSim does not even offer this functionality. Therefore, both Chisel elaboration stages and ChiselSim itself necessitate an update to make the Tywaves project feasible.
The diagram below provides an overview of the software architecture of the project and shows how tywaves integrates in the Chisel compilation pipeline to achieve the goals addressed. It is essentially an extension of the "standard" chisel pipeline from the previous figure.
 |
|---|
| Fig. 2 - Integration of Tywaves in the ChiselSim pipeline |
The images show 3 additional components:
- Tywaves-Chisel API: a scala library for managing easily a "tywaves simulation", internally implementing two high-level "PeekPoke" simulators with more advanced functionalities compared to
EphemeralSimulatorsuch as the emission of a trace file. A list of supported simulator settings are available here. - tywaves-rs: a rust library to parse the debug file (HGLDD) emitted by firtool, with the additional Chisel type information that tywaves introduces, and convert it to a usable well-defined data structure in rust, to link debug information with values from a trace file.
- Surfer-tywaves: a waveform viewer with a focus on extensibility. Although GTKWave is one of the most widely used open-source waveform viewer, it does not offer a great opportunity for extensibility to new features. Therefore, adding functionality would have required much more time and effort (https://github.com/gtkwave/gtkwave/issues/308). On the other hand, Surfer is built with a focus on flexibility which made it the preferred choice.
In addition to these new components, the project implied an update of ChiselSim, ChiselStage, and Firtool in order to generate and propagate debug information from Chisel, passing through the CIRCT debug dialect and HGLDD, to a waveform visualizer.
The next sections contain more details about what a chisel type is, the single components, and the changes in the Chisel/CIRCT to make tywaves feasible.