[LLHD] Add coroutine, call_coroutine, return ops

Add `llhd.coroutine`, `llhd.call_coroutine`, and `llhd.return` ops to
represent suspendable subroutines (SystemVerilog tasks) in the LLHD
dialect. Coroutines are `IsolatedFromAbove` function-like ops that can
contain `llhd.wait` and `llhd.halt`, just like processes. Calling a
coroutine suspends the caller until the coroutine returns.

Update the parent constraints on `llhd.wait` and `llhd.halt` to also
allow `llhd.coroutine` as a parent.

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

Author: fabianschuiki

include/circt/Dialect/LLHD/LLHDOps.td

@@ -14,7 +14,10 @@ include "circt/Dialect/LLHD/LLHDTypes.td"
 include "mlir/IR/EnumAttr.td"
 include "mlir/IR/OpAsmInterface.td"
 include "mlir/IR/SymbolInterfaces.td"
+include "mlir/IR/RegionKindInterface.td"
+include "mlir/Interfaces/CallInterfaces.td"
 include "mlir/Interfaces/ControlFlowInterfaces.td"
+include "mlir/Interfaces/FunctionInterfaces.td"
 include "mlir/Interfaces/InferTypeOpInterface.td"
 include "mlir/Interfaces/MemorySlotInterfaces.td"
 include "mlir/Interfaces/SideEffectInterfaces.td"
