ImportVerilogInternals.h

Go to the documentation of this file.

//===- ImportVerilogInternals.h - Internal implementation details ---------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
 
// NOLINTNEXTLINE(llvm-header-guard)
#ifndef CONVERSION_IMPORTVERILOG_IMPORTVERILOGINTERNALS_H
#define CONVERSION_IMPORTVERILOG_IMPORTVERILOGINTERNALS_H
 
#include "CaptureAnalysis.h"
#include "circt/Conversion/ImportVerilog.h"
#include "circt/Dialect/Debug/DebugOps.h"
#include "circt/Dialect/HW/HWOps.h"
#include "circt/Dialect/LTL/LTLOps.h"
#include "circt/Dialect/Moore/MooreOps.h"
#include "circt/Dialect/SV/SVAttributes.h"
#include "circt/Dialect/SV/SVDialect.h"
#include "circt/Dialect/Verif/VerifOps.h"
#include "mlir/Dialect/ControlFlow/IR/ControlFlowOps.h"
#include "mlir/Dialect/Func/IR/FuncOps.h"
#include "slang/ast/ASTVisitor.h"
#include "slang/ast/TimingControl.h"
#include "slang/text/SourceManager.h"
#include "llvm/ADT/ScopedHashTable.h"
#include "llvm/Support/Debug.h"
#include <map>
#include <queue>
 
#define DEBUG_TYPE "import-verilog"
 
namespace circt {
namespace ImportVerilog {
 
using moore::Domain;
 
/// Get the slang canonical body for the given `instance`, if there is one.
/// If there isn't one, fall back to the normal body.
inline const slang::ast::InstanceBodySymbol *
getCanonicalBody(const slang::ast::InstanceSymbol &inst) {
  const slang::ast::InstanceBodySymbol *body = inst.getCanonicalBody();
  return body == nullptr ? &inst.body : body;
}
 
/// Port lowering information.
struct PortLowering {
  const slang::ast::PortSymbol &ast;
  Location loc;
  BlockArgument arg;
  /// Slot index in the module signature. `outputIdx` is set for outputs;
  /// `inputIdx` is set for inputs and inouts. Regular and expanded
  /// interface-modport ports share one numbering per direction.
  std::optional<unsigned> outputIdx;
  std::optional<unsigned> inputIdx;
};
 
/// Lowering information for a single signal flattened from an interface port.
struct FlattenedIfacePort {
  StringAttr name;
  hw::ModulePort::Direction direction;
  mlir::Type type;
  Location loc;
  BlockArgument arg;
  /// the origin interface port symbol this was flattened from.
  const slang::ast::InterfacePortSymbol *origin;
  /// the interface body member (VariableSymbol , NetSymbol)
  const slang::ast::Symbol *bodySym;
  /// The connected interface instance backing this port (if any). This enables
  /// materializing virtual interface handles from interface ports.
  const slang::ast::InstanceSymbol *ifaceInstance = nullptr;
  /// For modport-typed iface ports, the ModportPortSymbol this was flattened
  /// from. Slang resolves in-body accesses like `bus.member` to a
  /// `HierarchicalValueExpression` whose symbol is the `ModportPortSymbol`,
  /// not the underlying interface body variable, so we register both keys in
  /// `valueSymbols` to make the lookup find this port's `BlockArgument`.
  const slang::ast::Symbol *modportPortSym = nullptr;
  /// Slot index in the module signature; see `PortLowering::outputIdx`.
  std::optional<unsigned> outputIdx;
  std::optional<unsigned> inputIdx;
};
 
/// Lowering information for an expanded interface instance. Maps each interface
/// body member to its expanded SSA value (moore.variable or moore.net).
struct InterfaceLowering {
  DenseMap<const slang::ast::Symbol *, Value> expandedMembers;
  DenseMap<StringAttr, Value> expandedMembersByName;
};
 
/// Cached lowering information for representing SystemVerilog `virtual
/// interface` handles as Moore types (a struct of references to interface
/// members).
struct VirtualInterfaceLowering {
  moore::UnpackedStructType type;
  SmallVector<StringAttr, 8> fieldNames;
};
 
/// A mapping entry for resolving Slang virtual interface member accesses.
///
/// Slang may resolve `vif.member` expressions (where `vif` has a
/// `VirtualInterfaceType`) directly to a `NamedValueExpression` for `member`.
/// This table records which virtual interface base symbol that member access is
/// rooted in, so ImportVerilog can materialize the appropriate Moore IR.
struct VirtualInterfaceMemberAccess {
  const slang::ast::ValueSymbol *base = nullptr;
  /// The name of the field in the lowered virtual interface handle struct that
  /// should be accessed for this member.
  StringAttr fieldName;
};
 
/// Module lowering information.
struct ModuleLowering {
  moore::SVModuleOp op;
  SmallVector<PortLowering> ports;
  SmallVector<FlattenedIfacePort> ifacePorts;
  DenseMap<const slang::syntax::SyntaxNode *, const slang::ast::PortSymbol *>
      portsBySyntaxNode;
  /// Number of explicit-port slots per direction. Hierarchical-name ports
  /// are appended after these in the module signature.
  unsigned numExplicitOutputs = 0;
  unsigned numExplicitInputs = 0;
};
 
/// Function lowering information. The `op` field holds either a `func::FuncOp`
/// (for SystemVerilog functions), a `moore::CoroutineOp` (for tasks), or a
/// `moore::DPIFuncOp` (for DPI-imported functions), all accessed through the
/// `FunctionOpInterface`.
struct FunctionLowering {
  mlir::FunctionOpInterface op;
 
