How do I get the module type from SymbolKind.UninstantiatedDef node?

[MatchlessJoyride]

Hello,
I am trying to understand pyslang. I started by editing one of the example scripts.

Here is the relevant portion of my script:

class AllExtractor:
    def __init__(self):
        self.objects = []

    def __call__(self, obj: Union[pyslang.Token, pyslang.SyntaxNode]) -> None:
        self.objects.append(obj)


def do_extraction(systemverilog_code, extractor_class):
    try:
        tree = pyslang.SyntaxTree.fromFile(systemverilog_code)

        compilation = pyslang.Compilation()
        compilation.addSyntaxTree(tree)

        diagnostics = compilation.getAllDiagnostics()

        if diagnostics:
            engine = pyslang.DiagnosticEngine(compilation.sourceManager)
            engine.reportAll(compilation.sourceManager, diagnostics)

        extractor = extractor_class()

        root = compilation.getRoot()

        root.visit(extractor)

        return extractor.objects

    except Exception as e:
        raise Exception(f"Failed to extract logic declarations: {e}")

When I run this on a toy verilog file, I get this printed to screen:

Found 25 objects:
   1. Symbol(SymbolKind.Root, "$root")
<snip>
  12. Symbol(SymbolKind.Net, "data")
  13. Symbol(SymbolKind.UninstantiatedDef, "u_child_a")
  14. Symbol(SymbolKind.UninstantiatedDef, "u_child_b")
  15. Symbol(SymbolKind.UninstantiatedDef, "u_child_c")
  16. Symbol(SymbolKind.ProceduralBlock, "")
<snip>
  25. Expression(ExpressionKind.Call)

Here's the toy code:

module top (
    input  wire       clk,
    input  wire       rst_n,
    input  wire       enable,
    input  wire [7:0] data
);

  child_a u_child_a (
      .clk(clk), .rst_n(rst_n), .enable(enable), .data(data)
  );

  child_b u_child_b (
      .clk(clk), .rst_n(rst_n), .enable(enable), .data(data)
  );

  child_c u_child_c (
      .clk(clk), .rst_n(rst_n), .enable(enable), .data(data)
  );

  // Print on every clock transition to aid debugging
  always @(enable) begin
    $display("[TOP] enable=%b @%0t", enable, $time);
  end

endmodule

I am struggling to figure out how to extract "child_a/b/c" as the module types of their respective instances. Is there a different data structure I need to look through? I thought that by doing root.visit() I'd be looking at every single node on the tree, but It seems like only lands on the leaves.

[MikePopoloski]

It sounds like you want the definitionName member of the UninstantiatedDef symbols? I'm not sure what you mean about not visiting every node; it looks like you got the whole list of them?

[MatchlessJoyride]

First off, thanks for the quick reply!

I didn't know definitionName was what I wanted, but yes that is what I need. That simple comment helped me figure it out.

Here's how I did it in case anyone else stumbles like I did:

    comp = pyslang.Compilation()
    comp.addSyntaxTree(tree)
    comp_objects = []

    def comp_visit_func(obj):
        comp_objects.append(obj)
    comp.getRoot().visit(comp_visit_func)

    print(f"# of comp_objects:{len(comp_objects)}")
    for _ in comp_objects:
        print(_.kind)
        if (_.kind == pyslang.SymbolKind.UninstantiatedDef):
            print(_.definitionName)

One thing I have noticed as I worked on this, is that the root of a Tree is different than the root of a Compilation. Thinking about that a bit more, it makes intuitive sense but I'd like to understand it more. For example I don't understand why I can only find the UninstantiatedDef in the Compilation, but it doesn't appear in the Tree.

Can you point me to where the difference is clearly explained in the documentation?

[MikePopoloski]

Everything under SyntaxTree and/or derived from SyntaxNode is part of the concrete or parsed syntax tree. After parsing, the Compilation does name resolution, type checking, elaboration, etc. Visiting the elaborated tree gives you the design hierarchy.

[MatchlessJoyride]

