svinst

This tool takes a SystemVerilog file as input and produces as output the module(s) declared in that file, along with the module(s) instantiated in each one of those module declarations. It uses sv-parser and is adapted from svlint.

For those interested to access this functionality from Python, please see pysvinst.

Purpose

The Verilog language has contains features for defining configs and libraries. However, these features are not well-supported by open-source tools, and even some commercial synthesis tools. By extracting a list of modules defined and instantiated in a file, a user can work around this problem by constructing their own design hierarchy outside of Verilog, and then passing that list of files back into the simulator / synthesis tool.

Installation

You can download a binary for your system from the Releases tab. This method does not require Rust be installed.

Alternatively, you can install the package with Cargo:

> cargo install svinst

Usage

The svinst binary accepts one or more SystemVerilog files as input, and prints a YAML-formatted representation of the modules defined and instantiated in those files:

> svinst verilog/test.sv
files:
  - file_name: "verilog/test.sv"
    defs:
      - mod_name: "A"
        insts:
      - mod_name: "B"
        insts:
      - mod_name: "C"
        insts:
          - mod_name: "A"
            inst_name: "I0"
          - mod_name: "B"
            inst_name: "I1"
      - mod_name: "D"
        insts:
          - mod_name: "X"
            inst_name: "I0"
          - mod_name: "Y"
            inst_name: "I1"

If there are any parsing errors, the return code of svinst is nonzero, and the error message(s) will be sent to stderr:

> svinst verilog/broken.sv > /dev/null
parse failed: "verilog/broken.sv"
 verilog/broken.sv:5:10
  |
5 | endmodule
  |
> echo $?
1

It is also possible to specify files to be included on the command line, via the -i INCLUDE_PATH option. Multiple include paths may be specified; pass each separately via individual -i options.

> svinst verilog/inc_test.sv -i verilog/
files:
  - file_name: "verilog/inc_test.sv"
    defs:
      - mod_name: "inc_top"
        insts:
          - mod_name: "mod_name_from_inc_sv"
            inst_name: "I0"

Pre-processor defines can be set from the command line as well. In this example, the first define has both a name and a value, controlling the name of the instantiated module from a define variable. The second define has only a name, and it causes a second module to be instantiated only if it has be defined.

> svinst verilog/def_test.sv -d MODULE_NAME=module_name_from_define -d EXTRA_INSTANCE
files:
  - file_name: "verilog/def_test.sv"
    defs:
      - mod_name: "def_top"
        insts:
          - mod_name: "module_name_from_define"
            inst_name: "I0"
          - mod_name: "module_from_ifdef"
            inst_name: "I1"

It is also possible to generate the full syntax tree for SystemVerilog file(s) using the full-tree option. The output is still in YAML format:

> svinst verilog/simple.sv --full-tree
files:
  - file_name: "verilog/simple.sv"
    syntax_tree:
      - SourceText:
        - Description:
          - ModuleDeclaration:
            - ModuleDeclarationAnsi:
              - ModuleAnsiHeader:
                - ModuleKeyword:
                  - Keyword:
                    - Token: "module"
                      Line: 1
                - ModuleIdentifier:
                  - Identifier:
                    - SimpleIdentifier:
                      - Token: "A"
                        Line: 1
                - Symbol:
                  - Token: ";"
                    Line: 1
              - Keyword:
                - Token: "endmodule"
                  Line: 2