Netlist Paths

Netlist Paths is a library and command-line tool for querying a Verilog netlist. It reads an XML representation of a design’s netlist, produced by Verilator, and provides facilities for inspecting variables and their data type and dependency information. The library is written in C++ and has a Python interface allowing it to be integrated easily into scripts.

Compared with standard front-end EDA tools such as Synopsys Verdi and Spyglass, Netlist Paths is oriented towards command-line use for exploration of a design (rather than with a GUI), and for integration with Python infrastructure (rather than TCL) to build tools for analysing or debugging a design. By focusing on source-level connectivity it is lightweight and will run faster than standard tools to perform a comparable task, whilst also being open source and unrestricted by licensing issues. Applications include critical timing path investigation, creation of unit tests for design structure and connectivity, and development of patterns for quality-of-result reporting.

Installation

The following dependencies must be installed:

C++ compiler supporting C++17
CMake (minimum 3.12.0)
Boost (minimum 1.65.0)
Python (minimum 3.8)
Make
Autoconf
Flex
Bison
Doxygen (only required if building the documentation)

In an Ubuntu 20.04 environment for instance, these can be satisfied with:

➜ apt-get update && apt-get install -yq build-essential git flex bison libboost-all-dev libfl-dev cmake

To build and install netlist paths, configure the build system with CMake, then run Make. Note that Verilator is included as a submodule and as part of the build.

➜ git clone https://github.com/jameshanlon/netlist-paths.git
➜ cd netlist-paths
➜ git submodule update --init --recursive
...
➜ mkdir Release
➜ cd Release
➜ cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=./install
...
➜ make -j8 install
...

Optionally, run the unit tests:

➜ ctest --verbose
...

To build the documentation add -DNETLIST_PATHS_BUILD_DOCS=1 to the cmake command, and before running the cmake step, install the dependencies in a virtualenv:

➜ cd Release
➜ virtualenv -p python3 env
...
➜ source env/bin/activate
➜ pip install -r ../docs/requirements.txt

Once the build and install steps have completed, set PATH and PYTHONPATH appropriately to the bin and lib directories of the installation to make the command-line tools and Python modules accessible.

User guide

Command-line tool

The easiest way to use Netlist Paths is with the netlist-paths command line tool, which provides ways to access the library’s functionalities. For example (assuming PATH includes your installation directory), to compile and view a list of named objects in the FSM example module:

➜ netlist-paths --compile examples/fsm.sv --dump-names
Name           Type DType        Width Direction Location
-------------- ---- ------------ ----- --------- ------------------
i_clk          PORT logic        1     INPUT     examples/fsm.sv:3
i_finish       PORT logic        1     INPUT     examples/fsm.sv:6
i_rst          PORT logic        1     INPUT     examples/fsm.sv:4
i_start        PORT logic        1     INPUT     examples/fsm.sv:5
i_wait         PORT logic        1     INPUT     examples/fsm.sv:7
o_state        PORT [2:0] logic  3     OUTPUT    examples/fsm.sv:8
fsm.i_clk      VAR  logic        1     INPUT     examples/fsm.sv:3
fsm.i_finish   VAR  logic        1     INPUT     examples/fsm.sv:6
fsm.i_rst      VAR  logic        1     INPUT     examples/fsm.sv:4
fsm.i_start    VAR  logic        1     INPUT     examples/fsm.sv:5
fsm.i_wait     VAR  logic        1     INPUT     examples/fsm.sv:7
fsm.next_state VAR  packed union 3     NONE      examples/fsm.sv:31
fsm.o_state    VAR  [2:0] logic  3     OUTPUT    examples/fsm.sv:8
fsm.state_q    REG  packed union 3     NONE      examples/fsm.sv:28

This output lists each of the variables in the design, their type (variable or register), the Verilog data type, with data type width, the direction of the variable (ports only) and the source location. This list can be filtered by also supplying a pattern (with the --regex flag to enable regular expression matching):

➜ netlist-paths --compile examples/fsm.sv --dump-names state --regex
Name           Type DType        Width Direction Location
-------------- ---- ------------ ----- --------- ------------------
o_state        PORT [2:0] logic  3     OUTPUT    examples/fsm.sv:8
fsm.next_state VAR  packed union 3     NONE      examples/fsm.sv:31
fsm.o_state    VAR  [2:0] logic  3     OUTPUT    examples/fsm.sv:8
fsm.state_q    REG  packed union 3     NONE      examples/fsm.sv:28

There is similar behaviour with --dump-nets, --dump-ports, --dump-regs to select only net, port or register variable types respectively. The argument --dump-dtypes reports the named data types used in the design:

➜ netlist-paths --compile examples/fsm.sv --dump-dtypes fsm --regex
Name             Width Description
---------------- ----- ------------
fsm.state_enum_t 3     enum
fsm.state_t      3     packed union

Note that the --compile argument causes Verilator to be run to create the XML netlist, and is useful for compiling simple examples. Execution of Verilator can be seen with verbose output:

➜ netlist-paths --compile examples/fsm.sv --verbose
info: Running ".../bin/np-verilator_bin" +1800-2012ext+.sv --bbox-sys --bbox-unsup
  --xml-only --flatten --error-limit 10000 --xml-output l9pvjzq6 examples/fsm.sv
