Add CIRCT standalone example

.github/workflows/unifiedBuildTestAndInstall.yml

@@ -389,7 +389,7 @@ jobs:
 
           # Run cmake.  Use one long line for `cmake` so that this works on
           # Linux/macOS AND Windows.
-          cmake -G Ninja -S "$(pwd)/../llvm/llvm" -DCMAKE_BUILD_TYPE=${{ inputs.cmake_build_type }} -DBUILD_SHARED_LIBS=${{ inputs.build_shared_libs }} -DLLVM_BUILD_TOOLS=ON -DLLVM_BUILD_EXAMPLES=OFF -DLLVM_ENABLE_ASSERTIONS=${{ inputs.llvm_enable_assertions }} -DLLVM_ENABLE_PROJECTS=mlir -DLLVM_EXTERNAL_PROJECTS=circt -DLLVM_EXTERNAL_CIRCT_SOURCE_DIR=".." -DLLVM_STATIC_LINK_CXX_STDLIB=ON -DLLVM_PARALLEL_LINK_JOBS=1 -DLLVM_TARGETS_TO_BUILD="host" -DLLVM_FORCE_ENABLE_STATS=ON -DLLVM_ENABLE_ZSTD=OFF -DCIRCT_RELEASE_TAG_ENABLED=ON -DCIRCT_RELEASE_TAG=firtool -DCMAKE_EXPORT_COMPILE_COMMANDS=OFF -DCMAKE_C_COMPILER=${{ steps.set-cmake-options.outputs.cmake_c_compiler }} -DCMAKE_CXX_COMPILER=${{ steps.set-cmake-options.outputs.cmake_cxx_compiler }} ${{ steps.configure-sccache.outputs.enable_sccache }} -DCMAKE_INSTALL_PREFIX="$(pwd)/../install" -DLLVM_INSTALL_UTILS=ON -DCIRCT_SLANG_FRONTEND_ENABLED=ON -DLLVM_LIT_ARGS="${{ steps.set-cmake-options.outputs.llvm_lit_args }}" ${{ steps.setup-linux.outputs.cmake }} ${{ steps.setup-macos.outputs.cmake }} ${{ steps.setup-macos-integration.outputs.cmake }} ${{ steps.setup-windows.outputs.cmake }} ${{ steps.integration-test-setup-generic.outputs.cmake }} ${{ inputs.extra_cmake_args }}
+          cmake -G Ninja -S "$(pwd)/../llvm/llvm" -DCMAKE_BUILD_TYPE=${{ inputs.cmake_build_type }} -DBUILD_SHARED_LIBS=${{ inputs.build_shared_libs }} -DLLVM_BUILD_TOOLS=ON -DLLVM_BUILD_EXAMPLES=OFF -DLLVM_ENABLE_ASSERTIONS=${{ inputs.llvm_enable_assertions }} -DLLVM_ENABLE_PROJECTS=mlir -DLLVM_EXTERNAL_PROJECTS=circt -DLLVM_EXTERNAL_CIRCT_SOURCE_DIR=".." -DLLVM_STATIC_LINK_CXX_STDLIB=ON -DLLVM_PARALLEL_LINK_JOBS=1 -DLLVM_TARGETS_TO_BUILD="host" -DLLVM_FORCE_ENABLE_STATS=ON -DLLVM_ENABLE_ZSTD=OFF -DCIRCT_RELEASE_TAG_ENABLED=ON -DCIRCT_RELEASE_TAG=firtool -DCMAKE_EXPORT_COMPILE_COMMANDS=OFF -DCMAKE_C_COMPILER=${{ steps.set-cmake-options.outputs.cmake_c_compiler }} -DCMAKE_CXX_COMPILER=${{ steps.set-cmake-options.outputs.cmake_cxx_compiler }} ${{ steps.configure-sccache.outputs.enable_sccache }} -DCMAKE_INSTALL_PREFIX="$(pwd)/../install" -DLLVM_INSTALL_UTILS=ON -DCIRCT_SLANG_FRONTEND_ENABLED=ON -DCIRCT_INCLUDE_EXAMPLES=ON -DLLVM_LIT_ARGS="${{ steps.set-cmake-options.outputs.llvm_lit_args }}" ${{ steps.setup-linux.outputs.cmake }} ${{ steps.setup-macos.outputs.cmake }} ${{ steps.setup-macos-integration.outputs.cmake }} ${{ steps.setup-windows.outputs.cmake }} ${{ steps.integration-test-setup-generic.outputs.cmake }} ${{ inputs.extra_cmake_args }}
 # Optionally test
       - name: Test CIRCT
         if: inputs.run_tests
