[clang] [CIR] Introduce `cir-offload-merge` tool with a combine mode (PR #240322)
David Rivera via cfe-commits
cfe-commits at lists.llvm.org
Tue Nov 10 21:22:36 PST 2026
================
@@ -0,0 +1,220 @@
+//===-- cir-offload-merge/cir-offload-merge.cpp ---------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+//
+// \file
+// This tool combines a host CIR module and its device CIR modules into a
+// single module marked as an offload container (carrying the
+// `cir.offload.container` unit attribute).
+//
+//===----------------------------------------------------------------------===//
+
+#include "mlir/Dialect/LLVMIR/LLVMDialect.h"
+#include "mlir/Dialect/MemRef/IR/MemRef.h"
+#include "mlir/IR/BuiltinAttributes.h"
+#include "mlir/IR/BuiltinOps.h"
+#include "mlir/IR/MLIRContext.h"
+#include "mlir/IR/OwningOpRef.h"
+#include "mlir/IR/Verifier.h"
+#include "mlir/Parser/Parser.h"
+#include "mlir/Support/FileUtilities.h"
+#include "clang/CIR/Dialect/IR/CIRDialect.h"
+#include "clang/CIR/InitAllDialects.h"
+#include "clang/Driver/OffloadBundler.h"
+#include "llvm/ADT/STLExtras.h"
+#include "llvm/ADT/SmallVector.h"
+#include "llvm/ADT/StringSet.h"
+#include "llvm/Support/CommandLine.h"
+#include "llvm/Support/InitLLVM.h"
+#include "llvm/Support/ToolOutputFile.h"
+#include "llvm/Support/raw_ostream.h"
+
+#include <string>
+
+static llvm::cl::OptionCategory
+ CIROffloadMergeCategory("cir-offload-merge options");
+
+static llvm::cl::opt<bool> Combine("combine",
+ llvm::cl::desc("Combine CIR inputs"),
+ llvm::cl::cat(CIROffloadMergeCategory));
+
+static llvm::cl::list<std::string>
+ InputFileNames("input",
+ llvm::cl::desc("Input CIR file. Can be specified multiple "
+ "times."),
+ llvm::cl::cat(CIROffloadMergeCategory));
+
+static llvm::cl::list<std::string>
+ TargetNames("targets", llvm::cl::CommaSeparated,
+ llvm::cl::desc("[<offload kind>-<target triple>,...]"),
+ llvm::cl::cat(CIROffloadMergeCategory));
+
+static llvm::cl::list<std::string>
+ OutputFileNames("output", llvm::cl::desc("Output CIR file."),
+ llvm::cl::cat(CIROffloadMergeCategory));
+
+namespace {
+struct InputTarget {
+ std::string Input;
+ std::string Target;
+ bool IsHost = false;
+};
+} // namespace
+
+static int reportError(const llvm::Twine &message) {
+ llvm::errs() << "error: " << message << '\n';
+ return 1;
+}
+
+// Targets are offload bundle IDs, so they are checked with
+// clang-offload-bundler's parser (thus, legalized). checkOffloadBundleID must
+// run first, since OffloadTargetInfo asserts on a malformed ID.
+static bool
+isValidCombineTarget(llvm::StringRef target,
+ const clang::OffloadBundlerConfig &bundlerConfig) {
+ if (!clang::checkOffloadBundleID(target))
+ return false;
+
+ clang::OffloadTargetInfo offloadInfo(target, bundlerConfig);
+ // The bundler has no "cuda" offload kind, but CUDA modules are combined here.
+ return (offloadInfo.isOffloadKindValid() ||
+ offloadInfo.OffloadKind == "cuda") &&
+ offloadInfo.isTripleValid();
+}
+
+static int
+validateCombineCommandLine(llvm::SmallVectorImpl<InputTarget> &inputTargets) {
+ if (InputFileNames.empty())
+ return reportError("missing required -input");
+ if (TargetNames.empty())
+ return reportError("missing required -targets");
+ if (OutputFileNames.empty())
+ return reportError("missing required -output");
+ if (OutputFileNames.size() != 1)
+ return reportError("combine mode expects exactly one output");
+ if (InputFileNames.size() != TargetNames.size())
+ return reportError("number of input files and targets should match in "
+ "combine mode");
+
+ // OffloadTargetInfo requires a bundler config; the defaults are enough to
+ // parse a target.
+ clang::OffloadBundlerConfig bundlerConfig;
+ llvm::StringSet<> seenTargets;
+ unsigned numHostTargets = 0;
+
+ for (auto [input, target] : llvm::zip_equal(InputFileNames, TargetNames)) {
+ if (!seenTargets.insert(target).second)
+ return reportError("duplicate target '" + target + "'");
+ if (!isValidCombineTarget(target, bundlerConfig))
+ return reportError("invalid target '" + target + "'");
+
+ bool isHost = clang::OffloadTargetInfo(target, bundlerConfig).hasHostKind();
+ numHostTargets += isHost;
+ inputTargets.push_back({input, target, isHost});
+ }
+
+ if (numHostTargets != 1)
+ return reportError("expected exactly one host target");
+ if (inputTargets.size() == 1)
+ return reportError("expected at least one device target");
+ return 0;
+}
+
+static void setOffloadAttrs(mlir::ModuleOp module, llvm::StringRef name,
+ cir::OffloadKind offloadKind,
+ llvm::StringRef bundleID) {
+ module.setSymName(name);
+ module->setAttr(cir::CIRDialect::getOffloadKindAttrName(),
+ cir::OffloadKindAttr::get(module.getContext(), offloadKind));
+ module->setAttr(cir::CIRDialect::getOffloadBundleIDAttrName(),
+ mlir::StringAttr::get(module.getContext(), bundleID));
+}
+
+static mlir::OwningOpRef<mlir::ModuleOp>
+combineInputs(llvm::ArrayRef<InputTarget> inputTargets,
+ mlir::MLIRContext &context) {
+ mlir::OwningOpRef<mlir::ModuleOp> hostModule;
+ llvm::SmallVector<mlir::OwningOpRef<mlir::ModuleOp>> deviceModules;
+
+ for (const InputTarget &inputTarget : inputTargets) {
+ mlir::OwningOpRef<mlir::ModuleOp> module =
+ mlir::parseSourceFile<mlir::ModuleOp>(inputTarget.Input,
+ mlir::ParserConfig(&context));
+ if (!module)
+ return {};
+
+ if (inputTarget.IsHost) {
+ setOffloadAttrs(*module, "host", cir::OffloadKind::Host,
+ inputTarget.Target);
+ hostModule = std::move(module);
+ continue;
+ }
+
+ std::string deviceName =
+ ("device_" + llvm::Twine(deviceModules.size())).str();
+ setOffloadAttrs(*module, deviceName, cir::OffloadKind::Device,
+ inputTarget.Target);
+ deviceModules.push_back(std::move(module));
+ }
+
+ // The container verifier expects the host module first, followed by the
+ // device modules.
+ mlir::ModuleOp container =
+ mlir::ModuleOp::create(mlir::UnknownLoc::get(&context));
+ container->setAttr(cir::CIRDialect::getOffloadContainerAttrName(),
+ mlir::UnitAttr::get(&context));
+ container.getBody()->push_back(hostModule.release());
+ for (mlir::OwningOpRef<mlir::ModuleOp> &deviceModule : deviceModules)
+ container.getBody()->push_back(deviceModule.release());
+ return container;
+}
+
+static int writeModuleToOutput(mlir::ModuleOp module,
+ llvm::StringRef outputFileName) {
+ // Type aliases are only printed for an operation without a parent.
+ assert(!module->getParentOp() && "expected a top-level module");
+ std::string errorMessage;
+ std::unique_ptr<llvm::ToolOutputFile> outputFile =
+ mlir::openOutputFile(outputFileName, &errorMessage);
+ if (!outputFile)
+ return reportError(errorMessage);
+
+ // TODO: Support bytecode output.
----------------
RiverDave wrote:
🤠I considered that early on, but the two tools diverge in a couple of important ways (I did a little read on the semantics of the bundler ahead of this response):
* The bundler packs and unpacks opaque files (text, bitcode, objects) and never parses them. This tool parses MLIR, verifies it, and produces a new module that we eventually want to run passes on (At least how we've planned it), which makes it closer to cir-opt than to bundling.
* Dependencies: folding combine into the bundler would pull MLIR and the CIR dialect into it. I’m not that familiar with how that would play out in the build system, though. @koparasy might know better. A change like that to a shared tool would probably also need an RFC with its maintainers.
https://github.com/llvm/llvm-project/pull/240322
More information about the cfe-commits
mailing list