...

The -I and -D arguments can be used with --compile to add include directories and macro definitions respectively for Verilator, but for more complex invocations, Verilator can just be run separately and the path to the XML output provided to netlist-paths as an argument.

Command-line tool reference

usage: netlist-paths [-h] [-c] [-I include_path] [-D definition] [-o file] [--dump-names [pattern]]
                     [--dump-nets [pattern]] [--dump-ports [pattern]] [--dump-regs [pattern]]
                     [--dump-dtypes [pattern]] [--dump-dot] [--from point] [--to point] [--through point]
                     [--avoid point] [--traverse-registers] [--start-anywhere] [--end-anywhere] [--all-paths]
                     [--regex] [--wildcard] [--ignore-hierarchy-markers] [-v] [-d]
                     files [files ...]

Query a Verilog netlist

positional arguments:
  files                       Input files

options:
  -h, --help                  Show this help message and exit
  --version                   Display the version number and exit
  -c, --compile               Run Verilator to compile a netlist
  -I include_path             Add an source include path (only with --compile)
  -D definition               Define a preprocessor macro (only with --compile)
  -o file,--output file       Specify an output file
  --dump-names [pattern]      Dump all named entities, filter by regex
  --dump-nets [pattern]       Dump all nets, filter by regex
  --dump-ports [pattern]      Dump all ports, filter by regex
  --dump-regs [pattern]       Dump all registers, filter by regex
  --dump-dtypes [pattern]     Dump all data types, filter by regex
  --dump-dot                  Dump a dotfile of the netlist's graph
  --from point                Specify a path start point
  --to point                  Specify a path finish point
  --through point             Specify a path though point
  --avoid point               Specify a point for a path to avoid
  --traverse-registers        Allow paths to traverse registers
  --start-anywhere            Allow paths to start on any variable
  --end-anywhere              Allow paths to end on any variable
  --all-paths                 Find all paths between two points (exponential time)
  --regex                     Enable regular expression matching of names
  --wildcard                  Enable wildcard matching of names
  --ignore-hierarchy-markers  Ignore hierarchy markers: _ . /
  -v, --verbose               Print execution information
  -d, --debug                 Print debugging information

Python module