  /// The AST symbols captured by this function, determined by the capture
  /// analysis pre-pass. These are added as extra parameters to the function
  /// during declaration.
  SmallVector<const slang::ast::ValueSymbol *, 4> capturedSymbols;
 
  explicit FunctionLowering(mlir::FunctionOpInterface op) : op(op) {}
};
 
// Class lowering information.
struct ClassLowering {
  circt::moore::ClassDeclOp op;
  bool methodsFinalized = false;
};
 
/// Information about a loops continuation and exit blocks relevant while
/// lowering the loop's body statements.
struct LoopFrame {
  /// The block to jump to from a `continue` statement.
  Block *continueBlock;
  /// The block to jump to from a `break` statement.
  Block *breakBlock;
};
 
/// Hierarchical path information.
/// The "hierName" means a different hierarchical name at different module
/// levels.
/// The "idx" means where the current hierarchical name is on the portlists.
/// The "direction" means hierarchical names whether downward(In) or
/// upward(Out).
struct HierPathInfo {
  mlir::StringAttr hierName;
  std::optional<unsigned int> idx;
  slang::ast::ArgumentDirection direction;
 
  /// The symbols this path resolves to, each paired with the elaborated
  /// instance body it was observed in. Sibling instances elaborate the same
  /// logical variable to distinct symbol objects. The pairing lets instance
  /// wiring bind each one to the right instance.
  llvm::SmallVector<std::pair<const slang::ast::ValueSymbol *,
                              const slang::ast::InstanceBodySymbol *>,
                    2>
      valueSyms;
};
 
/// ImportVerilog Elaboration Phases for Hierarchical Names
///
/// Hierarchical name resolution is performed in four distinct phases:
///
/// 1. Collection: The `traverseInstanceBody` pass walks the Slang AST to
///    identify all hierarchical references (e.g., `Top.sub.var`). It records
///    these in `hierPaths` mapped by module body.
///
/// 2. Port Generation: In `convertModuleHeader`, we inspect `hierPaths` for
///    the module and add corresponding input/output ports to the generated
///    `moore.module` to allow cross-module communication.
///
/// 3. Wiring: In `Structure.cpp` during instance creation, we look up the
///    canonical module body's `hierPaths` to determine which hierarchical
///    values need to be passed as inputs or captured as outputs from the
///    instance.
///
/// 4. Resolution: In `Expressions.cpp`, visitors for rvalues and lvalues
///    resolve hierarchical names by first checking function captures (inside
///    a function body the capture argument must be used to respect region
///    isolation), then the instance-aware `hierValueSymbols` map, and finally
///    standard scoped lookups.
 
// A slang::SourceLocation for deterministic comparisons. Comparisons use the
// buffer's sortKey rather than bufferId.
struct LocationKey {
  uint64_t sortKey;
  size_t offset;
 
