[HW] Add HWBypassInnerSymbols pass (#9291)

This pass moves inner symbols from ports to wires, then bypasses wire
operations with inner symbols by replacing uses with their inputs while
keeping the wire to preserve the symbol. This enables optimizations (like
imconstprop or parametization) to cross symbol boundaries while maintaining
symbol references.

The pass performs two main transformations:
1. Moves inner symbols from module ports to wire operations, allowing
   optimizations like constant propagation to cross port boundaries.
2. Bypasses wire operations that have inner symbols by replacing all uses
   of the wire's result with its input operand, while keeping the wire
   operation itself to preserve the inner symbol reference.

Note: This transformation assumes that values associated with inner symbols
are not mutated through inner symbols (e.g. force). This assumption may not
hold in design verification contexts, but is safe in synthesis.

Author: uenoku

include/circt/Dialect/HW/Passes.td

@@ -126,4 +126,26 @@ def HWParameterizeConstantPorts : Pass<"hw-parameterize-constant-ports",
   }];
 }
 
+def HWBypassInnerSymbols : Pass<"hw-bypass-inner-symbols", "hw::HWModuleOp"> {
+  let summary = "Pass through values through inner symbols";
+  let description = [{
+    This pass moves inner symbols from ports to wires, then bypasses wire
+    operations with inner symbols by replacing uses with their inputs while
+    keeping the wire to preserve the symbol. This enables optimizations to
+    cross symbol boundaries while maintaining symbol references.
+
+    Warning: This transformation assumes that values associated with inner
+    symbols are not mutated through inner symbols (e.g. force). This assumption
+    may not hold in simulation, but is safe in synthesis. This pass treats
+    inner symbols differently from the optimization-blocking semantics that
+    other parts of CIRCT use, so it is opt-in and should only be used when
+    the above assumptions hold.
+  }];
+
+  let statistics = [
+    Statistic<"numPortsMoved", "num-ports-moved",
+              "Number of inner symbols moved from ports to wires">
+  ];
+}
+
 #endif // CIRCT_DIALECT_HW_PASSES_TD

lib/Dialect/HW/Transforms/CMakeLists.txt

