[rfc] Waveform Viewing

[seldridge]

This is a feature request.

It would be nice if testers2 was integrated with a waveform viewer in some way. My current workflow is something that I think could be automated and integrated with ChiselTest.

Overview

Current Workflow

1. Run a test and generate an annotation file

   test(new Foo).withAnnotations(Seq(WriteVcdAnnotation)) { dut =>
   dut.io.bar.poke(1.U)
   dut.clock.step(1)
   }

2. Postprocess the VCD file to generate a GTKWave save file that (1) adds non-temporary signals and (2) groups signals by module. I currently do this by running GTKWave with a TCL script, but this could just as easily be done using Scala and likely more intelligently than processing the VCD header.

3. Open GTKWave loading the save file to get something like the following:

(Signal names are from something I'm working on and don't match the code example above.)

4. I then run the test, make modifications, and just reload the waveform inside my GTKWave instance (so long as no signals were added/removed or signal names changed).

Proposed Automated Workflow/API

I think this is entirely automatable behind some viewWaveform method that could be added to ChiselTest. Modifying the example above:

test(new Foo).withAnnotations(Seq(WriteVcdAnnotation)) { dut =>
  dut.io.bar.poke(1.U)
  dut.clock.step(1)

  dut.viewWaveform()
}

At minimum, this could blindly run through steps 1--3 above.

At best it could reload the waveform associated with that specific test or create one if it doesn't yet exist.

Implementation

For the minimum implementation, this is just encapsulating the current workflow above into a method. This shouldn't be hard to do and could, at further minimum, use the scripts I already have.

For the best approach, ChiselTest would need to maintain some global state associated with each test and some Option[Pipe] that connects to the TCL console of that test's waveform viewer. GTKWave supports a TCL console (that you can startup with -w/--wish) which can be used for things like reloading, etc. It would also be tractable to instead of using a script to setup the viewer, the TCL console could be used entirely.

Appendix E of the GTKWave manual documents the available TCL commands.

Discussion

The major benefit of something like this is that it doesn't involve rolling a custom waveform viewer like has been talked about in the past. GTKWave is totally open source (GPLv2), so there's no barrier to entry for using it with ChiselTest.

The one difficulty I've had is finding documentation of the save file format (outside of the source code). Granted, this isn't too complicated and the existing effort to script this out has discovered most of the interesting options that are needed.

[ducky64]

Interesting.

To clarify the use case a bit: this is mainly meant to help with waveform viewer startup cost? As in, once you get the waveform viewer started and configure the view to your liking (including adding signals), there would be very little difference between the automated proposal and your current manual workflow?

On one hand, I think there's definitely utility in making waveforms as easy as possible (one antipattern I see with novices is the tendency to debug by trial and error rather than starting up tools that give debug data and system visibility, likely because of the high perceived cost), but on the other hand, it's potentially a lot of engineering to eliminate a somewhat small startup cost (or maybe it's not as small as I'm interpreting it to be?).

That aside, I think there's a few practical details to resolve:

• Where should the start-waveform-viewer flag be put?
  • Since the primary use case I see for chiseltest is regressions, writing it in the test case seems a bit unclean. Practically, it could be something sprinkled in during the debug phase, then removed once things are fixed. But it still feels weird...
  • Alternatively, it might make more sense to be done automatically(-ish) on a test failure, with the expectation that this is where you want to see the waveform. The devil's in the details, though, since this would balance discoverability with not being too annoying.
  • This could also be an annotation or integrated into however we do options.
• Should it be written inline with the test (and should the positioning of this construct within the rest of the test sequence be meaningful), or as something to be done on a completed test? (and presumably, the completed test would have needed VCD dumping turned on)
• Is there universal (or at least widespread) agreement on what the default view should be? For example, it probably makes sense to display top-level IO by default, but I could see arguments for and against internal wires or internal module IOs.
• How would this (or would this even) support multiple tests that have the .viewWaveform()?
• There would probably need to be some abstraction layer to support other viewers in the future.