  static LocationKey get(const slang::SourceLocation &loc,
                         const slang::SourceManager &mgr) {
    return {
        mgr.getSortKey(loc.buffer()),
        loc.offset(),
    };
  }
 
  std::strong_ordering operator<=>(const LocationKey &) const = default;
  bool operator==(const LocationKey &) const = default;
};
 
/// A helper class to facilitate the conversion from a Slang AST to MLIR
/// operations. Keeps track of the destination MLIR module, builders, and
/// various worklists and utilities needed for conversion.
struct Context {
  Context(const ImportVerilogOptions &options,
          slang::ast::Compilation &compilation, mlir::ModuleOp intoModuleOp,
          const slang::SourceManager &sourceManager)
      : options(options), compilation(compilation), intoModuleOp(intoModuleOp),
        sourceManager(sourceManager),
        builder(OpBuilder::atBlockEnd(intoModuleOp.getBody())),
        symbolTable(intoModuleOp) {}
  Context(const Context &) = delete;
 
  /// Return the MLIR context.
  MLIRContext *getContext() { return intoModuleOp.getContext(); }
 
  /// Convert a slang `SourceLocation` into an MLIR `Location`.
  Location convertLocation(slang::SourceLocation loc);
  /// Convert a slang `SourceRange` into an MLIR `Location`.
  Location convertLocation(slang::SourceRange range);
 
  /// Convert a slang type into an MLIR type. Returns null on failure. Uses the
  /// provided location for error reporting, or tries to guess one from the
  /// given type. Types tend to have unreliable location information, so it's
  /// generally a good idea to pass in a location.
  Type convertType(const slang::ast::Type &type, LocationAttr loc = {});
  Type convertType(const slang::ast::DeclaredType &type);
 
  /// Convert hierarchy and structure AST nodes to MLIR ops.
  LogicalResult convertCompilation();
  /// Convert a module and its ports to an empty module op in the IR. Also adds
  /// the op to the worklist of module bodies to be lowered. This acts like a
  /// module "declaration", allowing instances to already refer to a module even
  /// before its body has been lowered.
  /// `module` must be the canonical module body if there is one.
  ModuleLowering *
  convertModuleHeader(const slang::ast::InstanceBodySymbol *module);
  /// Convert a module's body to the corresponding IR ops. The module op must
  /// have already been created earlier through a `convertModuleHeader` call.
  /// `module` must be the canonical module body if there is one.
  LogicalResult convertModuleBody(const slang::ast::InstanceBodySymbol *module);
  LogicalResult convertPackage(const slang::ast::PackageSymbol &package);
  FunctionLowering *
  declareFunction(const slang::ast::SubroutineSymbol &subroutine);
  LogicalResult defineFunction(const slang::ast::SubroutineSymbol &subroutine);
  LogicalResult
  convertPrimitiveInstance(const slang::ast::PrimitiveInstanceSymbol &prim);
  ClassLowering *declareClass(const slang::ast::ClassType &cls);
  LogicalResult buildClassProperties(const slang::ast::ClassType &classdecl);
  LogicalResult materializeClassMethods(const slang::ast::ClassType &classdecl);
  LogicalResult convertGlobalVariable(const slang::ast::VariableSymbol &var);
 
  /// Get the helper function implementing one of the `name`, `next`, and `prev`
  /// built-in methods for the given enum type, creating it on first use.
  /// Returns null and emits an error if the helper cannot be created.
  mlir::func::FuncOp
  getOrCreateEnumHelper(const slang::ast::Type &type,
                        slang::parsing::KnownSystemName method, Location loc);
 
