Structure.cpp

Go to the documentation of this file.

//===- Structure.cpp - Slang hierarchy conversion -------------------------===//
//
// 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 "ImportVerilogInternals.h"
#include "circt/Support/FVInt.h"
#include "slang/ast/Compilation.h"
#include "slang/ast/symbols/ClassSymbols.h"
#include "slang/ast/symbols/MemberSymbols.h"
#include "slang/syntax/AllSyntax.h"
#include "slang/syntax/SyntaxVisitor.h"
#include "llvm/ADT/STLFunctionalExtras.h"
#include "llvm/ADT/ScopeExit.h"
 
using namespace circt;
using namespace ImportVerilog;
 
static constexpr StringLiteral dpiExportAttrName = "circt.dpi.export";
 
//===----------------------------------------------------------------------===//
// Utilities
//===----------------------------------------------------------------------===//
 
/// Record `export "DPI-C"` directives in the given scope so that callable
/// declarations can be tagged with the exported C name. Slang resolves the
/// directives during elaboration but does not expose them on the subroutine
/// symbols themselves, so walk the scope's syntax to recover them.
static void recordDPIExportDirectives(Context &context,
                                      const slang::ast::Scope &scope,
                                      const slang::syntax::SyntaxNode *syntax) {
  if (!syntax)
    return;
 
  auto visitor = slang::syntax::makeSyntaxVisitor(
      [&](auto &visitor, const slang::syntax::DPIExportSyntax &exportSyntax) {
        auto svName = exportSyntax.name.valueText();
        if (svName.empty())
          return;
 
        const auto *symbol = scope.find(svName);
        const auto *subroutine =
            symbol ? symbol->as_if<slang::ast::SubroutineSymbol>() : nullptr;
        if (!subroutine)
          return;
 
        auto cName = exportSyntax.c_identifier.valueText();
        if (cName.empty())
          cName = svName;
        context.dpiExportCNames[subroutine] = std::string(cName);
      },
      [](auto &visitor, const slang::syntax::SyntaxNode &node) {
        visitor.visitDefault(node);
      });
  syntax->visit(visitor);
}
 
static void guessNamespacePrefix(const slang::ast::Symbol &symbol,
                                 SmallString<64> &prefix) {
  if (symbol.kind != slang::ast::SymbolKind::Package)
    return;
  guessNamespacePrefix(symbol.getParentScope()->asSymbol(), prefix);
  if (!symbol.name.empty()) {
    prefix += symbol.name;
    prefix += "::";
  }
}
 
//===----------------------------------------------------------------------===//
// Base Visitor
//===----------------------------------------------------------------------===//
 
namespace {
/// Base visitor which ignores AST nodes that are handled by Slang's name
/// resolution and type checking.
struct BaseVisitor {
  Context &context;
  Location loc;
  OpBuilder &builder;
 
  BaseVisitor(Context &context, Location loc)
      : context(context), loc(loc), builder(context.builder) {}
 
  // Skip semicolons.
  LogicalResult visit(const slang::ast::EmptyMemberSymbol &) {
    return success();
  }
 
  // Skip members that are implicitly imported from some other scope for the
  // sake of name resolution, such as enum variant names.
  LogicalResult visit(const slang::ast::TransparentMemberSymbol &) {
    return success();
  }
 
  // Handle classes without parameters or specialized generic classes
  LogicalResult visit(const slang::ast::ClassType &classdecl) {
    if (failed(context.buildClassProperties(classdecl)))
      return failure();
    return context.materializeClassMethods(classdecl);
  }
 
  // GenericClassDefSymbol represents parameterized (template) classes, which
  // per IEEE 1800-2023 §8.25 are abstract and not instantiable. Slang models
  // concrete specializations as ClassType, so we skip GenericClassDefSymbol
  // entirely.
  LogicalResult visit(const slang::ast::GenericClassDefSymbol &) {
    return success();
  }
 
  // Skip typedefs.
  LogicalResult visit(const slang::ast::TypeAliasType &) { return success(); }
  LogicalResult visit(const slang::ast::ForwardingTypedefSymbol &) {
    return success();
  }
 
  // Skip imports. The AST already has its names resolved.
  LogicalResult visit(const slang::ast::ExplicitImportSymbol &) {
    return success();
  }
  LogicalResult visit(const slang::ast::WildcardImportSymbol &) {
    return success();
  }
 
  // Skip type parameters. The Slang AST is already monomorphized.
  LogicalResult visit(const slang::ast::TypeParameterSymbol &) {
    return success();
  }
 
  // Skip elaboration system tasks. These are reported directly by Slang.
  LogicalResult visit(const slang::ast::ElabSystemTaskSymbol &) {
    return success();
  }
 
  // Handle parameters.
  LogicalResult visit(const slang::ast::ParameterSymbol &param) {
    visitParameter(param);
    return success();
  }
 
  LogicalResult visit(const slang::ast::SpecparamSymbol &param) {
    visitParameter(param);
    return success();
  }
 
  template <class Node>
  void visitParameter(const Node &param) {
    // If debug info is enabled, try to materialize the parameter's constant
    // value on a best-effort basis and create a `dbg.variable` to track the
    // value.
    if (!context.options.debugInfo)
      return;
    auto value =
        context.materializeConstant(param.getValue(), param.getType(), loc);
    if (!value)
      return;
    if (builder.getInsertionBlock()->getParentOp() == context.intoModuleOp) {
      auto key = LocationKey::get(param.location, context.sourceManager);
      context.orderedRootOps.insert({key, value.getDefiningOp()});
    }
 
    // Prefix the parameter name with the surrounding namespace to create
    // somewhat sane names in the IR.
    SmallString<64> paramName;
    guessNamespacePrefix(param.getParentScope()->asSymbol(), paramName);
    paramName += param.name;
 
    debug::VariableOp::create(builder, loc, builder.getStringAttr(paramName),
                              value, Value{});
  }
};
} // namespace
 
//===----------------------------------------------------------------------===//
// Top-Level Item Conversion
//===----------------------------------------------------------------------===//
 
namespace {
struct RootVisitor : public BaseVisitor {
  using BaseVisitor::BaseVisitor;
  using BaseVisitor::visit;
 
  // Handle packages.
  LogicalResult visit(const slang::ast::PackageSymbol &package) {
    return context.convertPackage(package);
  }
 
  // Handle functions and tasks.
  LogicalResult visit(const slang::ast::SubroutineSymbol &subroutine) {
    if (!context.declareFunction(subroutine))
      return failure();
    return success();
  }
 
  // Handle global variables.
  LogicalResult visit(const slang::ast::VariableSymbol &var) {
    return context.convertGlobalVariable(var);
  }
 
  // Emit an error for all other members.
  template <typename T>
  LogicalResult visit(T &&node) {
    mlir::emitError(loc, "unsupported construct: ")
        << slang::ast::toString(node.kind);
    return failure();
  }
};
} // namespace
 
//===----------------------------------------------------------------------===//
// Package Conversion
//===----------------------------------------------------------------------===//
 
namespace {
struct PackageVisitor : public BaseVisitor {
  using BaseVisitor::BaseVisitor;
  using BaseVisitor::visit;
 
  // Handle functions and tasks.
  LogicalResult visit(const slang::ast::SubroutineSymbol &subroutine) {
    if (!context.declareFunction(subroutine))
      return failure();
    return success();
  }
 
  // Handle global variables.
  LogicalResult visit(const slang::ast::VariableSymbol &var) {
    return context.convertGlobalVariable(var);
  }
 
  /// Emit an error for all other members.
  template <typename T>
  LogicalResult visit(T &&node) {
    mlir::emitError(loc, "unsupported package member: ")
        << slang::ast::toString(node.kind);
    return failure();
  }
};
} // namespace
 
//===----------------------------------------------------------------------===//
// Module Conversion
//===----------------------------------------------------------------------===//
 
static moore::ProcedureKind
convertProcedureKind(slang::ast::ProceduralBlockKind kind) {
  switch (kind) {
  case slang::ast::ProceduralBlockKind::Always:
    return moore::ProcedureKind::Always;
  case slang::ast::ProceduralBlockKind::AlwaysComb:
    return moore::ProcedureKind::AlwaysComb;
  case slang::ast::ProceduralBlockKind::AlwaysLatch:
    return moore::ProcedureKind::AlwaysLatch;
  case slang::ast::ProceduralBlockKind::AlwaysFF:
    return moore::ProcedureKind::AlwaysFF;
  case slang::ast::ProceduralBlockKind::Initial:
    return moore::ProcedureKind::Initial;
  case slang::ast::ProceduralBlockKind::Final:
    return moore::ProcedureKind::Final;
  }
  llvm_unreachable("all procedure kinds handled");
}
 
static moore::NetKind convertNetKind(slang::ast::NetType::NetKind kind) {
  switch (kind) {
  case slang::ast::NetType::Supply0:
    return moore::NetKind::Supply0;
  case slang::ast::NetType::Supply1:
    return moore::NetKind::Supply1;
  case slang::ast::NetType::Tri:
    return moore::NetKind::Tri;
  case slang::ast::NetType::TriAnd:
    return moore::NetKind::TriAnd;
  case slang::ast::NetType::TriOr:
    return moore::NetKind::TriOr;
  case slang::ast::NetType::TriReg:
    return moore::NetKind::TriReg;
  case slang::ast::NetType::Tri0:
    return moore::NetKind::Tri0;
  case slang::ast::NetType::Tri1:
    return moore::NetKind::Tri1;
  case slang::ast::NetType::UWire:
    return moore::NetKind::UWire;
  case slang::ast::NetType::Wire:
    return moore::NetKind::Wire;
  case slang::ast::NetType::WAnd:
    return moore::NetKind::WAnd;
  case slang::ast::NetType::WOr:
    return moore::NetKind::WOr;
  case slang::ast::NetType::Interconnect:
    return moore::NetKind::Interconnect;
  case slang::ast::NetType::UserDefined:
    return moore::NetKind::UserDefined;
  case slang::ast::NetType::Unknown:
    return moore::NetKind::Unknown;
  }
  llvm_unreachable("all net kinds handled");
}
 
namespace {
struct ModuleVisitor : public BaseVisitor {
  using BaseVisitor::visit;
 
  // A prefix of block names such as `foo.bar.` to put in front of variable and
  // instance names.
  StringRef blockNamePrefix;
 
  ModuleVisitor(Context &context, Location loc, StringRef blockNamePrefix = "")
      : BaseVisitor(context, loc), blockNamePrefix(blockNamePrefix) {}
 
  // Skip ports which are already handled by the module itself.
  LogicalResult visit(const slang::ast::PortSymbol &) { return success(); }
  LogicalResult visit(const slang::ast::MultiPortSymbol &) { return success(); }
  LogicalResult visit(const slang::ast::InterfacePortSymbol &) {
    return success();
  }
 
  // Skip genvars.
  LogicalResult visit(const slang::ast::GenvarSymbol &genvarNode) {
    return success();
  }
 
  // Skip defparams which have been handled by slang.
  LogicalResult visit(const slang::ast::DefParamSymbol &) { return success(); }
 
  // Ignore type parameters. These have already been handled by Slang's type
  // checking.
  LogicalResult visit(const slang::ast::TypeParameterSymbol &) {
    return success();
  }
 
  // Expand an interface instance into individual variable/net ops
  // in the enclosing module. Each signal declared in the interface body becomes
  // a separate op, named with the instance name as a prefix.
  LogicalResult
  expandInterfaceInstance(const slang::ast::InstanceSymbol &instNode) {
    auto prefix = (Twine(blockNamePrefix) + instNode.name + "_").str();
    auto lowering = std::make_unique<InterfaceLowering>();
    Context::ValueSymbolScope scope(context.valueSymbols);
 
    auto recordMember = [&](const slang::ast::Symbol &sym,
                            Value value) -> void {
      lowering->expandedMembers[&sym] = value;
      auto nameAttr = builder.getStringAttr(sym.name);
      lowering->expandedMembersByName[nameAttr] = value;
      if (auto *valueSym = sym.as_if<slang::ast::ValueSymbol>())
        context.valueSymbols.insert(valueSym, value);
    };
 
    for (const auto &member : instNode.body.members()) {
      // Error on nested interface instances.
      if (const auto *nestedInst = member.as_if<slang::ast::InstanceSymbol>()) {
        if (nestedInst->body.getDefinition().definitionKind ==
            slang::ast::DefinitionKind::Interface)
          return mlir::emitError(loc)
                 << "nested interface instances are not supported: `"
                 << nestedInst->name << "` inside `" << instNode.name << "`";
      }
      // Expand variables.
      if (const auto *var = member.as_if<slang::ast::VariableSymbol>()) {
        auto loweredType = context.convertType(*var->getDeclaredType());
        if (!loweredType)
          return failure();
        auto varOp = moore::VariableOp::create(
            builder, loc,
            moore::RefType::get(cast<moore::UnpackedType>(loweredType)),
            builder.getStringAttr(Twine(prefix) + StringRef(var->name)),
            Value());
        recordMember(*var, varOp);
        continue;
      }
      // Expand nets
      if (const auto *net = member.as_if<slang::ast::NetSymbol>()) {
        auto loweredType = context.convertType(*net->getDeclaredType());
        if (!loweredType)
          return failure();
        auto netKind = convertNetKind(net->netType.netKind);
        if (netKind == moore::NetKind::Interconnect ||
            netKind == moore::NetKind::UserDefined ||
            netKind == moore::NetKind::Unknown)
          return mlir::emitError(loc, "unsupported net kind `")
                 << net->netType.name << "`";
        auto netOp = moore::NetOp::create(
            builder, loc,
            moore::RefType::get(cast<moore::UnpackedType>(loweredType)),
            builder.getStringAttr(Twine(prefix) + StringRef(net->name)),
            netKind, Value());
        recordMember(*net, netOp);
        continue;
      }
      // Silently skip other members (modports, parameters , etc.)
    }
 
    // Record interface ports by mapping them to their connected expressions.
    // This is required for virtual interface usage (e.g. `vif.clk`) and for
    // modports that reference interface ports.
    for (const auto *con : instNode.getPortConnections()) {
      const auto *expr = con->getExpression();
      const auto *port = con->port.as_if<slang::ast::PortSymbol>();
      if (!port)
        continue;
      if (!expr) {
        // Leave unconnected interface ports unresolved for now.
        continue;
      }
 
      Value lvalue = context.convertLvalueExpression(*expr);
      if (!lvalue)
        return failure();
 
      recordMember(*port, lvalue);
      if (port->internalSymbol) {
        recordMember(*port->internalSymbol, lvalue);
      }
    }
 
    // Lower executable interface body members now that all interface signals
    // and port bindings are available in the scoped `valueSymbols` table.
    for (const auto &member : instNode.body.members()) {
      switch (member.kind) {
      case slang::ast::SymbolKind::ContinuousAssign:
      case slang::ast::SymbolKind::ProceduralBlock:
      case slang::ast::SymbolKind::StatementBlock:
        break;
      default:
        continue;
      }
      auto memberLoc = context.convertLocation(member.location);
      if (failed(member.visit(ModuleVisitor(context, memberLoc, prefix))))
        return failure();
      if (failed(context.flushPendingMonitors()))
        return failure();
    }
 
    context.interfaceInstanceStorage.push_back(std::move(lowering));
    context.interfaceInstances.insert(
        &instNode, context.interfaceInstanceStorage.back().get());
    return success();
  }
 