I see.

I really appreciate you taking the time to help me out. I just want to talk about one more thing - you've really helped me this morning.

When I look at the SyntaxTree of code like this:

module top (
    input  wire       clk,
    input  wire       rst_n,
    input  wire       enable,
    input  wire [7:0] data
);
  child_a u_child_a (
      .clk(clk), .rst_n(rst_n), .enable(enable), .data(data)
  );
`ifdef INCLUDE_CHILD_B
  child_b u_child_b (
      .clk(clk), .rst_n(rst_n), .enable(enable), .data(data)
  );
`endif
endmodule

I don't see any nodes that hint at the INCLUDE_CHILD_B define (maybe I'm doing something wrong here).

And when I look at the Compilation, I don't see child_b - which makes sense, since it didn't see INCLUDE_CHILD_B so it wasn't included in the design.

My questions:

• Is there any way to use pyslang to learn about the existence of INCLUDE_CHILD_B in the module, prior to compilation/elaboration?
• How can I pass INCLUDE_CHILD_B to the Compliation object so that it elaborates with the define set?

[MatchlessJoyride]

Ok, I think I answered my previous two questions.

Q: How do you discover INCLUDE_CHILD_B?

A: Look in the trivia. This script can do it:

from pathlib import Path

import pyslang


def main():
    """Main function demonstrating the logic declaration extractor."""

    import argparse

    parser = argparse.ArgumentParser(
        description="Slang example"
    )
    parser.add_argument(
        "file",
        help="SystemVerilog files to process (if none provided, uses built-in example)",
    )

    args = parser.parse_args()
    path = Path(args.file)

    tree = pyslang.SyntaxTree.fromFile(str(path.resolve()))

    directive_nodes = []  # list of *DirectiveSyntax nodes we discover

    seen_tokens: set[int] = set()  # deduplicate tokens via file offset

    def collect_directives(node):
        if not isinstance(node, pyslang.SyntaxNode):
            return

        def scan_token(tok):
            loc = tok.location.offset
            if loc in seen_tokens:
                return
            seen_tokens.add(loc)

            for trivia in tok.trivia:
                if trivia.kind == pyslang.TriviaKind.Directive:
                    directive_node = trivia.syntax()
                    kind_name = directive_node.kind.name if directive_node else "<unknown>"

                    # If it's an `ifdef/ifndef, grab just the identifier.
                    if directive_node.kind in (
                        pyslang.SyntaxKind.IfDefDirective,
                        pyslang.SyntaxKind.IfNDefDirective,
                    ):
                        # The identifier being checked is stored in the
                        # directive node’s expression; grab its first token.
                        ident_tok = directive_node.expr.getFirstToken()
                        raw_text = ident_tok.rawText if ident_tok else ""

                        directive_nodes.append((kind_name, raw_text))

        scan_token(node.getFirstToken())
        scan_token(node.getLastToken())

    tree.root.visit(collect_directives)

    print("Found pre-processing directives in the file:")
    for kind_name, raw in directive_nodes:
        print(f"  {kind_name:<20} {raw}")



if __name__ == "__main__":
    main()

Q: How do you pass INCLUDE_CHILD_B to the preprocessor?

A: Use a bag to collect preprocessor options and pass it to the Compilation object. Example:

options = pyslang.PreprocessorOptions()
options.predefines = ["INCLUDE_CHILD_B"]
bag = pyslang.Bag([options])

source_manager = pyslang.SourceManager()

tree = pyslang.SyntaxTree.fromFile(path.resolve(), source_manager, bag)

comp = pyslang.Compilation()
comp.addSyntaxTree(tree)

root = comp.getRoot()

Now, even though these examples work - are they the recommended/best practice ways to do it? Just looking for some validation here - I used Codex to arrive at these examples so it's very possible I missed a better way.

[MikePopoloski]

Yes, that looks right. Preprocessing is done prior to parsing and so you need to look in the trivia to see it, it's not part of the regular parse tree.

[MatchlessJoyride]

Thanks very much!