svinst 0.1.5

Python library for parsing module definitions and instantiations from SystemVerilog files

pysvinst

This Python library examines SystemVerilog files to determine what modules are defined and what modules are instantiated. The backend uses sv-parser, which has good support of SystemVerilog 2017.

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

This package can be installed via pip:

> pip install svinst

Alternatively, you can clone the repository and build the package yourself. This requires that Rust is installed.

> git clone https://github.com/sgherbst/pysvinst.git
> cd pysvinst
> pip install -e .

Usage

The main functionality of this package is provided through the function get_defs. In this first example, a list of module definitions is returned, each one containing a list module instantiations (if any) contained in that module definition.

>>> from svinst import get_defs
>>> defs = get_defs('tests/verilog/test.sv')
>>> _ = [print(str(def_)) for def_ in defs]
ModDef("A", [
])
ModDef("B", [
])
ModDef("C", [
  ModInst("A", "I0"),
  ModInst("B", "I1")
])
ModDef("D", [
  ModInst("X", "I0"),
  ModInst("Y", "I1")
])

It is also possible to add define variables and include directory paths, since both of these can change the modules that get defined and instantiated:

>>> get_defs('tests/verilog/inc_test.sv', includes=['tests/verilog'])
>>> get_defs('tests/verilog/def_test.sv',
             defines={'MODULE_NAME': 'module_name_from_define', 'EXTRA_INSTANCE': None})

If there is a syntax error, an error message is printed and an Exception is raised.

>>> get_defs('tests/verilog/broken.sv')
parse failed: "tests/verilog/broken.sv"
 tests/verilog/broken.sv:5:10
  |
5 | endmodule
  |  

Finally, the user can get a full syntax tree for advanced processing, using the command get_syntax_tree. That command also allows the arguments includes and defines.

>>> from svinst import get_syntax_tree
>>> tree = get_syntax_tree('tests/verilog/simple.sv')
>>> _ = [print(elem) for elem in tree]
SyntaxNode("SourceText", [
  SyntaxNode("Description", [
    SyntaxNode("ModuleDeclaration", [
      SyntaxNode("ModuleDeclarationAnsi", [
        SyntaxNode("ModuleAnsiHeader", [
          SyntaxNode("ModuleKeyword", [
            SyntaxNode("Keyword", [
              SyntaxToken("module", line=1)
            ])
          ]),
          SyntaxNode("ModuleIdentifier", [
            SyntaxNode("Identifier", [
              SyntaxNode("SimpleIdentifier", [
                SyntaxToken("A", line=1)
              ])
            ])
          ]),
          SyntaxNode("Symbol", [
            SyntaxToken(";", line=1)
          ])
        ]),
        SyntaxNode("Keyword", [
          SyntaxToken("endmodule", line=2)
        ])
      ])
    ])
  ])
])