  // Handle instances.
  LogicalResult visit(const slang::ast::InstanceSymbol &instNode) {
    using slang::ast::ArgumentDirection;
    using slang::ast::AssignmentExpression;
    using slang::ast::MultiPortSymbol;
    using slang::ast::PortSymbol;
 
    if (context.predeclaredInstances.contains(&instNode))
      return success();
 
    // Always operate on the canonical instance body if there is one.
    // This means any symbols we record will be the symbols from the
    // canonical body, which will match up with the symbols encountered
    // by analyses which visit the canonical bodies.
    const slang::ast::InstanceBodySymbol *body = getCanonicalBody(instNode);
 
    // Interface instances are expanded inline into individual variable/net ops
    // rather than creating a moore.instance op.
    auto defKind = body->getDefinition().definitionKind;
    if (defKind == slang::ast::DefinitionKind::Interface) {
      if (context.interfaceInstances.lookup(&instNode))
        return success();
      return expandInterfaceInstance(instNode);
    }
 
    auto *moduleLowering = context.convertModuleHeader(body);
    if (!moduleLowering)
      return failure();
    auto module = moduleLowering->op;
    auto moduleType = module.getModuleType();
 
    // Set visibility attribute for instantiated module.
    SymbolTable::setSymbolVisibility(module, SymbolTable::Visibility::Private);
 
    // Prepare the values that are involved in port connections. This creates
    // rvalues for input ports and appropriate lvalues for output, inout, and
    // ref ports. We also separate multi-ports into the individual underlying
    // ports with their corresponding connection.
    SmallDenseMap<const PortSymbol *, Value> portValues;
    portValues.reserve(moduleType.getNumPorts());
 
    // Map each InterfacePortSymbol to the connected interface instance.
    SmallDenseMap<const slang::ast::InterfacePortSymbol *,
                  const slang::ast::InstanceSymbol *>
        ifaceConnMap;
 
    for (const auto *con : instNode.getPortConnections()) {
      const auto *expr = con->getExpression();
 
      // Handle unconnected behavior. The expression is null if it have no
      // connection for the port.
      if (!expr) {
        auto *port = con->port.as_if<PortSymbol>();
        if (auto *existingPort =
                moduleLowering->portsBySyntaxNode.lookup(port->getSyntax()))
          port = existingPort;
 
        switch (port->direction) {
        case ArgumentDirection::In: {
          auto refType = moore::RefType::get(
              cast<moore::UnpackedType>(context.convertType(port->getType())));
 
          if (const auto *net =
                  port->internalSymbol->as_if<slang::ast::NetSymbol>()) {
            auto netOp = moore::NetOp::create(
                builder, loc, refType,
                StringAttr::get(builder.getContext(), net->name),
                convertNetKind(net->netType.netKind), nullptr);
            auto readOp = moore::ReadOp::create(builder, loc, netOp);
            portValues.insert({port, readOp});
          } else if (const auto *var =
                         port->internalSymbol
                             ->as_if<slang::ast::VariableSymbol>()) {
            auto varOp = moore::VariableOp::create(
                builder, loc, refType,
                StringAttr::get(builder.getContext(), var->name), nullptr);
            auto readOp = moore::ReadOp::create(builder, loc, varOp);
            portValues.insert({port, readOp});
          } else {
            return mlir::emitError(loc)
                   << "unsupported internal symbol for unconnected port `"
                   << port->name << "`";
          }
          continue;
        }
 
        // No need to express unconnected behavior for output port, skip to the
        // next iteration of the loop.
        case ArgumentDirection::Out:
          continue;
 
        case ArgumentDirection::InOut:
        case ArgumentDirection::Ref: {
          auto refType = moore::RefType::get(
              cast<moore::UnpackedType>(context.convertType(port->getType())));
 
          if (const auto *net =
                  port->internalSymbol->as_if<slang::ast::NetSymbol>()) {
            auto netOp = moore::NetOp::create(
                builder, loc, refType,
                StringAttr::get(builder.getContext(), net->name),
                convertNetKind(net->netType.netKind), nullptr);
            portValues.insert({port, netOp});
          } else if (const auto *var =
                         port->internalSymbol
                             ->as_if<slang::ast::VariableSymbol>()) {
            auto varOp = moore::VariableOp::create(
                builder, loc, refType,
                StringAttr::get(builder.getContext(), var->name), nullptr);
            portValues.insert({port, varOp});
          } else {
            return mlir::emitError(loc)
                   << "unsupported internal symbol for unconnected port `"
                   << port->name << "`";
          }
          continue;
        }
        }
      }
 
      // Unpack the `<expr> = EmptyArgument` pattern emitted by Slang for
      // output and inout ports.
      if (const auto *assign = expr->as_if<AssignmentExpression>())
        expr = &assign->left();
 
      // Regular ports lower the connected expression to an lvalue or rvalue and
      // either attach it to the instance as an operand (for input, inout, and
      // ref ports), or assign an instance output to it (for output ports).
      if (auto *port = con->port.as_if<PortSymbol>()) {
        // Convert as rvalue for inputs, lvalue for all others.
        auto value = (port->direction == ArgumentDirection::In)
                         ? context.convertRvalueExpression(*expr)
                         : context.convertLvalueExpression(*expr);
        if (!value)
          return failure();
        if (auto *existingPort =
                moduleLowering->portsBySyntaxNode.lookup(con->port.getSyntax()))
          port = existingPort;
 
        // IEEE 1800-2017 §23.3.3 requires `inout` port connections to be direct
        // connections, which does not allow for type conversion.
        if (port->direction == ArgumentDirection::InOut) {
          auto portType = moore::RefType::get(
              cast<moore::UnpackedType>(context.convertType(port->getType())));
          if (value.getType() != portType)
            return mlir::emitError(loc)
                   << "inout port `" << port->name << "` expects " << portType
                   << " but is connected to " << value.getType();
        }
 
        portValues.insert({port, value});
        continue;
      }
 
      // Multi-ports lower the connected expression to an lvalue and then slice
      // it up into multiple sub-values, one for each of the ports in the
      // multi-port.
      if (const auto *multiPort = con->port.as_if<MultiPortSymbol>()) {
        // Convert as lvalue.
        auto value = context.convertLvalueExpression(*expr);
        if (!value)
          return failure();
        unsigned offset = 0;
        for (const auto *port : llvm::reverse(multiPort->ports)) {
          if (auto *existingPort = moduleLowering->portsBySyntaxNode.lookup(
                  con->port.getSyntax()))
            port = existingPort;
          unsigned width = port->getType().getBitWidth();
          auto sliceType = context.convertType(port->getType());
          if (!sliceType)
            return failure();
          Value slice = moore::ExtractRefOp::create(
              builder, loc,
              moore::RefType::get(cast<moore::UnpackedType>(sliceType)), value,
              offset);
          // Create the "ReadOp" for input ports.
          if (port->direction == ArgumentDirection::In)
            slice = moore::ReadOp::create(builder, loc, slice);
          portValues.insert({port, slice});
          offset += width;
        }
        continue;
      }
 
      // Interface ports: record the connected interface instance for later
      // resolution via InterfaceLowering.
      if (const auto *ifacePort =
              con->port.as_if<slang::ast::InterfacePortSymbol>()) {
        auto ifaceConn = con->getIfaceConn();
        const auto *connInst =
            ifaceConn.first->as_if<slang::ast::InstanceSymbol>();
        if (connInst)
          ifaceConnMap[ifacePort] = connInst;
        continue;
      }
 
      mlir::emitError(loc) << "unsupported instance port `" << con->port.name
                           << "` (" << slang::ast::toString(con->port.kind)
                           << ")";
      return failure();
    }
 
    // Match the module's ports up with the port values determined above.
    // Values are placed by slot index so regular and expanded
    // interface-modport ports interleave in declaration order.
    SmallVector<Value> inputValues(moduleLowering->numExplicitInputs);
    SmallVector<Value> outputValues(moduleLowering->numExplicitOutputs);
 
    for (auto &port : moduleLowering->ports) {
      auto value = portValues.lookup(&port.ast);
      if (port.ast.direction == ArgumentDirection::Out)
        outputValues[*port.outputIdx] = value;
      else
        inputValues[*port.inputIdx] = value;
    }
 
    // Resolve flattened interface port values. For each flattened port,
    // look up the connected interface instance's InterfaceLowering and
    // find the body member's expanded SSA value.
    for (auto &fp : moduleLowering->ifacePorts) {
      if (!fp.bodySym || !fp.origin)
        continue;
      // Find which interface instance is connected to this port.
      auto it = ifaceConnMap.find(fp.origin);
      if (it == ifaceConnMap.end()) {
        mlir::emitError(loc)
            << "no interface connection for port `" << fp.name << "`";
        return failure();
      }
      const auto *connInst = it->second;
      // Look up the InterfaceLowering for that instance.
      auto *ifaceLowering = context.interfaceInstances.lookup(connInst);
      if (!ifaceLowering) {
        mlir::emitError(loc)
            << "interface instance `" << connInst->name << "` was not expanded";
        return failure();
      }
      // Find the expanded SSA value for this body member.
      auto valIt = ifaceLowering->expandedMembers.find(fp.bodySym);
      if (valIt == ifaceLowering->expandedMembers.end()) {
        mlir::emitError(loc)
            << "unresolved interface port signal `" << fp.name << "`";
        return failure();
      }
      Value val = valIt->second;
      if (fp.direction == hw::ModulePort::Output) {
        outputValues[*fp.outputIdx] = val;
      } else {
        // For input ports, if the value is a ref (from VariableOp/NetOp),
        // read it to get the rvalue, unless the port itself expects a ref.
        if (isa<moore::RefType>(val.getType()) && !isa<moore::RefType>(fp.type))
          val = moore::ReadOp::create(builder, loc, val);
        inputValues[*fp.inputIdx] = val;
      }
    }
 
    // Insert conversions for input ports. Unfilled slots (e.g. unresolved
    // interface-modport ports) are reported by the null-check loop below.
    for (auto [value, type] :
         llvm::zip(inputValues, moduleType.getInputTypes())) {
      if (!value)
        continue;
      // TODO: This should honor signedness in the conversion.
      value = context.materializeConversion(type, value, false, value.getLoc());
      if (!value)
        return mlir::emitError(loc) << "unsupported port";
    }
 
    // Here we use the hierarchical value recorded in `Context::valueSymbols`.
    // Then we pass it as the input port with the ref<T> type of the instance.
    // Note that `body` is always the canonical instance body here and in the
    // `hierPaths` keys.
    for (const auto &hierPath : context.hierPaths[body]) {
      assert(!hierPath.valueSyms.empty() && "hierPath must have valueSyms");
      if (!hierPath.hierName || hierPath.direction != ArgumentDirection::In)
        continue;
      // Which alias is bound in scope depends on which subtree the reference
      // was observed in, so try them all; a null value is caught below.
      Value hierValue;
      for (auto &alias : hierPath.valueSyms)
        if ((hierValue = context.valueSymbols.lookup(alias.first)))
          break;
      inputValues.push_back(hierValue);
    }
 
    // Check that all input values are non-null before creating the instance.
    for (auto value : inputValues)
      if (!value)
        return mlir::emitError(loc) << "unsupported port";
 
    // Determine the name of the instance. Slang clears the name of instance
    // array elements during elaboration; only the outermost array symbol
    // retains the name written in the source. Reconstruct per-element names by
    // appending the source index of each array dimension to the array name,
    // such that `foo u [2:0][1:0]` produces `u_0_0`, `u_0_1`, `u_1_0`, etc.
    // This mirrors the naming scheme used for for-generate blocks.
    SmallString<64> instName(blockNamePrefix);
    if (instNode.arrayPath.empty()) {
      instName += instNode.name;
    } else {
      instName += instNode.getArrayName();
      slang::SmallVector<slang::ConstantRange, 4> dims;
      instNode.getArrayDimensions(dims);
      for (auto [dim, index] : llvm::zip(dims, instNode.arrayPath)) {
        instName += '_';
        Twine(dim.lower() + int32_t(index)).toVector(instName);
      }
    }
 
    // Create the instance op itself.
    auto inputNames = builder.getArrayAttr(moduleType.getInputNames());
    auto outputNames = builder.getArrayAttr(moduleType.getOutputNames());
    auto inst = moore::InstanceOp::create(
        builder, loc, moduleType.getOutputTypes(),
        builder.getStringAttr(instName),
        FlatSymbolRefAttr::get(module.getSymNameAttr()), inputValues,
        inputNames, outputNames);
 
    // An alias belongs to this instance if the body containing its symbol is
    // nested anywhere under the instance in the elaborated tree.
    auto aliasReachedThroughInstance =
        [&](const slang::ast::InstanceBodySymbol *aliasBody) {
          for (auto *b = aliasBody; b && b->parentInstance;
               b = b->parentInstance->getParentScope()->getContainingInstance())
            if (b->parentInstance == &instNode)
              return true;
          return false;
        };
 
    // Record instance's results generated by hierarchical names.
    // Store in both valueSymbols (for same-scope lookups) and the persistent
    // hierValueSymbols map (for cross-scope lookups from other modules).
    // The hierValueSymbols key is {&instNode, hierName} to ensure
    // instance-specific resolution (e.g., p1 vs p2 get separate entries).
    for (const auto &hierPath : context.hierPaths[body])
      if (hierPath.idx && hierPath.direction == ArgumentDirection::Out) {
        auto result = inst->getResult(*hierPath.idx);
        for (auto &alias : hierPath.valueSyms)
          if (aliasReachedThroughInstance(alias.second))
            context.valueSymbols.insert(alias.first, result);
        context.hierValueSymbols[{&instNode, hierPath.hierName}] = result;
      }
 
    // Assign output values from the instance to the connected expression.
    for (auto [lvalue, output] : llvm::zip(outputValues, inst.getOutputs())) {
      if (!lvalue)
        continue;
      Value rvalue = output;
      auto dstType = cast<moore::RefType>(lvalue.getType()).getNestedType();
      // TODO: This should honor signedness in the conversion.
      rvalue = context.materializeConversion(dstType, rvalue, false, loc);
      if (!rvalue)
        return failure();
      moore::ContinuousAssignOp::create(builder, loc, lvalue, rvalue);
    }
 
    return success();
  }
 
  // Handle variables.
  LogicalResult visit(const slang::ast::VariableSymbol &varNode) {
    auto ref = context.valueSymbols.lookup(&varNode);
    if (!ref)
      return mlir::emitError(loc)
             << "internal error: missing predeclared variable `" << varNode.name
             << "`";
 
    auto varOp = ref.getDefiningOp<moore::VariableOp>();
    if (!varOp)
      return mlir::emitError(loc)
             << "internal error: predeclared variable `" << varNode.name
             << "` is not a moore.variable";
 
    if (const auto *init = varNode.getInitializer()) {
      auto loweredType = cast<moore::RefType>(ref.getType()).getNestedType();
      auto initial = context.convertRvalueExpression(*init, loweredType);
      if (!initial)
        return failure();
      varOp.getInitialMutable().assign(initial);
    }
 
    return success();
  }
 
  // Handle nets.
  LogicalResult visit(const slang::ast::NetSymbol &netNode) {
    auto ref = context.valueSymbols.lookup(&netNode);
    if (!ref)
      return mlir::emitError(loc) << "internal error: missing predeclared net `"
                                  << netNode.name << "`";
 
    auto netOp = ref.getDefiningOp<moore::NetOp>();
    if (!netOp)
      return mlir::emitError(loc) << "internal error: predeclared net `"
                                  << netNode.name << "` is not a moore.net";
 
    if (const auto *init = netNode.getInitializer()) {
      auto loweredType = cast<moore::RefType>(ref.getType()).getNestedType();
      auto assignment = context.convertRvalueExpression(*init, loweredType);
      if (!assignment)
        return failure();
      netOp.getAssignmentMutable().assign(assignment);
    }
    return success();
  }
 
