RTL Schematic View

[drom]

Brief explanation

A good RTL schematic view is very useful.

Detailed Explanation

• View can be rendered from some internal representation of synthesis flow via JSON?
• If done with HTML+CSS+SVG+javaScript then it can be embedded on Web, Atom, VScode, etc.
• Interactive to filter a schematic subset
• Also jump (cross-highlight) between Schematic and source code.
• FPGA LUTs rendering

Further reading

• https://wavedrom.com/tutorial2.html
• https://github.com/nturley/netlistsvg
• https://github.com/drom/logidrom/issues/9

[rjordans]

This would be great to have. I can check with one of my students to see if he's interested. He's already working on some improvements for netlistsvg (busses & hierarchical designs)

• https://github.com/djwubs/netlistsvg

GitHub

djwubs/netlistsvg

draws an SVG schematic from a JSON netlist. Contribute to djwubs/netlistsvg development by creating an account on GitHub.

[drom]

netlistsvg is the great step into right direction. We need more of such projects.

[mithro]

@nturley (the author of netlistsvg) has signed up to be a Google Summer of Code mentor for SymbiFlow.

[drom]

We need more students now!

[TheProgrammerIncarnate]

@drom I think I can help you with that. I'd love to work on something related to netlist visualization for GSoC. Here's some ideas I want to bounce off of you before writing a formal proposal.

-An RTL schematic view (this issue)

-A potential visual simulation in RTL view (so one can see which wires are on/off & step through clock cycles.) There's a LOT of potential for visualizing testbenches or failure traces.

-Would this be an extension of netlistsvg, icedrom, or its own project?

-Issue #42 (Render LUTs as gates) would probably be a part of this

-Algorithms, perhaps in Yosys to make a netlist more human-readable before displaying (I'm thinking of possible use in reverse-engineering cases, but how helpful would it be for development?)

-Could also work on #45 (Improve Wavedrom)

I was looking for Symbiflow GSoC ideas and came across this the other day. I've already been working on things within the same vein in my obsolete IC emulation project (I gave a talk about this at LatchUp 2019) (RIP LatchUp 2020 ;'/ ) and would love to finally contribute to SymbiFlow. Much of your existing code is in JavaScript, which I've got experience in. I also have a little experience in C-based WASM, which is a language option if we create a new project.

[drom]

@TheProgrammerIncarnate great to hear from you. I was super impressed with your work and presentation at LatchUp 2019. I would be glad to be your GSoC mentor for any of the ideas you have mentioned above. I am sure @nturley would love your participation too. Have you registered for GSoC?

[mithro]

Python or Javascript would both be acceptable for a new project. I'm sure that @drom would prefer you write it in Javascript and I would prefer you write it in Python -- ultimately it is up to what you are more comfortable in.

[nturley]

Hi @TheProgrammerIncarnate !

I'm not too afraid of a rewrite of netlistsvg especially if you abandon the idea of using it for board level schematics because that made a mess of the code. It was hard to write because I didn't know what I was doing more than it being a lot of code, so with the benefit of hindsight and clear objectives it would be pretty straightforward to write. Of course you are welcome to steal pieces of it or refer to it for inspiration. Hierarchical designs practically necessitate a complete rewrite anyway. The key elements that I believe make netlistsvg successful are using a separate library to solve for layout and the concept of using an SVG skin template file. Many similar projects get bogged down fiddling with poor layout algorithms or drawing all of the symbols in code.

There are some pieces of diagram layout that it is much easier to find JS libraries for and some parts that are much easier to find python libraries for. For instance, ELKjs was very useful and I don't know of any python libraries that are as powerful as ELK for layout. Ive been doing experiments for months on trying to use constraint solver based layout and python has dozens of easy to use libraries for constraint solvers whereas the JS landscape is a bit more sparse in that area.

My python skills are a little stronger than my JS skills but I've worked with both in commercial code bases at this point so I'm fine with either one. Demoing via web browser is a little flashier than trying to teach someone how to use pip, but theres a lot of advantages to python as well.

So if you are doing netlist visualization, the TLDR is