The functionality of Netlist Paths can be accessed in Python, using the py_netlist_paths module, which is is a wrapper around the C++ library. Full details of the API can be found in Python API reference, and for the C++ library in C++ API reference. As a simple example, the Python Netlist Paths library can be used interactively, first by creating an XML netlist file (and making sure the library install directory is a search path for Python modules:

➜ netlist-paths --compile examples/fsm.sv --output fsm.xml
➜ export PYTHONPATH=/path/to/netlist-paths/install/lib:$PYTHONPATH

A new Netlist object can then be created, specifying the XML file as an argument, and the list of named objects can be retrieved as above using the get_named_vertices() method:

➜ python3
Python 3.9.0 (default, Dec  6 2020, 18:02:34)
[Clang 12.0.0 (clang-1200.0.32.27)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from py_netlist_paths import Netlist
>>> netlist = Netlist('fsm.xml')
>>> for v in netlist.get_reg_vertices():
...     print(v.get_name())
...
fsm.state_q

This can then easily be turned into a script to create a tool that reports registers in a design:

import argparse
import sys
from py_netlist_paths import Netlist

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('netlist_file')
    args = parser.parse_args()
    netlist = np.Netlist(args.netlist_file)
    for register in netlist.get_reg_vertices():
        print('{} {}'.format(register.get_name(), register.get_dtype_str()))

This example tool can be run from the examples directory:

➜ netlist-paths --compile examples/fsm.sv --output fsm.xml
➜ python3 -m examples.list_registers -h
usage: list_registers.py [-h] netlist_file

positional arguments:
  netlist_file

optional arguments:
  -h, --help    show this help message and exit
➜ python3 -m examples.list_registers fsm.xml
fsm.state_q packed union

Running Netlist Paths on a design

If it is possible to elaborate a design with Verilator, then Netlist Paths can be used to analyse the XML netlist of that design. Verilator produces the netlist with the arguments --xml-only (causing it to only create XML output) and --flatten (causing it to force inlining of all modules, tasks and functions, fully elaborating the netlist). Examples of complex, real-world designs can be found in the netlist-paths-tests repository.

Limitations

Netlist Paths has some limitations that should be considered when using it:

It does not perform elaboration of the design at the bit level, meaning that dependencies are between named variables, rather than components of variables, such as subscripts, slices, or fields. As such, the dependencies it does infer are at a coarse level of granularity. Full bit-level elaboration (or bit blasting) will substantially impact the size of the netlist graph, and the corresponding runtimes, but it is something that may be supported in the future.
During elaboration of the design, Verilator introduces new entities that do not appear in the original design source, with names beginning or containing __V. This is a artefact of Verilator preparing the syntax tree for emission as C++ code for simulation, rather than as a true source-level netlist. Future releases of Verilator may improve this mapping.

Contributing

Contributions are welcome, check the GitHub issues page for work to do, and please follow the LLVM coding standards.

Developer notes

The command-line flags --verbose and --debug provide logging information that can aid debugging.

To produce XML from a test case (noting the underlying call to Verilator), using an adder as an example:

➜ cat tests/verilog/adder.sv
module adder
  #(parameter p_width = 32)(
    input  logic [p_width-1:0] i_a,
    input  logic [p_width-1:0] i_b,
    output logic [p_width-1:0] o_sum,
    output logic               o_co
  );
  assign {o_co, o_sum} = i_a + i_b;
endmodule
➜ netlist-paths --compile tests/verilog/adder.sv -o adder.xml --verbose
info: Running ".../netlist-paths/Debug/install/bin/np-verilator_bin" +1800-2012ext+.sv
   --bbox-sys --bbox-unsup --xml-only --flatten --error-limit 10000 --xml-output adder.xml tests/verilog/adder.sv
info: Parsing input XML file
info: 1 modules in netlist
info: 0 interfaces in netlist
info: 0 packages in netlist
info: 4 entries in type table
info: Netlist contains 15 vertices and 22 edges

To produce a visualisation of the netlist graph, a dot file can be produced and rendered into an image. This can be useful to understand the structure of the graph, although it is only practical to use with small designs.

➜ netlist-paths adder.xml --dump-dot -o adder.dot
➜ dot -Tpdf adder.dot -o adder.pdf

The tests are split into three categories: C++ unit tests for the library components, Python unit tests for the Python API and Python integration tests for the command-line tools. These can all be run automatically using ctest, or individually.

➜ ctest --verbose # Run all tests from the build directory.

For the C++ unit tests:

➜ ./tests/unit/UnitTests --help
➜ ./tests/unit/UnitTests --list_content # Report a list of all the tests.
➜ ./tests/unit/UnitTests # Run all the unit tests
...

For the Python API unit tests:

➜ cd Debug/tests/integration
➜ python3 -m unittest py_wrapper_tests.py
...

For the Python integration tests:

➜ cd Debug/tests/integration
➜ python3 -m unittest tool_tests.py
...

To run the extended test set, the netlist-paths-tests repository contains tests based on external System Verilog designs.

Internals

Netlist Paths works by reading an XML representation of a Verilog design produced by Verilator, which is a single flattened module with all tasks, functions, and sub-module instances inlined (Verilator is run using the --xml-only and --flatten options). The XML is traversed to build up a directed graph data structure representing the design netlist, where nodes of the graph are logic statements or variables, and edges are data dependencies between them. The data-type information of the design is also read from the XML, and a corresponding data-type table is constructed, that each variable references.

To support querying of paths that start and/or finish on registers (as is the case with physical timing reports), registers are identified during parsing of the XML so they can be split into two components: a source and a destination, with out-edges and in-edges of the original node respectively. Register variables are identified when they appear on the left-hand side of a non-blocking assignment 1. As an example, consider the following module that provides a bank of asynchronous-reset flip flops:

module pipestage
  #(parameter p_width=32) (
    input  logic               i_clk,
    input  logic               i_rst,
    input  logic [p_width-1:0] in,
    output logic [p_width-1:0] out
  );
  logic [p_width-1:0] data_q;
  always_ff @(posedge i_clk or posedge i_rst)
    if (i_rst) begin
      data_q <= '0;
    end else begin
      data_q <= in;
    end
  assign out = data_q;
endmodule

The netlist graph of the pipestage has two distinct components: the fan in-cone to data_q (appearing as a DST_REG) including the sensitivity list of the always block and the input port, and data_q driving the output port (appearing as a SRC_REG).

Edges between register endpoints and subsequent uses of the register are retained in the graph to support queries ‘through’ registers, which can be useful for establishing connectivity in a pipelined design.

1: Note that this condition is simplistic and will be extended to check the always block is sensitive to a rising or falling edge of a clock. It is however sufficient to identify registers in most RTL code, which generally does not mix blocking and non-blocking assignments. See Issue 5.

C++ API reference

DType

class netlist_paths::DType

Base class for data types.

Subclassed by netlist_paths::ArrayDType, netlist_paths::BasicDType, netlist_paths::ClassRefDType, netlist_paths::EnumDType, netlist_paths::MemberDType, netlist_paths::RefDType, netlist_paths::StructDType, netlist_paths::UnionDType, netlist_paths::VoidDType

Public Functions

inline virtual const std::string toString(const std::string suffix = "") const

Return the string representation of the data type.

Parameters: suffix – A suffix to allow unpacked array range specifications to be appended with the inner-most dimension on the LHS and outermost on the RHS.
Returns: A string representation of the data type.

Exception

class Exception : public exception

Base class for netlist_paths exceptions.

Subclassed by netlist_paths::XMLException

class XMLException : public netlist_paths::Exception : An exception from XML elaboration.

Netlist

class netlist_paths::Netlist

Wrapper for Python to manage the netlist object.

Public Functions

Netlist(const std::string &filename)

Construct a new netlist from an XML file.

Parameters: filename – A path to the XML netlist file.

const std::string getVertexDTypeStr(const std::string &name, VertexNetlistType vertexType = VertexNetlistType::ANY) const

Lookup the data type string of a single vertex.

Parameters

name – A pattern specifying a name to match.
vertexType – The type of the vertex to lookup.

Returns