@@ -401,6 +401,12 @@ jobs:
         run: |
           ${{ steps.setup-windows.outputs.setup }}
           ninja -C build check-circt-capi check-circt-integration
+      - name: Check CIRCT Standalone Example
+        if: inputs.run_tests
+        run: |
+          ${{ steps.setup-windows.outputs.setup }}
+          cmake -G Ninja -S "$(pwd)/examples/circt-standalone" -B "$(pwd)/build-circt-standalone" -DCMAKE_BUILD_TYPE=${{ inputs.cmake_build_type }} -DCMAKE_C_COMPILER=${{ steps.set-cmake-options.outputs.cmake_c_compiler }} -DCMAKE_CXX_COMPILER=${{ steps.set-cmake-options.outputs.cmake_cxx_compiler }} -DCIRCT_DIR="$(pwd)/build/lib/cmake/circt" -DMLIR_DIR="$(pwd)/build/lib/cmake/mlir"
+          cmake --build "$(pwd)/build-circt-standalone" --target check-circt-standalone
       - name: Install
         if: inputs.install_target
         run: |

examples/circt-standalone/CMakeLists.txt

@@ -0,0 +1,56 @@
+cmake_minimum_required(VERSION 3.20.0)
+project(circt-standalone LANGUAGES CXX C)
+
+set(CMAKE_BUILD_WITH_INSTALL_NAME_DIR ON)
+
+set(CMAKE_CXX_STANDARD 17 CACHE STRING "C++ standard to conform to")
+set(CMAKE_CXX_STANDARD_REQUIRED YES)
+
+if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
+  find_package(CIRCT REQUIRED CONFIG)
+
+  message(STATUS "Using CIRCTConfig.cmake in: ${CIRCT_DIR}")
+  message(STATUS "Using MLIRConfig.cmake in: ${MLIR_DIR}")
+  message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
+
+  set(LLVM_RUNTIME_OUTPUT_INTDIR ${CMAKE_BINARY_DIR}/bin)
+  set(LLVM_LIBRARY_OUTPUT_INTDIR ${CMAKE_BINARY_DIR}/lib)
+  set(MLIR_BINARY_DIR ${CMAKE_BINARY_DIR})
+
+  list(APPEND CMAKE_MODULE_PATH "${CIRCT_CMAKE_DIR}")
+  list(APPEND CMAKE_MODULE_PATH "${MLIR_CMAKE_DIR}")
+  list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
+
+  include(TableGen)
+  include(AddLLVM)
+  include(AddMLIR)
+  include(AddCIRCT)
+  include(HandleLLVMOptions)
+endif()
+
+set(CIRCT_STANDALONE_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR})
+set(CIRCT_STANDALONE_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR})
+
+include_directories(${LLVM_INCLUDE_DIRS})
+include_directories(${MLIR_INCLUDE_DIRS})
+include_directories(${CIRCT_INCLUDE_DIRS})
+include_directories(${CIRCT_STANDALONE_SOURCE_DIR}/include)
+include_directories(${CIRCT_STANDALONE_BINARY_DIR}/include)
+link_directories(${LLVM_BUILD_LIBRARY_DIR})
+link_directories(${CIRCT_LIBRARY_DIRS})
+add_definitions(${LLVM_DEFINITIONS})
+
+option(CIRCT_STANDALONE_INCLUDE_TESTS
+  "Generate build targets for the CIRCT standalone tests." ON)
+
+add_subdirectory(include)
+add_subdirectory(lib)
+add_subdirectory(circt-standalone-opt)
+set(CIRCT_STANDALONE_HAS_PLUGIN OFF)
+if(NOT WIN32 AND TARGET circt-opt)
+  add_subdirectory(circt-standalone-plugin)
+  set(CIRCT_STANDALONE_HAS_PLUGIN ON)
+endif()
+if(CIRCT_STANDALONE_INCLUDE_TESTS)
+  add_subdirectory(test)
+endif()