1. Start from scratch instead of building on netlistsvg but make sure you understand enough about how it works to make yours at least as good. :)
2. The layout parameters and symbols are going to be the bike shed of the design so they should be the easiest part to tweak, modify, and replace.
3. I'm happy with Python or JS

[drom]

I want to add a few points here:

Good automatic rendering of big schematic sheets is pretty hard technically and useless.

• hard -- because of the absence of adequate rendering algorithms, implementations. ELK.js is one of the best but still so so.
• useless -- cognitive load on the user is growing with the size of the schematic. Users becoming overwhelming at some point. Abandoning the whole idea of the schematic view.

In order to make a schematic view useful, it must be interactive.

The user must be able to select and filter a subset of the schematic. With multiple ways of filtering, tracing towards source/destination, to the driver, showing/hiding details, highlighting wires and gates.

The User must be able to jump between schematic, waveform, and source code views.

A good tool would provide smart filters, to present relevant pieces of the schematic. Like a critical path, test case failure, etc.

Interactive, responsive, Web-based view is a key to success. IMHO

[TheProgrammerIncarnate]

Exactly what I was thinking. I put a design equivalent to a few hundred LUTs into netlistsvg a while back and had these exact issues. Filtering, netlist formatting (basically anti-flatten), integration of waveform viewer & source code, etc would all very useful to help mitigate apparent complexity.

On language, I'm leaning towards some form of WebAssembly (compiled to that is, I'm not writing an application in WASM bytecode.) It should run everywhere JS does, but be much faster. Speed hasn't been much of a bottleneck so far, but it could become one if someone tries to debug an entire core or IP block. There should be a few weeks before we have to decide on one though.

[drom]

For the language. I would start with JavaScript. JS is the only language that has access to the Web page DOM. react + imutability-helper would probably be the best choice for virtual DOM. For heavy lifting engines like parsers, constraint solvers, synthesis, simulation, we should use/develop separate library/tool. They would be written in C/C++/Rust or something else that compiles into WASM.

[drom]

On pattern recognition for visualization topic: https://groups.google.com/d/msg/chisel-users/eZy2zQyvojE/FN6dc9k9AgAJ

Google Groups

Google Groups allows you to create and participate in online forums and email-based groups with a rich experience for community conversations.

[rjordans]

Hierarchical designs seem to start getting usable with the repo I mentioned above (hierarchy branch). One of the main things that I'm seeing for improvement could be the routing of wires, these seem to take lots of detours once you get a larger design which makes tracing them quite a big problem.

This hierarchical view currently uses a JSON config file to select which modules to expand, here's an example of what it can currently generate:

[drom]

@rjordans looks very good. How can we improve the routing of the wires? is it done by ELKjs?

[rjordans]

This is done using ELKjs hierarchical drawing, for the wires I have no clue on how to get them better yet. There's a few examples in the above picture where a mux select input goes closely past the target, takes a big detour downwards, and then finally ends up at the correct point. This seems a bit silly to me but I have no clue how this works internally. The linked project is of a student that I'm supervising so I'm not completely up to date on the internals.

[Raamakrishnan]

This is a great project. I would love open source tools to support RTL schematics. I want to add a few points to this discussion:

1. The features listed by @drom will be of great use. It will be good to take a look at the features that commercial tools offer (verdi, simvision etc.). For example, these tools allow the user to load the parts of design incrementally as they are being traced to.
2. I feel the above discussion is going towards a schematic of gate/LUT netlist. Getting a schematic out of RTL code might be slightly different. For example, a Verilog assign statement can be converted to list of gates. But an always block might remain a black box.

[nturley]

My theory for the vertical detours are because it's attempting to align the components in rows. So when there is a large variance in node height then it can shove things further down than necessary. There was an ELK option for post compaction that is supposed to address issues like this but it didn't seem very effective when I tried it. Avoiding tall components can help but for many designs there isn't really any easy way around it.

Some layout issues can be fixed either in post layout processing or by fiddling with the configuration options but really digging into the layout algorithm requires digging into the original Java implementation. The maintainers are quite active and very helpful but many issues filed about layout get responses like "making complex changes like this could degrade other cases that have been highly optimized"

[rjordans]