  /// Convert a Slang virtual interface type into the Moore type used to
  /// represent virtual interface handles. Populates internal caches so that
  /// interface instance references can be materialized consistently.
  FailureOr<moore::UnpackedStructType>
  convertVirtualInterfaceType(const slang::ast::VirtualInterfaceType &type,
                              Location loc);
 
  /// Materialize a Moore value representing a concrete interface instance as a
  /// virtual interface handle. This only succeeds for the Slang
  /// `VirtualInterfaceType` wrappers that refer to a real interface instance
  /// (`isRealIface`).
  FailureOr<Value>
  materializeVirtualInterfaceValue(const slang::ast::VirtualInterfaceType &type,
                                   Location loc);
 
  /// Register the interface members of a virtual interface base symbol for use
  /// in later expression conversion.
  LogicalResult
  registerVirtualInterfaceMembers(const slang::ast::ValueSymbol &base,
                                  const slang::ast::VirtualInterfaceType &type,
                                  Location loc);
 
  /// Checks whether one class (actualTy) is derived from another class
  /// (baseTy). True if it's a subclass, false otherwise.
  bool isClassDerivedFrom(const moore::ClassHandleType &actualTy,
                          const moore::ClassHandleType &baseTy);
 
  /// Tries to find the closest base class of actualTy that carries a property
  /// with name fieldName. The location is used for error reporting.
  moore::ClassHandleType
  getAncestorClassWithProperty(const moore::ClassHandleType &actualTy,
                               StringRef fieldName, Location loc);
 
  Value getImplicitThisRef() const {
    return currentThisRef; // block arg added in declareFunction
  }
 
  /// Maps sampled value system calls to their corresponding clocks
  DenseMap<const slang::ast::CallExpression *,
           const slang::ast::TimingControl *>
      sampledValueCallClocks;
 
  /// Generates a map from sampled value system calls to clocks using Slang's
  /// analysis
  void populateSampledValueClocks();
 
  Value getIndexedQueue() const { return currentQueue; }
 
  // Convert a statement AST node to MLIR ops.
  LogicalResult convertStatement(const slang::ast::Statement &stmt);
 
  // Convert an expression AST node to MLIR ops.
  Value convertRvalueExpression(const slang::ast::Expression &expr,
                                Type requiredType = {});
  Value convertLvalueExpression(const slang::ast::Expression &expr);
 
  // Convert an assertion expression AST node to MLIR ops.
  Value convertAssertionExpression(const slang::ast::AssertionExpr &expr,
                                   Location loc);
 
  // Convert a sampled value system call expression AST node to MLIR ops.
  Value convertSampledValueCallExpression(
      const slang::ast::CallExpression &expr,
      const slang::ast::CallExpression::SystemCallInfo &info, Location loc);
 
  // Traverse the whole AST to collect hierarchical names.
  void traverseInstanceBody(const slang::ast::InstanceSymbol &symbol);
 
  /// Build a composite key for hierValueSymbols from a hierarchical value
  /// expression. Returns {firstInstanceSymbol, dottedHierName} or std::nullopt
  /// if the expression has no instance path.
  std::optional<std::pair<const slang::ast::InstanceSymbol *, mlir::StringAttr>>
  buildHierValueKey(const slang::ast::HierarchicalValueExpression &expr);
 
  /// If `sym` is captured by the function currently being converted, return the
  /// value it is bound to (the capture block argument); otherwise return null.
  Value resolveCapturedValue(const slang::ast::ValueSymbol &sym);
 
  // Convert timing controls into a corresponding set of ops that delay
  // execution of the current block. Produces an error if the implicit event
  // control `@*` or `@(*)` is used.
  LogicalResult convertTimingControl(const slang::ast::TimingControl &ctrl);
  // Convert timing controls into a corresponding set of ops that delay
  // execution of the current block. Then converts the given statement, taking
  // note of the rvalues it reads and adding them to a wait op in case an
  // implicit event control `@*` or `@(*)` is used.
  LogicalResult convertTimingControl(const slang::ast::TimingControl &ctrl,
                                     const slang::ast::Statement &stmt);
 
