Support for plugins in GTKWave

[rameloni]

Hi, I am seeking a waveform viewer that can be extended. I wondered if GTKWave supports the integration of external plugins. The alternative idea is to fork/clone the repository and integrate the functionality. However, native support for plugins would be greater since it would work with any future change of gtkwave. I checked but I did not find anything related.

Would you have any guidelines to do so? Any information would be useful.

[rfuest]

I've started to integrate plugin support into GTKWave, but this feature is in a very early state of development and isn't very useful yet. You can see a demo of what is currently possible in #245. More features should be available via the plugin interface after #302 is merged.

Do you have a specific use case in mind? I'm always interested to know how users might want to extend GTKWave to help me design a better plugin API.

[rameloni]

I am currently working on my master thesis project and I am developing a typed waveform viewer that supports the type abstraction introduced by new modern languages for writing hardware (i.e. chisel).

So, I would want to extend GTKWave to support the representation of custom-typed signals (for example composite data structures like C structs). The current waveform representation used for chisel is far from the source code, there is no reference to high-level constructs. Namely, waveform viewers basically shows signals at the low rtl-level (verilog, vhdl, firrlt)

I performed an analysis that shows how debugging with current waveform viewers in conjunction with chiseltest, or other testing frameworks (such as hgdb) creates a huge gap between what it is written in chisel and what it is inspected. Quite often this debugging chisel in such a way is not ideal and far from trivial in some common cases, and also some issues that can be caused by some names of signals used in chisel code. This gap will be even more evident in the context of tydi-lang (where custom user defined types matters):

