Example of Surelog/UHDM usage

[alaindargelas]

How do you plan to use Surelog/UHDM next (if that can be disclosed)?

Use the Yosys plugin ?
Analyse the design using UHDM ?
...

I'm just beginning to study UHDM and still overwhelmed by the README. About 10 years ago I evaluated a product from a small startup called Invionics that allowed me to parse an entire Verilog design (using a commercial parser, I think it was cheetah, not Verific), and gave me a Python API to traverse the design tree, modules, instances, ports, etc.

Anyway, this is not an official project, I'm just trying the stuff.
My first objective was to build an HTML design browser. I already hacked one in python, which, given a Verilog design, it would build a static HTML file (no server needed) where I could fold the module hierarchy with instance names, and by clicking on a module, it would load it on the right side of the window.
Given its limited scope (only trace hierarchy, not signals), and the fact that it was more like a glorified regex beast that a real parser, it was OK. It did handle preprocessor defines, file lists, but it can't really handle stuff like if generate so it obviously parsed too much. It became too limiting and I wanted something better.
So the first project is to replicate it based on util/uhdm-hier.cpp as a starting point.

I'm also missing a tool that will give me a fully elaborated view of a design to make sure I got all the generate stuff correctly.

Another long-tem goal is to write a tool to track all the possible transaction paths inside the SoC, it has dozens of masters and slaves, using a simple company internal bus, and I would like to construct a table of all paths from each master to every slave connected to it, with the full path across the various design hierarchies, as well as the latency of each path (in clock cycles).

So while I started taking a look at UHDM, I see very little in term of user documentation and examples. Many of the source files mentioned in the UHDM README are not stand-alone programs, making it somewhat hard to see how they are actually used.
Perhaps by adding a github "Discussions" section to the UHDM repo will give a place where questions of "how to" could be asked and answered, which would be more appropriate than opening an Issue .

[alaindargelas]

HTML report:
Surelog creates optionally (-d coverhdm) a HTML report that shows all the files parsed and highlights the sections of the files that are actually part of the design (If a generate statement is not exercised, that section will be red in the report). This file uses Surelog data structure for the overall file-space and UHDM for the actual design-space (Subset of the file-space).
https://github.com/chipsalliance/Surelog/blob/master/src/DesignCompile/UhdmChecker.cpp

[alaindargelas]

UHDM Usage:
I added two references to complex examples of UHDM usage (Yosys plugin and Verilator plugin) to the UHDM README.

[alaindargelas]

"Another long-tem goal is to write a tool to track all the possible transaction paths inside the SoC":
Currently UHDM does not create a connected graph of signals in the design, nor a "netlist" of the design (RTL or gate-level). That task is left to Yosys to create a fully connected netlist during Synthesis (Using the Yosys-UHDM plugin). Such a RTL graph would be a welcome contribution in the form of a UHDM application (Like some already existing UHDM applications: https://github.com/chipsalliance/UHDM/blob/master/templates/UhdmLint.cpp or https://github.com/chipsalliance/UHDM/blob/master/templates/SynthSubset.cpp)

[udif]

All of these template files have no main(), no Makefile, and some of them contain tags in the form <...> that are obviously place markers for other tools to use these as templates for creating specific files (as the directory name already implies). I couldn't easily find how to use them, and which tool (if needed) is used to process those templates.

[alaindargelas]

You don't need to look at the template directory, it is used to create UHDM (Internal). I'm pointing to some examples there because it eats its own dog food: some UHDM code manually written uses the machine generated UHDM code.

The best examples are under util and tests (Although the tests are using Google tests - no main - and are compiled using Cmake).

[alaindargelas]

Also:
https://github.com/chipsalliance/Surelog/blob/master/src/hellouhdm.cpp

https://github.com/chipsalliance/Surelog/blob/master/src/hellodesign.cpp

[udif]

I understand there is also a Python API.

Are there Python examples showing how to parse/elaborate/load an existing UHDM file, and traverse it using the Python API?

[alaindargelas]

Noone has done it before.
There is a bit of DIY, but the essence is here: chipsalliance/Surelog#2635 (comment)
Use Surelog as you have been using, it creates a surelog.uhdm file, then create your own Python executable, by loading the libuhdm.so and the SWIG generated code. That is the general idea. If that is the road you want to take, please try to create (and contribute back) a Makefile that assembles it all and load into a python interpreter.
The only extra function you need is a wrapper to the Serializer::load UHDM.

But if you are familiar with C++ why not stay in C++ all the way?

[udif]

If I had functional Python bindings with full functionality, I would be 10x more productive than in C++ . Given that bindings are just bindings and that most of the tasks are done by the original library, these type of tools have acceptable level of performance.

[alaindargelas]

The Surelog Python API is mostly unused, it is a binding over the Antlr Parse tree, so pre-elaboration. It does not do anything with generate statements for instance, so pretty limited.

[udif]

Given the comment above, getting usable UHDM Python bindings is indeed more useful.

[alaindargelas]

Go ahead! Please tell me if you get stuck.

[udif]

The first step seems to be getting UHDM to generate a dynamic lib in addition to the static one.
I played a bit with UHDM's CMake configuration, but it's not finished yet. I managed to get a manual build of the .so file, so it can be dynamically loaded within Python (I created it using cmake -DBUILD_SHARED_LIBS:BOOL=ON but not as an integral part of the complete Surelog build.)

[alaindargelas]

Python API for UHDM is now supported. Closing this discussion.