  /// Helper function to convert a value to a MLIR I1 value.
  Value convertToI1(Value value);
 
  // Convert a slang timing control for LTL
  Value convertLTLTimingControl(const slang::ast::TimingControl &ctrl,
                                const Value &seqOrPro);
 
  /// Creates a delayed assignment based on the given TimingControl delay (or
  /// without a delay if the TimingControl is null)
  LogicalResult
  assignPrimOutputWithDelay(Value outputVal, Value assignment,
                            const slang::ast::TimingControl *delay,
                            Location loc);
 
  LogicalResult
  convertMOSSwitchPrimitive(const slang::ast::PrimitiveInstanceSymbol &prim);
 
  LogicalResult
  convertCMOSSwitchPrimitive(const slang::ast::PrimitiveInstanceSymbol &prim);
 
  LogicalResult
  convertNInputPrimitive(const slang::ast::PrimitiveInstanceSymbol &prim);
 
  LogicalResult
  convertNOutputPrimitive(const slang::ast::PrimitiveInstanceSymbol &prim);
 
  LogicalResult
  convertFixedPrimitive(const slang::ast::PrimitiveInstanceSymbol &prim);
 
  LogicalResult
  convertPullGatePrimitive(const slang::ast::PrimitiveInstanceSymbol &prim);
 
  FailureOr<moore::SVModuleOp>
  convertUserDefinedPrimitiveDef(const slang::ast::PrimitiveSymbol &primitive);
 
  LogicalResult convertUserDefinedPrimitiveInstance(
      const slang::ast::PrimitiveInstanceSymbol &prim);
 
  LogicalResult convertThreeStateGatePrimitive(
      const slang::ast::PrimitiveInstanceSymbol &prim);
 
  /// Helper function to convert a value to its "truthy" boolean value.
  Value convertToBool(Value value);
 
  /// Helper function to convert a value to its "truthy" boolean value and
  /// convert it to the given domain.
  Value convertToBool(Value value, Domain domain);
 
  /// Helper function to convert a value to its simple bit vector
  /// representation, if it has one. Otherwise returns null. Also returns null
  /// if the given value is null.
  Value convertToSimpleBitVector(Value value);
 
  /// Helper function to convert a `PackedType` value to its simple bit
  /// vector representation, with special handling for time values which
  /// require scaling by the local timescale. If `fallible` is true,
  /// conversion failures are reported by returning a null value without
  /// emitting diagnostics.
  Value materializePackedToSBVConversion(Value value, Location loc,
                                         bool fallible);
 
  /// Helper function to insert the necessary operations to cast a value from
  /// one type to another. If `fallible` is true, conversion failures are
  /// reported by returning a null value without emitting diagnostics.
  Value materializeConversion(Type type, Value value, bool isSigned,
                              Location loc, bool fallible = false);
 
  /// Helper function to materialize an `SVInt` as an SSA value.
  Value materializeSVInt(const slang::SVInt &svint,
                         const slang::ast::Type &type, Location loc);
 
  /// Helper function to materialize a real value as an SSA value.
  Value materializeSVReal(const slang::ConstantValue &svreal,
                          const slang::ast::Type &type, Location loc);
 
  /// Helper function to materialize a string as an SSA value.
  Value materializeString(const slang::ConstantValue &string,
                          const slang::ast::Type &astType, Location loc);
 
  /// Helper function to materialize an unpacked array of `SVInt`s as an SSA
  /// value.
  Value materializeFixedSizeUnpackedArrayType(
      const slang::ConstantValue &constant,
      const slang::ast::FixedSizeUnpackedArrayType &astType, Location loc);
 
