[Emit] Group file header ops into emit.fragment

Instead of using the replicated op mechanism, fragments of SV code
which must precede certain modules are grouped into fragment ops.
Modules which rely on them reference them through a `emit.fragment`
attribute. The fragments are printed through ExportVerilog.

Subsequent PRs will fully replace replaced ops using fragments.

include/circt/Conversion/Passes.td

@@ -418,10 +418,17 @@ def LowerFIRRTLToHW : Pass<"lower-firrtl-to-hw", "mlir::ModuleOp"> {
     Lower a module of FIRRTL dialect to the HW dialect family.
   }];
   let constructor = "circt::createLowerFIRRTLToHWPass()";
-  let dependentDialects = ["comb::CombDialect", "hw::HWDialect",
-                           "seq::SeqDialect", "sv::SVDialect",
-                           "ltl::LTLDialect", "verif::VerifDialect",
-                           "sim::SimDialect"];
+
+  let dependentDialects = [
+    "comb::CombDialect",
+    "emit::EmitDialect",
+    "hw::HWDialect",
+    "ltl::LTLDialect",
+    "seq::SeqDialect",
+    "sim::SimDialect",
+    "sv::SVDialect",
+    "verif::VerifDialect",
+  ];
   let options = [
     Option<"enableAnnotationWarning", "warn-on-unprocessed-annotations",
            "bool", "false",

include/circt/Dialect/Emit/EmitOps.td

@@ -64,6 +64,43 @@ def FileOp : EmitOp<"file", [
   }];
 }
 