@@ -628,10 +631,10 @@ def CombinationalOp : LLHDOp<"combinational", [
 
 def WaitOp : LLHDOp<"wait", [
   AttrSizedOperandSegments,
-  HasParent<"ProcessOp">,
+  ParentOneOf<["ProcessOp", "CoroutineOp"]>,
   Terminator,
 ]> {
-  let summary = "Suspend execution of a process";
+  let summary = "Suspend execution of a process or coroutine";
   let description = [{
     The `llhd.wait` terminator suspends execution of the parent process until
     any of the `observed` values change or a fixed `delay` has passed. Execution
@@ -664,10 +667,10 @@ def WaitOp : LLHDOp<"wait", [
 }
 
 def HaltOp : LLHDOp<"halt", [
-  ParentOneOf<["ProcessOp", "FinalOp"]>,
+  ParentOneOf<["ProcessOp", "FinalOp", "CoroutineOp"]>,
   Terminator,
 ]> {
-  let summary = "Terminate execution of a process";
+  let summary = "Terminate execution of a process or coroutine";
   let description = [{
     The `llhd.halt` terminator suspends execution of the parent process forever,
     effectively terminating it. The `yieldOperands` are yielded as the result
@@ -718,4 +721,172 @@ def YieldOp : LLHDOp<"yield", [
   let hasVerifier = 1;
 }
 
+//===----------------------------------------------------------------------===//
+// Coroutines
+//===----------------------------------------------------------------------===//
+
+def CoroutineOp : LLHDOp<"coroutine", [
+  IsolatedFromAbove,
+  FunctionOpInterface,
+  Symbol,
+  RegionKindInterface,
+  ProceduralRegion,
+  RecursiveMemoryEffects,
+]> {
+  let summary = "Define a coroutine";
+  let description = [{
+    The `llhd.coroutine` op defines a suspendable subroutine that can be called
+    from processes or other coroutines. It represents the lowered form of a
+    SystemVerilog task. Unlike regular functions, coroutines can suspend
+    execution using `llhd.wait` and terminate using `llhd.halt`, just like
+    processes. Calling a coroutine via `llhd.call_coroutine` suspends the caller
+    until the coroutine returns.
+
+    Example:
+    ```mlir
+    llhd.coroutine @waitForClk(%clk: !llhd.ref<i1>) {
+      %0 = llhd.prb %clk : !llhd.ref<i1>
+      llhd.wait (%clk : !llhd.ref<i1>), ^resume
+    ^resume:
+      llhd.return
+    }
+    ```
+  }];
+
+  let arguments = (ins
+    SymbolNameAttr:$sym_name,
+    TypeAttrOf<FunctionType>:$function_type,
+    OptionalAttr<StrAttr>:$sym_visibility,
+    OptionalAttr<DictArrayAttr>:$arg_attrs,
+    OptionalAttr<DictArrayAttr>:$res_attrs
+  );
+  let results = (outs);
+  let regions = (region MinSizedRegion<1>:$body);
+
+  let hasCustomAssemblyFormat = 1;
+
+  let builders = [
+    OpBuilder<(ins "mlir::StringAttr":$sym_name,
+                   "mlir::TypeAttr":$function_type), [{
+      build($_builder, $_state, sym_name, function_type,
+            /*sym_visibility=*/mlir::StringAttr(),
+            /*arg_attrs=*/nullptr, /*res_attrs=*/nullptr);
+    }]>,
+    OpBuilder<(ins "mlir::StringRef":$sym_name,
+                   "mlir::FunctionType":$function_type), [{
+      build($_builder, $_state,
+            $_builder.getStringAttr(sym_name),
+            mlir::TypeAttr::get(function_type),
+            /*sym_visibility=*/mlir::StringAttr(),
+            /*arg_attrs=*/nullptr, /*res_attrs=*/nullptr);
+    }]>,
+  ];
+
+  let extraClassDeclaration = [{
+    static mlir::RegionKind getRegionKind(unsigned index) {
+      return mlir::RegionKind::SSACFG;
+    }
+
+    /// Returns the argument types of this coroutine.
+    mlir::ArrayRef<mlir::Type> getArgumentTypes() {
+      return getFunctionType().getInputs();
+    }
+
+    /// Returns the result types of this coroutine.
+    mlir::ArrayRef<mlir::Type> getResultTypes() {
+      return getFunctionType().getResults();
+    }
+
+    //===------------------------------------------------------------------===//
+    // CallableOpInterface
+    //===------------------------------------------------------------------===//
+
+    mlir::Region *getCallableRegion() { return &getBody(); }
+  }];
+}
+
+def CallCoroutineOp : LLHDOp<"call_coroutine", [
+  CallOpInterface,
+  DeclareOpInterfaceMethods<SymbolUserOpInterface>,
+]> {
+  let summary = "Call a coroutine";
+  let description = [{
+    The `llhd.call_coroutine` op calls an `llhd.coroutine`. The calling process
+    or coroutine suspends until the callee returns. This is only valid inside a
+    process or another coroutine.
+
+    Example:
+    ```mlir
+    llhd.call_coroutine @waitForClk(%clk) : (!llhd.ref<i1>) -> ()
+    ```
+  }];
+
+  let arguments = (ins FlatSymbolRefAttr:$callee, Variadic<AnyType>:$operands);
+  let results = (outs Variadic<AnyType>);
+
+  let assemblyFormat = [{
+    $callee `(` $operands `)` attr-dict `:` functional-type(operands, results)
+  }];
+
+  let builders = [
+    OpBuilder<(ins "CoroutineOp":$coroutine,
+                   CArg<"mlir::ValueRange", "{}">:$operands), [{
+      build($_builder, $_state, coroutine.getFunctionType().getResults(),
+            mlir::SymbolRefAttr::get(coroutine), operands);
+    }]>,
+  ];
+
+  let extraClassDeclaration = [{
+    operand_range getArgOperands() {
+      return getOperands();
+    }
+    MutableOperandRange getArgOperandsMutable() {
+      return getOperandsMutable();
+    }
+
+    mlir::CallInterfaceCallable getCallableForCallee() {
+      return (*this)->getAttrOfType<mlir::SymbolRefAttr>("callee");
+    }
+
+    void setCalleeFromCallable(mlir::CallInterfaceCallable callee) {
+      (*this)->setAttr(getCalleeAttrName(),
+                       llvm::cast<mlir::SymbolRefAttr>(callee));
+    }
+
+    /// CallOpInterface requires ArgAndResultAttrsOpInterface, which needs
+    /// methods to get/set per-argument and per-result attributes. Call sites
+    /// don't carry these attributes, so we stub them out as no-ops.
+    mlir::ArrayAttr getArgAttrsAttr() { return nullptr; }
+    mlir::ArrayAttr getResAttrsAttr() { return nullptr; }
+    void setArgAttrsAttr(mlir::ArrayAttr args) {}
+    void setResAttrsAttr(mlir::ArrayAttr args) {}
+    mlir::Attribute removeArgAttrsAttr() { return nullptr; }
+    mlir::Attribute removeResAttrsAttr() { return nullptr; }
+  }];
+}
+
+def ReturnOp : LLHDOp<"return", [
+  HasParent<"CoroutineOp">,
+  Terminator,
+]> {
+  let summary = "Return from a coroutine";
+  let description = [{
+    The `llhd.return` op terminates execution of the enclosing
+    `llhd.coroutine` and returns control to the caller. It is the coroutine
+    equivalent of `llhd.halt` for processes.
+
+    Example:
+    ```mlir
+    llhd.coroutine @myTask() {
+      llhd.return
+    }
+    ```
+  }];
+  let arguments = (ins Variadic<AnyType>:$operands);
+  let assemblyFormat = [{
+    ($operands^ `:` type($operands))?
+    attr-dict
+  }];
+}
+
 #endif // CIRCT_DIALECT_LLHD_LLHDOPS_TD

lib/Dialect/LLHD/IR/LLHDOps.cpp

@@ -19,6 +19,7 @@
 #include "mlir/IR/Region.h"
 #include "mlir/IR/Types.h"
 #include "mlir/IR/Value.h"
+#include "mlir/Interfaces/FunctionImplementation.h"
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/SmallVector.h"
 
@@ -919,6 +920,67 @@ GetGlobalSignalOp::verifySymbolUses(SymbolTableCollection &symbolTable) {
   return success();
 }
 
+//===----------------------------------------------------------------------===//
+// CoroutineOp
+//===----------------------------------------------------------------------===//
+
+ParseResult CoroutineOp::parse(OpAsmParser &parser, OperationState &result) {
+  auto buildFuncType =
+      [](Builder &builder, ArrayRef<Type> argTypes, ArrayRef<Type> results,
+         function_interface_impl::VariadicFlag,
+         std::string &) { return builder.getFunctionType(argTypes, results); };
+
+  return function_interface_impl::parseFunctionOp(
+      parser, result, /*allowVariadic=*/false,
+      getFunctionTypeAttrName(result.name), buildFuncType,
+      getArgAttrsAttrName(result.name), getResAttrsAttrName(result.name));
+}
+
+void CoroutineOp::print(OpAsmPrinter &p) {
+  function_interface_impl::printFunctionOp(
+      p, *this, /*isVariadic=*/false, getFunctionTypeAttrName(),
+      getArgAttrsAttrName(), getResAttrsAttrName());
+}
+
+//===----------------------------------------------------------------------===//
+// CallCoroutineOp
+//===----------------------------------------------------------------------===//
+
+LogicalResult
+CallCoroutineOp::verifySymbolUses(SymbolTableCollection &symbolTable) {
+  auto calleeName = getCalleeAttr();
+  auto coroutine =
+      symbolTable.lookupNearestSymbolFrom<CoroutineOp>(*this, calleeName);
+  if (!coroutine)
+    return emitOpError() << "'" << calleeName.getValue()
+                         << "' does not reference a valid 'llhd.coroutine'";
+
+  auto type = coroutine.getFunctionType();
+  if (type.getNumInputs() != getNumOperands())
+    return emitOpError() << "has " << getNumOperands()
+                         << " operands, but callee expects "
+                         << type.getNumInputs();
+
+  for (unsigned i = 0, e = type.getNumInputs(); i != e; ++i)
+    if (getOperand(i).getType() != type.getInput(i))
+      return emitOpError() << "operand " << i << " type mismatch: expected "
+                           << type.getInput(i) << ", got "
+                           << getOperand(i).getType();
+
+  if (type.getNumResults() != getNumResults())
+    return emitOpError() << "has " << getNumResults()
+                         << " results, but callee returns "
+                         << type.getNumResults();
+
+  for (unsigned i = 0, e = type.getNumResults(); i != e; ++i)
+    if (getResult(i).getType() != type.getResult(i))
+      return emitOpError() << "result " << i << " type mismatch: expected "
+                           << type.getResult(i) << ", got "
+                           << getResult(i).getType();
+
+  return success();
+}
+
 //===----------------------------------------------------------------------===//
 // Auto-Generated Implementations
 //===----------------------------------------------------------------------===//

test/Dialect/LLHD/IR/basic.mlir

@@ -238,3 +238,34 @@ llhd.global_signal @GlobalSig2 : i42 init {
 
 // CHECK: llhd.get_global_signal @GlobalSig2 : <i42>
 llhd.get_global_signal @GlobalSig2 : <i42>
+
+// CHECK-LABEL: llhd.coroutine @myCoroutine(%arg0: !llhd.ref<i1>)
+llhd.coroutine @myCoroutine(%arg0: !llhd.ref<i1>) {
+  // CHECK-NEXT: llhd.return
+  llhd.return
+}
+
+// CHECK-LABEL: llhd.coroutine private @privateCoroutine()
+llhd.coroutine private @privateCoroutine() {
+  llhd.return
+}
+
+// Coroutines can contain wait, halt, and call_coroutine.
+// CHECK-LABEL: llhd.coroutine @coroutineWithWaitAndHalt
+llhd.coroutine @coroutineWithWaitAndHalt(%arg0: !llhd.ref<i1>, %arg1: i1) {
+  // CHECK: llhd.call_coroutine @myCoroutine(%arg0) : (!llhd.ref<i1>) -> ()
+  llhd.call_coroutine @myCoroutine(%arg0) : (!llhd.ref<i1>) -> ()
+  // CHECK: llhd.wait
+  llhd.wait (%arg1 : i1), ^bb1
+^bb1:
+  // CHECK: llhd.halt
+  llhd.halt
+}
+
+hw.module @coroutineCallFromProcess(in %clk: !llhd.ref<i1>) {
+  llhd.process {
+    // CHECK: llhd.call_coroutine @myCoroutine(%clk) : (!llhd.ref<i1>) -> ()
+    llhd.call_coroutine @myCoroutine(%clk) : (!llhd.ref<i1>) -> ()
+    llhd.halt
+  }
+}

test/Dialect/LLHD/IR/errors.mlir

@@ -123,3 +123,30 @@ llhd.global_signal @Foo : i9001
 llhd.global_signal @Foo : i42 init {
   llvm.unreachable
 }
+
+// -----
+
+llhd.coroutine @caller() {
+  // expected-error @below {{'nonexistent' does not reference a valid 'llhd.coroutine'}}
+  llhd.call_coroutine @nonexistent() : () -> ()
+  llhd.return
+}
+
+// -----
+
+func.func @notACoroutine() { return }
+llhd.coroutine @callerCoroutine() {
+  // expected-error @below {{'notACoroutine' does not reference a valid 'llhd.coroutine'}}
+  llhd.call_coroutine @notACoroutine() : () -> ()
+  llhd.return
+}
+
+// -----
+
+// A func.func cannot call an llhd.coroutine via func.call.
+llhd.coroutine @someCoroutine() { llhd.return }
+func.func @funcCallingCoroutine() {
+  // expected-error @below {{'someCoroutine' does not reference a valid function}}
+  func.call @someCoroutine() : () -> ()
+  return
+}