[ImportVerilog] Add capture analysis pre-pass for functions

Add a pre-pass over the slang AST that determines which non-local,
non-global variables each function captures, either directly or
transitively through calls. This walks the entire AST, collecting
variable references and call graph edges, then propagates captures
through the inverse call graph using a worklist until stable.

This analysis is a prerequisite for switching ImportVerilog to a
two-phase declare-then-define approach for functions. Currently,
function bodies are converted eagerly during package/module member
iteration, which can fail when a function transitively references a
variable that hasn't been declared yet (e.g., UVM's `m_uvm_core_state`).
With the capture sets known upfront, function declarations can include
the correct capture parameters from the start, and body conversion can
be deferred.

Also add `MapVector`, `SmallMapVector`, and `SmallSetVector` re-exports.

The analysis is not yet directly used in ImportVerilog. This will be
done in a follow-up commit.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: fabianschuiki

include/circt/Support/LLVM.h

@@ -72,17 +72,26 @@ using mlir::TypeSwitch;       // NOLINT(misc-unused-using-decls)
 // Forward declarations of LLVM classes to be imported in to the circt
 // namespace.
 namespace llvm {
+template <typename KeyT, typename ValueT, typename MapType, typename VectorType>
+class MapVector;
 template <typename KeyT, typename ValueT, unsigned InlineBuckets,
           typename KeyInfoT, typename BucketT>
 class SmallDenseMap;
+template <typename KeyT, typename ValueT, unsigned N>
+struct SmallMapVector;
 template <typename T, unsigned N, typename C>
 class SmallSet;
+template <typename T, unsigned N>
+class SmallSetVector;
 } // namespace llvm
 
 // Import things we want into our namespace.
 namespace circt {
-using llvm::SmallDenseMap; // NOLINT(misc-unused-using-decls)
-using llvm::SmallSet;      // NOLINT(misc-unused-using-decls)
+using llvm::MapVector;      // NOLINT(misc-unused-using-decls)
+using llvm::SmallDenseMap;  // NOLINT(misc-unused-using-decls)
+using llvm::SmallMapVector; // NOLINT(misc-unused-using-decls)
+using llvm::SmallSet;       // NOLINT(misc-unused-using-decls)
+using llvm::SmallSetVector; // NOLINT(misc-unused-using-decls)
 } // namespace circt
 
 // Forward declarations of classes to be imported in to the circt namespace.

lib/Conversion/ImportVerilog/CMakeLists.txt

