Hierarchy Viewer Pass/Tool

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 called 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:

// 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:

<vhier>
 <cells>
  <cell name="Foo" submodname="Foo" hier="Foo" filename="Foo.v">
    <cell name="bar1" submodname="Bar" hier="Foo.bar1" filename="Foo.v">
      <cell name="baz1" submodname="Baz" hier="Foo.bar1.baz1" filename="Foo.v">
      </cell>
      <cell name="baz2" submodname="Baz" hier="Foo.bar1.baz2" filename="Foo.v">
      </cell>
    </cell>
    <cell name="bar2" submodname="Bar" hier="Foo.bar2" filename="Foo.v">
      <cell name="baz1" submodname="Baz" hier="Foo.bar2.baz1" filename="Foo.v">
      </cell>
      <cell name="baz2" submodname="Baz" hier="Foo.bar2.baz2" filename="Foo.v">
      </cell>
    </cell>
  </cell>
 </cells>
</vhier>

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.)

llvm / circt