llvm / llvm/circt

Hierarchy Viewer Pass/Tool

Open
#911 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
C++
Stars
2.2k
Forks
524
Avg merge
3d 2h
Merged PRs (30d)
46

Description

A common request is to provide hierarchy information for a design.

E.g., for a given design, you'd like to have a representation of the design that includes who instantiated what. This format could be textual/command line (like the output of `tree`), conforming to some standard (IP-XACT, DuH), or entirely one-off.

This should support the ability to dump out a hierarchy for different operation types. E.g., a mix of FIRRTL, RTL, and SV modules should compose correctly.

Build a command line tool that can read in some MLIR and dump out its hierarchy in some format. (This is likely a single pass and a wrapper tool where the pass could be including in a pass pipeline if desired.)

### Examples

#### `Verilog::Perl` utility `vhier`

Wilson Snyder ships a tool as part of [`Verilog::Perl`](https://metacpan.org/release/Verilog-Perl) called [`vhier`](https://metacpan.org/pod/distribution/Verilog-Perl/vhier) that will dump out a `tree`-like output or give you an XML representation of a Verilog hierarchy.

E.g., for the following Verilog:

```verilog
// Foo.v
module Baz(
input a);

endmodule

module Bar(
input a);

Baz baz1 (
.a (a)
);
Baz baz2 (
.a (a)
);
endmodule

module Foo(
input a);

Bar bar1 (
.a (a)
);
Bar bar2 (
.a (a)
);
endmodule
```

You can then dump out something `tree`-like with `vhier --forest --instance --cells Foo.v`:

```
Foo Foo
|--bar1 Bar
| |--baz1 Baz
| \--baz2 Baz
\--bar2 Bar
|--baz1 Baz
\--baz2 Baz
```

Alternatively, you can get an XML-based representation (which is non-standard as far as I can tell) with `vhier --xml --instance --cells Foo.v`:

```xml
















```

#### Vendor Tools

Vendor tools support this in varying forms. E.g., in some tools you can bring up a window that lets you browse different "views" of a design. These may include module/instance hierarchy, looking at different nets in the design, and grouping in different ways.

Vendor tools also provide some APIs for directly querying their data model representation which _allows users to build hierarchy dumpers in some language_ (probably TCL).

(I envision us solving this with Python bindings that allow querying the MLIR directly. However, this is out of scope of this issue.)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue names no implementation files, tests, or existing entry points. Start by examining how the project reads MLIR and represents FIRRTL, RTL, and SV modules, then determine the hierarchy semantics and output format. Done means a command-line tool and reusable pass can dump a mixed-design hierarchy and participate in a pass pipeline.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
cli, compilers
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.