OK, sounds like it may be worth checking if there's some low hanging fruit we can catch with the ELK configuration options first then. That will probably take some effort in visually inspecting the results for some larger set of test cases though so it'll be difficult to evaluate what the 'best' settings would be.

[rjordans]

@Raamakrishnan maybe to get back to your comment above. For your second point you mention that Verilog always blocks may remain black boxes.

Currently with Yosys + netlistsvg, you can run the 'proc' task in Yosys to translate the always blocks into actual processes. As a result these blocks will translate into their RTL structure, either gates for combinational logic, or registers plus gates for clocked blocks. The example output I posted previously is generated from Verilog code where this was done.

Once you have things in the RTL structure you can decide how many of the Yosys steps to run to either get a generic listing, or something else like LUTs in FPGA or mapped gates in ASIC designs.

[rjordans]

FYI: There is now a pull request to netlistsvg for merging the hierarchical view nturley/netlistsvg#92

[drom]

@Raamakrishnan maybe to get back to your comment above. For your second point you mention that Verilog always blocks may remain black boxes.

Currently with Yosys + netlistsvg, you can run the 'proc' task in Yosys to translate the always blocks into actual processes. As a result these blocks will translate into their RTL structure, either gates for combinational logic, or registers plus gates for clocked blocks. The example output I posted previously is generated from Verilog code where this was done.

Once you have things in the RTL structure you can decide how many of the Yosys steps to run to either get a generic listing, or something else like LUTs in FPGA or mapped gates in ASIC designs.

always block is a good reference point for a designer. It is important to visually localize logic symbols synthesized by the same always block. There are cases when several always & initial blocks have to be visually merged together.

One could think about the "schematic viewer" rendering some "visual netlist", that was synthesized for visualization purposes only. Like any other synthesis target (ASIC, FPGA) it has own "standard cell library", own limitation, own optimization criteria, own complexity criteria.

[eine]

FTR, see On the Automatic Layout of Data Flow Diagrams by Miro Spönemann, referenced in ghdl/ghdl#111:363395770 by @Nic30 (see Nic30/d3-hwschematic). See also Nic30/d3-wave and (RTL) Schematic view.

EDIT

umarcor/hwstudio contains the plumbing for a 3D RTL schematic viewer based on three.js and vuetify, with backends in either Python (Flas) or Electron. However, the visualization is a module, hence it can be used as a wrapper for netlistsvg, logidrom or any other library.

[drom]

FTR, see On the Automatic Layout of Data Flow Diagrams by Miro Spönemann

@eine thank you for sharing. Very interesting work, indeed.

[Nic30]

@drom there is whole team of people working on Layered graphs on Keil (search for people from previously mentioned thesis on researchgate)

I also used Ariane as a testing design for d3-hwschematic and I found out some serious problem which you probably do not know about yet.

• Just RTL visualizer is useless, it is already done by other tools and you won't be able to see anything, unless you have query language for highlighting etc. And even then it will be very slow simply because the circuit will be too complicated. The ELK.js can not handle even small cores like Arriane in real time If you expand all gates, like it is shown in example images in this conversation. (I solved it by putting all gates specific to a process to a process node which is not expanded by default.)

• The size of json can quickly become problem as well, lazy loading on component expansions also slows down.

• The behaviour of ELK is not deterministic. If you expand the component, circuit around component may change as well etc.

• ELK does not natively support components with fixed positions, hierarchical ports etc.

[drom]

@Nic30 all good points!