examples/circt-standalone/README.md

@@ -0,0 +1,35 @@
+# CIRCT Standalone Example
+
+This is a minimal out-of-tree CIRCT project, modeled after MLIR's
+`examples/standalone`, for bootstrapping a dialect, pass library, optimizer
+driver, and plugin.
+
+Configure it against a CIRCT build or install tree:
+
+```sh
+cd examples/circt-standalone
+mkdir build-circt-standalone
+CIRCT_BUILD_DIR=<path-to-circt-build-or-install>
+# This the same as CIRCT_BUILD_DIR when unified build is used
+MLIR_BUILD_DIR=<path-to-mlir-build-or-install>
+cmake -G Ninja -S . -B build-circt-standalone \
+  -DCIRCT_DIR=$CIRCT_BUILD_DIR/lib/cmake/circt \
+  -DMLIR_DIR=$MLIR_BUILD_DIR/lib/cmake/mlir
+```
+
+Build the optimizer, plugin, and tests:
+
+```sh
+ninja -C build-circt-standalone check-circt-standalone
+```
+
+Like MLIR's `examples/standalone`, this example is not built by the in-tree
+examples target.  Configure it separately as shown above.
+
+The plugin can be loaded into `circt-opt`:
+
+```sh
+circt-opt input.mlir \
+  --load-dialect-plugin=build-circt-standalone/lib/CIRCTStandalonePlugin.so \
+  --pass-pipeline='builtin.module(hw.module(circt-standalone-rename-wires))'
+```

examples/circt-standalone/circt-standalone-opt/CMakeLists.txt

@@ -0,0 +1,25 @@
+set(LLVM_LINK_COMPONENTS
+  Support
+)
+
+add_llvm_executable(circt-standalone-opt
+  circt-standalone-opt.cpp
+
+  DEPENDS
+  SUPPORT_PLUGINS
+)
+
+llvm_update_compile_flags(circt-standalone-opt)
+
+target_link_libraries(circt-standalone-opt
+  PRIVATE
+  CIRCTStandalone
+  CIRCTHW
+  MLIRIR
+  MLIROptLib
+  MLIRParser
+  MLIRSupport
+  MLIRTransforms
+)
+
+export_executable_symbols_for_plugins(circt-standalone-opt)

examples/circt-standalone/circt-standalone-opt/circt-standalone-opt.cpp

@@ -0,0 +1,33 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 "CIRCTStandalone/CIRCTStandaloneDialect.h"
+#include "CIRCTStandalone/CIRCTStandalonePasses.h"
+#include "circt/Dialect/HW/HWDialect.h"
+#include "circt/Support/Version.h"
+#include "mlir/Pass/PassRegistry.h"
+#include "mlir/Tools/mlir-opt/MlirOptMain.h"
+#include "mlir/Transforms/Passes.h"
+#include "llvm/Support/PrettyStackTrace.h"
+
+int main(int argc, char **argv) {
+  llvm::setBugReportMsg(circt::circtBugReportMsg);
+
+  mlir::DialectRegistry registry;
+  registry.insert<circt::hw::HWDialect>();
+  registry.insert<circt::standalone::CIRCTStandaloneDialect>();
+
+  circt::standalone::registerPasses();
+  mlir::registerCanonicalizerPass();
+  mlir::registerCSEPass();
+  llvm::cl::AddExtraVersionPrinter(
+      [](llvm::raw_ostream &os) { os << circt::getCirctVersion() << '\n'; });
+
+  return mlir::failed(mlir::MlirOptMain(
+      argc, argv, "CIRCT standalone optimizer driver", registry));
+}

examples/circt-standalone/circt-standalone-plugin/CMakeLists.txt

