Add sv.verbatim.source and sv.verbatim.module ops for inline black box extmodules (#9227)

A second attempt of #9131. Changes from the first PR were made in order to
support parametrized black boxes. Because parameters can affect the port
interface of a module, we need two ops:

1. sv.verbatim.source to represent the shared verbatim definition of a module
2. sv.verbatim.module to represent a particular parametrization of that module
   that can be instantiated

The pipeline is largely the same:

- BlackBoxInlineAnno and BlackBoxPathAnno are converted to VerbatimBlackBoxAnno
  by BlackBoxReader for consumption by LowerToHW.

- LowerToHW will lower firrtl.extmodules with a VerbatimBlackBoxAnno to a
  sv.verbatim.source (only one per file) and a sv.verbatim.module.

Author: tmckay-sifive

docs/Dialects/FIRRTL/FIRRTLAnnotations.md

@@ -305,6 +305,38 @@ Example:
 }
 ```
 
+### VerbatimBlackBoxAnno
+
+| Property   | Type   | Description                          |
+| ---------- | ------ | -------------                        |
+| class      | string | `circt.VerbatimBlackBoxAnno`         |
+| target     | string | An ExtModule name target             |
+| files      | array  | Array of file objects                |
+
+Specifies verbatim black box source code with one or more files. Each file
+object in the `files` array contains:
+
+- `content`: The literal source code content
+- `output_file`: Path to the output file
+
+This annotation is used internally by CIRCT to represent partially lowered
+FIRRTL extmodules with verbatim content.
+
+Example:
+
+```json
+{
+  "class": "circt.VerbatimBlackBoxAnno",
+  "target": "~Foo|MyBlackBox",
+  "files": [
+    {
+      "content": "module MyBlackBox(\n  input clk,\n  output out\n);\n  assign out = clk;\nendmodule",
+      "output_file": "blackbox.v"
+    }
+  ]
+}
+```
+
 ### Convention
 
 | Property   | Type   | Description                             |

include/circt/Dialect/FIRRTL/AnnotationDetails.h

@@ -58,6 +58,7 @@ constexpr const char *blackBoxTargetDirAnnoClass =
     "firrtl.transforms.BlackBoxTargetDirAnno";
 constexpr const char *blackBoxAnnoClass =
     "firrtl.transforms.BlackBox"; // Not in SFC
+constexpr const char *verbatimBlackBoxAnnoClass = "circt.VerbatimBlackBoxAnno";
 constexpr const char *mustDedupAnnoClass =
     "firrtl.transforms.MustDeduplicateAnnotation";
 constexpr const char *runFIRRTLTransformAnnoClass =

include/circt/Dialect/SV/SVTypeDecl.td

@@ -11,6 +11,8 @@
 //===----------------------------------------------------------------------===//
 
 include "circt/Dialect/HW/HWOpInterfaces.td"
+include "circt/Dialect/HW/HWTypes.td"
+include "circt/Dialect/HW/HWAttributes.td"
 include "mlir/IR/EnumAttr.td"
 
 //===----------------------------------------------------------------------===//
@@ -206,6 +208,89 @@ def ModportType : SVType<"Modport"> {
   let assemblyFormat = "`<` $modport `>`";
 }
 
+//===----------------------------------------------------------------------===//
+// Verbatim source operation
+//===----------------------------------------------------------------------===//
+
+def SVVerbatimSourceOp
+    : SVOp<"verbatim.source", [Symbol, HasParent<"mlir::ModuleOp">,
+                               DeclareOpInterfaceMethods<SymbolUserOpInterface>]> {
+  let summary = "Verbatim verilog source";
+  let description = [{
+    The "sv.verbatim.source" operation represents verbatim verilog definition for
+    a module which may have parameters. Concrete parametrizations and their ports
+    are represented by a `hw.module.extern`.
+  }];
+
+  let arguments = (ins SymbolNameAttr:$sym_name,
+      StrAttr:$content,
+      OutputFileAttr:$output_file,
+      ParamDeclArrayAttr:$parameters,
+      OptionalAttr<SymbolRefArrayAttr>:$additional_files,
+      StrAttr:$verilogName);
+
+  let hasCustomAssemblyFormat = 1;
+
+  let hasVerifier = 1;
+}
+
+//===----------------------------------------------------------------------===//
+// Verbatim module operation
+//===----------------------------------------------------------------------===//
+
+def SVVerbatimModuleOp
+    : SVOp<"verbatim.module", [DeclareOpInterfaceMethods<PortList>,
+                               DeclareOpInterfaceMethods<HWModuleLike>, Symbol,
+                               DeclareOpInterfaceMethods<SymbolUserOpInterface>,
+                               HasParent<"mlir::ModuleOp">]> {
+  let summary = "Verbatim verilog module";
+  let description = [{
+    The "sv.verbatim.module" operation represents a the module interface of a
+    verbatim verilog module. It references an "sv.verbatim.source" operation
+    that contains the actual verilog source code.
+  }];
+
+  let arguments = (ins SymbolNameAttr:$sym_name,
+      TypeAttrOf<ModuleType>:$module_type,
+      OptionalAttr<DictArrayAttr>:$per_port_attrs,
+      OptionalAttr<LocationArrayAttr>:$port_locs,
+      ParamDeclArrayAttr:$parameters,
+      FlatSymbolRefAttr:$source,
+      OptionalAttr<StrAttr>:$verilogName);
+
+  let results = (outs);
+
+  let hasCustomAssemblyFormat = 1;
+
+  let builders = [
+    OpBuilder<(ins "StringAttr":$name,
+                   "ArrayRef<hw::PortInfo>":$ports,
+                   "FlatSymbolRefAttr":$source,
+                   CArg<"ArrayAttr", "{}">:$parameters,
+                   CArg<"StringAttr", "{}">:$verilogName), [{
+      SmallVector<hw::ModulePort> modulePorts;
+      SmallVector<Attribute> portAttrs, portLocs;
+      for (const auto &port : ports) {
+        Type portType = port.type;
+        hw::ModulePort::Direction portDir = port.dir;
+        if (auto inoutType = dyn_cast<hw::InOutType>(port.type)) {
+          portType = inoutType.getElementType();
+          portDir = hw::ModulePort::Direction::InOut;
+        }
+        modulePorts.push_back({port.name, portType, portDir});
+        portAttrs.push_back(port.attrs ? port.attrs : $_builder.getDictionaryAttr({}));
+        portLocs.push_back(port.loc ? static_cast<Location>(port.loc) : $_builder.getUnknownLoc());
+      }
+      auto moduleType = hw::ModuleType::get($_builder.getContext(), modulePorts);
+      build($_builder, $_state, name, TypeAttr::get(moduleType),
+            $_builder.getArrayAttr(portAttrs), $_builder.getArrayAttr(portLocs),
+            parameters, source, verilogName);
+    }]>
+  ];
+
+  let hasVerifier = 1;
+}
+
 //===----------------------------------------------------------------------===//
 // Other operations
 //===----------------------------------------------------------------------===//

include/circt/Dialect/SV/SVVisitors.h

@@ -43,10 +43,10 @@ class Visitor {
             FWriteOp, FFlushOp, SystemFunctionOp, VerbatimOp, MacroRefOp,
             FuncCallOp, FuncCallProceduralOp, ReturnOp, IncludeOp, MacroErrorOp,
             // Type declarations.
-            InterfaceOp, InterfaceSignalOp, InterfaceModportOp,
-            InterfaceInstanceOp, GetModportOp, AssignInterfaceSignalOp,
-            ReadInterfaceSignalOp, MacroDeclOp, MacroDefOp, FuncOp,
-            FuncDPIImportOp,
+            InterfaceOp, SVVerbatimSourceOp, InterfaceSignalOp,
+            InterfaceModportOp, InterfaceInstanceOp, GetModportOp,
+            AssignInterfaceSignalOp, ReadInterfaceSignalOp, MacroDeclOp,
+            MacroDefOp, FuncOp, FuncDPIImportOp,
             // Verification statements.
             AssertOp, AssumeOp, CoverOp, AssertConcurrentOp, AssumeConcurrentOp,
             CoverConcurrentOp, AssertPropertyOp, AssumePropertyOp,
@@ -147,6 +147,7 @@ class Visitor {
 
   // Type declarations.
   HANDLE(InterfaceOp, Unhandled);
+  HANDLE(SVVerbatimSourceOp, Unhandled);
   HANDLE(InterfaceInstanceOp, Unhandled);
   HANDLE(InterfaceSignalOp, Unhandled);
   HANDLE(InterfaceModportOp, Unhandled);

integration_test/Bindings/Python/dialects/sv_verbatim.py

@@ -0,0 +1,88 @@
+# REQUIRES: bindings_python
+# RUN: %PYTHON% %s | FileCheck %s
+
+import circt
+from circt.dialects import hw, sv, emit
+from circt import ir
+
+with ir.Context() as ctx, ir.Location.unknown():
+  circt.register_dialects(ctx)
+
+  i1 = ir.IntegerType.get_signless(1)
+  i8 = ir.IntegerType.get_signless(8)
+  i32 = ir.IntegerType.get_signless(32)
+
+  m = ir.Module.create()
+  with ir.InsertionPoint(m.body):
+    verbatim_content = "module MyVerbatim(input clk, output reg out); always @(posedge clk) out <= ~out; endmodule"
+    verbatim_source = sv.SVVerbatimSourceOp(
+        sym_name="MyVerbatim.v",
+        content=verbatim_content,
+        output_file=hw.OutputFileAttr.get_from_filename(
+            ir.StringAttr.get("MyVerbatim.v"), False, False),
+        verilog_name="MyVerbatim")
+
+    # CHECK:      sv.verbatim.source @MyVerbatim.v
+    # CHECK-SAME:   attributes {
+    # CHECK-SAME:     content = "module MyVerbatim(input clk, output reg out); always @(posedge clk) out <= ~out; endmodule",
+    # CHECK-SAME:     output_file = #hw.output_file<"MyVerbatim.v">,
+    # CHECK-SAME:     verilogName = "MyVerbatim"
+    # CHECK-SAME:   }
+    print(verbatim_source)
+
+    verbatim_module = sv.SVVerbatimModuleOp(
+        name="MyVerbatim",
+        source=ir.FlatSymbolRefAttr.get("MyVerbatim.v"),
+        input_ports=[("clk", i1)],
+        output_ports=[("out", i1)],
+        verilog_name="MyVerbatim")
+
+    # CHECK:      sv.verbatim.module @MyVerbatim
+    # CHECK-SAME:   (in %clk : i1, out out : i1)
+    # CHECK-SAME    attributes {
+    # CHECK-SAME:     source = @MyVerbatim.v,
+    # CHECK-SAME:     verilogName = "MyVerbatim"
+    # CHECK-SAME:   }
+    print(verbatim_module)
+
+    param = hw.ParamDeclAttr.get("WIDTH", i32, ir.IntegerAttr.get(i32, 8))
+    parameters = ir.ArrayAttr.get([param])
+
+    param_verbatim_source = sv.SVVerbatimSourceOp(
+        sym_name="ParametrizedVerbatim.v",
+        content=
+        "module ParametrizedVerbatim #(parameter int WIDTH = 8)(); endmodule",
+        output_file=hw.OutputFileAttr.get_from_filename(
+            ir.StringAttr.get("ParametrizedVerbatim.v"), False, False),
+        parameters=parameters,
+        verilog_name="ParametrizedVerbatim")
+
+    # CHECK:      sv.verbatim.source @ParametrizedVerbatim.v
+    # CHECK-SAME:   <WIDTH: i32 = 8>
+    # CHECK-SAME:   attributes {
+    # CHECK-SAME:     content = "module ParametrizedVerbatim #(parameter int WIDTH = 8)(); endmodule",
+    # CHECK-SAME:     output_file = #hw.output_file<"ParametrizedVerbatim.v">,
+    # CHECK-SAME:     verilogName = "ParametrizedVerbatim"
+    # CHECK-SAME:   }
+    print(param_verbatim_source)
+
+    # Test parametrized verbatim module
+    param_verbatim_module = sv.SVVerbatimModuleOp(
+        name="ParametrizedVerbatim",
+        source=ir.FlatSymbolRefAttr.get("ParametrizedVerbatim.v"),
+        input_ports=[("data_in", i8)],
+        output_ports=[("data_out", i8)],
+        parameters=[param],
+        verilog_name="ParametrizedVerbatim")
+
+    # CHECK:      sv.verbatim.module @ParametrizedVerbatim
+    # CHECK-SAME:   <WIDTH: i32 = 8>
+    # CHECK-SAME    (in %data_in : i8, out data_out : i8)
+    # CHECK-SAME:   attributes {
+    # CHECK-SAME:     source = @ParametrizedVerbatim.v,
+    # CHECK-SAME:     verilogName = "ParametrizedVerbatim"
+    # CHECK-SAME:   }
+    print(param_verbatim_module)
+
+  print("=== SV Verbatim Operations Test Completed ===")
+  # CHECK: === SV Verbatim Operations Test Completed ===

lib/Bindings/Python/dialects/sv.py

@@ -10,7 +10,7 @@
 from ._sv_ops_gen import *
 from ._sv_ops_gen import _Dialect
 
-from typing import List
+from typing import List, Optional
 
 
 @_ods_cext.register_operation(_Dialect, replace=True)
@@ -109,3 +109,109 @@ def create(value):
     value = support.get_value(value)
     type = support.get_self_or_inner(value.type).element_type
     return sv.ReadInOutOp(value)
+
+
+@_ods_cext.register_operation(_Dialect, replace=True)
+class SVVerbatimSourceOp(SVVerbatimSourceOp):
+
+  def __init__(self,
+               sym_name,
+               content,
+               output_file,
+               *,
+               parameters=None,
+               additional_files=None,
+               verilog_name=None,
+               loc=None,
+               ip=None):
+    attributes = {}
+    attributes["sym_name"] = StringAttr.get(str(sym_name))
+    attributes["content"] = StringAttr.get(str(content))
+    attributes["output_file"] = output_file
+
+    if parameters is not None:
+      attributes["parameters"] = parameters
+    else:
+      attributes["parameters"] = ArrayAttr.get([])
+
+    if additional_files is not None:
+      attributes["additional_files"] = additional_files
+
+    if verilog_name is not None:
+      attributes["verilogName"] = StringAttr.get(str(verilog_name))
+    else:
+      # Default to using the symbol name without file extension
+      name = str(sym_name)
+      if name.endswith('.v'):
+        attributes["verilogName"] = StringAttr.get(name[:-2])
+      else:
+        attributes["verilogName"] = StringAttr.get(name)
+
+    OpView.__init__(
+        self,
+        self.build_generic(attributes=attributes,
+                           results=[],
+                           operands=[],
+                           successors=None,
+                           regions=0,
+                           loc=loc,
+                           ip=ip))
+
+
+@_ods_cext.register_operation(_Dialect, replace=True)
+class SVVerbatimModuleOp(SVVerbatimModuleOp):
+
+  def __init__(self,
+               name,
+               source,
+               input_ports=[],
+               output_ports=[],
+               *,
+               parameters=None,
+               verilog_name=None,
+               attributes={},
+               loc=None,
+               ip=None):
+    attributes = dict(attributes)
+    attributes["source"] = source
+
+    if parameters is not None:
+      attributes["parameters"] = parameters
+    else:
+      attributes["parameters"] = ArrayAttr.get([])
+
+    if verilog_name is not None:
+      attributes["verilogName"] = StringAttr.get(str(verilog_name))
+
+    hw.ModuleLike.init(self,
+                       name,
+                       input_ports,
+                       output_ports,
+                       parameters=parameters if parameters is not None else [],
+                       attributes=attributes,
+                       body_builder=None,
+                       loc=loc,
+                       ip=ip)
+
+  def instantiate(self, *args, **kwargs):
+    return hw.ModuleLike.instantiate(self, *args, **kwargs)
+
+  @property
+  def type(self):
+    return hw.ModuleLike.type(self)
+
+  @property
+  def name(self):
+    return hw.ModuleLike.name(self)
+
+  @property
+  def is_external(self):
+    return True
+
+  @property
+  def parameters(self) -> list[hw.ParamDeclAttr]:
+    return hw.ModuleLike.parameters(self)
+
+
+VerbatimSourceOp = SVVerbatimSourceOp
+VerbatimModuleOp = SVVerbatimModuleOp