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.

Introduction ¶

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 consists of hw or firrtl modules, though other entities, such as sv 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 top-level builtin.module or firrtl.circuit operations define a symbol table, and all modules contained define symbols, with instances referring by symbol to their instantiated module.

Inner Symbol ¶

Within a firrtl or 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 inner_sym resides in arbitrarily-nested regions of a region that defines an InnerSymbolTable and a Symbol .

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 firrtl.circuit or 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 inner_sym, something not allowed by normal symbols.

Inner Symbol Reference Attribute ¶

An 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 symbols.

Cost ¶

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 hw.GlobalRefOp and firrtl.NonLocalAnchor.