A string representing the data type.

size_t getVertexDTypeWidth(const std::string &name, VertexNetlistType vertexType = VertexNetlistType::ANY) const

Lookup the data type width of a single vertex.

Parameters

name – A pattern specifying a name to match.
vertexType – The type of the vertex to lookup.

Returns

The width of the data type.

size_t getDTypeWidth(const std::string &name) const

Lookup the width of a data type by name.

Parameters: name – A pattern specifying a name to match.
Returns: The width of the data type.

const std::vector<DType*> getNamedDTypes(const std::string pattern = std::string()) const: Return a vector of data types in the design. Convert to raw pointers for Python.

bool startpointExists(const std::string &name) const

Return true if a single startpoint matching a pattern exists.

Parameters: name – A pattern specifying a name to match.
Returns: True if the startpoint exists.

bool endpointExists(const std::string &name) const

Return true if a single endpoint matching a pattern ‘name’ exists.

Parameters: name – A pattern specifying a name to match.
Returns: True if the endpoint exists.

bool anyStartpointExists(const std::string &name) const

Return true if any startpoint matching a pattern ‘name’ exists.

Parameters: name – A pattern specifying a name to match.
Returns: True if any startpoint exists.

bool anyEndpointExists(const std::string &name) const

Return true if any endpoint matching a pattern ‘name’ exists.

Parameters: name – A pattern specifying a name to match.
Returns: True if any endpoint exists.

bool regExists(const std::string &name) const

Return true if a single register matching a pattern ‘name’ exists.

Parameters: name – A pattern specifying a name to match.
Returns: True if the register exists.

bool anyRegExists(const std::string &name) const

Return true if any register matching a pattern ‘name’ exists.

Parameters: name – A pattern specifying a name to match.
Returns: True if any register exists.

bool pathExists(Waypoints waypoints) const

Return a Boolean to indicate whether any path exists between two points.

Parameters: waypoints – A waypoints object constraining the path.
Returns: True if a path exists.

Path getAnyPath(Waypoints waypoints) const

Return any path between two points.

Parameters: waypoints – A waypoints object constraining the path.
Returns: A path if one exists, otherwise an empty vector.

std::vector<Path> getAllPaths(Waypoints waypoints) const

Return all paths between two points, useful for testing.

Parameters: waypoints – A waypoints object constraining the path.
Returns: All paths matching the waypoints, otherwise an empty vector.

std::vector<Path> getAllFanOut(const std::string startName) const

Return a vector of paths fanning out from a particular start point.

Parameters: startName – A pattern matching a start point.
Returns: All paths fanning out from the matching startpoint, otherwise an empty vector.

std::vector<Path> getAllFanIn(const std::string endName) const

Return a vector of paths fanning out from a particular start point.

Parameters: endName – A pattern matching an end point.
Returns: All paths fanning in to the matching endpoint, otherwise an empty vector.

std::vector<std::reference_wrapper<const Vertex>> getNamedVertices(const std::string pattern = std::string()) const

Return a sorted list of unique named vertices in the netlist for searching.

Parameters: pattern – A pattern to match vertices against.
Returns: A vector of Vertex references.

inline std::vector<Vertex*> getNamedVerticesPtr(const std::string pattern = std::string()) const

Return a vector of pointers to vertices that have names.

Parameters: pattern – A pattern to match vertices against.
Returns: A vector of pointers to Vertex objects.

inline std::vector<Vertex*> getNetVerticesPtr(const std::string pattern = std::string()) const

Return a vector of pointers to net vertices.

Parameters: pattern – A pattern to match vertices against.
Returns: A vector of pointers to Vertex objects.

inline std::vector<Vertex*> getPortVerticesPtr(const std::string pattern = std::string()) const

Return a vector of pointers to port vertices.

Parameters: pattern – A pattern to match vertices against.
Returns: A vector of pointers to Vertex objects.

inline std::vector<Vertex*> getRegVerticesPtr(const std::string pattern = std::string()) const

Return a vector of pointers to register vertices.

Parameters: pattern – A pattern to match vertices against.
Returns: A vector of pointers to Vertex objects.

inline void dumpDotFile(const std::string &outputFilename) const

Write a dot-file represenation of the netlist graph to a file.

Parameters: outputFilename – The file to write the dot output to.

inline bool isEmpty() const: Return true if the netlist is empty.

Options

class netlist_paths::Options

A class encapsulating options.

Public Functions

inline void setMatchWildcard(): Set matching to use wildcards.

inline void setMatchRegex(): Set matching to use regular expressions.

inline void setMatchExact(): Set matching to be exact.

inline void setIgnoreHierarchyMarkers(bool value): Set matching to ignore (true) or respect (false) hierarchy markers (only with wildcard or regular expression matching modes). Note that hierarchy markers are ‘.’, ‘/’ and ‘_’.

inline void setMatchOneVertex(): Set matching to identify one vertex, and for it to be an error if more than one vertex is matched.

inline void setMatchAnyVertex(): Set matching to identify multiple vertices, and for just one to be chosen arbitrarily.

inline void setTraverseRegisters(bool value): Enable or disable path traversal of registers.

inline void setRestrictStartPoints(bool value): Set path start point restriction. When set to true, paths must start on top-level ports or registers. When set to false, paths can start on any variable.