@@ -2,6 +2,7 @@ include(SlangCompilerOptions)
 
 add_circt_translation_library(CIRCTImportVerilog
   AssertionExpr.cpp
+  CaptureAnalysis.cpp
   Expressions.cpp
   FormatStrings.cpp
   HierarchicalNames.cpp

lib/Conversion/ImportVerilog/CaptureAnalysis.cpp

@@ -0,0 +1,153 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#include "CaptureAnalysis.h"
+#include "slang/ast/ASTVisitor.h"
+#include "llvm/ADT/MapVector.h"
+#include "llvm/Support/SaveAndRestore.h"
+
+using namespace slang::ast;
+using namespace circt;
+using namespace circt::ImportVerilog;
+
+/// Check whether `var` is local to `func`. Walk up from the variable's parent
+/// scope; if we reach `func` before hitting another function boundary, the
+/// variable is local.
+static bool isLocalToFunction(const ValueSymbol &var,
+                              const SubroutineSymbol &func) {
+  for (const Scope *scope = var.getParentScope(); scope;
+       scope = scope->asSymbol().getParentScope()) {
+    if (&scope->asSymbol() == &func)
+      return true;
+    if (scope->asSymbol().kind == SymbolKind::Subroutine)
+      return false;
+  }
+  return false;
+}
+
+/// Check whether `var` is a global variable. Walk up from the variable's parent
+/// scope; if we hit a function or instance body, it's not global. Otherwise
+/// (package, compilation unit, root) it is.
+static bool isGlobalVariable(const ValueSymbol &var) {
+  for (const Scope *scope = var.getParentScope(); scope;
+       scope = scope->asSymbol().getParentScope()) {
+    switch (scope->asSymbol().kind) {
+    case SymbolKind::Subroutine:
+    case SymbolKind::InstanceBody:
+      return false;
+    default:
+      break;
+    }
+  }
+  return true;
+}
+
+namespace {
+
+/// Walk the entire AST to collect captured variables and the call graph for
+/// each function. Uses slang's `ASTVisitor` with both statement and expression
+/// visiting enabled so that we recurse into all function bodies.
+struct CaptureWalker
+    : public ASTVisitor<CaptureWalker, /*VisitStatements=*/true,
+                        /*VisitExpressions=*/true> {
+
+  /// The function whose body we are currently inside, or nullptr if we are at
+  /// a scope outside any function.
+  const SubroutineSymbol *currentFunc = nullptr;
+
+  /// Captured variables per function.
+  CaptureMap capturedVars;
+
+  /// Inverse call graph: maps each callee to the set of callers that call it.
+  /// Used to propagate captures from callees to their callers. Uses MapVector
+  /// for deterministic iteration order during propagation.
+  MapVector<const SubroutineSymbol *,
+            SmallSetVector<const SubroutineSymbol *, 4>>
+      callers;
+
+  /// When we enter a function body, record it as the current function and
+  /// recurse into its members and body statements.
+  void handle(const SubroutineSymbol &func) {
+    llvm::SaveAndRestore guard(currentFunc, &func);
+    visitDefault(func);
+  }
+
+  /// When we see a named value reference inside a function, check if it needs
+  /// to be captured.
+  void handle(const NamedValueExpression &expr) {
+    if (!currentFunc)
+      return;
+
+    auto &var = expr.symbol;
+
+    // Class properties are accessed through `this`, not captured.
+    if (var.kind == SymbolKind::ClassProperty)
+      return;
+
+    // Function arguments are local by definition.
+    if (var.kind == SymbolKind::FormalArgument)
+      return;
+
+    // Only capture variables that are non-local and non-global.
+    if (isLocalToFunction(var, *currentFunc) || isGlobalVariable(var))
+      return;
+
+    capturedVars[currentFunc].insert(&var);
+  }
+
+  /// Record call graph edges when we see a function call.
+  void handle(const CallExpression &expr) {
+    if (currentFunc)
+      if (auto *const *callee =
+              std::get_if<const SubroutineSymbol *>(&expr.subroutine))
+        callers[*callee].insert(currentFunc);
+    visitDefault(expr);
+  }
+
+  /// Propagate captures transitively through the call graph. For each callee
+  /// that has captures, push each captured variable upward through all
+  /// transitive callers using a worklist. A captured variable is only
+  /// propagated to a caller if it is not local to that caller.
+  void propagateCaptures() {
+    using WorkItem = std::pair<const SubroutineSymbol *, const ValueSymbol *>;
+    SmallSetVector<WorkItem, 16> worklist;
+
+    for (auto &[func, _] : callers) {
+      // Check if this function captures any variables. Nothing to do if it
+      // doesn't.
+      auto it = capturedVars.find(func);
+      if (it == capturedVars.end())
+        continue;
+
+      // Prime the worklist with the captured variables.
+      for (auto *var : it->second)
+        worklist.insert({func, var});
+
+      // Push each captured variables to the func's callers transitively.
+      while (!worklist.empty()) {
+        auto [func, cap] = worklist.pop_back_val();
+        auto callersIt = callers.find(func);
+        if (callersIt == callers.end())
+          continue;
+        for (auto *caller : callersIt->second)
+          if (!isLocalToFunction(*cap, *caller))
+            if (capturedVars[caller].insert(cap))
+              worklist.insert({caller, cap});
+      }
+    }
+  }
+};
+
+} // namespace
+
+CaptureMap ImportVerilog::analyzeFunctionCaptures(const RootSymbol &root) {
+  CaptureWalker walker;
+  root.visit(walker);
+  walker.propagateCaptures();
+  return std::move(walker.capturedVars);
+}

lib/Conversion/ImportVerilog/CaptureAnalysis.h

@@ -0,0 +1,55 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+//
+// Pre-pass over the slang AST to determine which non-local, non-global
+// variables each function captures, either directly or transitively through
+// calls to other functions.
+//
+// This information is needed before any MLIR conversion happens so that
+// function declarations can be created with the correct signature (including
+// extra capture parameters) upfront, enabling a clean two-phase
+// declare-then-define approach for functions.
+//
+//===----------------------------------------------------------------------===//
+
+// NOLINTNEXTLINE(llvm-header-guard)
+#ifndef CONVERSION_IMPORTVERILOG_CAPTUREANALYSIS_H
+#define CONVERSION_IMPORTVERILOG_CAPTUREANALYSIS_H
+
+#include "circt/Support/LLVM.h"
+#include "llvm/ADT/SetVector.h"
+
+namespace slang {
+namespace ast {
+class RootSymbol;
+class SubroutineSymbol;
+class ValueSymbol;
+} // namespace ast
+} // namespace slang
+
+namespace circt {
+namespace ImportVerilog {
+
+/// The result of capture analysis: for each function, the set of non-local,
+/// non-global variable symbols that the function captures directly or
+/// transitively through calls.
+using CaptureMap = DenseMap<const slang::ast::SubroutineSymbol *,
+                            SmallSetVector<const slang::ast::ValueSymbol *, 4>>;
+
+/// Analyze the AST rooted at `root` to determine which variables each function
+/// captures. A variable is considered captured by a function if it is
+/// referenced inside the function's body (or transitively through called
+/// functions) and is neither local to the function nor a global variable
+/// (package-scope or compilation-unit-scope variables that are lowered via
+/// `get_global_signal`).
+CaptureMap analyzeFunctionCaptures(const slang::ast::RootSymbol &root);
+
+} // namespace ImportVerilog
+} // namespace circt
+
+#endif // CONVERSION_IMPORTVERILOG_CAPTUREANALYSIS_H

unittests/CMakeLists.txt

@@ -9,6 +9,7 @@ function(add_circt_unittest test_dirname)
   add_unittest(CIRCTUnitTests ${test_dirname} ${ARGN})
 endfunction()
 
+add_subdirectory(Conversion)
 add_subdirectory(Dialect)
 add_subdirectory(Support)
 add_subdirectory(Tools)

unittests/Conversion/CMakeLists.txt

@@ -0,0 +1,3 @@
+if(CIRCT_SLANG_FRONTEND_ENABLED)
+  add_subdirectory(ImportVerilog)
+endif()

unittests/Conversion/ImportVerilog/CMakeLists.txt

@@ -0,0 +1,17 @@
+include(SlangCompilerOptions)
+
+add_circt_unittest(CIRCTImportVerilogTests
+  CaptureAnalysisTest.cpp
+)
+
+target_include_directories(CIRCTImportVerilogTests
+  PRIVATE
+  ${CIRCT_MAIN_SRC_DIR}
+)
+
+target_link_libraries(CIRCTImportVerilogTests
+  PRIVATE
+  CIRCTImportVerilog
+  LLVMSupport
+  slang_slang
+)