@@ -1,5 +1,6 @@
 add_circt_dialect_library(CIRCTHWTransforms
   HWAggregateToComb.cpp
+  HWBypassInnerSymbols.cpp
   HWParameterizeConstantPorts.cpp
   HWPrintInstanceGraph.cpp
   HWSpecialize.cpp

lib/Dialect/HW/Transforms/HWBypassInnerSymbols.cpp

@@ -0,0 +1,104 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+//
+//  This pass moves inner symbols from ports to wires, then bypasses wire
+//  operations with inner symbols by replacing uses with their inputs while
+//  keeping the wire to preserve the symbol. This enables optimizations to
+//  cross symbol boundaries while maintaining symbol references.
+//
+//  Note: This transformation assumes that values associated with inner
+//  symbols are not mutated through inner symbols (e.g. force). This assumption
+//  may not hold in design verification contexts, but is safe in synthesis.
+//
+//===----------------------------------------------------------------------===//
+
+#include "circt/Dialect/HW/HWOps.h"
+#include "circt/Dialect/HW/HWPasses.h"
+#include "circt/Dialect/HW/PortImplementation.h"
+#include "mlir/IR/PatternMatch.h"
+#include "mlir/Transforms/WalkPatternRewriteDriver.h"
+
+namespace circt {
+namespace hw {
+#define GEN_PASS_DEF_HWBYPASSINNERSYMBOLS
+#include "circt/Dialect/HW/Passes.h.inc"
+} // namespace hw
+} // namespace circt
+
+using namespace circt;
+using namespace circt::hw;
+
+namespace {
+struct HWBypassInnerSymbolsPass
+    : public impl::HWBypassInnerSymbolsBase<HWBypassInnerSymbolsPass> {
+  void runOnOperation() override;
+  using HWBypassInnerSymbolsBase<
+      HWBypassInnerSymbolsPass>::HWBypassInnerSymbolsBase;
+};
+
+/// Pattern to bypass wire operations with inner symbols.
+struct BypassWireWithInnerSym : public OpRewritePattern<WireOp> {
+  using OpRewritePattern<WireOp>::OpRewritePattern;
+
+  LogicalResult matchAndRewrite(WireOp wire,
+                                PatternRewriter &rewriter) const override {
+    // Only bypass wires that have an inner symbol or use
+    if (!wire.getInnerSymAttr() || wire.use_empty())
+      return failure();
+
+    // Replace all uses of the wire with its input
+    rewriter.modifyOpInPlace(wire, [&] {
+      wire->replaceAllUsesWith(ArrayRef<Value>{wire.getInput()});
+    });
+    return success();
+  }
+};
+} // namespace
+
+void HWBypassInnerSymbolsPass::runOnOperation() {
+  auto module = getOperation();
+
+  // First move the inner symbol from the port to allow constprop and other
+  // optimizations to cross the boundary.
+  hw::ModulePortInfo portList(module.getPortList());
+  auto *outputOp = module.getBodyBlock()->getTerminator();
+  OpBuilder builder(&getContext());
+  bool hasInnerSym = false;
+  auto moduleType = module.getModuleType();
+  for (auto [index, port] : llvm::enumerate(portList)) {
+    auto sym = port.getSym();
+    if (!sym)
+      continue;
+    hasInnerSym = true;
+    ++numPortsMoved;
+    if (port.isOutput()) {
+      auto value = outputOp->getOperand(moduleType.getOutputIdForPortId(index));
+      builder.setInsertionPointAfterValue(value);
+      auto wire = WireOp::create(builder, value.getLoc(), value);
+      wire.setInnerSymAttr(sym);
+    } else {
+      auto arg = module.getBodyBlock()->getArgument(
+          moduleType.getInputIdForPortId(index));
+      builder.setInsertionPointToStart(module.getBodyBlock());
+      auto wire = WireOp::create(builder, arg.getLoc(), arg);
+      wire.setInnerSymAttr(sym);
+    }
+  }
+
+  if (hasInnerSym) {
+    // Bulk clear all port symbols.
+    auto innerSymAttr = StringAttr::get(
+        &getContext(), hw::HWModuleLike::getPortSymbolAttrName());
+    SmallVector<Attribute, 0> newAttrs(portList.size(), {});
+    cast<HWModuleLike>(*module).setPortAttrs(innerSymAttr, newAttrs);
+  }
+
+  RewritePatternSet patterns(&getContext());
+  patterns.add<BypassWireWithInnerSym>(&getContext());
+  mlir::walkAndApplyPatterns(module, std::move(patterns));
+}

test/Dialect/HW/bypass-inner-symbols.mlir

@@ -0,0 +1,29 @@
+// RUN: circt-opt -hw-bypass-inner-symbols %s | FileCheck %s
+
+// CHECK-LABEL: hw.module @BypassMultipleWires
+// CHECK-SAME: in %a : i8, in %b : i8, out out : i8
+hw.module @BypassMultipleWires(in %a: i8, in %b: i8, out out: i8) {
+  // Multiple wires with symbols should all be bypassed
+  // CHECK: %wire1 = hw.wire %a sym @wire1 : i8
+  // CHECK: %wire2 = hw.wire %b sym @wire2 : i8
+  // CHECK: %[[ADD:.+]] = comb.add bin %a, %b
+  %wire1 = hw.wire %a sym @wire1 : i8
+  %wire2 = hw.wire %b sym @wire2 : i8
+  %result = comb.add bin %wire1, %wire2 : i8
+
+  // CHECK: hw.output %[[ADD]]
+  hw.output %result : i8
+}
+
+// CHECK-LABEL: hw.module @BypassInputPortWithSym
+// CHECK-SAME: in %a : i32, in %b : i32, out out : i32
+hw.module @BypassInputPortWithSym(in %a: i32 {hw.exportPort = #hw<innerSym@in>}, in %b: i32, out out: i32 {hw.exportPort = #hw<innerSym@out>}) {
+  // Port symbols are moved to wires, then wires are bypassed
+  // CHECK: %[[WIRE_IN:.+]] = hw.wire %a sym @in : i32
+  // CHECK: %[[ADD:.+]] = comb.add bin %a, %b
+  // CHECK: %[[WIRE_OUT:.+]] = hw.wire %[[ADD]] sym @out : i32
+  %result = comb.add bin %a, %b : i32
+
+  // CHECK: hw.output %[[ADD]]
+  hw.output %result : i32
+}