@@ -0,0 +1,17 @@
+add_llvm_library(CIRCTStandalonePlugin
+  MODULE BUILDTREE_ONLY
+  circt-standalone-plugin.cpp
+
+  DEPENDS
+  CIRCTStandalone
+  PLUGIN_TOOL
+  circt-opt
+
+  LINK_LIBS
+  CIRCTStandalone
+)
+
+target_include_directories(CIRCTStandalonePlugin
+  PRIVATE
+  "${CIRCT_STANDALONE_BINARY_DIR}/include"
+)

examples/circt-standalone/circt-standalone-plugin/circt-standalone-plugin.cpp

@@ -0,0 +1,29 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 "CIRCTStandalone/CIRCTStandaloneDialect.h"
+#include "CIRCTStandalone/CIRCTStandalonePasses.h"
+#include "mlir/Tools/Plugins/DialectPlugin.h"
+#include "mlir/Tools/Plugins/PassPlugin.h"
+#include "llvm/Config/llvm-config.h"
+#include "llvm/Support/Compiler.h"
+
+extern "C" LLVM_ATTRIBUTE_WEAK mlir::DialectPluginLibraryInfo
+mlirGetDialectPluginInfo() {
+  return {MLIR_PLUGIN_API_VERSION, "CIRCTStandalone", LLVM_VERSION_STRING,
+          [](mlir::DialectRegistry *registry) {
+            registry->insert<circt::standalone::CIRCTStandaloneDialect>();
+            circt::standalone::registerPasses();
+          }};
+}
+
+extern "C" LLVM_ATTRIBUTE_WEAK mlir::PassPluginLibraryInfo
+mlirGetPassPluginInfo() {
+  return {MLIR_PLUGIN_API_VERSION, "CIRCTStandalonePasses", LLVM_VERSION_STRING,
+          []() { circt::standalone::registerPasses(); }};
+}

examples/circt-standalone/include/CIRCTStandalone/CIRCTStandaloneDialect.h

@@ -0,0 +1,16 @@
+//===- CIRCTStandaloneDialect.h - CIRCT standalone dialect ------*- 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
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef CIRCT_STANDALONE_CIRCTSTANDALONEDIALECT_H
+#define CIRCT_STANDALONE_CIRCTSTANDALONEDIALECT_H
+
+#include "mlir/IR/Dialect.h"
+
+#include "CIRCTStandalone/CIRCTStandaloneOpsDialect.h.inc"
+
+#endif // CIRCT_STANDALONE_CIRCTSTANDALONEDIALECT_H

examples/circt-standalone/include/CIRCTStandalone/CIRCTStandaloneDialect.td

@@ -0,0 +1,27 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef CIRCT_STANDALONE_DIALECT
+#define CIRCT_STANDALONE_DIALECT
+
+include "mlir/IR/OpBase.td"
+
+def CIRCTStandaloneDialect : Dialect {
+  let name = "circt_standalone";
+  let summary = "An out-of-tree CIRCT example dialect";
+  let description = [{
+    This dialect demonstrates the boilerplate required to build an out-of-tree
+    CIRCT project with a dialect, passes, an optimizer driver, and a plugin.
+  }];
+  let cppNamespace = "::circt::standalone";
+}
+
+class CIRCTStandaloneOp<string mnemonic, list<Trait> traits = []> :
+    Op<CIRCTStandaloneDialect, mnemonic, traits>;
+
+#endif // CIRCT_STANDALONE_DIALECT

examples/circt-standalone/include/CIRCTStandalone/CIRCTStandaloneOps.h

@@ -0,0 +1,22 @@
+//===- CIRCTStandaloneOps.h - CIRCT standalone ops -------------*- 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
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef CIRCT_STANDALONE_CIRCTSTANDALONEOPS_H
+#define CIRCT_STANDALONE_CIRCTSTANDALONEOPS_H
+
+#include "CIRCTStandalone/CIRCTStandaloneDialect.h"
+#include "mlir/IR/Builders.h"
+#include "mlir/IR/BuiltinTypes.h"
+#include "mlir/IR/OpDefinition.h"
+#include "mlir/IR/OpImplementation.h"
+#include "mlir/Interfaces/SideEffectInterfaces.h"
+
+#define GET_OP_CLASSES
+#include "CIRCTStandalone/CIRCTStandaloneOps.h.inc"
+
+#endif // CIRCT_STANDALONE_CIRCTSTANDALONEOPS_H

