[Emit] Organize output files using the emit dialect (#6727)

docs/Dialects/Emit/RationaleEmit.md

@@ -0,0 +1,22 @@
+# Emission (Emit) Dialect Rationale
+
+This document describes various design points of the `emit` dialect, why it is
+the way it is, and current status. This follows in the spirit of other [MLIR
+Rationale docs](https://mlir.llvm.org/docs/Rationale/).
+
+## Introduction
+
+The `emit` dialects controls the structure and formatting of the files emitted
+from CIRCT. It captures information about both SystemVerilog output files and
+generic collateral files. The ops are translated to output files in
+`ExportVerilog`. Presently, the dialect is intertwined with SystemVerilog -
+it can reference items in a design through symbols to emit references to
+them through SystemVerilog names in the output.
+
+## Operations
+
+The dialect is centred around the `emit.file` operation which groups a list
+of statements in its body, responsible for producing the contents of the file.
+The `emit.file_list` operation pins down a list of references to emitted files
+and outputs a file list file enumerating the paths to them.
+Together, these operations represent the SV and collateral output of CIRCT.

docs/Dialects/Emit/_index.md

@@ -0,0 +1,3 @@
+# 'emit' Dialect
+
+[include "Dialects/Emit.md"]

include/circt/Dialect/CMakeLists.txt

@@ -11,6 +11,7 @@ add_subdirectory(Calyx)
 add_subdirectory(Comb)
 add_subdirectory(DC)
 add_subdirectory(Debug)
+add_subdirectory(Emit)
 add_subdirectory(ESI)
 add_subdirectory(FIRRTL)
 add_subdirectory(FSM)

include/circt/Dialect/Emit/CMakeLists.txt

@@ -0,0 +1,14 @@
+##===- CMakeLists.txt - Emit dialect build definitions --------*- cmake -*-===//
+##
+## 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
+##
+##===----------------------------------------------------------------------===//
+##
+##
+##===----------------------------------------------------------------------===//
+
+add_circt_dialect(Emit emit)
+add_circt_dialect_doc(Emit emit)
+add_dependencies(circt-headers MLIREmitIncGen)

include/circt/Dialect/Emit/Emit.td

@@ -0,0 +1,24 @@
+//===- Emit.td - Emit dialect definition -------------------*- tablegen -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// This is the top level file for the `emit` dialect.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef CIRCT_DIALECT_EMIT_EMIT_TD
+#define CIRCT_DIALECT_EMIT_EMIT_TD
+
+include "mlir/IR/AttrTypeBase.td"
+include "mlir/IR/OpBase.td"
+include "mlir/IR/OpAsmInterface.td"
+include "mlir/IR/SymbolInterfaces.td"
+
+include "circt/Dialect/Emit/EmitDialect.td"
+include "circt/Dialect/Emit/EmitOps.td"
+
+#endif // CIRCT_DIALECT_EMIT_EMIT_TD

include/circt/Dialect/Emit/EmitDialect.h

@@ -0,0 +1,22 @@
+//===- EmitDialect.h - Emit dialect declaration -----------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// This file defines an `emit` MLIR dialect.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef CIRCT_DIALECT_EMIT_EMITDIALECT_H
+#define CIRCT_DIALECT_EMIT_EMITDIALECT_H
+
+#include "circt/Dialect/HW/HWAttributes.h"
+#include "circt/Support/LLVM.h"
+#include "mlir/IR/Dialect.h"
+
+#include "circt/Dialect/Emit/EmitDialect.h.inc"
+
+#endif // CIRCT_DIALECT_EMIT_EMITDIALECT_H

include/circt/Dialect/Emit/EmitDialect.td

@@ -0,0 +1,28 @@
+//===- EmitDialect.td - Emit dialect definition ------------*- tablegen -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// This contains the EmitDialect definition to be included in other files.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef CIRCT_DIALECT_EMIT_EMITDIALECT
+#define CIRCT_DIALECT_EMIT_EMITDIALECT
+
+def EmitDialect : Dialect {
+  let name = "emit";
+  let cppNamespace = "::circt::emit";
+
+  let summary = "Types and operations for the `emit` dialect";
+  let description = [{
+    The `emit` dialect is intended to model the structure of the emitted RTL.
+
+    It organizes the files, file lists, directories and collateral.
+  }];
+}
+
+#endif // CIRCT_DIALECT_EMIT_EMITDIALECT

include/circt/Dialect/Emit/EmitOps.h

@@ -0,0 +1,28 @@
+//===- EmitOps.h - Declare Emit dialect operations --------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// This file declares the operation classes for the Emit dialect.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef CIRCT_DIALECT_EMIT_EMITOPS_H
+#define CIRCT_DIALECT_EMIT_EMITOPS_H
+
+#include "mlir/Bytecode/BytecodeOpInterface.h"
+#include "mlir/IR/OpImplementation.h"
+#include "mlir/IR/SymbolTable.h"
+
+#include "circt/Dialect/Emit/EmitDialect.h"
+#include "circt/Dialect/Seq/SeqDialect.h"
+#include "circt/Dialect/Seq/SeqTypes.h"
+#include "circt/Support/BuilderUtils.h"
+
+#define GET_OP_CLASSES
+#include "circt/Dialect/Emit/Emit.h.inc"
+
+#endif // CIRCT_DIALECT_EMIT_EMITOPS_H

include/circt/Dialect/Emit/EmitOps.td

@@ -0,0 +1,112 @@
+//===- EmitOps.td - `emit` dialect ops ---------------------*- tablegen -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// This describes the MLIR ops for `emit`.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef CIRCT_DIALECT_EMIT_EMITOPS_TD
+#define CIRCT_DIALECT_EMIT_EMITOPS_TD
+
+include "circt/Dialect/Emit/EmitDialect.td"
+include "mlir/IR/OpAsmInterface.td"
+
+class EmitOp<string mnemonic, list<Trait> traits = []> :
+    Op<EmitDialect, mnemonic, traits>;
+
+def FileOp : EmitOp<"file", [
+    Symbol,
+    SingleBlock,
+    NoTerminator,
+    NoRegionArguments,
+    IsolatedFromAbove
+]> {
+  let summary = "Represents the contents of an emitted file";
+
+  let description = [{
+    This operation groups a set of nested operations to be emitted to a file.
+
+    Other operations (such as file lists)can reference a file to access its
+    filename through an optional symbol.
+  }];
+
+  let regions = (region SizedRegion<1>:$body);
+  let arguments = (ins
+    StrAttr:$file_name,
+    OptionalAttr<SymbolNameAttr>:$sym_name
+  );
+  let results = (outs);
+
+  let assemblyFormat = "$file_name (`sym` $sym_name^)? $body attr-dict";
+
+  let skipDefaultBuilders = 1;
+  let builders = [
+    // Creates a file with a callback. While the callback is executed, the
+    // insertion point of the builder is moved inside the body of the file op.
+    OpBuilder<(ins "StringRef":$fileName, "StringRef":$symName,
+                    CArg<"llvm::function_ref<void()>">:$bodyCtor)>,
+    OpBuilder<(ins "StringRef":$fileName,
+                    CArg<"llvm::function_ref<void()>">:$bodyCtor)>,
+  ];
+
+  let extraClassDeclaration = [{
+    // SymbolOpInterface
+    static bool isOptionalSymbol() { return true; }
+
+    // Utilities
+    Block *getBodyBlock() { return &getBodyRegion().front(); }
+  }];
+}
+
+def VerbatimOp : EmitOp<"verbatim", [HasParent<"circt::emit::FileOp">]> {
+  let summary = "Verbatim opaque text emitted inline.";
+  let description = [{
+    This operation produces opaque text inline in the file.
+
+    `emit.verbatim` allows symbol reference substitutions with {{0}} syntax.
+  }];
+
+  let arguments = (ins
+    StrAttr:$text
+  );
+
+  let assemblyFormat = [{
+    $text attr-dict
+  }];
+}
+
+
+def FileListOp : EmitOp<"file_list", [
+    Symbol,
+    DeclareOpInterfaceMethods<SymbolUserOpInterface>
+]> {
+  let summary = "Represents a file list";
+
+  let description = [{
+    This operation emits a file list referencing a set of files.
+
+    File lists can be references from other ops (including other file lists)
+    through an optional symbol.
+  }];
+
+  let arguments = (ins
+    StrAttr:$file_name,
+    FlatSymbolRefArrayAttr:$files,
+    OptionalAttr<SymbolNameAttr>:$sym_name
+  );
+  let results = (outs);
+
+  let assemblyFormat = "$file_name `,` $files (`sym` $sym_name^)? attr-dict";
+
+  let extraClassDeclaration = [{
+    // SymbolOpInterface
+    static bool isOptionalSymbol() { return true; }
+  }];
+}
+
+#endif // CIRCT_DIALECT_EMIT_EMITOPS_TD

include/circt/InitAllDialects.h

@@ -20,6 +20,7 @@
 #include "circt/Dialect/DC/DCDialect.h"
 #include "circt/Dialect/Debug/DebugDialect.h"
 #include "circt/Dialect/ESI/ESIDialect.h"
+#include "circt/Dialect/Emit/EmitDialect.h"
 #include "circt/Dialect/FIRRTL/CHIRRTLDialect.h"
 #include "circt/Dialect/FIRRTL/FIRRTLDialect.h"
 #include "circt/Dialect/FSM/FSMOps.h"
@@ -55,6 +56,7 @@ inline void registerAllDialects(mlir::DialectRegistry &registry) {
     comb::CombDialect,
     dc::DCDialect,
     debug::DebugDialect,
+    emit::EmitDialect,
     esi::ESIDialect,
     firrtl::FIRRTLDialect,
     fsm::FSMDialect,

lib/Dialect/CMakeLists.txt

@@ -14,6 +14,7 @@ add_subdirectory(Calyx)
 add_subdirectory(Comb)
 add_subdirectory(DC)
 add_subdirectory(Debug)
+add_subdirectory(Emit)
 add_subdirectory(ESI)
 add_subdirectory(FIRRTL)
 add_subdirectory(FSM)

lib/Dialect/Emit/CMakeLists.txt

@@ -0,0 +1,30 @@
+##===- CMakeLists.txt - build definitions for Emit ------------*- cmake -*-===//
+##
+## 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
+##
+##===----------------------------------------------------------------------===//
+##
+##
+##===----------------------------------------------------------------------===//
+
+add_circt_dialect_library(CIRCTEmit
+  EmitDialect.cpp
+  EmitOps.cpp
+
+  ADDITIONAL_HEADER_DIRS
+  ${CIRCT_MAIN_INCLUDE_DIR}/circt/Dialect/Emit
+
+  DEPENDS
+  MLIREmitIncGen
+
+  LINK_COMPONENTS
+  Support
+
+  LINK_LIBS PUBLIC
+  CIRCTHW
+  MLIRIR
+  MLIRPass
+  MLIRTransforms
+)

lib/Dialect/Emit/EmitDialect.cpp

@@ -0,0 +1,34 @@
+//===- EmitDialect.cpp - Implement the Emit dialect -----------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// This file implements the Emit dialect.
+//
+//===----------------------------------------------------------------------===//
+
+#include "circt/Dialect/Emit/EmitDialect.h"
+#include "circt/Dialect/Emit/EmitOps.h"
+#include "circt/Dialect/HW/HWOps.h"
+#include "mlir/IR/Builders.h"
+#include "mlir/IR/BuiltinTypes.h"
+#include "mlir/IR/DialectImplementation.h"
+
+using namespace circt;
+using namespace emit;
+
+//===----------------------------------------------------------------------===//
+// Dialect specification.
+//===----------------------------------------------------------------------===//
+
+void EmitDialect::initialize() {
+  addOperations<
+#define GET_OP_LIST
+#include "circt/Dialect/Emit/Emit.cpp.inc"
+      >();
+}
+
+#include "circt/Dialect/Emit/EmitDialect.cpp.inc"