inline void setRestrictEndPoints(bool value): Set path end point restriction. When set to true, paths must end on top-level ports or registers. When set to false, paths can end on any variable.

inline void setErrorOnUnmatchedNode(bool value): Setup the XML parser to raise an error when an unmatched node is encountered. For testing purposes only.

inline void setLoggingVerbose(): Enable verbose output.

inline void setLoggingDebug(): Enable debug output (including verbose messages).

inline void setLoggingQuiet(): Supress verbose and debug messages.

inline void setLoggingErrorOnly(): Supress warning, verbose and debug messages.

Public Static Functions

static inline Options &getInstance(): Return a reference to the Options object.

static inline Options *getInstancePtr(): Return a pointer to the Options object.

Path

class netlist_paths::Path

A class to represent a path through the netlist graph.

Public Functions

inline Path(): Construct an empty path.

inline Path(const std::vector<const Vertex*> sourceVertices)

Constrct a Path from a list of Vertices.

Parameters: sourceVertices – A vector of vertices to copy.

inline Path(const Path &path)

Copy constructor.

Parameters: path – The Path to copy.

inline bool operator==(const Path &other) const

Test equality with another path.

Parameters: other – The Path to test against.
Returns: A Boolean indicating equal or not.

inline bool contains(const Vertex *vertex) const

Return true if the vertex is contained in this path.

Parameters: vertex – The Vertex to test.
Returns: A Boolean indicating whether vertex is contained in this path.

inline void reverse(): Reverse the order of vertices in this path.

inline void appendVertex(const Vertex *vertex)

Append a vertex to the end of this path.

Parameters: vertex – The Vertex to append to this path.

inline void appendPath(const Path &path)

Append a path to the end of this path.

Parameters: path – The Path to append to this path.

RunVerilator

class netlist_paths::RunVerilator

A class that provides facilities to run Verilator and produce XML netlists.

Public Functions

RunVerilator(): Default constructor. Locate the Netlist Paths Verilator executable relative to the location of the Netlist Paths library.

RunVerilator(const std::string &verilatorLocation)

Constructor, providing a path to a Verilator executable.

Parameters: verilatorLocation – The location of the Netlists Paths Verilator executable (np-verilator_bin).

int run(const std::vector<std::string> &includes, const std::vector<std::string> &defines, const std::vector<std::string> &inputFiles, const std::string &topModule, const std::string &outputFile) const

Run Verilator.

Parameters

includes – A vector of search paths for include files.
defines – A vector of macro definitions.
inputFiles – A vector of source file paths.
outputFile – A path specifying an output file.

int run(const std::string &inputFile, const std::string &outputFile) const

Run Verilator with a single source file and no other options.

Parameters

inputFile – A source file path.
outputFile – A path specifying an output file.

Vertex

class netlist_paths::Vertex

A class representing a vertex in the netlist graph.

Public Functions

inline Vertex(VertexAstType type, Location location)

Construct a logic vertex.

Parameters

type – The AST type of the logic statement.
location – The source location of the logic statement.

inline Vertex(VertexAstType type, VertexDirection direction, Location location, std::shared_ptr<DType> dtype, const std::string &name, bool isParam, const std::string &paramValue, bool publicVisibility)

Construct a variable vertex.

Parameters

type – The AST type of the variable.
direction – The direction of the variable type.
location – The source location of the variable declaration.
dtype – The data type of the variable.
name – The name of the variable.
isParam – A flag indicating the variable is a parameter.
paramValue – The value of the parameter variable.
publicVisibility – A flag indicating the variable has public visibility.

inline Vertex(const Vertex &v): Copy constructor.

inline std::string getBasename() const

Given a hierarchical variable name, eg a.b.c, return the last component c.

Returns: The last heirarchical component of a variable name.

inline bool isGraphType(VertexNetlistType type) const

Match this vertex against different graph types.

Parameters: type – A categorisation of a vertex.
Returns: Whether the vertex matches the specified type.

inline bool compareLessThan(const Vertex &b) const: Less than comparison between two Vertex objects.

inline bool compareEqual(const Vertex &b) const: Equality comparison between two vertex objects.

inline bool isTop() const: Return true if the vertex is in the top scope.

inline bool isPublic() const: Return true if the vertex has public visibility.

inline bool isSrcReg() const: Return true if the vertex is a source register.

inline bool isDstReg() const: Return true if the vertex is a destination register.

inline bool isLogic() const: Return true if the vertex is a logic statement.

inline bool isParameter() const: Return true if the vertex is a parameter variable.

inline bool isNet() const: Return true if the vertex is a net variable.

inline bool isReg() const: Return true if the vertex is a register variable.

inline bool isSrcRegAlias() const: Return true if the vertex is an alias of a source register variable.

inline bool isDstRegAlias() const: Return true if the vertex is an alias of a destination register variable.

inline bool isPort() const: Return true if the vertex is a port variable. Handle a special case where port registers have REG VertexAstType.

inline bool isCombStartPoint() const

Return true if the vertex is a valid start point for a combinatorial path within the netlist.

Source register
Alias of a source register
A top input or inout port

inline bool isCombEndPoint() const