  // Handle continuous assignments.
  LogicalResult visit(const slang::ast::ContinuousAssignSymbol &assignNode) {
    const auto &expr =
        assignNode.getAssignment().as<slang::ast::AssignmentExpression>();
    auto lhs = context.convertLvalueExpression(expr.left());
    if (!lhs)
      return failure();
 
    auto rhs = context.convertRvalueExpression(
        expr.right(), cast<moore::RefType>(lhs.getType()).getNestedType());
    if (!rhs)
      return failure();
 
    // Handle delayed assignments.
    if (auto *timingCtrl = assignNode.getDelay()) {
      if (auto *ctrl = timingCtrl->as_if<slang::ast::DelayControl>()) {
        auto delay = context.convertRvalueExpression(
            ctrl->expr, moore::TimeType::get(builder.getContext()));
        if (!delay)
          return failure();
        moore::DelayedContinuousAssignOp::create(builder, loc, lhs, rhs, delay);
        return success();
      }
      mlir::emitError(loc) << "unsupported delay with rise/fall/turn-off";
      return failure();
    }
 
    // Otherwise this is a regular assignment.
    moore::ContinuousAssignOp::create(builder, loc, lhs, rhs);
    return success();
  }
 
  // Handle procedures.
  LogicalResult convertProcedure(moore::ProcedureKind kind,
                                 const slang::ast::Statement &body) {
    if (body.as_if<slang::ast::ConcurrentAssertionStatement>())
      return context.convertStatement(body);
    auto procOp = moore::ProcedureOp::create(builder, loc, kind);
    OpBuilder::InsertionGuard guard(builder);
    builder.setInsertionPointToEnd(&procOp.getBody().emplaceBlock());
    Context::ValueSymbolScope scope(context.valueSymbols);
    Context::VirtualInterfaceMemberScope vifMemberScope(
        context.virtualIfaceMembers);
    if (failed(context.convertStatement(body)))
      return failure();
    if (builder.getBlock())
      moore::ReturnOp::create(builder, loc);
    return success();
  }
 
  LogicalResult visit(const slang::ast::ProceduralBlockSymbol &procNode) {
    // Slang wraps module-level concurrent assertions in a synthetic `always`
    // procedure. The assertion is self-clocked, so it needs no process.
    if (auto *syntax = procNode.getSyntax();
        syntax &&
        syntax->kind == slang::syntax::SyntaxKind::ConcurrentAssertionMember)
      return context.convertStatement(procNode.getBody());
 
    // Detect `always @(*) <stmt>` and convert to `always_comb <stmt>` if
    // requested by the user.
    if (context.options.lowerAlwaysAtStarAsComb) {
      auto *stmt = procNode.getBody().as_if<slang::ast::TimedStatement>();
      if (procNode.procedureKind == slang::ast::ProceduralBlockKind::Always &&
          stmt &&
          stmt->timing.kind == slang::ast::TimingControlKind::ImplicitEvent)
        return convertProcedure(moore::ProcedureKind::AlwaysComb, stmt->stmt);
    }
 
    return convertProcedure(convertProcedureKind(procNode.procedureKind),
                            procNode.getBody());
  }
 
  // Handle generate block.
  LogicalResult visit(const slang::ast::GenerateBlockSymbol &genNode) {
    // Ignore uninstantiated blocks.
    if (genNode.isUninstantiated)
      return success();
 
    // If the block has a name, add it to the list of block name prefices.
    SmallString<64> prefix = blockNamePrefix;
    if (!genNode.name.empty() ||
        genNode.getParentScope()->asSymbol().kind !=
            slang::ast::SymbolKind::GenerateBlockArray) {
      prefix += genNode.getExternalName();
      prefix += '.';
    }
 
    // Visit each member of the generate block.
    for (auto &member : genNode.members())
      if (failed(member.visit(ModuleVisitor(context, loc, prefix))))
        return failure();
    return success();
  }
 
  // Handle generate block array.
  LogicalResult visit(const slang::ast::GenerateBlockArraySymbol &genArrNode) {
    // If the block has a name, add it to the list of block name prefices and
    // prepare to append the array index and a `.` in each iteration.
    SmallString<64> prefix = blockNamePrefix;
    prefix += genArrNode.getExternalName();
    prefix += '_';
    auto prefixBaseLen = prefix.size();
 
    // Visit each iteration entry of the generate block.
    for (const auto *entry : genArrNode.entries) {
      // Append the index to the prefix.
      prefix.resize(prefixBaseLen);
      if (entry->arrayIndex)
        prefix += entry->arrayIndex->toString();
      else
        Twine(entry->constructIndex).toVector(prefix);
      prefix += '.';
 
      // Visit this iteration entry.
      if (failed(entry->asSymbol().visit(ModuleVisitor(context, loc, prefix))))
        return failure();
    }
    return success();
  }
 
  // Ignore statement block symbols. These get generated by Slang for blocks
  // with variables and other declarations. For example, having an initial
  // procedure with a variable declaration, such as `initial begin int x;
  // end`, will create the procedure with a block and variable declaration as
  // expected, but will also create a `StatementBlockSymbol` with just the
  // variable layout _next to_ the initial procedure.
  LogicalResult visit(const slang::ast::StatementBlockSymbol &) {
    return success();
  }
 
  // Ignore sequence declarations. The declarations are already evaluated by
  // Slang and are part of an AssertionInstance.
  LogicalResult visit(const slang::ast::SequenceSymbol &seqNode) {
    return success();
  }
 
  // Ignore property declarations. The declarations are already evaluated by
  // Slang and are part of an AssertionInstance.
  LogicalResult visit(const slang::ast::PropertySymbol &propNode) {
    return success();
  }
 
  // Ignore clocking blocks. The clocking is already inferred by slang at
  // each use.
  LogicalResult visit(const slang::ast::ClockingBlockSymbol &) {
    return success();
  }
 
  // Ignore let declarations. Slang expands uses into AssertionInstance
  // expressions, which are lowered when the use site is imported.
  LogicalResult visit(const slang::ast::LetDeclSymbol &) { return success(); }
 
  // Handle functions and tasks.
  LogicalResult visit(const slang::ast::SubroutineSymbol &subroutine) {
    if (!context.declareFunction(subroutine))
      return failure();
    return success();
  }
 
  // Handle primitive instances.
  LogicalResult visit(const slang::ast::PrimitiveInstanceSymbol &prim) {
    return context.convertPrimitiveInstance(prim);
  }
 
  // Handle instance arrays.
  LogicalResult visit(const slang::ast::InstanceArraySymbol &arrNode) {
    // Slang already nicely unrolls these into distinct instances for us.
    for (const auto *element : arrNode.elements)
      if (failed(element->visit(*this)))
        return failure();
    return success();
  }
 
  /// Emit an error for all other members.
  template <typename T>
  LogicalResult visit(T &&node) {
    mlir::emitError(loc, "unsupported module member: ")
        << slang::ast::toString(node.kind);
    return failure();
  }
};
 
struct ModulePredeclaration {
  Context &context;
  OpBuilder &builder;
 
  ModulePredeclaration(Context &context)
      : context(context), builder(context.builder) {}
 
  LogicalResult declareVariable(const slang::ast::VariableSymbol &varNode,
                                Location loc, StringRef blockNamePrefix) {
    auto loweredType = context.convertType(*varNode.getDeclaredType());
    if (!loweredType)
      return failure();
 
    auto varOp = moore::VariableOp::create(
        builder, loc,
        moore::RefType::get(cast<moore::UnpackedType>(loweredType)),
        builder.getStringAttr(Twine(blockNamePrefix) + varNode.name), Value{});
    context.valueSymbols.insert(&varNode, varOp);
 
    const auto &canonTy = varNode.getType().getCanonicalType();
    if (const auto *vi = canonTy.as_if<slang::ast::VirtualInterfaceType>())
      if (failed(context.registerVirtualInterfaceMembers(varNode, *vi, loc)))
        return failure();
 
    return success();
  }
 
  LogicalResult declareNet(const slang::ast::NetSymbol &netNode, Location loc,
                           StringRef blockNamePrefix) {
    auto loweredType = context.convertType(*netNode.getDeclaredType());
    if (!loweredType)
      return failure();
 
    auto netkind = convertNetKind(netNode.netType.netKind);
    if (netkind == moore::NetKind::Interconnect ||
        netkind == moore::NetKind::UserDefined ||
        netkind == moore::NetKind::Unknown)
      return mlir::emitError(loc, "unsupported net kind `")
             << netNode.netType.name << "`";
 
    auto netOp = moore::NetOp::create(
        builder, loc,
        moore::RefType::get(cast<moore::UnpackedType>(loweredType)),
        builder.getStringAttr(Twine(blockNamePrefix) + netNode.name), netkind,
        Value{});
    context.valueSymbols.insert(&netNode, netOp);
    return success();
  }
 
  SmallString<64>
  getGenerateBlockPrefix(const slang::ast::GenerateBlockSymbol &genNode,
                         StringRef blockNamePrefix) {
    SmallString<64> prefix = blockNamePrefix;
    if (!genNode.name.empty() ||
        genNode.getParentScope()->asSymbol().kind !=
            slang::ast::SymbolKind::GenerateBlockArray) {
      prefix += genNode.getExternalName();
      prefix += '.';
    }
    return prefix;
  }
 
  LogicalResult
  predeclareStorageGenerateBlock(const slang::ast::GenerateBlockSymbol &genNode,
                                 StringRef blockNamePrefix) {
    if (genNode.isUninstantiated)
      return success();
    return predeclareStorageScope(
        genNode, getGenerateBlockPrefix(genNode, blockNamePrefix));
  }
 
  LogicalResult predeclareInterfaceGenerateBlock(
      const slang::ast::GenerateBlockSymbol &genNode,
      StringRef blockNamePrefix) {
    if (genNode.isUninstantiated)
      return success();
    return predeclareInterfaceScope(
        genNode, getGenerateBlockPrefix(genNode, blockNamePrefix));
  }
 
  LogicalResult predeclareModuleInstanceGenerateBlock(
      const slang::ast::GenerateBlockSymbol &genNode,
      StringRef blockNamePrefix) {
    if (genNode.isUninstantiated)
      return success();
    return predeclareModuleInstanceScope(
        genNode, getGenerateBlockPrefix(genNode, blockNamePrefix));
  }
 
  LogicalResult predeclareGenerateBlockArray(
      const slang::ast::GenerateBlockArraySymbol &genArrNode,
      StringRef blockNamePrefix,
      llvm::function_ref<LogicalResult(const slang::ast::GenerateBlockSymbol &,
                                       StringRef)>
          predeclareBlock) {
    SmallString<64> prefix = blockNamePrefix;
    prefix += genArrNode.getExternalName();
    prefix += '_';
    auto prefixBaseLen = prefix.size();
 
    for (const auto *entry : genArrNode.entries) {
      prefix.resize(prefixBaseLen);
      if (entry->arrayIndex)
        prefix += entry->arrayIndex->toString();
      else
        Twine(entry->constructIndex).toVector(prefix);
      prefix += '.';
 
      if (failed(predeclareBlock(*entry, prefix)))
        return failure();
    }
    return success();
  }
 
  LogicalResult predeclareStorageMember(const slang::ast::Symbol &member,
                                        StringRef blockNamePrefix) {
    auto loc = context.convertLocation(member.location);
    if (const auto *varNode = member.as_if<slang::ast::VariableSymbol>())
      return declareVariable(*varNode, loc, blockNamePrefix);
 
    if (const auto *netNode = member.as_if<slang::ast::NetSymbol>())
      return declareNet(*netNode, loc, blockNamePrefix);
 
    if (const auto *genNode = member.as_if<slang::ast::GenerateBlockSymbol>())
      return predeclareStorageGenerateBlock(*genNode, blockNamePrefix);
 
    if (const auto *genArrNode =
            member.as_if<slang::ast::GenerateBlockArraySymbol>())
      return predeclareGenerateBlockArray(
          *genArrNode, blockNamePrefix,
          [&](const slang::ast::GenerateBlockSymbol &gen, StringRef prefix) {
            return predeclareStorageGenerateBlock(gen, prefix);
          });
 
    return success();
  }
 
  LogicalResult predeclareInterfaceMember(const slang::ast::Symbol &member,
                                          StringRef blockNamePrefix) {
    auto loc = context.convertLocation(member.location);
    if (const auto *instNode = member.as_if<slang::ast::InstanceSymbol>()) {
      if (instNode->body.getDefinition().definitionKind ==
          slang::ast::DefinitionKind::Interface)
        return ModuleVisitor(context, loc, blockNamePrefix)
            .expandInterfaceInstance(*instNode);
      return success();
    }
 
    if (const auto *genNode = member.as_if<slang::ast::GenerateBlockSymbol>())
      return predeclareInterfaceGenerateBlock(*genNode, blockNamePrefix);
 
    if (const auto *genArrNode =
            member.as_if<slang::ast::GenerateBlockArraySymbol>())
      return predeclareGenerateBlockArray(
          *genArrNode, blockNamePrefix,
          [&](const slang::ast::GenerateBlockSymbol &gen, StringRef prefix) {
            return predeclareInterfaceGenerateBlock(gen, prefix);
          });
 
    return success();
  }
 
  LogicalResult predeclareModuleInstanceMember(const slang::ast::Symbol &member,
                                               StringRef blockNamePrefix) {
    auto loc = context.convertLocation(member.location);
    if (const auto *instNode = member.as_if<slang::ast::InstanceSymbol>()) {
      if (instNode->body.getDefinition().definitionKind !=
          slang::ast::DefinitionKind::Interface) {
        if (failed(
                ModuleVisitor(context, loc, blockNamePrefix).visit(*instNode)))
          return failure();
        context.predeclaredInstances.insert(instNode);
      }
      return success();
    }
 
    if (const auto *arrNode = member.as_if<slang::ast::InstanceArraySymbol>()) {
      for (const auto *element : arrNode->elements)
        if (failed(predeclareModuleInstanceMember(*element, blockNamePrefix)))
          return failure();
      return success();
    }
 
    if (const auto *genNode = member.as_if<slang::ast::GenerateBlockSymbol>())
      return predeclareModuleInstanceGenerateBlock(*genNode, blockNamePrefix);
 
    if (const auto *genArrNode =
            member.as_if<slang::ast::GenerateBlockArraySymbol>())
      return predeclareGenerateBlockArray(
          *genArrNode, blockNamePrefix,
          [&](const slang::ast::GenerateBlockSymbol &gen, StringRef prefix) {
            return predeclareModuleInstanceGenerateBlock(gen, prefix);
          });
 
    return success();
  }
 
  LogicalResult predeclareStorageScope(const slang::ast::Scope &scope,
                                       StringRef blockNamePrefix) {
    for (auto &member : scope.members())
      if (failed(predeclareStorageMember(member, blockNamePrefix)))
        return failure();
    return success();
  }
 
  LogicalResult predeclareInterfaceScope(const slang::ast::Scope &scope,
                                         StringRef blockNamePrefix) {
    for (auto &member : scope.members())
      if (failed(predeclareInterfaceMember(member, blockNamePrefix)))
        return failure();
    return success();
  }
 
  LogicalResult predeclareModuleInstanceScope(const slang::ast::Scope &scope,
                                              StringRef blockNamePrefix) {
    for (auto &member : scope.members())
      if (failed(predeclareModuleInstanceMember(member, blockNamePrefix)))
        return failure();
    return success();
  }
 
