This repository contains a summary of the Tywaves project and an API to easily use it for testing a Chisel project. Tywaves consists of implementing a new type based waveform viewer for Chisel and Tydi-Chisel circuits.
The full project aims to successfully display waveforms of a Chisel circuit while maintaining the source code structure, constructs, hierarchies and source language type information (the Scala data type and constructor parameters) of signals and modules.
To achieve this goal, the project:
If you are interested in using the tool and have any feedback on its implementation,
please open an issue or contact me.
The internal structure of the Tywaves project, how it works and details about the work done can be found in the [wiki](https://github.com/rameloni/tywaves-chisel-demo/wiki) pages.
Note: The Tywaves project is currently under development. For now, the new functionality in
chisel
,firtool
andsurfer
is available in my forks of the repositories. Pull-requests have been issued to the official repositories This would allow the Tywaves project to have a better integration and availability directly in the official releases.
The full project depends on the following tools. To install them, please check the links below:
openssl
for installing the waveform
gui (instructions)v4.228+
)The Makefile contains all the necessary commands to install the tools and the Tywaves-Chisel-API library.
You can run make all
to install everything in one go, or you can install the components separately.
To install the latest release of the fork:
make install-surfer-tywaves
make clean # Delete the cloned repository
or install the development version:
make install-surfer-tywaves-dev
make clean
make install-chisel-fork
make install-firtool-fork-bin # Download the Linux precompiled version (too long to compile)
If you want to compile the firtool
from source, you can check
the instructions, once cloned the
correct version.
git checkout <your-release>
make install-tywaves-chisel-api
Once published locally, you can use it in your project by adding the following line to your build.sbt
file:
libraryDependencies += "com.github.rameloni" %% "tywaves-chisel-api" % "your-version-here"
The Tywaves-Chisel-API
is a library that allows to easily enable the Tywaves in a Chisel project. It provides 2
high-level simulators with functionalities to simulate a circuit
through svsim, emit VCD traces and generate a symbol table
for the surfer-tywaves waveform viewer itself automatically:
Their usage is very similar to ChiselTest
and EphemeralSimulator since they both
implement the PeekPokeAPI
, but they use the new official ChiselSim, and they offer additional features compared to
EphemeralSimulator. A simulation can be run as follows:
// Import the simulator
import tywaves.simulator.simulatorSettings._
import tywaves.simulator.ParametricSimulator._
//import tywaves.simulator.TywavesSimulator._
simulate(
new DUT(), // The module to simulate
settings = Seq(/* List of simulator settings */),
simName = "Name_of_the_simulation", // used to name the directory in test_run_dir
) {
dut => // Body of the simulation using the PeekPokeAPI
}
A simulation can be customized by passing some settings to the simulator. The following options can be specified
for ParametricSimulator
and / or TywavesSimulator
classes using the following syntax:
Setting | Description | Simulator |
---|---|---|
VcdTrace |
Enable the VCD output optimizing out signals starting with an underscore (_) in the final verilog | ParametricSimulator and TywavesSimulator |
VcdTraceWithUnderscore |
Enable the VCD output (including "underscored" signals) | ParametricSimulator and TywavesSimulator |
SaveWorkdir |
Save the workdir of svsim |
ParametricSimulator and TywavesSimulator |
SaveWorkdirFile(name: String) |
Save the workdir with a specific name | ParametricSimulator and TywavesSimulator |
NameTrace(name: String) |
Give a name to the VCD trace | ParametricSimulator and TywavesSimulator |
WithFirtoolArgs(args: Seq[String]) |
Pass arguments to firtool under the simulation |
TywavesSimulator |
WithTywavesWaveforms(runWaves: Boolean) |
Enable the generation of extra debug information (to fully exploit the tywaves project) and (optionally runWaves=true ) launch the waveform viewer directly once the simulation has been completed |
ParametricSimulator and TywavesSimulator |
WithTywavesWaveformsGo(runWaves: Boolean) |
Same as WithTywavesWaveforms but without blocking sbt if runWaves is true |
TywavesSimulator |
Note: please open an issue/PR to request new settings.
To run a quick example you can try to run the examples in the examples folder.
cd example
# Run the gcd example
scala-cli test gcd.test.scala
# Run a Tydi-Chisel example
scala-cli test tydi-chisel.test.scala
The following images show the classic and tywaves waveform visualization of the GCD module.
/** A simple module useful for testing Chisel generation and testing */
class GCD extends Module {
val io = IO(new Bundle {
val a = Input(UInt(32.W))
val b = Input(UInt(32.W))
val loadValues = Input(Bool())
val result = Output(UInt(32.W))
val resultIsValid = Output(Bool())
})
val x = Reg(UInt(32.W))
val y = Reg(UInt(32.W))
when(x > y)(x := x -% y).otherwise(y := y -% x)
when(io.loadValues) {
x := io.a
y := io.b
}
io.result := x
io.resultIsValid := y === 0.U
}
Only VCD loaded | Tywaves |
---|---|
![]() |
![]() |
If you are interested to see Tywaves working in an existing Chisel design, you can refer to this section. This example has been used in the official publication to assess Tywaves.
The following list shows a summary of the features added by the Tywaves project to Chisel/CIRCT and Surfer:
when
and otherwise
blocks)tywaves-rs
and Surfer.TyVcdBuilder
to further improve the performance of the viewer.toString()
method.Use the new name of the library in your sbt dependencies: com.github.rameloni::tywaves-chisel-api:<version>
.
IMPORTANT NOTE: Always use the latest version of Tywaves
Release | Chisel fork version (from rameloni/chisel ) |
Firtool fork version (from rameloni/circt ) |
Tywaves-rs version | Surfer-tywaves version |
---|---|---|---|---|
0.4.1-SNAPSHOT | v6.4.3-tywaves-SNAPSHOT | v0.1.4 | v0.1.4 | v0.3.2-tywaves-dev-SNAPSHOT |
0.4.0-SNAPSHOT | v6.4.3-tywaves-SNAPSHOT | v0.1.3 | v0.1.4 | v0.3.2-tywaves-dev-SNAPSHOT |
0.3.0-SNAPSHOT | v6.4.2-tywaves-SNAPSHOT | v0.1.1 | v0.1.1 | v0.3.0-tywaves-dev-SNAPSHOT |
Use the old name of the library in your sbt dependencies: com.github.rameloni::tywaves-demo-backend:<version>
.
Release | Chisel fork version (from rameloni/chisel ) |
Firtool version (official CIRCT repo) | Tywaves-rs version | Surfer-tywaves version |
---|---|---|---|---|
0.2.1-SNAPSHOT | v6.1.0-tywaves-SNAPSHOT | v1.75.0 | v0.1.0 | v0.2.1-tywaves-dev-SNAPSHOT |
0.2.0-SNAPSHOT | v6.1.0-tywaves-SNAPSHOT | v1.75.0 | - | v0.2.0-tywaves-dev-SNAPSHOT |
0.1.1-SNAPSHOT | v6.1.0-tywaves-SNAPSHOT | v1.75.0 | - | [v0.1.1-SNAPSHOT]() |
0.1.0-SNAPSHOT | v6.1.0 official repo | v1.62.0 | - | [v0.1.0-SNAPSHOT]() |
The paper on Tywaves has been submitted for publication NorCAS 2024. It is currently available at https://arxiv.org/abs/2408.10082. If you like Tywaves, you can cite this work using the following BibTex entry:
@unpublished{meloni2024tywavestypedwaveformviewer,
title={{Tywaves: A Typed Waveform Viewer for Chisel}},
author={Raffaele Meloni and H. Peter Hofstee and Zaid Al-Ars},
year={2024},
eprint={2408.10082},
archivePrefix={arXiv},
primaryClass={cs.AR},
url={https://arxiv.org/abs/2408.10082},
note={Submitted for publication}
}
The BibTex entry will be updated when the paper will be officially published.
For more details about the original work and the justification behind design choices, please refer to the respective MSc thesis:
Raffaele Meloni. Tywaves: A Typed Waveform Viewer for Chisel HDL with Typed Circuit Components and Tydi Streams. MSc thesis, TU Delft, Aug. 2024. Available: https://repository.tudelft.nl/record/uuid:829f43e0-1c34-4624-8c33-5182b71bd027.
Tywaves is licensed under the Apache License 2.0. Please see LICENSE for details.
[^1]: While TywavesSimulator
is a central part of the Tywaves project, the ParametricSimulator
is able to simulate any Chisel circuit independently from Tywaves. In case you need to simulate a circuit without a "Chisel" representation, you can use ParametricSimulator
to emit a VCD trace.
If you want to try the functionalities of Tywaves
then TywavesSimulator
is the right choice.