Return true if the vertex is a valid end point for a combinatorial path within the netlist.

Destination register
Alias of a destination register
A top output or inout port

inline bool isStartPoint() const: Return true if the vertex is a valid start point for a path.

inline bool isEndPoint() const: Return true if the vertex is a valid end point for a path.

inline bool isMidPoint() const: Return true if the vertex is a valid mid point for a path.

inline bool canIgnore() const: Return true if the vertex has been introduced by Verilator.

inline bool isNamed() const: Return true if the vertex has a name, ie is a variable of some description.

inline const char *getSimpleAstTypeStr() const: Map Vertex AST types to useful names that can be included in reports.

inline std::string toString() const: Return a string description of this vertex.

Public Static Functions

static inline bool determineIsTop(const std::string &name)

Return whether a variable name is a top signal.

A variable is ‘top’ when it is not prefixed with any hierarchy path. This applies to top-level ports and parameters only, since all other variables exist within a module scope.

Parameters: name – The name of a variable.
Returns: Whether the variable is in the top scope.

enum class netlist_paths::VertexAstType

Vertex types corresponding to the Verilator XML AST format.

Values:

enumerator ALWAYS

enumerator ASSIGN

enumerator ASSIGN_ALIAS

enumerator ASSIGN_DLY

enumerator ASSIGN_W

enumerator CASE

enumerator C_CALL

enumerator C_FUNC

enumerator C_METHOD_CALL

enumerator C_STMT

enumerator DISPLAY

enumerator DST_REG

enumerator DST_REG_ALIAS

enumerator FINISH

enumerator IF

enumerator INITIAL

enumerator INSTANCE

enumerator JUMP_BLOCK

enumerator LOGIC

enumerator PORT

enumerator READ_MEM

enumerator SEN_GATE

enumerator SFORMATF

enumerator SRC_REG

enumerator SRC_REG_ALIAS

enumerator VAR

enumerator WHILE

enumerator WIRE

enumerator INVALID

enum class netlist_paths::VertexNetlistType

Vertex categorisation within the netlist graph, used for selecting collections of vertices with particular properties.

Values:

enumerator DST_REG

enumerator DST_REG_ALIAS

enumerator END_POINT

enumerator IS_NAMED

enumerator LOGIC

enumerator MID_POINT

enumerator NET

enumerator PORT

enumerator REG

enumerator SRC_REG

enumerator SRC_REG_ALIAS

enumerator START_POINT

enumerator ANY

enum class netlist_paths::VertexDirection

The direction of a variable, applying only to ports.

Values:

enumerator NONE

enumerator INPUT

enumerator OUTPUT

enumerator INOUT

Waypoints

class netlist_paths::Waypoints

A class representing a set of waypoints to constrain a search for a path.

Public Functions

inline Waypoints(): Construct an empty Waypoints object.

inline Waypoints(const std::string start, const std::string end)

Construct a Waypoints object with patterns matching start and finish points.

Parameters

start – A pattern specifying a start point.
end – A pattern specifying an end point.

inline void addStartPoint(const std::string name)

Set a named start point.

Parameters: name – A pattern specifying a start point.

inline void addEndPoint(const std::string name)

Set a named end point.

Parameters: name – A pattern specifying an end point.

inline void addThroughPoint(const std::string name)

Add a through point.

Parameters: name – A pattern specifying a mid point.

inline void addAvoidPoint(const std::string name)

Add a point to avoid.

Parameters: name – A pattern specifying a mid point to avoid.

inline const std::vector<std::string> &getWaypoints() const

Access the waypoints.

Returns: An ordered vector of patterns for each waypoint.

inline const std::vector<std::string> &getAvoidPoints() const

Access the avoid points.

Returns: An ordered vector of patterns for each avoid point.

Python API reference

DType

class py_netlist_paths.DType

append((DType)arg1, (object)arg2) → None :

C++ signature :: void append(std::vector<netlist_paths::DType*, std::allocator<netlist_paths::DType*> > {lvalue},boost::python::api::object)

extend((DType)arg1, (object)arg2) → None :

C++ signature :: void extend(std::vector<netlist_paths::DType*, std::allocator<netlist_paths::DType*> > {lvalue},boost::python::api::object)

Options

class py_netlist_paths.Options

static get_instance() → Options :

C++ signature :: netlist_paths::Options* get_instance()

set_error_on_unmatched_node((Options)arg1, (bool)arg2) → None :

C++ signature :: void set_error_on_unmatched_node(netlist_paths::Options {lvalue},bool)

set_ignore_hierarchy_markers((Options)arg1, (bool)arg2) → None :

C++ signature :: void set_ignore_hierarchy_markers(netlist_paths::Options {lvalue},bool)

set_logging_debug((Options)arg1) → None :

C++ signature :: void set_logging_debug(netlist_paths::Options {lvalue})

set_logging_error_only((Options)arg1) → None :

C++ signature :: void set_logging_error_only(netlist_paths::Options {lvalue})

set_logging_quiet((Options)arg1) → None :

C++ signature :: void set_logging_quiet(netlist_paths::Options {lvalue})

set_logging_verbose((Options)arg1) → None :

C++ signature :: void set_logging_verbose(netlist_paths::Options {lvalue})