  LogicalResult predeclareScope(const slang::ast::Scope &scope,
                                StringRef blockNamePrefix) {
    // First create variables and nets for the whole generated scope tree so
    // later phases can bind port connections or hierarchical references to
    // declarations that appear later in source.
    if (failed(predeclareStorageScope(scope, blockNamePrefix)))
      return failure();
 
    // Then expand interface instances. Interface expansion may lower
    // continuous assignments or procedures from the interface body, so all
    // storage symbols must already be available.
    if (failed(predeclareInterfaceScope(scope, blockNamePrefix)))
      return failure();
 
    // Finally instantiate modules. This makes later hierarchical references
    // to instance internals available before earlier procedural blocks lower.
    return predeclareModuleInstanceScope(scope, blockNamePrefix);
  }
};
} // namespace
 
//===----------------------------------------------------------------------===//
// Structure and Hierarchy Conversion
//===----------------------------------------------------------------------===//
 
/// Convert an entire Slang compilation to MLIR ops. This is the main entry
/// point for the conversion.
LogicalResult Context::convertCompilation() {
  const auto &root = compilation.getRoot();
 
  // Keep track of the local time scale. `getTimeScale` automatically looks
  // through parent scopes to find the time scale effective locally.
  auto prevTimeScale = timeScale;
  timeScale = root.getTimeScale().value_or(slang::TimeScale());
  llvm::scope_exit timeScaleGuard([&] { timeScale = prevTimeScale; });
 
  // Analyze function captures upfront so that function declarations can be
  // created with the correct signature including capture parameters.
  SmallVector<AmbiguousHierCapture> ambiguousHierCaptures;
  functionCaptures = analyzeFunctionCaptures(root, ambiguousHierCaptures);
  for (auto &ambiguous : ambiguousHierCaptures) {
    auto d = mlir::emitError(convertLocation(ambiguous.function->location))
             << "hierarchical reference to `" << ambiguous.symbol->name
             << "` is ambiguous: this function reaches it through more than "
                "one instance of the same module, which is not yet supported";
    d.attachNote(convertLocation(ambiguous.symbol->location))
        << "symbol declared here";
  }
  if (!ambiguousHierCaptures.empty())
    return failure();
 
  // Visit the whole AST to collect the hierarchical names without any operation
  // creating.
  for (auto *inst : root.topInstances)
    traverseInstanceBody(*inst);
 
  // Analyze the compilation to infer clocks for assertion system calls
  // using Slang's LRM clock inference.
  populateSampledValueClocks();
 
  // Visit all top-level declarations in all compilation units. This does not
  // include instantiable constructs like modules, interfaces, and programs,
  // which are listed separately as top instances.
  for (auto *unit : root.compilationUnits) {
    recordDPIExportDirectives(*this, *unit, unit->getSyntax());
    for (const auto &member : unit->members()) {
      auto loc = convertLocation(member.location);
      if (failed(member.visit(RootVisitor(*this, loc))))
        return failure();
    }
  }
 
  // Prime the root definition worklist by adding all the top-level modules.
  // Interfaces are not lowered as modules; they are expanded inline at each
  // use site, so skip them here.
  SmallVector<const slang::ast::InstanceSymbol *> topInstances;
  for (auto *inst : root.topInstances) {
    const slang::ast::InstanceBodySymbol *body = getCanonicalBody(*inst);
    if (body->getDefinition().definitionKind !=
        slang::ast::DefinitionKind::Interface)
      if (!convertModuleHeader(body))
        return failure();
  }
 
  // Convert all the root module definitions.
  while (!moduleWorklist.empty()) {
    auto *module = moduleWorklist.front();
    moduleWorklist.pop();
    if (failed(convertModuleBody(module)))
      return failure();
  }
 
  // It's possible that after converting modules, we haven't converted all
  // methods yet, especially if they are unused. Do that in this pass.
  SmallVector<const slang::ast::ClassType *, 16> classMethodWorklist;
  classMethodWorklist.reserve(classes.size());
  for (auto &kv : classes)
    classMethodWorklist.push_back(kv.first);
 
  for (auto *inst : classMethodWorklist) {
    if (failed(materializeClassMethods(*inst)))
      return failure();
  }
 
  // Define all function bodies. Functions are declared (and pushed onto the
  // worklist) during module body conversion and class method materialization.
  // Defining a function body may discover additional functions through call
  // expressions, which are declared and added to the worklist on the fly.
  while (!functionWorklist.empty()) {
    auto *fn = functionWorklist.front();
    functionWorklist.pop();
    if (failed(defineFunction(*fn)))
      return failure();
  }
 
  // Convert the initializers of global variables.
  for (auto *var : globalVariableWorklist) {
    auto varOp = globalVariables.at(var);
    auto &block = varOp.getInitRegion().emplaceBlock();
    OpBuilder::InsertionGuard guard(builder);
    builder.setInsertionPointToEnd(&block);
    auto value =
        convertRvalueExpression(*var->getInitializer(), varOp.getType());
    if (!value)
      return failure();
    moore::YieldOp::create(builder, varOp.getLoc(), value);
  }
  globalVariableWorklist.clear();
 
  return success();
}
 
ModuleLowering *
Context::convertModuleHeader(const slang::ast::InstanceBodySymbol *module) {
  using slang::ast::ArgumentDirection;
  using slang::ast::MultiPortSymbol;
  using slang::ast::ParameterSymbol;
  using slang::ast::PortSymbol;
  using slang::ast::TypeParameterSymbol;
 
  // Keep track of the local time scale. `getTimeScale` automatically looks
  // through parent scopes to find the time scale effective locally.
  auto prevTimeScale = timeScale;
  timeScale = module->getTimeScale().value_or(slang::TimeScale());
  llvm::scope_exit timeScaleGuard([&] { timeScale = prevTimeScale; });
 
  // `module` is the canonical module body if it exists (i.e. deduplicated by
  // slang).
  auto &slot = modules[module];
  if (slot)
    return slot.get();
  slot = std::make_unique<ModuleLowering>();
  auto &lowering = *slot;
 
  auto loc = convertLocation(module->location);
  OpBuilder::InsertionGuard g(builder);
 
  // We only support modules and programs here. Interfaces are handled
  // separately by expanding them inline at each use site (see
  // expandInterfaceInstance in ModuleVisitor)
  auto kind = module->getDefinition().definitionKind;
  if (kind != slang::ast::DefinitionKind::Module &&
      kind != slang::ast::DefinitionKind::Program) {
    mlir::emitError(loc) << "unsupported definition: "
                         << module->getDefinition().getKindString();
    return {};
  }
 
  // Handle the port list.
  auto block = std::make_unique<Block>();
  SmallVector<hw::ModulePort> modulePorts;
 
  // It's used to tag where a hierarchical name is on the port list.
  unsigned int outputIdx = 0, inputIdx = 0;
  for (auto *symbol : module->getPortList()) {
    auto handlePort = [&](const PortSymbol &port) {
      auto portLoc = convertLocation(port.location);
      auto type = convertType(port.getType());
      if (!type)
        return failure();
      auto portName = builder.getStringAttr(port.name);
      BlockArgument arg;
      std::optional<unsigned> portOutputIdx;
      std::optional<unsigned> portInputIdx;
      if (port.direction == ArgumentDirection::Out) {
        modulePorts.push_back({portName, type, hw::ModulePort::Output});
        portOutputIdx = outputIdx++;
      } else {
        // Only the ref type wrapper exists for the time being, the net type
        // wrapper for inout may be introduced later if necessary.
        if (port.direction != ArgumentDirection::In)
          type = moore::RefType::get(cast<moore::UnpackedType>(type));
        modulePorts.push_back({portName, type, hw::ModulePort::Input});
        arg = block->addArgument(type, portLoc);
        portInputIdx = inputIdx++;
      }
      lowering.ports.push_back(
          {port, portLoc, arg, portOutputIdx, portInputIdx});
      return success();
    };
 
    // Lambda to handle interface ports by flattening them into individual
    // signal ports. Uses modport directions if a modport is specified,
    // otherwise treats all signals as inout (ref type)
    auto handleIfacePort = [&](const slang::ast::InterfacePortSymbol
                                   &ifacePort) {
      auto portLoc = convertLocation(ifacePort.location);
      auto [connSym, modportSym] = ifacePort.getConnection();
      const auto *ifaceInst =
          connSym ? connSym->as_if<slang::ast::InstanceSymbol>() : nullptr;
      auto portPrefix = (Twine(ifacePort.name) + "_").str();
 
      if (modportSym) {
        // Modport specified: iterate modport members for signal directions.
        for (const auto &member : modportSym->members()) {
          const auto *mpp = member.as_if<slang::ast::ModportPortSymbol>();
          if (!mpp)
            continue;
          auto type = convertType(mpp->getType());
          if (!type)
            return failure();
          auto name =
              builder.getStringAttr(Twine(portPrefix) + StringRef(mpp->name));
          BlockArgument arg;
          hw::ModulePort::Direction dir;
          std::optional<unsigned> ifaceOutputIdx;
          std::optional<unsigned> ifaceInputIdx;
          if (mpp->direction == ArgumentDirection::Out) {
            dir = hw::ModulePort::Output;
            modulePorts.push_back({name, type, dir});
            ifaceOutputIdx = outputIdx++;
          } else {
            dir = hw::ModulePort::Input;
            if (mpp->direction != ArgumentDirection::In)
              type = moore::RefType::get(cast<moore::UnpackedType>(type));
            modulePorts.push_back({name, type, dir});
            arg = block->addArgument(type, portLoc);
            ifaceInputIdx = inputIdx++;
          }
          lowering.ifacePorts.push_back(
              {name, dir, type, portLoc, arg, &ifacePort, mpp->internalSymbol,
               ifaceInst, mpp, ifaceOutputIdx, ifaceInputIdx});
        }
      } else {
        // No modport: iterate interface body for all variables and nets.
        // Treat them all as inout (input with ref type).
        const auto *instSym = connSym->as_if<slang::ast::InstanceSymbol>();
        if (!instSym) {
          mlir::emitError(portLoc)
              << "unsupported interface port connection for `" << ifacePort.name
              << "`";
          return failure();
        }
        for (const auto &member : instSym->body.members()) {
          const slang::ast::Type *slangType = nullptr;
          const slang::ast::Symbol *bodySym = nullptr;
          if (const auto *var = member.as_if<slang::ast::VariableSymbol>()) {
            slangType = &var->getType();
            bodySym = var;
          } else if (const auto *net = member.as_if<slang::ast::NetSymbol>()) {
            slangType = &net->getType();
            bodySym = net;
          } else {
            continue;
          }
          auto type = convertType(*slangType);
          if (!type)
            return failure();
          auto name = builder.getStringAttr(Twine(portPrefix) +
                                            StringRef(bodySym->name));
          auto refType = moore::RefType::get(cast<moore::UnpackedType>(type));
          modulePorts.push_back({name, refType, hw::ModulePort::Input});
          auto arg = block->addArgument(refType, portLoc);
          lowering.ifacePorts.push_back(
              {name, hw::ModulePort::Input, refType, portLoc, arg, &ifacePort,
               bodySym, instSym, nullptr, std::nullopt, inputIdx++});
        }
      }
      return success();
    };
 
    if (const auto *port = symbol->as_if<PortSymbol>()) {
      if (failed(handlePort(*port)))
        return {};
    } else if (const auto *multiPort = symbol->as_if<MultiPortSymbol>()) {
      for (auto *port : multiPort->ports)
        if (failed(handlePort(*port)))
          return {};
    } else if (const auto *ifacePort =
                   symbol->as_if<slang::ast::InterfacePortSymbol>()) {
      if (failed(handleIfacePort(*ifacePort)))
        return {};
    } else {
      mlir::emitError(convertLocation(symbol->location))
          << "unsupported module port `" << symbol->name << "` ("
          << slang::ast::toString(symbol->kind) << ")";
      return {};
    }
  }
 
  // Record explicit-port counts before hierarchical-name ports are appended.
  lowering.numExplicitOutputs = outputIdx;
  lowering.numExplicitInputs = inputIdx;
 
  // Mapping hierarchical names into the module's ports.
  for (auto &hierPath : hierPaths[module]) {
    assert(!hierPath.valueSyms.empty() && "hierPath must have valueSyms");
    auto hierType = convertType(hierPath.valueSyms.front().first->getType());
    if (!hierType)
      return {};
 
    if (auto hierName = hierPath.hierName) {
      // The type of all hierarchical names are marked as the "RefType".
      hierType = moore::RefType::get(cast<moore::UnpackedType>(hierType));
      if (hierPath.direction == ArgumentDirection::Out) {
        hierPath.idx = outputIdx++;
        modulePorts.push_back({hierName, hierType, hw::ModulePort::Output});
      } else {
        hierPath.idx = inputIdx++;
        modulePorts.push_back({hierName, hierType, hw::ModulePort::Input});
        auto hierLoc =
            convertLocation(hierPath.valueSyms.front().first->location);
        block->addArgument(hierType, hierLoc);
      }
    }
  }
  auto moduleType = hw::ModuleType::get(getContext(), modulePorts);
 
  // Pick an insertion point for this module according to the source file
  // location.
  auto key = LocationKey::get(module->location, sourceManager);
  auto it = orderedRootOps.upper_bound(key);
  if (it == orderedRootOps.end())
    builder.setInsertionPointToEnd(intoModuleOp.getBody());
  else
    builder.setInsertionPoint(it->second);
 
  // Create an empty module that corresponds to this module.
  auto moduleOp =
      moore::SVModuleOp::create(builder, loc, module->name, moduleType);
  orderedRootOps.insert(it, {key, moduleOp});
  moduleOp.getBodyRegion().push_back(block.release());
  lowering.op = moduleOp;
 
  // Add the module to the symbol table of the MLIR module, which uniquifies its
  // name as we'd expect.
  symbolTable.insert(moduleOp);
 
  // Schedule the body to be lowered.
  moduleWorklist.push(module);
 
  // Map duplicate port by Syntax
  for (const auto &port : lowering.ports)
    lowering.portsBySyntaxNode.insert({port.ast.getSyntax(), &port.ast});
 
  return &lowering;
}
 
