Symbol and Inner Symbol Rationale
This document describes various design points of the major CIRCT dialects relating to the use of symbols and the introduction of inner symbols and related types. This follows in the spirit of other MLIR Rationale docs.
Verilog and FIRRTL have, from a software compiler perspective, an unusual
number of nameable entities which can be referred to non-locally. These entities
have deep nesting in the code structures. The requirements of dealing with
these entities and references entails more complexity than provided by MLIR’s
symbols and symbol tables. Several CIRCT dialects, therefore, share a common
supplemental mechanism called “Inner Symbols” to manage these requirements.
Inner Symbols necessarily deviate from MLIR nested symbol tables to enable representation of the behavior of Verilog and FIRRTL.
Use of MLIR symbols ¶
MLIR symbols are directly used for items in the global scope. This primarily
firrtl modules, though other entities, such as
interfaces and bind statements and
firrtl non-local anchors, also share this
space. Modules and instances of them are well suited to MLIR symbols. They
are analogous in scoping and structure to functions and call instructions. The
firrtl.circuit operations define a symbol table, and all
modules contained define symbols, with instances referring by symbol to their
Inner Symbol ¶
hw module, many entities may exist which can be referenced
outside the module. Operations and ports (and memory ports), need to define
symbol-like data to allow forming non-SSA linkage between disparate elements.
To accomplish this, an attribute named
inner_sym is attached, providing a
scoped symbol-like name to the element. An operation with an
resides in arbitrarily-nested regions of a region that defines an
InnerSymbolTable and a
Inner Symbols are different from normal symbols due to MLIR symbol table
resolution rules. Specifically, normal symbols are resolved by first going up
to the closest parent symbol table and resolving down from there (recursing
back down for nested symbol paths). In FIRRTL and HW, modules define a symbol in a
builtin.module symbol table. For instances to be able to resolve the
modules they instantiate, the symbol use in an instance must resolve in the
top-level symbol table. If a module were a symbol table, instances resolving a
symbol would start from their own module, never seeing other modules (since
resolution would start in the parent module of the instance and be unable to go
to the global scope). The second problem arises from nesting. Symbol
defining operations must be immediate children of a symbol table. FIRRTL and HW/SV
operations which define an
inner_sym are grandchildren, at least, of a symbol
table and may be much further nested. Lastly, ports need to define
something not allowed by normal symbols.
Inner Symbol Reference Attribute ¶
InnerRefAttr is provided to encapsulate references to inner
symbols. This attribute stores the parent symbol and the inner symbol. This
provides a uniform type for storing and manipulating references to inner
Inner symbols are more costly than normal symbols, precisely from the
relaxation of MLIR symbol constraints. Since nested regions are allowed,
finding all operations defining an
inner_sym requires a recursive IR scan.
Verification is likewise trickier, partly due the significant increase in non-local references.
Common Use ¶
The most common use for
InnerRefAttrs are to build paths through the instantiation
graph to use a subset of the instances of an entity in some way. This may
be reading values via SystemVerilog’s cross-module references (XMRs),
specifying SV bind constraints,
specifying placement constraints, or representing non-local attributes (FIRRTL).
The common element for building paths of instances through the instantiation
graph is with a
NameRefArrayAttr attribute. This is used, for example, by