• Tydi: an open specification for complex data structures over hardware streams.
• Tydi-lang-2: a language for typed streaming hardware.
• Tydi-Chisel: an implementation of Tydi interfaces and concepts in Chisel to improve collaborative and interface-driven data-streaming accelerators.

  Even if two types have the same representation at verilog level (namely bit-width), they are not the same type in tydi. For example, the following types are all internally represented by wires of 8 bits, but in tydi they are different types(Integer != MyCustomInt.

  // Piece of code in tydi-lang-2
  Char_t = Bit(8);
  Integer = Bit(8);
  MyCustomInt = Bit(8);

[tbybell]

You probably should look at the header files and docs for the FSDB reader and writer used by Novas/Synopsys. If your uni has VCS installed, those files probably are going to be buried somewhere in the install, and the API docs pdfs should be around there as well. Specifically, fsdbShr.h, ffwAPI.h, and ffrAPI.h are of interest, and any example code should be installed in the vicinity of those files. It is very likely that KDB (their design database--I think that's it) may also be of help here, but it's not too important as you can get similar information from looking at Verilator's XML representation of a compiled design.

Historically, waveform viewers have been based around a VCD-like view of sim state that reflects what is going on at a low, 01xz (MVL4) representation level in the RTL, and over time extensions grew around that. Novas addressed the issue some with extensions for VHDL and SystemVerilog, so those may be interesting implementation areas to examine. Much of the time, if memory serves me correctly, complex structs are decomposed into levels of hierarchy and signals in accordance with how the viewer traditionally has displayed information, and this is mostly based around internals of how that struct exists in the simulator. How you access element X of a complex struct from the VPI/DPI will tell you a lot about how the compiler and simulator play together.

When you're looking at waves, what you're looking at has largely been unchanged with respect to how RTL simulation debug has visualized since the late 1990s. I've only recently seen SystemVerilog structs being used in commercial designs that I've personally worked on. Before that, one would pass dozens or hundreds of related signals across modules one signal at a time. Do complex structs belong in the wave viewer, in some external or popup window that shows some source level or source inspired view, or in both? One size doesn't fit all here.

A problem with these newer HDLs like Chisel is that they are taking the old AT&T cfront approach to C++: translate C++ code into incomprehensible C code. Sure, it functions correctly with respect to the language definition, but is cumbersome, difficult, or near impossible to debug using traditional tools. You definitely need some sort of higher level -> Verilog mapping tables from parsing. Those will drive what your visualization tools can do.

With respect to that Tydi stuff, you might want to shoot a note off to Peter Hofstee for his opinion on things and to find out if IBM EDA is doing any work in this area and if so, how it fits into their internal tool flow, and perhaps who there to talk to. Everyone I know from there has long since retired. I used to work with the Austin folks: I remember him from the Playstation3 days at Building 906 in Austin. He doesn't know me as I was temporarily loaned out to the SPU group for six months for verification, but I remember him. Cell was a highly challenging once in a career project with great memories of teamwork.

[rameloni]

You probably should look at the header files and docs for the FSDB reader and writer used by Novas/Synopsys. If your uni has VCS installed, those files probably are going to be buried somewhere in the install, and the API docs pdfs should be around there as well. Specifically, fsdbShr.h, ffwAPI.h, and ffrAPI.h are of interest, and any example code should be installed in the vicinity of those files. It is very likely that KDB (their design database--I think that's it) may also be of help here, but it's not too important as you can get similar information from looking at Verilator's XML representation of a compiled design.

I need to check this, I don't think my university has access to that. But I will ask to the service desk and wait for their reply.

Historically, waveform viewers have been based around a VCD-like view of sim state that reflects what is going on at a low, 01xz (MVL4) representation level in the RTL, and over time extensions grew around that. Novas addressed the issue some with extensions for VHDL and SystemVerilog, so those may be interesting implementation areas to examine. Much of the time, if memory serves me correctly, complex structs are decomposed into levels of hierarchy and signals in accordance with how the viewer traditionally has displayed information, and this is mostly based around internals of how that struct exists in the simulator. How you access element X of a complex struct from the VPI/DPI will tell you a lot about how the compiler and simulator play together.

Chisel toolchain has several components to do that. The circuit is elaborated and transformed each time into a lower-level representation. During elaboration, a "high-level" hardware graph is created from chisel source code (every detected hardware component in chisel is pushed into that), and then that hardware graph is transformed into an intermediate representation called FIRRTL that can be either directly simulated using a simulator called treadle, or compiled to verilog and simulated through verilator. Both simulators are supported by chisel and chiseltest. Based on what I found so far, the used simulators have currently no knowledge about the source-level code.

When you're looking at waves, what you're looking at has largely been unchanged with respect to how RTL simulation debug has visualized since the late 1990s. I've only recently seen SystemVerilog structs being used in commercial designs that I've personally worked on. Before that, one would pass dozens or hundreds of related signals across modules one signal at a time. Do complex structs belong in the wave viewer, in some external or popup window that shows some source level or source inspired view, or in both? One size doesn't fit all here.

What I thought is to have a multi-level supported view. In my specific context of tydi: tydi-lang, chisel and the currently supported low level RTL. And yes I would say the structs will belong in the viewer. Let's take the following chisel example which shows part of the analysis I made:

object Months extends ChiselEnum {
val Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec = Value
}
class Time extends Bundle {
val hour = UInt(5.W)
val minute = UInt(6.W)
val second = UInt(6.W)
}
val timestamp = Wire(new Bundle {
val time = new Time
val date = new Bundle {
val day = UInt(5.W)
val month = Months()
val year = UInt(8.W)
}
})
val timestamp_date_day = Wire(SInt(5.W))

There is no reference in the viewer about the enum, there is no hierarchical representation of the Bundles and there is no clear difference between timestamp_date_day and timestamp.date.day part of the bundle. People would say that I can always retrieve the signal by checking the naming convention but I proved in this section that this may be critical in some cases due to the naming convention used. I think a typed representation will add more value to chisel since it will reduce the gap we currently have due to the nature of simulators used (that simulate low rtl and dump traces from them).

A problem with these newer HDLs like Chisel is that they are taking the old AT&T cfront approach to C++: translate C++ code into incomprehensible C code. Sure, it functions correctly with respect to the language definition, but is cumbersome, difficult, or near impossible to debug using traditional tools. You definitely need some sort of higher level -> Verilog mapping tables from parsing. Those will drive what your visualization tools can do.

Yes my final goal is to map the low level rtl (either firrtl or verilog) to the original source (tydi and chisel). I am already working on that. But in the end, I will also need to visualize somehow and that's why I thought that writing a plugin for gtkwave might be a good idea.

With respect to that Tydi stuff, you might want to shoot a note off to Peter Hofstee for his opinion on things and to find out if IBM EDA is doing any work in this area and if so, how it fits into their internal tool flow, and perhaps who there to talk to. Everyone I know from there has long since retired. I used to work with the Austin folks: I remember him from the Playstation3 days at Building 906 in Austin. He doesn't know me as I was temporarily loaned out to the SPU group for six months for verification, but I remember him. Cell was a highly challenging once in a career project with great memories of teamwork.

Peter is my supervisor and I keep in touch with him weekly.

[tbybell]

FST supports enums. I believe Verilator and nvc both use this capability. I understand why programmers would want to visualize them, but I've never used them except in rare cases. Try ECOing that Wed value to a Fri one and tell me which bits/gates are involved. :-) Enums, disassemblies, etc. have their usage cases for speeding through debug, though. It's going to be interesting to see where FPGAs drive hardware design, because if you're not at the mercy of dealing with a fab's cost and turnaround times, design and debug get easier and higher level data representations are usable because one doesn't have to dig down to the technology gate level.

There were FST adds for supplemental datatypes for VHDL as well, though nothing like supporting them dynamically.

Note there's a fairly generic attributes mechanism that gtkwave uses (at least for FST) that allows some extension of viewer capabilities. It's like the old computing joke: "There is no problem that can't be solved without an added layer of indirection." You can add attributes anywhere in dumping using fstWriterSetAttrBegin/fstWriterSetAttrEnd, so the possibility for adding the information to FST files that can be ignored sideband data is possible. That is, in theory you should be able to extend what you dump into an FST file without breaking backward compatibility because the FST loader won't process data that it wasn't programmed to recognize.

[rameloni]

FST supports enums. I believe Verilator and nvc both use this capability.

This is nice to know. But the problem is that chisel doesn't seem to provide that capability "out-of-the-box". During its elaboration, Chisel makes some code optimizations and some information is lost. For example, the enum variants are directly replaced by their numeric values in the output verilog file and no reference to variant types is accessible. If timestamp.date.month := Months.Feb is done, the verilog will have timestamp_date_month = VALUE. So, since the simulator uses low level IR dialect or verilog code that is obtained from chisel elaboration, the association between VALUE and Months.Feb is unknown by the simulator itself.

... Try ECOing that Wed value to a Fri one and tell me which bits/gates are involved. :-) ...

I agree with you, if this is the target it's really difficult to understand what changes. But, it really depends on the use case, I don't think that users who wants to know differences at bit/gate level would use Chisel. Chisel was born to "improve productivity" by raising the asbtraction level and with "type-safe hardware design and generation" but still allowing the user to act at the bit-level.

There were FST adds for supplemental datatypes for VHDL as well, though nothing like supporting them dynamically.

Note there's a fairly generic attributes mechanism that gtkwave uses (at least for FST) that allows some extension of viewer capabilities. It's like the old computing joke: "There is no problem that can't be solved without an added layer of indirection." You can add attributes anywhere in dumping using fstWriterSetAttrBegin/fstWriterSetAttrEnd, so the possibility for adding the information to FST files that can be ignored sideband data is possible. That is, in theory you should be able to extend what you dump into an FST file without breaking backward compatibility because the FST loader won't process data that it wasn't programmed to recognize.

So FST could be extended by dumping custom information.

[rameloni]

I checked your paper about the FST format: Implementation of an Efficient Method for Digital Waveform Compression in Appendix F of the GTKWave user's guide. I saw you cited both the "Verdi3 and Siloti Command Reference", "Open FSDB Writer", and "Open FSDB Reader" documents but I was not able to find them.

In the meantime, I requested access to my university for VCS, even though I am not too confident I will get it.