  /// Helper function to materialize a `ConstantValue` as an SSA value. Returns
  /// null if the constant cannot be materialized.
  Value materializeConstant(const slang::ConstantValue &constant,
                            const slang::ast::Type &type, Location loc);
 
  /// Convert a list of string literal arguments with formatting specifiers and
  /// arguments to be interpolated into a `!moore.format_string` value. Returns
  /// failure if an error occurs. Returns a null value if the formatted string
  /// is trivially empty. Otherwise returns the formatted string.
  FailureOr<Value> convertFormatString(
      std::span<const slang::ast::Expression *const> arguments, Location loc,
      moore::IntFormat defaultFormat = moore::IntFormat::Decimal,
      bool appendNewline = false);
 
  /// Result of converting a scan format string. The final cursor of the
  /// consuming chain and the list of (destination expression, scanned value,
  /// matched flag) tuples to assign
  struct ScanStringResult {
    Value finalCursor;
    SmallVector<std::tuple<const slang::ast::Expression *, Value, Value>>
        assignments;
  };
 
  /// Convert a scan format string into a consuming chain of `moore.scan.*`
  /// operations starting from `initialCursor`. Each non-suppressed specifier
  /// produces an entry in `assignments`; the caller is responsible for emitting
  /// the corresponding `moore.blocking_assign` ops. Returns failur if an erro
  /// occurs.
  FailureOr<ScanStringResult>
  convertScanString(StringRef formatStr, Value initialCursor,
                    std::span<const slang::ast::Expression *const> destinations,
                    Location loc);
 
  /// Convert system function calls. Returns a null `Value` on failure after
  /// emitting an error.
  Value convertSystemCall(const slang::ast::SystemSubroutine &subroutine,
                          Location loc,
                          std::span<const slang::ast::Expression *const> args);
 
  /// Convert sampled value system function calls with a single argument.
  FailureOr<Value>
  convertSampledValueCallArity1(const slang::ast::SystemSubroutine &subroutine,
                                Location loc, Value value, Type originalType,
                                Value clockVal);
 
  /// Evaluate the constant value of an expression.
  slang::ConstantValue evaluateConstant(const slang::ast::Expression &expr);
 
  /// Convert the inside/set-membership expression.
  Value convertInsideCheck(Value insideLhs, Location loc,
                           const slang::ast::Expression &expr);
 
  const ImportVerilogOptions &options;
  slang::ast::Compilation &compilation;
  mlir::ModuleOp intoModuleOp;
  const slang::SourceManager &sourceManager;
 
  /// The builder used to create IR operations.
  OpBuilder builder;
  /// A symbol table of the MLIR module we are emitting into.
  SymbolTable symbolTable;
 
  /// The top-level operations ordered by their Slang source location. This is
  /// used to produce IR that follows the source file order.
  std::map<LocationKey, Operation *> orderedRootOps;
 
  /// How we have lowered modules to MLIR.
  /// The keys must be the slang canonical module bodies where they exist.
  DenseMap<const slang::ast::InstanceBodySymbol *,
           std::unique_ptr<ModuleLowering>>
      modules;
 
  /// Expanded interface instances, keyed by the InstanceSymbol pointer.
  /// Each entry maps body members to their expanded SSA values. Scoped
  /// per-module so entries are cleaned up when a module's conversion ends.
  using InterfaceInstances =
      llvm::ScopedHashTable<const slang::ast::InstanceSymbol *,
                            InterfaceLowering *>;
  using InterfaceInstanceScope = InterfaceInstances::ScopeTy;
  InterfaceInstances interfaceInstances;
  /// Owning storage for InterfaceLowering objects
  /// because ScopedHashTable stores values by copy.
  SmallVector<std::unique_ptr<InterfaceLowering>> interfaceInstanceStorage;
 
  /// Module instances already emitted by the predeclaration pass. These are
  /// skipped during the later source-order module-body walk to avoid emitting
  /// duplicate instances.
  DenseSet<const slang::ast::InstanceSymbol *> predeclaredInstances;
 