LogicalResult
Context::convertModuleBody(const slang::ast::InstanceBodySymbol *module) {
  auto &lowering = *modules[module];
  auto prevDefinition = currentDefinition;
  currentDefinition = &module->getDefinition();
  llvm::scope_exit currentDefinitionGuard(
      [&] { currentDefinition = prevDefinition; });
  recordDPIExportDirectives(*this, *module, module->getSyntax());
 
  OpBuilder::InsertionGuard g(builder);
  builder.setInsertionPointToEnd(lowering.op.getBody());
 
  ValueSymbolScope scope(valueSymbols);
  InterfaceInstanceScope ifaceScope(interfaceInstances);
  VirtualInterfaceMemberScope vifMemberScope(virtualIfaceMembers);
 
  // Keep track of the local time scale. `getTimeScale` automatically looks
  // through parent scopes to find the time scale effective locally.
  auto prevTimeScale = timeScale;
  timeScale = module->getTimeScale().value_or(slang::TimeScale());
  llvm::scope_exit timeScaleGuard([&] { timeScale = prevTimeScale; });
 
  // Collect downward hierarchical names. Such as,
  // module SubA; int x = Top.y; endmodule. The "Top" module is the parent of
  // the "SubA", so "Top.y" is the downward hierarchical name.
  for (auto &hierPath : hierPaths[module])
    if (hierPath.direction == slang::ast::ArgumentDirection::In &&
        hierPath.idx) {
      auto arg = lowering.op.getBody()->getArgument(*hierPath.idx);
      for (auto &alias : hierPath.valueSyms)
        valueSymbols.insert(alias.first, arg);
    }
 
  // Register flattened interface port members before lowering the module body
  // so expressions can refer to them. Also build per-port interface instance
  // lowerings, which enables materializing virtual interface values from
  // interface ports.
  DenseMap<const slang::ast::InstanceSymbol *, InterfaceLowering *>
      ifacePortLowerings;
 
  auto getIfacePortLowering =
      [&](const slang::ast::InstanceSymbol *ifaceInst) -> InterfaceLowering * {
    if (!ifaceInst)
      return nullptr;
    if (auto *existing = interfaceInstances.lookup(ifaceInst))
      return existing;
    if (auto it = ifacePortLowerings.find(ifaceInst);
        it != ifacePortLowerings.end())
      return it->second;
 
    auto lowering = std::make_unique<InterfaceLowering>();
    InterfaceLowering *ptr = lowering.get();
    interfaceInstanceStorage.push_back(std::move(lowering));
    interfaceInstances.insert(ifaceInst, ptr);
    ifacePortLowerings.try_emplace(ifaceInst, ptr);
    return ptr;
  };
 
  for (auto &fp : lowering.ifacePorts) {
    if (!fp.bodySym)
      continue;
    auto *valueSym = fp.bodySym->as_if<slang::ast::ValueSymbol>();
    if (!valueSym)
      continue;
 
    Value portValue;
    if (fp.direction == hw::ModulePort::Output) {
      // Output interface ports are not referenceable within the module body.
      // Create internal variables for them and return their value through the
      // module terminator.
      portValue = moore::VariableOp::create(
          builder, fp.loc,
          moore::RefType::get(cast<moore::UnpackedType>(fp.type)), fp.name,
          Value());
    } else {
      portValue = fp.arg;
    }
    valueSymbols.insert(valueSym, portValue);
    // Slang resolves in-body accesses (e.g. `bus.r`) through the
    // ModportPortSymbol rather than the interface body's variable. Register
    // both so the body-level expression lookup finds this port.
    if (fp.modportPortSym)
      if (auto *mppSym = fp.modportPortSym->as_if<slang::ast::ValueSymbol>())
        if (mppSym != valueSym)
          valueSymbols.insert(mppSym, portValue);
 
    if (!fp.ifaceInstance)
      continue;
    if (Value val = valueSymbols.lookup(valueSym)) {
      auto *ifaceLowering = getIfacePortLowering(fp.ifaceInstance);
      if (!ifaceLowering)
        continue;
      ifaceLowering->expandedMembers[fp.bodySym] = val;
      ifaceLowering
          ->expandedMembersByName[builder.getStringAttr(fp.bodySym->name)] =
          val;
    }
  }
 
  predeclaredInstances.clear();
  llvm::scope_exit predeclaredInstancesGuard(
      [&] { predeclaredInstances.clear(); });
 
  // Always create module-scope storage, expanded interface members, and
  // instance shells before the source-order body walk. Slang rejects
  // use-before-declare before ImportVerilog runs unless the option is enabled,
  // but once the AST is valid this predeclaration supports both source-order
  // and forward references. Declaration initializers are still lowered when the
  // body visitor reaches the declaration, so they see the same local context as
  // other source-ordered expressions.
  if (failed(ModulePredeclaration(*this).predeclareScope(*module, "")))
    return failure();
 
  // Convert the body of the module.
  for (auto &member : module->members()) {
    auto loc = convertLocation(member.location);
    if (failed(member.visit(ModuleVisitor(*this, loc))))
      return failure();
    // Flush any pending monitors after each member. This places the monitor
    // procedures immediately after the code that sets them up.
    if (failed(flushPendingMonitors()))
      return failure();
  }
 
  // Create additional ops to drive input port values onto the corresponding
  // internal variables and nets, and to collect output port values for the
  // terminator. Outputs are placed by slot index so regular and
  // interface-modport outputs interleave in declaration order.
  SmallVector<Value> outputs(lowering.numExplicitOutputs);
  for (auto &port : lowering.ports) {
    Value value;
    if (auto *expr = port.ast.getInternalExpr()) {
      value = convertLvalueExpression(*expr);
    } else if (port.ast.internalSymbol) {
      if (const auto *sym =
              port.ast.internalSymbol->as_if<slang::ast::ValueSymbol>())
        value = valueSymbols.lookup(sym);
    }
    if (!value)
      return mlir::emitError(port.loc, "unsupported port: `")
             << port.ast.name
             << "` does not map to an internal symbol or expression";
 
    // Collect output port values to be returned in the terminator.
    if (port.ast.direction == slang::ast::ArgumentDirection::Out) {
      if (isa<moore::RefType>(value.getType()))
        value = moore::ReadOp::create(builder, value.getLoc(), value);
      outputs[*port.outputIdx] = value;
      continue;
    }
 
    // Assign the value coming in through the port to the internal net or symbol
    // of that port.
    Value portArg = port.arg;
    if (port.ast.direction != slang::ast::ArgumentDirection::In)
      portArg = moore::ReadOp::create(builder, port.loc, port.arg);
    moore::ContinuousAssignOp::create(builder, port.loc, value, portArg);
  }
 
  // Collect output values for flattened interface ports. The internal
  // references are set up before lowering the module body.
  for (auto &fp : lowering.ifacePorts) {
    if (fp.direction != hw::ModulePort::Output)
      continue;
    auto *valueSym =
        fp.bodySym ? fp.bodySym->as_if<slang::ast::ValueSymbol>() : nullptr;
    if (!valueSym)
      continue;
    Value ref = valueSymbols.lookup(valueSym);
    if (!ref)
      continue;
    outputs[*fp.outputIdx] =
        moore::ReadOp::create(builder, fp.loc, ref).getResult();
  }
 
  // Ensure the number of operands of this module's terminator and the number of
  // its(the current module) output ports remain consistent.
  for (auto &hierPath : hierPaths[module]) {
    assert(!hierPath.valueSyms.empty() && "hierPath must have valueSyms");
    if (hierPath.direction != slang::ast::ArgumentDirection::Out)
      continue;
    // A Symbol lowered in this module body resolves through the scoped table.
    Value hierValue;
    for (auto &alias : hierPath.valueSyms)
      if ((hierValue = valueSymbols.lookup(alias.first)))
        break;
    // Otherwise the value comes from an inner instance's hierarchical port:
    // strip the leading instance name and use the instance-keyed map.
    if (!hierValue) {
      auto name = hierPath.hierName.getValue();
      if (auto dot = name.find("."); dot != llvm::StringRef::npos) {
        auto innerName = builder.getStringAttr(name.drop_front(dot + 1));
        for (auto &member : module->members())
          if (auto *inst = member.as_if<slang::ast::InstanceSymbol>())
            if (llvm::StringRef(inst->name.data(), inst->name.size()) ==
                name.take_front(dot)) {
              hierValue = hierValueSymbols.lookup({inst, innerName});
              break;
            }
      } else if (auto *sym =
                     module->find(std::string_view(name.data(), name.size()))) {
        // A dot-free path names a symbol declared directly in this module.
        if (auto *valueSym = sym->as_if<slang::ast::ValueSymbol>())
          hierValue = valueSymbols.lookup(valueSym);
      }
    }
    if (!hierValue)
      return mlir::emitError(lowering.op.getLoc())
             << "unable to resolve hierarchical output `"
             << hierPath.hierName.getValue() << "` in module `" << module->name
             << "`";
    outputs.push_back(hierValue);
  }
 
  moore::OutputOp::create(builder, lowering.op.getLoc(), outputs);
  return success();
}
 
/// Convert a package and its contents.
LogicalResult
Context::convertPackage(const slang::ast::PackageSymbol &package) {
  // Keep track of the local time scale. `getTimeScale` automatically looks
  // through parent scopes to find the time scale effective locally.
  auto prevTimeScale = timeScale;
  timeScale = package.getTimeScale().value_or(slang::TimeScale());
  llvm::scope_exit timeScaleGuard([&] { timeScale = prevTimeScale; });
 
  recordDPIExportDirectives(*this, package, package.getSyntax());
 
  OpBuilder::InsertionGuard g(builder);
  builder.setInsertionPointToEnd(intoModuleOp.getBody());
  ValueSymbolScope scope(valueSymbols);
  for (auto &member : package.members()) {
    auto loc = convertLocation(member.location);
    if (failed(member.visit(PackageVisitor(*this, loc))))
      return failure();
  }
  return success();
}
 
/// Convert a function and its arguments to a function declaration in the IR.
/// This does not convert the function body.
FunctionLowering *
Context::declareFunction(const slang::ast::SubroutineSymbol &subroutine) {
  // Check if there already is a declaration for this function.
  auto &lowering = functions[&subroutine];
  if (lowering) {
    if (!lowering->op.getOperation())
      return {};
    return lowering.get();
  }
 
  if (!subroutine.thisVar) {
 
    SmallString<64> name;
    guessNamespacePrefix(subroutine.getParentScope()->asSymbol(), name);
    name += subroutine.name;
 
    SmallVector<Type, 1> noThis = {};
    return declareCallableImpl(subroutine, name, noThis);
  }
 
  auto loc = convertLocation(subroutine.location);
 
  // Extract 'this' type and ensure it's a class.
  const slang::ast::Type &thisTy = subroutine.thisVar->getType();
  moore::ClassDeclOp ownerDecl;
 
  if (auto *classTy = thisTy.as_if<slang::ast::ClassType>()) {
    auto &ownerLowering = classes[classTy];
    ownerDecl = ownerLowering->op;
  } else {
    mlir::emitError(loc) << "expected 'this' to be a class type, got "
                         << thisTy.toString();
    return {};
  }
 
  // Build qualified name: @"Pkg::Class"::subroutine
  SmallString<64> qualName;
  qualName += ownerDecl.getSymName(); // already qualified
  qualName += "::";
  qualName += subroutine.name;
 
  // %this : class<@C>
  SmallVector<Type, 1> extraParams;
  {
    auto classSym = mlir::FlatSymbolRefAttr::get(ownerDecl.getSymNameAttr());
    auto handleTy = moore::ClassHandleType::get(getContext(), classSym);
    extraParams.push_back(handleTy);
  }
 
  auto *fLowering = declareCallableImpl(subroutine, qualName, extraParams);
  return fLowering;
}
 
/// Helper function to generate the function signature from a SubroutineSymbol
/// and optional extra arguments (used for %this argument)
static FunctionType getFunctionSignature(
    Context &context, const slang::ast::SubroutineSymbol &subroutine,
    ArrayRef<Type> prefixParams, ArrayRef<Type> suffixParams = {}) {
  using slang::ast::ArgumentDirection;
 
  SmallVector<Type> inputTypes;
  inputTypes.append(prefixParams.begin(), prefixParams.end());
  SmallVector<Type, 1> outputTypes;
 
  for (const auto *arg : subroutine.getArguments()) {
    auto type = context.convertType(arg->getType());
    if (!type)
      return {};
    if (arg->direction == ArgumentDirection::In) {
      inputTypes.push_back(type);
    } else {
      inputTypes.push_back(
          moore::RefType::get(cast<moore::UnpackedType>(type)));
    }
  }
 
  inputTypes.append(suffixParams.begin(), suffixParams.end());
 
  const auto &returnType = subroutine.getReturnType();
  if (!returnType.isVoid()) {
    auto type = context.convertType(returnType);
    if (!type)
      return {};
    outputTypes.push_back(type);
  }
 
  return FunctionType::get(context.getContext(), inputTypes, outputTypes);
}
 
static FailureOr<SmallVector<moore::DPIArgInfo>>
getDPISignature(Context &context,
                const slang::ast::SubroutineSymbol &subroutine) {
  using slang::ast::ArgumentDirection;
 
  SmallVector<moore::DPIArgInfo> args;
  args.reserve(subroutine.getArguments().size() +
               (!subroutine.getReturnType().isVoid() ? 1 : 0));
 
  for (const auto *arg : subroutine.getArguments()) {
    auto type = context.convertType(arg->getType());
    if (!type)
      return failure();
    moore::DPIArgDirection dir;
    switch (arg->direction) {
    case ArgumentDirection::In:
      dir = moore::DPIArgDirection::In;
      break;
    case ArgumentDirection::Out:
      dir = moore::DPIArgDirection::Out;
      break;
    case ArgumentDirection::InOut:
      dir = moore::DPIArgDirection::InOut;
      break;
    case ArgumentDirection::Ref:
      llvm_unreachable("'ref' is not legal for DPI functions");
    }
    args.push_back(
        {StringAttr::get(context.getContext(), arg->name), type, dir});
  }
 
  if (!subroutine.getReturnType().isVoid()) {
    auto type = context.convertType(subroutine.getReturnType());
    if (!type)
      return failure();
    args.push_back({StringAttr::get(context.getContext(), "return"), type,
                    moore::DPIArgDirection::Return});
  }
 
  return args;
}
 
/// Convert a function and its arguments to a function declaration in the IR.
/// This does not convert the function body.
FunctionLowering *
Context::declareCallableImpl(const slang::ast::SubroutineSymbol &subroutine,
                             mlir::StringRef qualifiedName,
                             llvm::SmallVectorImpl<Type> &extraParams) {
  auto loc = convertLocation(subroutine.location);
  // Pick an insertion point for this function according to the source file
  // location.
  OpBuilder::InsertionGuard g(builder);
  auto locationKey = LocationKey::get(subroutine.location, sourceManager);
  auto it = orderedRootOps.upper_bound(locationKey);
  if (it == orderedRootOps.end())
    builder.setInsertionPointToEnd(intoModuleOp.getBody());
  else
    builder.setInsertionPoint(it->second);
 
  // Build the capture parameter types. These are appended after the user-
  // defined arguments, not in the extraParams prefix, so the function type has
  // the layout [this?] [user args] [captures].
  SmallVector<Type> captureTypes;
  auto capturesIt = functionCaptures.find(&subroutine);
  if (capturesIt != functionCaptures.end()) {
    for (auto *sym : capturesIt->second) {
      auto type = convertType(sym->getType());
      if (!type)
        return nullptr;
      captureTypes.push_back(
          moore::RefType::get(cast<moore::UnpackedType>(type)));
    }
  }
 
  auto funcTy =
      getFunctionSignature(*this, subroutine, extraParams, captureTypes);
  if (!funcTy)
    return nullptr;
 
  std::unique_ptr<FunctionLowering> lowering;
  Operation *insertedOp = nullptr;
  auto dpiExportIt = dpiExportCNames.find(&subroutine);
  bool isDPIExport = dpiExportIt != dpiExportCNames.end();
  // DPI-exported subroutines must keep a public symbol tagged with the
  // exported C name so later pipeline stages can materialize the export.
  auto setVisibilityAndExportAttr = [&](Operation *op) {
    if (isDPIExport) {
      op->setAttr(dpiExportAttrName,
                  builder.getStringAttr(dpiExportIt->second));
      SymbolTable::setSymbolVisibility(op, SymbolTable::Visibility::Public);
      return;
    }
    SymbolTable::setSymbolVisibility(op, SymbolTable::Visibility::Private);
  };
  if (!subroutine.thisVar &&
      subroutine.flags.has(slang::ast::MethodFlags::DPIImport)) {
    // DPI-imported function: create a moore.func.dpi declaration.
    auto dpiSig = getDPISignature(*this, subroutine);
    if (failed(dpiSig))
      return nullptr;
 
    auto dpiOp = moore::DPIFuncOp::create(
        builder, loc, StringAttr::get(getContext(), qualifiedName), *dpiSig,
        /*argumentLocs=*/ArrayAttr(),
        StringAttr::get(getContext(), subroutine.name));
    setVisibilityAndExportAttr(dpiOp);
    lowering = std::make_unique<FunctionLowering>(dpiOp);
    insertedOp = dpiOp;
  } else if (subroutine.subroutineKind == slang::ast::SubroutineKind::Task) {
    // Create a coroutine for tasks (which can suspend).
    auto op = moore::CoroutineOp::create(builder, loc, qualifiedName, funcTy);
    setVisibilityAndExportAttr(op);
    lowering = std::make_unique<FunctionLowering>(op);
    insertedOp = op;
  } else {
    // Create a function for regular functions (which cannot suspend).
    auto funcOp =
        mlir::func::FuncOp::create(builder, loc, qualifiedName, funcTy);
    setVisibilityAndExportAttr(funcOp);
    lowering = std::make_unique<FunctionLowering>(funcOp);
    insertedOp = funcOp;
  }
  orderedRootOps.insert(it, {locationKey, insertedOp});
 
  // Store the captured symbols so call sites can look them up.
  if (capturesIt != functionCaptures.end())
    lowering->capturedSymbols.assign(capturesIt->second.begin(),
                                     capturesIt->second.end());
 
  // Add the op to the symbol table of the MLIR module, which uniquifies
  // its name.
  symbolTable.insert(insertedOp);
  functions[&subroutine] = std::move(lowering);
 
  // Schedule the body to be defined later.
  functionWorklist.push(&subroutine);
 
  return functions[&subroutine].get();
}
 
