Hierarchy
Functions for working with the hierarchy of dependencies between
Verilog descriptions.
In Verilog-2005, the modules in a design form a hierarchy. Here is
some terminology we'll use regarding this hierarchy:
- We say that superior modules depend on the modules they
instantiate.
- We say that submodules are necessary for the modules that
instantiate them.
- We say that modules are missing if they are instantiated but never
defined.
- We say that a module list is complete if every module that is ever
instantiated has a definition.
SystemVerilog adds many kinds of top-level descriptions besides modules.
For instance, we may have interfaces, packages, programs, and so forth. There
may also be top-level declarations of parameters, functions, etc., that are not
embedded within any containing package, module, etc.
We can imagine a similar, expanded notion of hierarchy that can be applied
to designs with these other kinds of descriptions.
In the functions below, we take a rather inclusive view of the dependencies
between design elements. We view the design as containing a directed graph of
dependencies:
- The nodes are any top-level design elements. For instance, a node might be
a top-level container such as a module, interface, or package; it also might be
a top-level function declaration, parameter, etc.
- The edges in the graph are dependencies from one node to another. For
instance, we will say a superior module depends on the submodule it
instantiates, an interface depends on any packages it imports, a parameter
depends on the data type it refers to, and so forth.
This inclusive view makes collecting dependencies somewhat involved. We
have to walk through the expressions and check for references to items from
other packages. We also have to examine the data type of every variable. The
work of extracting the core dependency graph is done by the immdeps
functions.
Once we have collected a dependency graph, we can use it for many
purposes.
Subtopics
- Vl-design-toplevel
- (vl-design-toplevel x) gathers the names of any modules or
interfaces that are defined but are never instantiated in a design, and returns
them as an ordered set.
- Vl-remove-unnecessary-elements
- Throws away whatever part of the design is not necessary for
particular design elements.
- Vl-necessary-elements-transitive
- Gathers the names of all design elements that particular descriptions
transitively depend on.
- Vl-interfacelist-everinstanced
- Gather the names of every module and interface ever instanced in a
interface list or used in an interface port.
- Vl-dependent-elements-transitive
- Gather the names of all design elements that transitively depend
on particular descriptions.
- Vl-necessary-elements-direct
- Gathers the names of all design elements that particular descriptions
directly depend on.
- Vl-modulelist-everinstanced
- Gather the names of every module and interface ever instanced in a
module list or used in an interface port.
- Vl-dependent-elements-direct
- Gathers the names of all design elements that directly depend on
particular descriptions.
- Vl-design-deporder-modules
- Dependency-order sort the modules of a design.
- Vl-design-check-complete
- Check whether we have definitions for all of the descriptions used
throughout the design.
- Vl-design-upgraph
- Graph of upward dependencies. Fast alist.
- Immdeps
- Functions for collecting the immediate dependencies for various kinds
of descriptions, i.e., for collecting the edges of the hierarchy graph.
- Vl-design-downgraph
- Graph of downward dependencies. Fast alist.
- Vl-collect-dependencies
- Vl-hierarchy-free
- Free memoize tables associated with hierarchy functions.