examples/circt-standalone/include/CIRCTStandalone/CIRCTStandaloneOps.td

@@ -0,0 +1,25 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef CIRCT_STANDALONE_OPS
+#define CIRCT_STANDALONE_OPS
+
+include "CIRCTStandalone/CIRCTStandaloneDialect.td"
+include "mlir/Interfaces/SideEffectInterfaces.td"
+
+def CIRCTStandalone_FooOp : CIRCTStandaloneOp<"foo", [Pure]> {
+  let summary = "Illustrates how to define an operation";
+  let description = [{
+    The `circt_standalone.foo` operation illustrates the minimum TableGen
+    needed for a custom operation in an out-of-tree CIRCT dialect.
+  }];
+
+  let assemblyFormat = "attr-dict";
+}
+
+#endif // CIRCT_STANDALONE_OPS

examples/circt-standalone/include/CIRCTStandalone/CIRCTStandalonePasses.h

@@ -0,0 +1,26 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef CIRCT_STANDALONE_CIRCTSTANDALONEPASSES_H
+#define CIRCT_STANDALONE_CIRCTSTANDALONEPASSES_H
+
+#include "mlir/Pass/Pass.h"
+
+namespace circt {
+namespace standalone {
+
+#define GEN_PASS_DECL
+#include "CIRCTStandalone/CIRCTStandalonePasses.h.inc"
+
+#define GEN_PASS_REGISTRATION
+#include "CIRCTStandalone/CIRCTStandalonePasses.h.inc"
+
+} // namespace standalone
+} // namespace circt
+
+#endif // CIRCT_STANDALONE_CIRCTSTANDALONEPASSES_H

examples/circt-standalone/include/CIRCTStandalone/CIRCTStandalonePasses.td

@@ -0,0 +1,24 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef CIRCT_STANDALONE_PASSES
+#define CIRCT_STANDALONE_PASSES
+
+include "mlir/Pass/PassBase.td"
+
+def RenameWires
+    : Pass<"circt-standalone-rename-wires", "hw::HWModuleOp"> {
+  let summary = "Rename all hw.wire operations in a module";
+  let description = [{
+    This pass is intentionally small and CIRCT-specific: it walks a hardware
+    module and renames each `hw.wire` operation to `foo_<n>`.
+  }];
+  let dependentDialects = ["::circt::hw::HWDialect"];
+}
+
+#endif // CIRCT_STANDALONE_PASSES

examples/circt-standalone/include/CIRCTStandalone/CMakeLists.txt

@@ -0,0 +1,5 @@
+add_mlir_dialect(CIRCTStandaloneOps circt_standalone)
+
+set(LLVM_TARGET_DEFINITIONS CIRCTStandalonePasses.td)
+mlir_tablegen(CIRCTStandalonePasses.h.inc -gen-pass-decls)
+add_public_tablegen_target(CIRCTStandalonePassesIncGen)

examples/circt-standalone/include/CMakeLists.txt

@@ -0,0 +1 @@
+add_subdirectory(CIRCTStandalone)

examples/circt-standalone/lib/CIRCTStandalone/CIRCTStandaloneDialect.cpp

@@ -0,0 +1,22 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 "CIRCTStandalone/CIRCTStandaloneDialect.h"
+#include "CIRCTStandalone/CIRCTStandaloneOps.h"
+
+using namespace circt;
+using namespace circt::standalone;
+
+#include "CIRCTStandalone/CIRCTStandaloneOpsDialect.cpp.inc"
+
+void CIRCTStandaloneDialect::initialize() {
+  addOperations<
+#define GET_OP_LIST
+#include "CIRCTStandalone/CIRCTStandaloneOps.cpp.inc"
+      >();
+}