/// Define a function’s body. The function must already have been declared via
/// `declareFunction`. This is called from the function worklist after all
/// declarations have been created, ensuring that all function prototypes are
/// available for calls within the body.
LogicalResult
Context::defineFunction(const slang::ast::SubroutineSymbol &subroutine) {
  auto *lowering = functions.at(&subroutine).get();
 
  // Keep track of the local time scale. `getTimeScale` automatically looks
  // through parent scopes to find the time scale effective locally.
  auto prevTimeScale = timeScale;
  timeScale = subroutine.getTimeScale().value_or(slang::TimeScale());
  llvm::scope_exit timeScaleGuard([&] { timeScale = prevTimeScale; });
 
  // DPI-C imported functions are extern declarations with no Verilog body.
  // Leave the func.func without a body region so it survives as an external
  // symbol and calls to it are not eliminated.
  if (subroutine.flags.has(slang::ast::MethodFlags::DPIImport))
    return success();
 
  const bool isMethod = (subroutine.thisVar != nullptr);
 
  ValueSymbolScope scope(valueSymbols);
  VirtualInterfaceMemberScope vifMemberScope(virtualIfaceMembers);
  if (isMethod) {
    if (const auto *classTy =
            subroutine.thisVar->getType().as_if<slang::ast::ClassType>()) {
      for (auto &member : classTy->members()) {
        const auto *prop = member.as_if<slang::ast::ClassPropertySymbol>();
        if (!prop)
          continue;
        const auto &propCanon = prop->getType().getCanonicalType();
        if (const auto *vi =
                propCanon.as_if<slang::ast::VirtualInterfaceType>()) {
          auto propLoc = convertLocation(prop->location);
          if (failed(registerVirtualInterfaceMembers(*prop, *vi, propLoc)))
            return failure();
        }
      }
    }
  }
 
  // Create a function body block and populate it with block arguments.
  SmallVector<moore::VariableOp> argVariables;
  auto &block = lowering->op.getFunctionBody().emplaceBlock();
 
  // If this is a class method, the first input is %this :
  // !moore.class<@C>
  if (isMethod) {
    auto thisLoc = convertLocation(subroutine.location);
    auto thisType =
        cast<FunctionType>(lowering->op.getFunctionType()).getInput(0);
    auto thisArg = block.addArgument(thisType, thisLoc);
 
    // Bind `this` so NamedValue/MemberAccess can find it.
    valueSymbols.insert(subroutine.thisVar, thisArg);
  }
 
  // Add user-defined block arguments. The function type has the shape
  // [this?] [user args] [capture args], so we skip the prefix and suffix.
  auto inputs = cast<FunctionType>(lowering->op.getFunctionType()).getInputs();
  auto astArgs = subroutine.getArguments();
  unsigned prefixCount = isMethod ? 1 : 0;
  auto valInputs = llvm::ArrayRef<Type>(inputs)
                       .drop_front(prefixCount)
                       .take_front(astArgs.size());
 
  for (auto [astArg, type] : llvm::zip(astArgs, valInputs)) {
    auto loc = convertLocation(astArg->location);
    auto blockArg = block.addArgument(type, loc);
 
    if (isa<moore::RefType>(type)) {
      valueSymbols.insert(astArg, blockArg);
    } else {
      OpBuilder::InsertionGuard g(builder);
      builder.setInsertionPointToEnd(&block);
 
      auto shadowArg = moore::VariableOp::create(
          builder, loc, moore::RefType::get(cast<moore::UnpackedType>(type)),
          StringAttr{}, blockArg);
      valueSymbols.insert(astArg, shadowArg);
      argVariables.push_back(shadowArg);
    }
 
    const auto &argCanon = astArg->getType().getCanonicalType();
    if (const auto *vi = argCanon.as_if<slang::ast::VirtualInterfaceType>())
      if (failed(registerVirtualInterfaceMembers(*astArg, *vi, loc)))
        return failure();
  }
 
  // Convert the body of the function.
  OpBuilder::InsertionGuard g(builder);
  builder.setInsertionPointToEnd(&block);
 
  Value returnVar;
  if (subroutine.returnValVar) {
    auto type = convertType(*subroutine.returnValVar->getDeclaredType());
    if (!type)
      return failure();
    returnVar = moore::VariableOp::create(
        builder, lowering->op->getLoc(),
        moore::RefType::get(cast<moore::UnpackedType>(type)), StringAttr{},
        Value{});
    valueSymbols.insert(subroutine.returnValVar, returnVar);
  }
 
  // Add block arguments for captured variables and bind them in the symbol
  // table. The captures were already added to the function type during
  // declaration; here we create the corresponding block arguments and map each
  // captured AST symbol to its block argument so that references in the body
  // resolve to the capture parameter instead of the enclosing scope’s value.
  for (auto *sym : lowering->capturedSymbols) {
    auto type = convertType(sym->getType());
    if (!type)
      return failure();
    auto refType = moore::RefType::get(cast<moore::UnpackedType>(type));
    auto loc = convertLocation(sym->location);
    auto blockArg = block.addArgument(refType, loc);
    valueSymbols.insert(sym, blockArg);
  }
 
  auto savedThis = currentThisRef;
  currentThisRef = valueSymbols.lookup(subroutine.thisVar);
  llvm::scope_exit restoreThis([&] { currentThisRef = savedThis; });
 
  auto *savedFunctionLowering = currentFunctionLowering;
  currentFunctionLowering = lowering;
  llvm::scope_exit restoreFunctionLowering(
      [&] { currentFunctionLowering = savedFunctionLowering; });
 
  if (failed(convertStatement(subroutine.getBody())))
    return failure();
 
  // If there was no explicit return statement provided by the user, insert a
  // default one.
  if (builder.getBlock()) {
    if (isa<moore::CoroutineOp>(lowering->op.getOperation())) {
      moore::ReturnOp::create(builder, lowering->op->getLoc());
    } else if (returnVar && !subroutine.getReturnType().isVoid()) {
      Value read =
          moore::ReadOp::create(builder, returnVar.getLoc(), returnVar);
      mlir::func::ReturnOp::create(builder, lowering->op->getLoc(), read);
    } else {
      mlir::func::ReturnOp::create(builder, lowering->op->getLoc(),
                                   ValueRange{});
    }
  }
  if (returnVar && returnVar.use_empty())
    returnVar.getDefiningOp()->erase();
 
  for (auto var : argVariables) {
    if (llvm::all_of(var->getUsers(),
                     [](auto *user) { return isa<moore::ReadOp>(user); })) {
      for (auto *user : llvm::make_early_inc_range(var->getUsers())) {
        user->getResult(0).replaceAllUsesWith(var.getInitial());
        user->erase();
      }
      var->erase();
    }
  }
 
  return success();
}
 
LogicalResult
Context::assignPrimOutputWithDelay(Value outputVal, Value assignment,
                                   const slang::ast::TimingControl *delay,
                                   Location loc) {
  if (delay) {
    const slang::ast::Expression *delayExpr;
    if (const auto *delay3 = delay->as_if<slang::ast::Delay3Control>()) {
      if (delay3->expr2 || delay3->expr3)
        return mlir::emitError(loc) << "only primitives that specify a "
                                       "single delay are currently supported.";
      delayExpr = &delay3->expr1;
    } else if (const auto *delayControl =
                   delay->as_if<slang::ast::DelayControl>()) {
      delayExpr = &delayControl->expr;
    } else {
      llvm_unreachable("unexpected delay control type in primitive instance");
    }
    auto delayVal = this->convertRvalueExpression(
        *delayExpr, moore::TimeType::get(getContext()));
    if (!delayVal)
      return failure();
    moore::DelayedContinuousAssignOp::create(builder, loc, outputVal,
                                             assignment, delayVal);
  } else {
    moore::ContinuousAssignOp::create(builder, loc, outputVal, assignment);
  }
 
  return success();
}
 
/// Convert a primitive instance.
LogicalResult Context::convertPrimitiveInstance(
    const slang::ast::PrimitiveInstanceSymbol &prim) {
  if (prim.getDriveStrength().first.has_value() ||
      prim.getDriveStrength().second.has_value())
    return mlir::emitError(convertLocation(prim.location))
           << "primitive instances with explicit drive strengths are not "
              "supported.";
 
  switch (prim.primitiveType.primitiveKind) {
  case slang::ast::PrimitiveSymbol::PrimitiveKind::NInput:
    return this->convertNInputPrimitive(prim);
    break;
  case slang::ast::PrimitiveSymbol::PrimitiveKind::NOutput:
    return this->convertNOutputPrimitive(prim);
    break;
  case slang::ast::PrimitiveSymbol::PrimitiveKind::Fixed:
    return this->convertFixedPrimitive(prim);
    break;
  default:
    return mlir::emitError(convertLocation(prim.location))
           << "unsupported instance of primitive `" << prim.primitiveType.name
           << "`";
  }
}
 
LogicalResult Context::convertNInputPrimitive(
    const slang::ast::PrimitiveInstanceSymbol &prim) {
  auto loc = convertLocation(prim.location);
  auto primName = prim.primitiveType.name;
 
  auto portConns = prim.getPortConnections();
  assert(portConns.size() >= 2 &&
         "n-input primitives should have at least 2 ports");
 
  // Get SSA values corresponding to operands (and unwrap where necessary)
  auto &outputConn =
      portConns[0]->as<slang::ast::AssignmentExpression>().left();
 
  auto outputVal = this->convertLvalueExpression(outputConn);
  if (!outputVal)
    return failure();
 
  SmallVector<Value> inputVals;
  inputVals.reserve(portConns.size() - 1);
  for (const auto *inputConn : portConns.subspan(1, portConns.size() - 1)) {
    auto inputVal = convertRvalueExpression(*inputConn);
    if (!inputVal)
      return failure();
    inputVals.push_back(inputVal);
  }
 
  Value nextInput = inputVals.front();
  auto result =
      llvm::StringSwitch<std::function<Value()>>(prim.primitiveType.name)
          .Case("and", ([&] {
                  for (Value inputVal : llvm::drop_begin(inputVals))
                    nextInput =
                        moore::AndOp::create(builder, loc, nextInput, inputVal);
                  return nextInput;
                }))
          .Case("or", ([&] {
                  for (Value inputVal : llvm::drop_begin(inputVals))
                    nextInput =
                        moore::OrOp::create(builder, loc, nextInput, inputVal);
                  return nextInput;
                }))
          .Case("xor", ([&] {
                  for (Value inputVal : llvm::drop_begin(inputVals))
                    nextInput =
                        moore::XorOp::create(builder, loc, nextInput, inputVal);
                  return nextInput;
                }))
          .Case("nand", ([&] {
                  for (Value inputVal : llvm::drop_begin(inputVals))
                    nextInput =
                        moore::AndOp::create(builder, loc, nextInput, inputVal);
                  return moore::NotOp::create(builder, loc, nextInput);
                }))
          .Case("nor", ([&] {
                  for (Value inputVal : llvm::drop_begin(inputVals))
                    nextInput =
                        moore::OrOp::create(builder, loc, nextInput, inputVal);
                  return moore::NotOp::create(builder, loc, nextInput);
                }))
          .Case("xnor", ([&] {
                  for (Value inputVal : llvm::drop_begin(inputVals))
                    nextInput =
                        moore::XorOp::create(builder, loc, nextInput, inputVal);
                  return moore::NotOp::create(builder, loc, nextInput);
                }))
          .Default([&] {
            mlir::emitError(loc)
                << "unsupported primitive `" << primName << "`";
            return Value();
          })();
 
  if (!result)
    return failure();
 
  auto dstType = cast<moore::RefType>(outputVal.getType()).getNestedType();
  result = materializeConversion(dstType, result, false, loc);
  if (!result)
    return failure();
 
  return assignPrimOutputWithDelay(outputVal, result, prim.getDelay(), loc);
}
 
LogicalResult Context::convertNOutputPrimitive(
    const slang::ast::PrimitiveInstanceSymbol &prim) {
  auto loc = convertLocation(prim.location);
  auto primName = prim.primitiveType.name;
 
  auto portConns = prim.getPortConnections();
  assert(portConns.size() >= 2 &&
         "n-output primitives should have at least 2 ports");
 
  // Get SSA values corresponding to operands (and unwrap where necessary)
  SmallVector<Value> outputVals;
  outputVals.reserve(portConns.size() - 1);
  for (const auto *outputConn : portConns.subspan(0, portConns.size() - 1)) {
    auto &output = outputConn->as<slang::ast::AssignmentExpression>().left();
    auto outputVal = this->convertLvalueExpression(output);
    if (!outputVal)
      return failure();
    outputVals.push_back(outputVal);
  }
 
  auto inputVal = this->convertRvalueExpression(*portConns.back());
  if (!inputVal)
    return failure();
 
  auto result =
      llvm::StringSwitch<std::function<Value()>>(prim.primitiveType.name)
          .Case("not",
                ([&] { return moore::NotOp::create(builder, loc, inputVal); }))
          .Case("buf", ([&] {
                  return moore::BoolCastOp::create(builder, loc, inputVal);
                }))
          .Default([&] {
            mlir::emitError(loc)
                << "unsupported primitive `" << primName << "`";
            return Value();
          })();
 
  if (!result)
    return failure();
 
  for (auto outputVal : outputVals) {
    auto dstType = cast<moore::RefType>(outputVal.getType()).getNestedType();
    Value converted = materializeConversion(dstType, result, false, loc);
    if (!converted)
      return failure();
    if (failed(assignPrimOutputWithDelay(outputVal, converted, prim.getDelay(),
                                         loc)))
      return failure();
  }
 
  return success();
}
 