  /// Cached virtual interface layouts (type + field order).
  DenseMap<const slang::ast::InstanceBodySymbol *, VirtualInterfaceLowering>
      virtualIfaceLowerings;
  DenseMap<const slang::ast::ModportSymbol *, VirtualInterfaceLowering>
      virtualIfaceModportLowerings;
  /// A list of modules for which the header has been created, but the body has
  /// not been converted yet.
  std::queue<const slang::ast::InstanceBodySymbol *> moduleWorklist;
 
  /// A list of functions for which the declaration has been created, but the
  /// body has not been defined yet.
  std::queue<const slang::ast::SubroutineSymbol *> functionWorklist;
 
  /// Functions that have already been converted.
  DenseMap<const slang::ast::SubroutineSymbol *,
           std::unique_ptr<FunctionLowering>>
      functions;
 
  /// DPI-C export directives keyed by the SystemVerilog subroutine they expose.
  DenseMap<const slang::ast::SubroutineSymbol *, std::string> dpiExportCNames;
 
  /// Helper functions generated for the enum built-in methods, keyed by the
  /// canonical enum type and the method they implement.
  DenseMap<
      std::pair<const slang::ast::EnumType *, slang::parsing::KnownSystemName>,
      mlir::func::FuncOp>
      enumHelpers;
 
  /// Classes that have already been converted.
  DenseMap<const slang::ast::ClassType *, std::unique_ptr<ClassLowering>>
      classes;
 
  /// A table of defined values, such as variables, that may be referred to by
  /// name in expressions. The expressions use this table to lookup the MLIR
  /// value that was created for a given declaration in the Slang AST node.
  using ValueSymbols =
      llvm::ScopedHashTable<const slang::ast::ValueSymbol *, Value>;
  using ValueSymbolScope = ValueSymbols::ScopeTy;
  ValueSymbols valueSymbols;
 
  /// A table mapping symbols for interface members accessed through a virtual
  /// interface to the virtual interface base value symbol.
  using VirtualInterfaceMembers =
      llvm::ScopedHashTable<const slang::ast::ValueSymbol *,
                            VirtualInterfaceMemberAccess>;
  using VirtualInterfaceMemberScope = VirtualInterfaceMembers::ScopeTy;
  VirtualInterfaceMembers virtualIfaceMembers;
 
  /// A table of defined global variables that may be referred to by name in
  /// expressions.
  DenseMap<const slang::ast::ValueSymbol *, moore::GlobalVariableOp>
      globalVariables;
  /// A list of global variables that still need their initializers to be
  /// converted.
  SmallVector<const slang::ast::ValueSymbol *> globalVariableWorklist;
 
  /// Pre-computed capture analysis: maps each function to the set of non-local,
  /// non-global variables it captures (directly or transitively).
  CaptureMap functionCaptures;
 
  /// Collect all hierarchical names used for the per module/instance.
  /// The keys are the slang canonical instance bodies (or the real instance
  /// if slang's getCanonicalBody() returned null).
  DenseMap<const slang::ast::InstanceBodySymbol *, SmallVector<HierPathInfo>>
      hierPaths;
 
  /// Persistent map for hierarchical value lookups. Keyed by a composite
  /// of the instance symbol (the specific instance being wired, e.g., p1 or
  /// p2) and the hierarchical path name (e.g., "child.child_val"). This
  /// ensures instance-specific resolution even when Slang shares or doesn't
  /// share instance bodies across multiple instances of the same module.
  DenseMap<std::pair<const slang::ast::InstanceSymbol *, mlir::StringAttr>,
           Value>
      hierValueSymbols;
 
  /// A stack of assignment left-hand side values. Each assignment will push its
  /// lowered left-hand side onto this stack before lowering its right-hand
  /// side. This allows expressions to resolve the opaque
  /// `LValueReferenceExpression`s in the AST.
  SmallVector<Value> lvalueStack;
 