set_match_any_vertex((Options)arg1) → None :

C++ signature :: void set_match_any_vertex(netlist_paths::Options {lvalue})

set_match_exact((Options)arg1) → None :

C++ signature :: void set_match_exact(netlist_paths::Options {lvalue})

set_match_one_vertex((Options)arg1) → None :

C++ signature :: void set_match_one_vertex(netlist_paths::Options {lvalue})

set_match_regex((Options)arg1) → None :

C++ signature :: void set_match_regex(netlist_paths::Options {lvalue})

set_match_wildcard((Options)arg1) → None :

C++ signature :: void set_match_wildcard(netlist_paths::Options {lvalue})

set_restrict_end_points((Options)arg1, (bool)arg2) → None :

C++ signature :: void set_restrict_end_points(netlist_paths::Options {lvalue},bool)

set_restrict_start_points((Options)arg1, (bool)arg2) → None :

C++ signature :: void set_restrict_start_points(netlist_paths::Options {lvalue},bool)

set_traverse_registers((Options)arg1, (bool)arg2) → None :

C++ signature :: void set_traverse_registers(netlist_paths::Options {lvalue},bool)

Netlist

class py_netlist_paths.Netlist

any_endpoint_exists((Netlist)arg1, (str)arg2) → bool :

C++ signature :: bool any_endpoint_exists(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

any_reg_exists((Netlist)arg1, (str)arg2) → bool :

C++ signature :: bool any_reg_exists(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

any_startpoint_exists((Netlist)arg1, (str)arg2) → bool :

C++ signature :: bool any_startpoint_exists(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

dump_dot_file((Netlist)arg1, (str)arg2) → None :

C++ signature :: void dump_dot_file(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

endpoint_exists((Netlist)arg1, (str)arg2) → bool :

C++ signature :: bool endpoint_exists(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

get_all_fanin_paths((Netlist)arg1, (str)arg2) → PathList :

C++ signature :: std::vector<netlist_paths::Path, std::allocator<netlist_paths::Path> > get_all_fanin_paths(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

get_all_fanout_paths((Netlist)arg1, (str)arg2) → PathList :

C++ signature :: std::vector<netlist_paths::Path, std::allocator<netlist_paths::Path> > get_all_fanout_paths(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

get_all_paths((Netlist)arg1, (Waypoints)arg2) → PathList :

C++ signature :: std::vector<netlist_paths::Path, std::allocator<netlist_paths::Path> > get_all_paths(netlist_paths::Netlist {lvalue},netlist_paths::Waypoints)

get_any_path((Netlist)arg1, (Waypoints)arg2) → Path :

C++ signature :: netlist_paths::Path get_any_path(netlist_paths::Netlist {lvalue},netlist_paths::Waypoints)

get_dtype_width((Netlist)arg1, (str)arg2) → int :

C++ signature :: unsigned long get_dtype_width(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

get_named_dtypes((Netlist)arg1, (str)arg2) → DType :

C++ signature :: std::vector<netlist_paths::DType*, std::allocator<netlist_paths::DType*> > get_named_dtypes(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

get_named_vertices((Netlist)arg1[, (str)arg2]) → VertexList :

C++ signature :: std::vector<netlist_paths::Vertex*, std::allocator<netlist_paths::Vertex*> > get_named_vertices(netlist_paths::Netlist {lvalue} [,std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >])

get_net_vertices((Netlist)arg1[, (str)arg2]) → VertexList :

C++ signature :: std::vector<netlist_paths::Vertex*, std::allocator<netlist_paths::Vertex*> > get_net_vertices(netlist_paths::Netlist {lvalue} [,std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >])

get_port_vertices((Netlist)arg1[, (str)arg2]) → VertexList :

C++ signature :: std::vector<netlist_paths::Vertex*, std::allocator<netlist_paths::Vertex*> > get_port_vertices(netlist_paths::Netlist {lvalue} [,std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >])

get_reg_vertices((Netlist)arg1[, (str)arg2]) → VertexList :

C++ signature :: std::vector<netlist_paths::Vertex*, std::allocator<netlist_paths::Vertex*> > get_reg_vertices(netlist_paths::Netlist {lvalue} [,std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >])

get_vertex_dtype_str((Netlist)arg1, (str)arg2[, (object)arg3]) → str :

C++ signature :: std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > get_vertex_dtype_str(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > [,netlist_paths::VertexNetlistType])

get_vertex_dtype_width((Netlist)arg1, (str)arg2[, (object)arg3]) → int :

C++ signature :: unsigned long get_vertex_dtype_width(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > [,netlist_paths::VertexNetlistType])

path_exists((Netlist)arg1, (Waypoints)arg2) → bool :

C++ signature :: bool path_exists(netlist_paths::Netlist {lvalue},netlist_paths::Waypoints)

reg_exists((Netlist)arg1, (str)arg2) → bool :

C++ signature :: bool reg_exists(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

startpoint_exists((Netlist)arg1, (str)arg2) → bool :

C++ signature :: bool startpoint_exists(netlist_paths::Netlist {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

Waypoints

class py_netlist_paths.Waypoints

add_avoid_point((Waypoints)arg1, (str)arg2) → None :

C++ signature :: void add_avoid_point(netlist_paths::Waypoints {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

add_finish_point((Waypoints)arg1, (str)arg2) → None :

C++ signature :: void add_finish_point(netlist_paths::Waypoints {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

add_start_point((Waypoints)arg1, (str)arg2) → None :

C++ signature :: void add_start_point(netlist_paths::Waypoints {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

add_through_point((Waypoints)arg1, (str)arg2) → None :

C++ signature :: void add_through_point(netlist_paths::Waypoints {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

Path

class py_netlist_paths.Path

append_path((Path)arg1, (Path)arg2) → None :

C++ signature :: void append_path(netlist_paths::Path {lvalue},netlist_paths::Path)

append_vertex((Path)arg1, (Vertex)arg2) → None :

C++ signature :: void append_vertex(netlist_paths::Path {lvalue},netlist_paths::Vertex const*)

contains_vertex((Path)arg1, (Vertex)arg2) → bool :

C++ signature :: bool contains_vertex(netlist_paths::Path {lvalue},netlist_paths::Vertex const*)

empty((Path)arg1) → bool :

C++ signature :: bool empty(netlist_paths::Path {lvalue})

get_finish_vertex((Path)arg1) → Vertex :

C++ signature :: netlist_paths::Vertex* get_finish_vertex(netlist_paths::Path {lvalue})

get_start_vertex((Path)arg1) → Vertex :

C++ signature :: netlist_paths::Vertex* get_start_vertex(netlist_paths::Path {lvalue})

get_vertex((Path)arg1, (int)arg2) → Vertex :

C++ signature :: netlist_paths::Vertex* get_vertex(netlist_paths::Path {lvalue},unsigned long)

get_vertices((Path)arg1) → VertexList :

C++ signature :: std::vector<netlist_paths::Vertex*, std::allocator<netlist_paths::Vertex*> > get_vertices(netlist_paths::Path {lvalue})

length((Path)arg1) → int :

C++ signature :: unsigned long length(netlist_paths::Path {lvalue})

reverse((Path)arg1) → None :

C++ signature :: void reverse(netlist_paths::Path {lvalue})

RunVerilator

class py_netlist_paths.RunVerilator

run((RunVerilator)arg1, (str)arg2, (str)arg3) → int :

C++ signature :
int run(netlist_paths::RunVerilator {lvalue},std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >,std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

run( (RunVerilator)arg1, (list)arg2, (list)arg3, (list)arg4, (str)arg5, (str)arg6) -> int :

C++ signature :
int run(netlist_paths::RunVerilator {lvalue},boost::python::list,boost::python::list,boost::python::list,std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >,std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >)

Vertex

class py_netlist_paths.Vertex

can_ignore((Vertex)arg1) → bool :

C++ signature :: bool can_ignore(netlist_paths::Vertex {lvalue})

get_ast_type_str((Vertex)arg1) → str :

C++ signature :: char const* get_ast_type_str(netlist_paths::Vertex {lvalue})

get_direction_str((Vertex)arg1) → str :

C++ signature :: std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > get_direction_str(netlist_paths::Vertex {lvalue})

get_dtype((Vertex)arg1) → DType :

C++ signature :: netlist_paths::DType* get_dtype(netlist_paths::Vertex {lvalue})

get_dtype_str((Vertex)arg1) → str :

C++ signature :: std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > get_dtype_str(netlist_paths::Vertex {lvalue})

get_dtype_width((Vertex)arg1) → int :

C++ signature :: unsigned long get_dtype_width(netlist_paths::Vertex {lvalue})

get_id((Vertex)arg1) → int :

C++ signature :: unsigned long get_id(netlist_paths::Vertex {lvalue})

get_location_str((Vertex)arg1) → str :

C++ signature :: std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > get_location_str(netlist_paths::Vertex {lvalue})

get_name((Vertex)arg1) → str :

C++ signature :: std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > get_name(netlist_paths::Vertex {lvalue})

is_end_point((Vertex)arg1) → bool :

C++ signature :: bool is_end_point(netlist_paths::Vertex {lvalue})

is_logic((Vertex)arg1) → bool :

C++ signature :: bool is_logic(netlist_paths::Vertex {lvalue})

is_mid_point((Vertex)arg1) → bool :

C++ signature :: bool is_mid_point(netlist_paths::Vertex {lvalue})

is_net((Vertex)arg1) → bool :

C++ signature :: bool is_net(netlist_paths::Vertex {lvalue})

is_parameter((Vertex)arg1) → bool :

C++ signature :: bool is_parameter(netlist_paths::Vertex {lvalue})

is_port((Vertex)arg1) → bool :

C++ signature :: bool is_port(netlist_paths::Vertex {lvalue})

is_public((Vertex)arg1) → bool :

C++ signature :: bool is_public(netlist_paths::Vertex {lvalue})

is_reg((Vertex)arg1) → bool :

C++ signature :: bool is_reg(netlist_paths::Vertex {lvalue})

is_start_point((Vertex)arg1) → bool :

C++ signature :: bool is_start_point(netlist_paths::Vertex {lvalue})

is_top((Vertex)arg1) → bool :

C++ signature :: bool is_top(netlist_paths::Vertex {lvalue})