LogicalResult Context::convertFixedPrimitive(
    const slang::ast::PrimitiveInstanceSymbol &prim) {
  auto primName = prim.primitiveType.name;
  auto loc = convertLocation(prim.location);
 
  // Fixed primitives cover a few different cases, so dispatch those separately
 
  if (primName == "pullup" || primName == "pulldown")
    return convertPullGatePrimitive(prim);
 
  if (primName == "bufif0" || primName == "bufif1" || primName == "notif0" ||
      primName == "notif1")
    return convertThreeStateGatePrimitive(prim);
 
  if (primName == "nmos" || primName == "pmos" || primName == "rnmos" ||
      primName == "rpmos") {
    return convertMOSSwitchPrimitive(prim);
  }
 
  if (primName == "cmos" || primName == "rcmos")
    return convertCMOSSwitchPrimitive(prim);
 
  // Remaining fixed primitives still need handling
  mlir::emitError(loc) << "unsupported primitive `" << primName << "`";
  return failure();
}
 
LogicalResult Context::convertPullGatePrimitive(
    const slang::ast::PrimitiveInstanceSymbol &prim) {
  assert((prim.primitiveType.name == "pullup" ||
          prim.primitiveType.name == "pulldown") &&
         "expected pullup or pulldown primitive");
  // Slang should catch this
  assert(!prim.getDelay() &&
         "SystemVerilog does not allow pull gate primitives with delays");
  auto loc = convertLocation(prim.location);
  auto primName = prim.primitiveType.name;
 
  auto portConns = prim.getPortConnections();
  // Slang should ensure this for us
  assert(portConns.size() == 1 &&
         "pullup/pulldown primitives should have exactly one port");
 
  Value portVal = this->convertLvalueExpression(
      portConns.front()->as<slang::ast::AssignmentExpression>().left());
 
  auto dstType = cast<moore::RefType>(portVal.getType()).getNestedType();
  auto dstTypeWidth = dstType.getBitSize();
  // This should be caught elsewhere
  assert(dstTypeWidth &&
         "expected fixed-width type for pullup/pulldown primitive");
  auto constVal = primName == "pullup" ? -1 : 0;
  auto c = moore::ConstantOp::create(
      builder, loc,
      moore::IntType::getInt(this->getContext(), dstTypeWidth.value()),
      constVal);
 
  Value converted = materializeConversion(dstType, c, false, loc);
  if (!converted)
    return failure();
  moore::ContinuousAssignOp::create(builder, loc, portVal, converted);
  return success();
}
 
/// Yields `data` unless it is exactly Z, in which case yields X instead.
/// Per IEEE 1800-2023 Section 28.6's table 28-5 for three-state gates, a Z
/// data input yields X on either the actively-driven or ambiguous-enable path.
/// Known 0/1 data values pass through unchanged. For three-state gates this
/// depends on the assumption that we collapse L to 0 and H to 1.
static Value collapseZToX(OpBuilder &builder, Location loc, Value data,
                          Type dstType) {
  auto dstIntType = cast<moore::IntType>(dstType);
  Value xVal =
      moore::ConstantOp::create(builder, loc, dstIntType, FVInt::getAllX(1));
  Value zVal =
      moore::ConstantOp::create(builder, loc, dstIntType, FVInt::getAllZ(1));
 
  auto isZ = moore::CaseEqOp::create(builder, loc, data, zVal);
  auto condOp = moore::ConditionalOp::create(builder, loc, dstType, isZ);
  auto &trueBlk = condOp.getTrueRegion().emplaceBlock();
  auto &falseBlk = condOp.getFalseRegion().emplaceBlock();
  {
    OpBuilder::InsertionGuard g(builder);
    builder.setInsertionPointToStart(&trueBlk);
    moore::YieldOp::create(builder, loc, xVal);
    builder.setInsertionPointToStart(&falseBlk);
    moore::YieldOp::create(builder, loc, data);
  }
  return condOp.getResult();
}
 
LogicalResult Context::convertThreeStateGatePrimitive(
    const slang::ast::PrimitiveInstanceSymbol &prim) {
  auto loc = convertLocation(prim.location);
  auto primName = prim.primitiveType.name;
 
  auto portConns = prim.getPortConnections();
  assert(portConns.size() == 3 &&
         "Expected exactly 3 ports in three-state gate primitives");
 
  auto &outputConn =
      portConns[0]->as<slang::ast::AssignmentExpression>().left();
  auto outputVal = convertLvalueExpression(outputConn);
  if (!outputVal)
    return failure();
 
  auto inVal = convertRvalueExpression(*portConns[1]);
  auto enVal = convertRvalueExpression(*portConns[2]);
  if (!inVal || !enVal)
    return failure();
 
  auto enType = cast<moore::IntType>(enVal.getType());
  auto enWidth = enType.getBitSize();
  // Slang automatically casts enable signals (or errors if it can't be cast)
  assert(enWidth && *enWidth == 1 &&
         "enable signal of a three-state gate primitive must be 1 bit");
 
  auto dstType = cast<moore::RefType>(outputVal.getType()).getNestedType();
  auto dstWidth = dstType.getBitSize();
  if (!dstWidth || *dstWidth != 1)
    return mlir::emitError(loc)
           << "output of a three-state gate primitive must be 1 bit";
 
  if (primName == "notif0" || primName == "notif1")
    inVal = moore::NotOp::create(builder, loc, inVal);
 
  inVal = materializeConversion(dstType, inVal, false, loc);
  if (!inVal)
    return failure();
 
  // Value of enable to be considered active or inactive
  int inactiveLevel = (primName == "bufif1" || primName == "notif1") ? 0 : 1;
  Value inactiveConst =
      moore::ConstantOp::create(builder, loc, enType, inactiveLevel, false);
 
  auto dstIntType = cast<moore::IntType>(dstType);
  Value zVal =
      moore::ConstantOp::create(builder, loc, dstIntType, FVInt::getAllZ(1));
 
  // Compare enable to what we consider inactive (0 or 1 depending on type of
  // buffer)
  auto condInactive =
      moore::CaseEqOp::create(builder, loc, enVal, inactiveConst);
  auto inactiveOp =
      moore::ConditionalOp::create(builder, loc, dstType, condInactive);
  auto &inactiveTrue = inactiveOp.getTrueRegion().emplaceBlock();
  auto &inactiveFalse = inactiveOp.getFalseRegion().emplaceBlock();
 
  {
    OpBuilder::InsertionGuard g(builder);
    builder.setInsertionPointToStart(&inactiveTrue);
    moore::YieldOp::create(builder, loc, zVal);
    builder.setInsertionPointToStart(&inactiveFalse);
    moore::YieldOp::create(builder, loc,
                           collapseZToX(builder, loc, inVal, dstType));
  }
 
  Value result = inactiveOp.getResult();
 
  return assignPrimOutputWithDelay(outputVal, result, prim.getDelay(), loc);
}
 
LogicalResult Context::convertMOSSwitchPrimitive(
    const slang::ast::PrimitiveInstanceSymbol &prim) {
  assert(
      prim.primitiveType.name == "nmos" || prim.primitiveType.name == "pmos" ||
      prim.primitiveType.name == "rnmos" || prim.primitiveType.name == "rpmos");
 
  auto loc = convertLocation(prim.location);
  auto primName = prim.primitiveType.name;
 
  auto portConns = prim.getPortConnections();
 
  assert(portConns.size() == 3 && "mos primitive should have exactly 3 ports");
 
  auto &outputConn =
      portConns[0]->as<slang::ast::AssignmentExpression>().left();
 
  auto outputVal = convertLvalueExpression(outputConn);
  if (!outputVal)
    return failure();
 
  auto inputVal = convertRvalueExpression(*portConns[1]);
  if (!inputVal)
    return failure();
 
  // Slang automatically casts MOS switch inputs to 1-bit logic.
  assert(cast<moore::IntType>(inputVal.getType()).getBitSize() == 1 &&
         "MOS switch input must be 1 bit");
 
  Value controlIsOff;
 
  auto control = convertRvalueExpression(*portConns[2]);
  if (!control)
    return failure();
 
  auto controlType = cast<moore::IntType>(control.getType());
  assert(controlType.getBitSize() == 1 && "MOS switch control must be 1 bit");
 
  int offLevel = (primName == "nmos" || primName == "rnmos") ? 0 : 1;
  auto offValue = moore::ConstantOp::create(
      builder, loc, controlType, FVInt(1, static_cast<uint64_t>(offLevel)));
 
  controlIsOff = moore::CaseEqOp::create(builder, loc, control, offValue);
  auto dstType = cast<moore::RefType>(outputVal.getType()).getNestedType();
 
  auto dstIntType = dyn_cast<moore::IntType>(dstType);
  if (!dstIntType || dstIntType.getBitSize() != 1)
    return mlir::emitError(loc) << "MOS switch output must be 1 bit";
 
  auto convertedInput = materializeConversion(dstType, inputVal, false, loc);
  if (!convertedInput)
    return failure();
 
  Value zVal =
      moore::ConstantOp::create(builder, loc, dstIntType, FVInt::getAllZ(1));
 
  auto condOp =
      moore::ConditionalOp::create(builder, loc, dstType, controlIsOff);
 
  auto &trueBlock = condOp.getTrueRegion().emplaceBlock();
  auto &falseBlock = condOp.getFalseRegion().emplaceBlock();
 
  builder.setInsertionPointToStart(&trueBlock);
  moore::YieldOp::create(builder, loc, zVal);
 
  builder.setInsertionPointToStart(&falseBlock);
  moore::YieldOp::create(builder, loc, convertedInput);
 
  builder.setInsertionPointAfter(condOp);
 
  return assignPrimOutputWithDelay(outputVal, condOp.getResult(),
                                   prim.getDelay(), loc);
}
 
LogicalResult Context::convertCMOSSwitchPrimitive(
    const slang::ast::PrimitiveInstanceSymbol &prim) {
  assert(prim.primitiveType.name == "cmos" ||
         prim.primitiveType.name == "rcmos");
 
  auto loc = convertLocation(prim.location);
  auto portConns = prim.getPortConnections();
  assert(portConns.size() == 4 && "cmos primitive should have exactly 4 ports");
 
  auto &outputConn =
      portConns[0]->as<slang::ast::AssignmentExpression>().left();
  auto outputVal = convertLvalueExpression(outputConn);
  if (!outputVal)
    return failure();
 
  auto dataVal = convertRvalueExpression(*portConns[1]);
  if (!dataVal)
    return failure();
  // Slang automatically casts CMOS switch inputs to 1-bit logic.
  assert(cast<moore::IntType>(dataVal.getType()).getBitSize() == 1 &&
         "CMOS switch input must be 1 bit");
 
  auto ncontrolVal = convertRvalueExpression(*portConns[2]);
  if (!ncontrolVal)
    return failure();
  assert(cast<moore::IntType>(ncontrolVal.getType()).getBitSize() == 1 &&
         "CMOS switch ncontrol must be 1 bit");
 
  auto pcontrolVal = convertRvalueExpression(*portConns[3]);
  if (!pcontrolVal)
    return failure();
  assert(cast<moore::IntType>(pcontrolVal.getType()).getBitSize() == 1 &&
         "CMOS switch pcontrol must be 1 bit");
 
  auto dstType = cast<moore::RefType>(outputVal.getType()).getNestedType();
  auto dstIntType = dyn_cast<moore::IntType>(dstType);
  if (!dstIntType || dstIntType.getBitSize() != 1)
    return mlir::emitError(loc) << "CMOS switch output must be 1 bit";
 
  auto convertedData = materializeConversion(dstType, dataVal, false, loc);
  if (!convertedData)
    return failure();
 
  auto logicType = moore::IntType::getLogic(getContext(), 1);
 
  auto makeConst = [&](FVInt val) -> Value {
    Value c = moore::ConstantOp::create(builder, loc, logicType, val);
    return materializeConversion(dstType, c, false, loc);
  };
  Value zVal = makeConst(FVInt::getAllZ(1));
  Value xVal = makeConst(FVInt::getAllX(1));
  if (!zVal || !xVal)
    return failure();
 
  auto makeLevelConstant = [&](Value value, int level) -> Value {
    auto type = cast<moore::IntType>(value.getType());
    return moore::ConstantOp::create(builder, loc, type,
                                     FVInt(1, static_cast<uint64_t>(level)));
  };
 
  auto muxZOrData = [&](Value cond) -> Value {
    auto condOp = moore::ConditionalOp::create(builder, loc, dstType, cond);
    auto &trueBlk = condOp.getTrueRegion().emplaceBlock();
    auto &falseBlk = condOp.getFalseRegion().emplaceBlock();
    builder.setInsertionPointToStart(&trueBlk);
    moore::YieldOp::create(builder, loc, zVal);
    builder.setInsertionPointToStart(&falseBlk);
    moore::YieldOp::create(builder, loc, convertedData);
    builder.setInsertionPointAfter(condOp);
    return condOp.getResult();
  };
 
  // N side: behaves like NMOS -- off (Z) when ncontrol === 0.
  auto nOff = makeLevelConstant(ncontrolVal, 0);
  auto nIsOff = moore::CaseEqOp::create(builder, loc, ncontrolVal, nOff);
  Value nResult = muxZOrData(nIsOff);
 
  // P side: behaves like PMOS -- off (Z) when pcontrol === 1.
  auto pOff = makeLevelConstant(pcontrolVal, 1);
  auto pIsOff = moore::CaseEqOp::create(builder, loc, pcontrolVal, pOff);
  Value pResult = muxZOrData(pIsOff);
 
  auto agree = moore::CaseEqOp::create(builder, loc, nResult, pResult);
  auto nIsZ = moore::CaseEqOp::create(builder, loc, nResult, zVal);
  auto pIsZ = moore::CaseEqOp::create(builder, loc, pResult, zVal);
 
  auto outerCond = moore::ConditionalOp::create(builder, loc, dstType, agree);
  auto &outerTrue = outerCond.getTrueRegion().emplaceBlock();
  auto &outerFalse = outerCond.getFalseRegion().emplaceBlock();
 
  {
    OpBuilder::InsertionGuard guard(builder);
    builder.setInsertionPointToStart(&outerTrue);
    moore::YieldOp::create(builder, loc, nResult);
 
    builder.setInsertionPointToStart(&outerFalse);
    auto middleCond = moore::ConditionalOp::create(builder, loc, dstType, nIsZ);
    auto &middleTrue = middleCond.getTrueRegion().emplaceBlock();
    auto &middleFalse = middleCond.getFalseRegion().emplaceBlock();
    moore::YieldOp::create(builder, loc, middleCond.getResult());
 
    builder.setInsertionPointToStart(&middleTrue);
    moore::YieldOp::create(builder, loc, pResult);
 
    builder.setInsertionPointToStart(&middleFalse);
    auto innerCond = moore::ConditionalOp::create(builder, loc, dstType, pIsZ);
    auto &innerTrue = innerCond.getTrueRegion().emplaceBlock();
    auto &innerFalse = innerCond.getFalseRegion().emplaceBlock();
 
    builder.setInsertionPointToStart(&innerTrue);
    moore::YieldOp::create(builder, loc, nResult);
    builder.setInsertionPointToStart(&innerFalse);
    moore::YieldOp::create(builder, loc, xVal);
 
    builder.setInsertionPointAfter(innerCond);
    moore::YieldOp::create(builder, loc, innerCond.getResult());
  }
 
  return assignPrimOutputWithDelay(outputVal, outerCond.getResult(),
                                   prim.getDelay(), loc);
}
 