  /// A stack of loop continuation and exit blocks. Each loop will push the
  /// relevant info onto this stack, lower its loop body statements, and pop the
  /// info off the stack again. Continue and break statements encountered as
  /// part of the loop body statements will use this information to branch to
  /// the correct block.
  SmallVector<LoopFrame> loopStack;
 
  /// A listener called for every variable or net being read. This can be used
  /// to collect all variables read as part of an expression or statement, for
  /// example to populate the list of observed signals in an implicit event
  /// control `@*`.
  std::function<void(moore::ReadOp)> rvalueReadCallback;
  /// A listener called for every variable or net being assigned. This can be
  /// used to collect all variables assigned in a task scope.
  std::function<void(mlir::Operation *)> variableAssignCallback;
 
  /// Whether we are currently converting expressions inside a timing control,
  /// such as `@(posedge clk)`. This is used by the implicit event control
  /// callback to avoid adding reads from explicit event controls to the
  /// implicit sensitivity list.
  bool isInsideTimingControl = false;
 
  /// The time scale currently in effect.
  slang::TimeScale timeScale;
 
  /// Variable to track the value of the current function's implicit `this`
  /// reference
  Value currentThisRef = {};
 
  /// The function currently being converted, if any. Used to give captured
  /// symbols priority over module-level hierarchical values inside function
  /// bodies.
  FunctionLowering *currentFunctionLowering = nullptr;
 
  /// Variable that tracks the queue which we are currently converting the index
  /// expression for. This is necessary to implement the `$` operator, which
  /// returns the index of the last element of the queue.
  Value currentQueue = {};
 
  /// The definition symbol of the module body currently being converted.
  /// Used to resolve the `%l`/`%L` library binding format specifier.
  const slang::ast::DefinitionSymbol *currentDefinition = nullptr;
 
  /// Ensure that the global variables for `$monitor` state exist. This creates
  /// the `__monitor_active_id` and `__monitor_enabled` globals on first call.
  void ensureMonitorGlobals();
 
  /// Ensure that the global variable for `$timeformat` state exists.
  /// This creates the `__timeformat_state` global on first call.
  void ensureTimeFormatGlobal();
 
  /// Process any pending `$monitor` calls and generate the monitoring
  /// procedures at module level.
  LogicalResult flushPendingMonitors();
 
  /// Global variable ops for `$monitor` state management. These are created on
  /// demand by `ensureMonitorGlobals()`.
  moore::GlobalVariableOp monitorActiveIdGlobal = nullptr;
  moore::GlobalVariableOp monitorEnabledGlobal = nullptr;
 
  /// Global variable ops for `$timeformat` state management. These are created
  /// on demand by `ensureTimeFormatGlobal()`.
  moore::GlobalVariableOp timeFormatGlobal = nullptr;
 
  /// The next monitor ID to allocate. ID 0 is reserved for "no monitor active".
  unsigned nextMonitorId = 1;
 
  /// Information about a pending `$monitor` call that needs to be converted
  /// after the current module's body has been processed.
  struct PendingMonitor {
    unsigned id;
    Location loc;
    const slang::ast::CallExpression *call;
  };
 
  /// Pending `$monitor` calls that need to be converted at module level.
  SmallVector<PendingMonitor> pendingMonitors;
 
private:
  /// Helper function to extract the commonalities in lowering of functions and
  /// methods
  FunctionLowering *
  declareCallableImpl(const slang::ast::SubroutineSymbol &subroutine,
                      mlir::StringRef qualifiedName,
                      llvm::SmallVectorImpl<Type> &extraParams);
};
 
/// Map an index into an array, with bounds `range`, to a bit offset of the
/// underlying bit storage. This is a dynamic version of
/// `slang::ConstantRange::translateIndex`.
Value getSelectIndex(Context &context, Location loc, Value index,
                     const slang::ConstantRange &range);
 
} // namespace ImportVerilog
} // namespace circt
#endif // CONVERSION_IMPORTVERILOG_IMPORTVERILOGINTERNALS_H