• Yes, I am aware that (ELK) is chocking at big graphs :( I use it at work. As well as any other layout engine I am aware of.
• Even when we will find/develop a 10x faster layout engine (MAGIC) it will probably slow down with the graph complexity too.
• Faster rendering is better than slow rendering, and the user will feel uncomfortable when it is too slow.
• Agree, that the perceptual usability of large rendering is questionable.

The goals I see are:

• convey more useful information with fewer nodes/edges
• develop a visual language (lines, shapes, colors, text) to simplify tracking
• increase inner complexity of the nodes (mini circuits)
• show higher level HDL constructs (FSMs, Case, generators)
• collapsing repetitive structures (N times something)
• collapsing secondary nodes into (cloudy blobs)
• filter (google) useful subset of nodes/edges (spotlight)
• provide means of quick/intuitive navigation into invisible space (dark zone)
• key bindings, scroll, zoom, touch,...

We need to find a better forum to prototype and discuss all these ideas.

[Nic30]

By MAGIC do you mean https://github.com/RTimothyEdwards/magic ?

Also note that d3-hwschematic has everything you mentioned

• convey more useful information with fewer nodes/edges

process body not expanded by default (note that this context process may not necessary means verilog always statement but the collection of the drivers for named signal)

• develop a visual language (lines, shapes, colors, text) to simplify tracking
• filter (google) useful subset of nodes/edges (spotlight)
• provide means of quick/intuitive navigation into invisible space (dark zone)

all object styles are customizable from json, "visual language" is d3.js library query which is used for all manipulations with svg

• increase inner complexity of the nodes (mini circuits)
• show higher level HDL constructs (FSMs, Case, generators)
• collapsing secondary nodes into (cloudy blobs)

"process nodes" previously mentioned (excluding generators, because it is very complicated to visualize non elaborated design)

• collapsing repetitive structures (N times something)

Done during generation of json, not part of d3-hwschematic

• key bindings, scroll, zoom, touch,...

d3.js zoom, move etc.

I am saying this because I believe that d3-hwschematic may be exactly what you are trying to write. I am just a single programmer you guys seems to have quite lot of followers, I would gladly transfer ownership of d3-hwschematic in to some github organisation, if required. I really do not see any reason why to do the same thing again.

Also think about this message as my personal opinion after reading previous messages, I do have only rough idea about your requirements.

GitHub

RTimothyEdwards/magic

Magic VLSI Layout Tool. Contribute to RTimothyEdwards/magic development by creating an account on GitHub.

[drom]

By MAGIC do you mean https://github.com/RTimothyEdwards/magic ?

@Nic30 no MAGIC was a code name of the imaginary layout engine that is 10x faster than ELK

[drom]

I am saying this because I believe that d3-hwschematic may be exactly what you are trying to write. I am just a single programmer you guys seems to have quite lot of followers, I would gladly transfer ownership of d3-hwschematic in to some github organisation, if required. I really do not see any reason why to do the same thing again.

@Nic30 thank you for sharing. Great work with d3-hwschematic! I like how it is done, language, and libraries. I also don't the reason to reimplement it.

I still don't see how final system should look. That is why I am looking for a platform for fast prototyping of ideas, rather than final implementation.

[Nic30]

Let me share one more idea.

I think that there are actually 2 use-cases for RTL viewer.

• doc
• prototyping and design analysis

The doc use-case is "simple", it is only required to render the graph and have possibility to filter/search in nodes. However the expectations from RTL viewer during prototyping are much higher.

I was experimenting with online GUIs but I always find out that there is some feature which I would like to have as a user but I need to add it in to GUI itself as a GUI developer.

I think that this is a common case, e. g. I would like to add a picture for the component body . But even if GUI allows a arbitrary html for the component body there is a problem where to store the image etc. (and this is just a simple example which comes to my mind)

Rather than developing IDE like GUI I think it would be better to have widget for interaction with the user. For d3-hwschematic I am using this jupyter_widget_hwt (but it is still a prototype). The widget can be also used as a control element, (e.g. selection of the signals for simulation, component for some transformation etc).

I think that widget would support user creativity better than IDE like web GUI.

[drom]

Let me share one more idea.

I think that there are actually 2 use-cases for RTL viewer.

• doc
• prototyping and design analysis

The doc use-case is "simple", it is only required to render the graph and have possibility to filter/search in nodes. However the expectations from RTL viewer during prototyping are much higher.

I was experimenting with online GUIs but I always find out that there is some feature which I would like to have as a user but I need to add it in to GUI itself as a GUI developer.

I think that this is a common case, e. g. I would like to add a picture for the component body . But even if GUI allows a arbitrary html for the component body there is a problem where to store the image etc. (and this is just a simple example which comes to my mind)

Rather than developing IDE like GUI I think it would be better to have widget for interaction with the user. For d3-hwschematic I am using this jupyter_widget_hwt (but it is still a prototype). The widget can be also used as a control element, (e.g. selection of the signals for simulation, component for some transformation etc).

I think that widget would support user creativity better than IDE like web GUI.

@Nic30 yes, that would be super cool to create some widget library, that user can use to quickly describe some component visualization.

[mithro]

FYI - I'm mostly interested in schematic view for documentation.

[umarcor]

• https://github.com/circuitgraph/circuitgraph
• https://schemdraw.readthedocs.io/en/latest/gallery/logicgate.html

GitHub

circuitgraph/circuitgraph

Tools for working with circuits as graphs in python - circuitgraph/circuitgraph

Logic Gates — SchemDraw 0.9.1 documentation

[mithro]

You might be interested in the following too;

• https://hackaday.com/2021/03/30/wires-vs-words-pcb-routing-in-python/
• https://excamera.com/sphinx/article-cuflow-crossbar.html

The interesting thing is the "river routing";

Key to this project is a concept [James] calls rivers — the Dazzler board shown above contains only eight of them. Connections get to their destination by taking one or more of these rivers which can be split, joined, and merged along the way as needed in a very Pythonic manner. River navigation is performed using Turtle graphics-like commands such as left(90) and the appropriately named shimmy(d)that aligns two displaced rivers. He also makes extensive use of pin / gate swapping to make the routing smoother, and there’s a nifty shuffler feature which arbitrarily reorders signals in a crossbar manner. Routing to complex packages, like the BGA shown, is made easier by embedding signal escapes for each part’s library definition.

It feels like this could be directly suitable for schematics diagrams and even place and route too.

[umarcor]

It feels like this could be directly suitable for schematics diagrams and even place and route too.

Agree. Schematics in 2.5D would be nice. @Nic30, any thought about multilayer algorithms vs the one used in d3-hwschematic?

[Nic30]

@umarcor right now I think that the the multi-layer algs. are required for PCB as wires can not cross otherwise but in scheme wires can cross and having more degrees of freedom may require longer layout time.

about cuflow I am not sure how much actually is automatic and how much is done manually. about river routing, I thing that it is beneficial for schemes on signal level, but it is possible to just replace river with some bus. e.g. in Altium:

If you do have buses then you usually do not need river routing (now I do ignore the fact that you do not have an explicit info about buses in Verilog..).

[pka88]

Hi,

I came up with this thread while searching for a way to have a interactive diagram for analyzing the clock tree from RTL. In general, the user could select a particular signal and keep tracing forward or backwards based on the RTL design instead of netlist. Please suggest if such capability already exists in any of the tools. Can SV -> Verible -> Kythe graph representations be used for such a representation instead of the default web UI?

Thanks in advance.

[Nic30]

@pka88 I am using verilog -> yosys -> json and then I am viewing it in d3-hwschematic (there is also netlistsvg which can do the same thing without aggregations) I am using it often to visualize combinational loops and pipelines discovered by a simple script. However for things like https://github.com/ultraembedded/biriscv the tool does not work out of the box (you have to limit max hierarchy level), the generated json is so big that the browser does not have enough memory. We are currently working on it.

based on the RTL design instead of netlist

You could try this in RTL and it will be doable for most of the cases but in general it is not doable and it requires conversion to netlist.

[drom]

There is a library to visualize set of small, but manageable logical tree structures without large graph rendering.

This page renders random circuit: https://drom.io/firrtl/

[pka88]

@Nic30 : Yes, I am looking for an interactive diagram with limited scope of analysis as the design is too big for getting any useful information if analyzed as a whole. Mainly the clock tree portion which is only connectivity across hierarchies in the RTL (much similar to the netlist). I have posted this comment in the Surelog thread from where I had reached this thread earlier. Maybe we would continue the discussion in that post?

@drom : Is the drom.io interactive ? are there any tools to parse an RTL to generate the GraphVIZ kind of representation needed for this ?

[drom]

@pka88 the demo above is just a random circuit. It can be made interactive, with left and right side path expansion.

[michael-lehn]

@drom

This page renders random circuit: https://drom.io/firrtl/

Link seems to be broken

[drom]

@michael-lehn

@drom

This page renders random circuit: https://drom.io/firrtl/

Link seems to be broken

Thank you for reporting. Should be fixed now.