namespace {
 
/// Construct a fully qualified class name containing the instance hierarchy
/// and the class name formatted as H1::H2::@C
mlir::StringAttr fullyQualifiedClassName(Context &ctx,
                                         const slang::ast::Type &ty) {
  SmallString<64> name;
  SmallVector<llvm::StringRef, 8> parts;
 
  const slang::ast::Scope *scope = ty.getParentScope();
  while (scope) {
    const auto &sym = scope->asSymbol();
    switch (sym.kind) {
    case slang::ast::SymbolKind::Root:
      scope = nullptr; // stop at $root
      continue;
    case slang::ast::SymbolKind::InstanceBody:
    case slang::ast::SymbolKind::Instance:
    case slang::ast::SymbolKind::Package:
    case slang::ast::SymbolKind::ClassType:
      if (!sym.name.empty())
        parts.push_back(sym.name); // keep packages + outer classes
      break;
    default:
      break;
    }
    scope = sym.getParentScope();
  }
 
  for (auto p : llvm::reverse(parts)) {
    name += p;
    name += "::";
  }
  name += ty.name; // class’s own name
  return mlir::StringAttr::get(ctx.getContext(), name);
}
 
/// Helper function to construct the classes fully qualified base class name
/// and the name of all implemented interface classes
std::pair<mlir::SymbolRefAttr, mlir::ArrayAttr>
buildBaseAndImplementsAttrs(Context &context,
                            const slang::ast::ClassType &cls) {
  mlir::MLIRContext *ctx = context.getContext();
 
  // Base class (if any)
  mlir::SymbolRefAttr base;
  if (const auto *b = cls.getBaseClass())
    base = mlir::SymbolRefAttr::get(fullyQualifiedClassName(context, *b));
 
  // Implemented interfaces (if any)
  SmallVector<mlir::Attribute> impls;
  if (auto ifaces = cls.getDeclaredInterfaces(); !ifaces.empty()) {
    impls.reserve(ifaces.size());
    for (const auto *iface : ifaces)
      impls.push_back(mlir::FlatSymbolRefAttr::get(
          fullyQualifiedClassName(context, *iface)));
  }
 
  mlir::ArrayAttr implArr =
      impls.empty() ? mlir::ArrayAttr() : mlir::ArrayAttr::get(ctx, impls);
 
  return {base, implArr};
}
 
/// Base class for visiting slang::ast::ClassType members.
/// Contains common state and utility methods.
struct ClassDeclVisitorBase {
  Context &context;
  OpBuilder &builder;
  ClassLowering &classLowering;
 
  ClassDeclVisitorBase(Context &ctx, ClassLowering &lowering)
      : context(ctx), builder(ctx.builder), classLowering(lowering) {}
 
protected:
  Location convertLocation(const slang::SourceLocation &sloc) {
    return context.convertLocation(sloc);
  }
};
 
/// Visitor for class property declarations.
/// Populates the ClassDeclOp body with PropertyDeclOps.
struct ClassPropertyVisitor : ClassDeclVisitorBase {
  using ClassDeclVisitorBase::ClassDeclVisitorBase;
 
  /// Build the ClassDeclOp body and populate it with property declarations.
  LogicalResult run(const slang::ast::ClassType &classAST) {
    if (!classLowering.op.getBody().empty())
      return success();
 
    OpBuilder::InsertionGuard ig(builder);
 
    Block *body = &classLowering.op.getBody().emplaceBlock();
    builder.setInsertionPointToEnd(body);
 
    // Visit only ClassPropertySymbols
    for (const auto &mem : classAST.members()) {
      if (const auto *prop = mem.as_if<slang::ast::ClassPropertySymbol>()) {
        if (failed(prop->visit(*this)))
          return failure();
      }
    }
 
    return success();
  }
 
  // Properties: ClassPropertySymbol
  LogicalResult visit(const slang::ast::ClassPropertySymbol &prop) {
    auto loc = convertLocation(prop.location);
    auto ty = context.convertType(prop.getType());
    if (!ty)
      return failure();
 
    if (prop.lifetime == slang::ast::VariableLifetime::Automatic) {
      moore::ClassPropertyDeclOp::create(builder, loc, prop.name,
                                         /*sym_visibility=*/{}, ty);
      return success();
    }
 
    // Static variables should be accessed like globals, and not emit any
    // property declaration. Static variables might get hoisted elsewhere
    // so check first whether they have been declared already.
 
    if (!context.globalVariables.lookup(&prop))
      return context.convertGlobalVariable(prop);
    return success();
  }
 
  // Nested class definition, convert
  LogicalResult visit(const slang::ast::ClassType &cls) {
    return context.buildClassProperties(cls);
  }
 
  // Catch-all: ignore everything else during property pass
  template <typename T>
  LogicalResult visit(T &&) {
    return success();
  }
};
 
/// Visitor for class method declarations.
/// Materializes methods and nested class definitions.
struct ClassMethodVisitor : ClassDeclVisitorBase {
  using ClassDeclVisitorBase::ClassDeclVisitorBase;
 
  /// Materialize class methods. The body must already exist from property pass.
  LogicalResult run(const slang::ast::ClassType &classAST) {
    if (classLowering.methodsFinalized)
      return success();
 
    if (classLowering.op.getBody().empty())
      return failure();
 
    OpBuilder::InsertionGuard ig(builder);
    builder.setInsertionPointToEnd(&classLowering.op.getBody().front());
 
    // Visit everything except ClassPropertySymbols
    for (const auto &mem : classAST.members()) {
      if (failed(mem.visit(*this)))
        return failure();
    }
 
    classLowering.methodsFinalized = true;
    return success();
  }
 
  // Skip properties during method pass
  LogicalResult visit(const slang::ast::ClassPropertySymbol &) {
    return success();
  }
 
  // Parameters in specialized classes hold no further information; slang
  // already elaborates them in all relevant places.
  LogicalResult visit(const slang::ast::ParameterSymbol &) { return success(); }
 
  // Parameters in specialized classes hold no further information; slang
  // already elaborates them in all relevant places.
  LogicalResult visit(const slang::ast::TypeParameterSymbol &) {
    return success();
  }
 
  // Type aliases in specialized classes hold no further information; slang
  // already elaborates them in all relevant places.
  LogicalResult visit(const slang::ast::TypeAliasType &) { return success(); }
 
  // Nested class definition, skip
  LogicalResult visit(const slang::ast::GenericClassDefSymbol &) {
    return success();
  }
 
  // Transparent members: ignore (inherited names pulled in by slang)
  LogicalResult visit(const slang::ast::TransparentMemberSymbol &) {
    return success();
  }
 
  // Empty members: ignore
  LogicalResult visit(const slang::ast::EmptyMemberSymbol &) {
    return success();
  }
 
  // Fully-fledged functions - SubroutineSymbol
  LogicalResult visit(const slang::ast::SubroutineSymbol &fn) {
    if (fn.flags & slang::ast::MethodFlags::BuiltIn) {
      static bool remarkEmitted = false;
      if (remarkEmitted)
        return success();
 
      mlir::emitRemark(classLowering.op.getLoc())
          << "Class builtin functions (needed for randomization, constraints, "
             "and covergroups) are not yet supported and will be dropped "
             "during lowering.";
      remarkEmitted = true;
      return success();
    }
 
    const mlir::UnitAttr isVirtual =
        (fn.flags & slang::ast::MethodFlags::Virtual)
            ? UnitAttr::get(context.getContext())
            : nullptr;
 
    auto loc = convertLocation(fn.location);
    // Pure virtual functions regulate inheritance rules during parsing.
    // They don't emit any code, so we don't need to convert them, we only need
    // to register them for the purpose of stable VTable construction.
    if (fn.flags & slang::ast::MethodFlags::Pure) {
      // Add an extra %this argument.
      SmallVector<Type, 1> extraParams;
      auto classSym =
          mlir::FlatSymbolRefAttr::get(classLowering.op.getSymNameAttr());
      auto handleTy =
          moore::ClassHandleType::get(context.getContext(), classSym);
      extraParams.push_back(handleTy);
 
      auto funcTy = getFunctionSignature(context, fn, extraParams);
      if (!funcTy) {
        mlir::emitError(loc) << "Invalid function signature for " << fn.name;
        return failure();
      }
 
      moore::ClassMethodDeclOp::create(builder, loc, fn.name,
                                       /*sym_visibility=*/{}, funcTy, nullptr);
      return success();
    }
 
    auto *lowering = context.declareFunction(fn);
    if (!lowering)
      return failure();
 
    // We only emit methoddecls for virtual methods.
    if (!isVirtual)
      return success();
 
    // Grab the function type from the declaration.
    FunctionType fnTy = cast<FunctionType>(lowering->op.getFunctionType());
    // Emit the method decl into the class body, preserving source order.
    moore::ClassMethodDeclOp::create(
        builder, loc, fn.name, /*sym_visibility=*/{}, fnTy,
        SymbolRefAttr::get(lowering->op.getNameAttr()));
 
    return success();
  }
 
  // A method prototype corresponds to the forward declaration of a concrete
  // method, the forward declaration of a virtual method, or the defintion of an
  // interface method meant to be implemented by classes implementing the
  // interface class.
  // In the first two cases, the best thing to do is to look up the actual
  // implementation and translate it when reading the method prototype, so we
  // can insert the MethodDeclOp in the correct order in the ClassDeclOp.
  // The latter case requires support for virtual interface methods, which is
  // currently not implemented. Since forward declarations of non-interface
  // methods must be followed by an implementation within the same compilation
  // unit, we can simply return a failure if we can't find a unique
  // implementation until we implement support for interface methods.
  LogicalResult visit(const slang::ast::MethodPrototypeSymbol &fn) {
    const auto *externImpl = fn.getSubroutine();
    // We needn't convert a forward declaration without a unique implementation.
    if (!externImpl) {
      mlir::emitError(convertLocation(fn.location))
          << "Didn't find an implementation matching the forward declaration "
             "of "
          << fn.name;
      return failure();
    }
    return visit(*externImpl);
  }
 
  // Nested class definition, convert
  LogicalResult visit(const slang::ast::ClassType &cls) {
    if (failed(context.buildClassProperties(cls)))
      return failure();
    return context.materializeClassMethods(cls);
  }
 
  // Emit an error for all other members.
  template <typename T>
  LogicalResult visit(T &&node) {
    Location loc = UnknownLoc::get(context.getContext());
    if constexpr (requires { node.location; })
      loc = convertLocation(node.location);
    mlir::emitError(loc) << "unsupported construct in ClassType members: "
                         << slang::ast::toString(node.kind);
    return failure();
  }
};
} // namespace
 
ClassLowering *Context::declareClass(const slang::ast::ClassType &cls) {
  // Check if there already is a declaration for this class.
  auto &lowering = classes[&cls];
  if (lowering)
    return lowering.get();
  lowering = std::make_unique<ClassLowering>();
  auto loc = convertLocation(cls.location);
 
  // Pick an insertion point for this function according to the source file
  // location.
  OpBuilder::InsertionGuard g(builder);
  auto locationKey = LocationKey::get(cls.location, sourceManager);
  auto it = orderedRootOps.upper_bound(locationKey);
  if (it == orderedRootOps.end())
    builder.setInsertionPointToEnd(intoModuleOp.getBody());
  else
    builder.setInsertionPoint(it->second);
 
  auto symName = fullyQualifiedClassName(*this, cls);
 
  auto [base, impls] = buildBaseAndImplementsAttrs(*this, cls);
  auto classDeclOp = moore::ClassDeclOp::create(
      builder, loc, symName, /*sym_visibility=*/{}, base, impls);
 
  SymbolTable::setSymbolVisibility(classDeclOp,
                                   SymbolTable::Visibility::Public);
  orderedRootOps.insert(it, {locationKey, classDeclOp});
  lowering->op = classDeclOp;
 
  symbolTable.insert(classDeclOp);
  return lowering.get();
}
 
LogicalResult
Context::buildClassProperties(const slang::ast::ClassType &classdecl) {
  // Keep track of local time scale.
  auto prevTimeScale = timeScale;
  timeScale = classdecl.getTimeScale().value_or(slang::TimeScale());
  llvm::scope_exit timeScaleGuard([&] { timeScale = prevTimeScale; });
 
  // Skip if classdecl is already built
  if (classes[&classdecl])
    return success();
 
  // Build base class properties first.
  if (classdecl.getBaseClass()) {
    if (const auto *baseClassDecl =
            classdecl.getBaseClass()->as_if<slang::ast::ClassType>()) {
      if (failed(buildClassProperties(*baseClassDecl)))
        return failure();
    }
  }
 
  // Declare the class and build the ClassDeclOp with property declarations.
  auto *lowering = declareClass(classdecl);
  if (!lowering)
    return failure();
 
  return ClassPropertyVisitor(*this, *lowering).run(classdecl);
}
 
LogicalResult
Context::materializeClassMethods(const slang::ast::ClassType &classdecl) {
  // Keep track of local time scale.
  auto prevTimeScale = timeScale;
  timeScale = classdecl.getTimeScale().value_or(slang::TimeScale());
  llvm::scope_exit timeScaleGuard([&] { timeScale = prevTimeScale; });
 
  // The class must have been declared already via buildClassProperties.
  auto *lowering = classes[&classdecl].get();
  if (!lowering)
    return failure();
 
  // Materialize base class methods first. This may insert new entries into the
  // `classes` map (e.g. for nested classes), so we must not hold an iterator
  // or reference into the map across this call.
  if (classdecl.getBaseClass()) {
    if (const auto *baseClassDecl =
            classdecl.getBaseClass()->as_if<slang::ast::ClassType>()) {
      if (failed(materializeClassMethods(*baseClassDecl)))
        return failure();
    }
  }
 
  return ClassMethodVisitor(*this, *lowering).run(classdecl);
}
 
/// Convert a variable to a `moore.global_variable` operation.
LogicalResult
Context::convertGlobalVariable(const slang::ast::VariableSymbol &var) {
  auto loc = convertLocation(var.location);
 
  // Pick an insertion point for this variable according to the source file
  // location.
  OpBuilder::InsertionGuard g(builder);
  auto locationKey = LocationKey::get(var.location, sourceManager);
  auto it = orderedRootOps.upper_bound(locationKey);
  if (it == orderedRootOps.end())
    builder.setInsertionPointToEnd(intoModuleOp.getBody());
  else
    builder.setInsertionPoint(it->second);
 
  // Prefix the variable name with the surrounding namespace to create somewhat
  // sane names in the IR.
  SmallString<64> symName;
 
  // If the variable is a class property, the symbol name needs to be fully
  // qualified with the hierarchical class name
  if (const auto *classVar = var.as_if<slang::ast::ClassPropertySymbol>()) {
    if (const auto *parentScope = classVar->getParentScope()) {
      if (const auto *parentClass =
              parentScope->asSymbol().as_if<slang::ast::ClassType>())
        symName = fullyQualifiedClassName(*this, *parentClass);
      else {
        mlir::emitError(loc)
            << "Could not access parent class of class property "
            << classVar->name;
        return failure();
      }
    } else {
      mlir::emitError(loc) << "Could not get parent scope of class property "
                           << classVar->name;
      return failure();
    }
    symName += "::";
    symName += var.name;
  } else {
    guessNamespacePrefix(var.getParentScope()->asSymbol(), symName);
    symName += var.name;
  }
 
  // Determine the type of the variable.
  auto type = convertType(var.getType());
  if (!type)
    return failure();
 
  // Create the variable op itself.
  auto varOp = moore::GlobalVariableOp::create(builder, loc, symName,
                                               /*sym_visibility=*/{},
                                               cast<moore::UnpackedType>(type));
  orderedRootOps.insert({locationKey, varOp});
  globalVariables.insert({&var, varOp});
 
  // Add the variable to the symbol table of the MLIR module, which uniquifies
  // its name.
  symbolTable.insert(varOp);
 
  // If the variable has an initializer expression, remember it for later such
  // that we can convert the initializers once we have seen all global
  // variables.
  if (var.getInitializer())
    globalVariableWorklist.push_back(&var);
 
  return success();
}