+def FragmentOp : EmitOp<"fragment", [
+    Symbol,
+    SingleBlock,
+    NoTerminator,
+    NoRegionArguments,
+    IsolatedFromAbove,
+    HasParent<"mlir::ModuleOp">
+]> {
+  let summary = "Emittable fragment which can be replicated before modules";
+  let description = [{
+    The fragment operation is a container for other operations that can
+    be emitted before other operations. It carries a symbol that can be
+    referenced by an `emit.fragments` attribute placed on operations before
+    which the fragments should be inserted.
+
+    In single-file mode, each fragment is emitted once. In split file emission
+    mode, fragments precede all operations that reference them, but are still
+    emitted at most once per file.
+  }];
+
+  let regions = (region SizedRegion<1>:$bodyRegion);
+  let arguments = (ins SymbolNameAttr:$sym_name);
+
+  let assemblyFormat = "$sym_name $bodyRegion attr-dict";
+
+  let skipDefaultBuilders = 1;
+  let builders = [
+    OpBuilder<(ins "StringRef":$symName,
+                    CArg<"llvm::function_ref<void()>", "{}">:$bodyCtor), [{
+      return build(
+          $_builder, $_state, $_builder.getStringAttr(symName), bodyCtor);
+    }]>,
+    OpBuilder<(ins "StringAttr":$symName,
+                    CArg<"llvm::function_ref<void()>", "{}">:$bodyCtor)>,
+  ];
+}
+
 def VerbatimOp : EmitOp<"verbatim", [HasParent<"circt::emit::FileOp">]> {
   let summary = "Verbatim opaque text emitted inline.";
   let description = [{

lib/Conversion/ExportVerilog/ExportVerilog.cpp

@@ -6039,16 +6039,22 @@ class FileEmitter : public EmitterBase {
 public:
   explicit FileEmitter(VerilogEmitterState &state) : EmitterBase(state) {}
 
-  void emit(emit::FileOp op);
+  void emit(emit::FileOp op) {
+    emit(op.getBody());
+    ps.eof();
+  }
+  void emit(emit::FragmentOp op) { emit(op.getBody()); }
   void emit(emit::FileListOp op);
 
 private:
+  void emit(Block *block);
+
   void emitOp(emit::RefOp op);
   void emitOp(emit::VerbatimOp op);
 };
 
-void FileEmitter::emit(emit::FileOp op) {
-  for (Operation &op : *op.getBody()) {
+void FileEmitter::emit(Block *block) {
+  for (Operation &op : *block) {
     TypeSwitch<Operation *>(&op)
         .Case<emit::VerbatimOp, emit::RefOp>([&](auto op) { emitOp(op); })
         .Case<VerbatimOp, IfDefOp, MacroDefOp>(
@@ -6057,7 +6063,6 @@ void FileEmitter::emit(emit::FileOp op) {
         .Default(
             [&](auto op) { emitOpError(op, "cannot be emitted to a file"); });
   }
-  ps.eof();
 }
 
 void FileEmitter::emit(emit::FileListOp op) {
@@ -6218,6 +6223,9 @@ void SharedEmitterState::gatherFiles(bool separateModules) {
           fileMapping.try_emplace(file.getSymNameAttr(), file);
           separateFile(file, file.getFileName());
         })
+        .Case<emit::FragmentOp>([&](auto fragment) {
+          fragmentMapping.try_emplace(fragment.getSymNameAttr(), fragment);
+        })
         .Case<HWModuleOp>([&](auto mod) {
           // Build the IR cache.
           auto sym = mod.getNameAttr();
@@ -6338,20 +6346,37 @@ void SharedEmitterState::collectOpsForFile(const FileInfo &file,
   size_t numReplicatedOps =
       file.emitReplicatedOps && !emitHeaderInclude ? replicatedOps.size() : 0;
 
-  thingsToEmit.reserve(thingsToEmit.size() + numReplicatedOps +
-                       file.ops.size());
-
   // Emit each operation in the file preceded by the replicated ops not yet
   // printed.
+  DenseSet<emit::FragmentOp> includedFragments;
   for (const auto &opInfo : file.ops) {
+    Operation *op = opInfo.op;
+
     // Emit the replicated per-file operations before the main operation's
     // position (if enabled).
     for (; lastReplicatedOp < std::min(opInfo.position, numReplicatedOps);
          ++lastReplicatedOp)
       thingsToEmit.emplace_back(replicatedOps[lastReplicatedOp]);
 
+    // Pull in the fragments that the op references. In one file, each
+    // fragment is emitted only once.
+    if (auto fragments = op->getAttrOfType<ArrayAttr>("emit.fragments")) {
+      for (auto sym : fragments.getAsRange<FlatSymbolRefAttr>()) {
+        auto it = fragmentMapping.find(sym.getAttr());
+        if (it == fragmentMapping.end()) {
+          encounteredError = true;
+          op->emitError("cannot find referenced fragment ") << sym;
+          continue;
+        }
+        emit::FragmentOp fragment = it->second;
+        if (includedFragments.insert(fragment).second) {
+          thingsToEmit.emplace_back(it->second);
+        }
+      }
+    }
+
     // Emit the operation itself.
-    thingsToEmit.emplace_back(opInfo.op);
+    thingsToEmit.emplace_back(op);
   }
 
   // Emit the replicated per-file operations after the last operation (if
@@ -6376,7 +6401,7 @@ static void emitOperation(VerilogEmitterState &state, Operation *op) {
       .Case<TypeScopeOp>([&](auto typedecls) {
         ModuleEmitter(state).emitStatement(typedecls);
       })
-      .Case<emit::FileOp, emit::FileListOp>(
+      .Case<emit::FileOp, emit::FileListOp, emit::FragmentOp>(
           [&](auto op) { FileEmitter(state).emit(op); })
       .Case<MacroDefOp>(
           [&](auto op) { ModuleEmitter(state).emitStatement(op); })

lib/Conversion/ExportVerilog/ExportVerilogInternals.h

@@ -10,6 +10,7 @@
 #define CONVERSION_EXPORTVERILOG_EXPORTVERILOGINTERNAL_H
 
 #include "circt/Dialect/Comb/CombVisitors.h"
+#include "circt/Dialect/Emit/EmitOps.h"
 #include "circt/Dialect/HW/HWOps.h"
 #include "circt/Dialect/HW/HWSymCache.h"
 #include "circt/Dialect/HW/HWVisitors.h"
@@ -328,6 +329,9 @@ class StringOrOpToEmit {
 /// Mapping from symbols to file operations.
 using FileMapping = DenseMap<StringAttr, Operation *>;
 
+/// Mapping from symbols to file operations.
+using FragmentMapping = DenseMap<StringAttr, emit::FragmentOp>;
+
 /// This class tracks the top-level state for the emitters, which is built and
 /// then shared across all per-file emissions that happen in parallel.
 struct SharedEmitterState {
@@ -369,6 +373,9 @@ struct SharedEmitterState {
   /// Tracks the referenceable files through their symbol.
   FileMapping fileMapping;
 
+  /// Tracks referenceable files through their symbol.
+  FragmentMapping fragmentMapping;
+
   explicit SharedEmitterState(ModuleOp designOp, const LoweringOptions &options,
                               GlobalNameTable globalNames)
       : designOp(designOp), options(options),

lib/Conversion/FIRRTLToHW/CMakeLists.txt

@@ -9,6 +9,7 @@ add_circt_conversion_library(CIRCTFIRRTLToHW
 
   LINK_LIBS PUBLIC
   CIRCTComb
+  CIRCTEmit
   CIRCTFIRRTL
   CIRCTHW
   CIRCTLTL