[clang-offload-bundler] Add support for -check-input-archive (llvm#73709)

lamb-j · ronlieb · commit 3b96b6572ac9 · 2023-11-30T19:40:30.000-05:00
In this patch, we add support for checking a heterogeneous archive. We
also significantly improve the clang-offload-bundler documentation.

Change-Id: I332f5810bfc90b1f702d05295767789c33e4e22b
diff --git a/clang/docs/ClangOffloadBundler.rst b/clang/docs/ClangOffloadBundler.rst
@@ -295,10 +295,10 @@ Compatibility Rules for Bundle Entry ID
   A code object, specified using its Bundle Entry ID, can be loaded and
   executed on a target processor, if:
 
-  * Their offload kind are the same.
-  * Their target triple are compatible.
-  * Their Target ID are compatible as defined in :ref:`compatibility-target-id`.
-  
+  * Their offload kinds are the same.
+  * Their target triples are compatible.
+  * Their Target IDs are compatible as defined in :ref:`compatibility-target-id`.
+
 .. _clang-target-id:
 
 Target ID
@@ -410,10 +410,18 @@ collection of device binaries for a specific target.
   where, Fi-Tj-DeviceBinary.X represents device binary of i-th bundled device
   binary file for target Tj.
 
-clang-offload-bundler extracts compatible device binaries for a given target
+The clang-offload-bundler extracts compatible device binaries for a given target
 from the bundled device binaries in a heterogeneous device archive and creates
 a target-specific device archive without bundling.
 
+The clang-offload-bundler determines whether a device binary is compatible
+with a target by comparing bundle IDs. Two bundle IDs are considered
+compatible if:
+
+  * Their offload kinds are the same
+  * Their target triples are the same
+  * Their Target IDs are the same
+
 Creating a Heterogeneous Device Archive
 ---------------------------------------
 
@@ -428,7 +436,7 @@ Creating a Heterogeneous Device Archive
       -Xopenmp-target=nvptx64-nvidia-cuda -march=sm_70 \
       -Xopenmp-target=nvptx64-nvidia-cuda -march=sm_80 \
       -c func_1.c -o func_1.o
-    
+
     clang -O2 -fopenmp -fopenmp-targets=amdgcn-amd-amdhsa,amdgcn-amd-amdhsa,
       nvptx64-nvidia-cuda, nvptx64-nvidia-cuda \
       -Xopenmp-target=amdgcn-amd-amdhsa -march=gfx906:sramecc-:xnack+ \
@@ -491,18 +499,12 @@ Additional Options while Archive Unbundling
   Check if input heterogeneous device archive follows rules for composition
   as defined in :ref:`code-object-composition` before creating device-specific
   archive(s).
-clang-offload-bundler determines whether a device binary is compatible with a
-target by comparing bundle ID's. Two bundle ID's are considered compatible if:
 
 **-debug-only=CodeObjectCompatibility**
   Verbose printing of matched/unmatched comparisons between bundle entry id of
   a device binary from HDA and bundle entry ID of a given target processor
   (see :ref:`compatibility-bundle-entry-id`).
 
-  * Their offload kind are the same
-  * Their target triple are the same
-  * Their GPUArch are the same
-
 Compression and Decompression
 =============================
 
diff --git a/clang/lib/Driver/OffloadBundler.cpp b/clang/lib/Driver/OffloadBundler.cpp
@@ -164,51 +164,6 @@ static std::string getDeviceLibraryFileName(StringRef BundleFileName,
   return Result;
 }
 
-/// @brief Checks if a code object \p CodeObjectInfo is compatible with a given
-/// target \p TargetInfo.
-/// @link https://clang.llvm.org/docs/ClangOffloadBundler.html#bundle-entry-id
-bool isCodeObjectCompatible(const OffloadTargetInfo &CodeObjectInfo,
-                            const OffloadTargetInfo &TargetInfo) {
-
-  // Compatible in case of exact match.
-  if (CodeObjectInfo == TargetInfo) {
-    DEBUG_WITH_TYPE("CodeObjectCompatibility",
-                    dbgs() << "Compatible: Exact match: \t[CodeObject: "
-                           << CodeObjectInfo.str()
-                           << "]\t:\t[Target: " << TargetInfo.str() << "]\n");
-    return true;
-  }
-
-  // Incompatible if Kinds or Triples mismatch.
-  if (!CodeObjectInfo.isOffloadKindCompatible(TargetInfo.OffloadKind) ||
-      !CodeObjectInfo.Triple.isCompatibleWith(TargetInfo.Triple)) {
-    DEBUG_WITH_TYPE(
-        "CodeObjectCompatibility",
-        dbgs() << "Incompatible: Kind/Triple mismatch \t[CodeObject: "
-               << CodeObjectInfo.str() << "]\t:\t[Target: " << TargetInfo.str()
-               << "]\n");
-    return false;
-  }
-
-  // Incompatible if target IDs are incompatible.
-  if (!clang::isCompatibleTargetID(CodeObjectInfo.TargetID,
-                                   TargetInfo.TargetID)) {
-    DEBUG_WITH_TYPE(
-        "CodeObjectCompatibility",
-        dbgs() << "Incompatible: target IDs are incompatible \t[CodeObject: "
-               << CodeObjectInfo.str() << "]\t:\t[Target: " << TargetInfo.str()
-               << "]\n");
-    return false;
-  }
-
-  DEBUG_WITH_TYPE(
-      "CodeObjectCompatibility",
-      dbgs() << "Compatible: Code Objects are compatible \t[CodeObject: "
-             << CodeObjectInfo.str() << "]\t:\t[Target: " << TargetInfo.str()
-             << "]\n");
-  return true;
-}
-
 namespace {
 /// Generic file handler interface.
 class FileHandler {
@@ -1130,6 +1085,99 @@ Error OffloadBundler::ListBundleIDsInFile(
   return FH->listBundleIDs(DecompressedInput);
 }
 
+/// @brief Checks if a code object \p CodeObjectInfo is compatible with a given
+/// target \p TargetInfo.
+/// @link https://clang.llvm.org/docs/ClangOffloadBundler.html#bundle-entry-id
+bool isCodeObjectCompatible(const OffloadTargetInfo &CodeObjectInfo,
+                            const OffloadTargetInfo &TargetInfo) {
+
+  // Compatible in case of exact match.
+  if (CodeObjectInfo == TargetInfo) {
+    DEBUG_WITH_TYPE("CodeObjectCompatibility",
+                    dbgs() << "Compatible: Exact match: \t[CodeObject: "
+                           << CodeObjectInfo.str()
+                           << "]\t:\t[Target: " << TargetInfo.str() << "]\n");
+    return true;
+  }
+
+  // Incompatible if Kinds or Triples mismatch.
+  if (!CodeObjectInfo.isOffloadKindCompatible(TargetInfo.OffloadKind) ||
+      !CodeObjectInfo.Triple.isCompatibleWith(TargetInfo.Triple)) {
+    DEBUG_WITH_TYPE(
+        "CodeObjectCompatibility",
+        dbgs() << "Incompatible: Kind/Triple mismatch \t[CodeObject: "
+               << CodeObjectInfo.str() << "]\t:\t[Target: " << TargetInfo.str()
+               << "]\n");
+    return false;
+  }
+
+  // Incompatible if Processors mismatch.
+  llvm::StringMap<bool> CodeObjectFeatureMap, TargetFeatureMap;
+  std::optional<StringRef> CodeObjectProc = clang::parseTargetID(
+      CodeObjectInfo.Triple, CodeObjectInfo.TargetID, &CodeObjectFeatureMap);
+  std::optional<StringRef> TargetProc = clang::parseTargetID(
+      TargetInfo.Triple, TargetInfo.TargetID, &TargetFeatureMap);
+
+  // Both TargetProc and CodeObjectProc can't be empty here.
+  if (!TargetProc || !CodeObjectProc ||
+      CodeObjectProc.value() != TargetProc.value()) {
+    DEBUG_WITH_TYPE("CodeObjectCompatibility",
+                    dbgs() << "Incompatible: Processor mismatch \t[CodeObject: "
+                           << CodeObjectInfo.str()
+                           << "]\t:\t[Target: " << TargetInfo.str() << "]\n");
+    return false;
+  }
+
+  // Incompatible if CodeObject has more features than Target, irrespective of
+  // type or sign of features.
+  if (CodeObjectFeatureMap.getNumItems() > TargetFeatureMap.getNumItems()) {
+    DEBUG_WITH_TYPE("CodeObjectCompatibility",
+                    dbgs() << "Incompatible: CodeObject has more features "
+                              "than target \t[CodeObject: "
+                           << CodeObjectInfo.str()
+                           << "]\t:\t[Target: " << TargetInfo.str() << "]\n");
+    return false;
+  }
+
+  // Compatible if each target feature specified by target is compatible with
+  // target feature of code object. The target feature is compatible if the
+  // code object does not specify it (meaning Any), or if it specifies it
+  // with the same value (meaning On or Off).
+  for (const auto &CodeObjectFeature : CodeObjectFeatureMap) {
+    auto TargetFeature = TargetFeatureMap.find(CodeObjectFeature.getKey());
+    if (TargetFeature == TargetFeatureMap.end()) {
+      DEBUG_WITH_TYPE(
+          "CodeObjectCompatibility",
+          dbgs()
+              << "Incompatible: Value of CodeObject's non-ANY feature is "
+                 "not matching with Target feature's ANY value \t[CodeObject: "
+              << CodeObjectInfo.str() << "]\t:\t[Target: " << TargetInfo.str()
+              << "]\n");
+      return false;
+    } else if (TargetFeature->getValue() != CodeObjectFeature.getValue()) {
+      DEBUG_WITH_TYPE(
+          "CodeObjectCompatibility",
+          dbgs() << "Incompatible: Value of CodeObject's non-ANY feature is "
+                    "not matching with Target feature's non-ANY value "
+                    "\t[CodeObject: "
+                 << CodeObjectInfo.str()
+                 << "]\t:\t[Target: " << TargetInfo.str() << "]\n");
+      return false;
+    }
+  }
+
+  // CodeObject is compatible if all features of Target are:
+  //   - either, present in the Code Object's features map with the same sign,
+  //   - or, the feature is missing from CodeObjects's features map i.e. it is
+  //   set to ANY
+  DEBUG_WITH_TYPE(
+      "CodeObjectCompatibility",
+      dbgs() << "Compatible: Target IDs are compatible \t[CodeObject: "
+             << CodeObjectInfo.str() << "]\t:\t[Target: " << TargetInfo.str()
+             << "]\n");
+  return true;
+}
+
 /// Bundle the files. Return true if an error was found.
 Error OffloadBundler::BundleFiles() {
   std::error_code EC;
@@ -1348,99 +1396,6 @@ static Archive::Kind getDefaultArchiveKindForHost() {
                                                             : Archive::K_GNU;
 }
 
-/// @brief Checks if a code object \p CodeObjectInfo is compatible with a given
-/// target \p TargetInfo.
-/// @link https://clang.llvm.org/docs/ClangOffloadBundler.html#bundle-entry-id
-bool isCodeObjectCompatible(OffloadTargetInfo &CodeObjectInfo,
-                            OffloadTargetInfo &TargetInfo) {
-
-  // Compatible in case of exact match.
-  if (CodeObjectInfo == TargetInfo) {
-    DEBUG_WITH_TYPE("CodeObjectCompatibility",
-                    dbgs() << "Compatible: Exact match: \t[CodeObject: "
-                           << CodeObjectInfo.str()
-                           << "]\t:\t[Target: " << TargetInfo.str() << "]\n");
-    return true;
-  }
-
-  // Incompatible if Kinds or Triples mismatch.
-  if (!CodeObjectInfo.isOffloadKindCompatible(TargetInfo.OffloadKind) ||
-      !CodeObjectInfo.Triple.isCompatibleWith(TargetInfo.Triple)) {
-    DEBUG_WITH_TYPE(
-        "CodeObjectCompatibility",
-        dbgs() << "Incompatible: Kind/Triple mismatch \t[CodeObject: "
-               << CodeObjectInfo.str() << "]\t:\t[Target: " << TargetInfo.str()
-               << "]\n");
-    return false;
-  }
-
-  // Incompatible if Processors mismatch.
-  llvm::StringMap<bool> CodeObjectFeatureMap, TargetFeatureMap;
-  std::optional<StringRef> CodeObjectProc = clang::parseTargetID(
-      CodeObjectInfo.Triple, CodeObjectInfo.TargetID, &CodeObjectFeatureMap);
-  std::optional<StringRef> TargetProc = clang::parseTargetID(
-      TargetInfo.Triple, TargetInfo.TargetID, &TargetFeatureMap);
-
-  // Both TargetProc and CodeObjectProc can't be empty here.
-  if (!TargetProc || !CodeObjectProc ||
-      CodeObjectProc.value() != TargetProc.value()) {
-    DEBUG_WITH_TYPE("CodeObjectCompatibility",
-                    dbgs() << "Incompatible: Processor mismatch \t[CodeObject: "
-                           << CodeObjectInfo.str()
-                           << "]\t:\t[Target: " << TargetInfo.str() << "]\n");
-    return false;
-  }
-
-  // Incompatible if CodeObject has more features than Target, irrespective of
-  // type or sign of features.
-  if (CodeObjectFeatureMap.getNumItems() > TargetFeatureMap.getNumItems()) {
-    DEBUG_WITH_TYPE("CodeObjectCompatibility",
-                    dbgs() << "Incompatible: CodeObject has more features "
-                              "than target \t[CodeObject: "
-                           << CodeObjectInfo.str()
-                           << "]\t:\t[Target: " << TargetInfo.str() << "]\n");
-    return false;
-  }
-
-  // Compatible if each target feature specified by target is compatible with
-  // target feature of code object. The target feature is compatible if the
-  // code object does not specify it (meaning Any), or if it specifies it
-  // with the same value (meaning On or Off).
-  for (const auto &CodeObjectFeature : CodeObjectFeatureMap) {
-    auto TargetFeature = TargetFeatureMap.find(CodeObjectFeature.getKey());
-    if (TargetFeature == TargetFeatureMap.end()) {
-      DEBUG_WITH_TYPE(
-          "CodeObjectCompatibility",
-          dbgs()
-              << "Incompatible: Value of CodeObject's non-ANY feature is "
-                 "not matching with Target feature's ANY value \t[CodeObject: "
-              << CodeObjectInfo.str() << "]\t:\t[Target: " << TargetInfo.str()
-              << "]\n");
-      return false;
-    } else if (TargetFeature->getValue() != CodeObjectFeature.getValue()) {
-      DEBUG_WITH_TYPE(
-          "CodeObjectCompatibility",
-          dbgs() << "Incompatible: Value of CodeObject's non-ANY feature is "
-                    "not matching with Target feature's non-ANY value "
-                    "\t[CodeObject: "
-                 << CodeObjectInfo.str()
-                 << "]\t:\t[Target: " << TargetInfo.str() << "]\n");
-      return false;
-    }
-  }
-
-  // CodeObject is compatible if all features of Target are:
-  //   - either, present in the Code Object's features map with the same sign,
-  //   - or, the feature is missing from CodeObjects's features map i.e. it is
-  //   set to ANY
-  DEBUG_WITH_TYPE(
-      "CodeObjectCompatibility",
-      dbgs() << "Compatible: Target IDs are compatible \t[CodeObject: "
-             << CodeObjectInfo.str() << "]\t:\t[Target: " << TargetInfo.str()
-             << "]\n");
-  return true;
-}
-
 /// @brief Computes a list of targets among all given targets which are
 /// compatible with this code object
 /// @param [in] CodeObjectInfo Code Object
@@ -1468,8 +1423,9 @@ getCompatibleOffloadTargets(OffloadTargetInfo &CodeObjectInfo,
 // rule: for a specific processor, a feature either shows up in all target IDs,
 // or does not show up in any target IDs. Otherwise the target ID combination is
 // invalid.
-static Error CheckHeterogeneousArchive(StringRef ArchiveName,
-                                       const OffloadBundlerConfig &BundlerConfig) {
+static Error
+CheckHeterogeneousArchive(StringRef ArchiveName,
+                          const OffloadBundlerConfig &BundlerConfig) {
   std::vector<std::unique_ptr<MemoryBuffer>> ArchiveBuffers;
   ErrorOr<std::unique_ptr<MemoryBuffer>> BufOrErr =
       MemoryBuffer::getFileOrSTDIN(ArchiveName, true, false);
diff --git a/clang/tools/clang-offload-bundler/ClangOffloadBundler.cpp b/clang/tools/clang-offload-bundler/ClangOffloadBundler.cpp
@@ -130,11 +130,11 @@ int main(int argc, const char **argv) {
     BundleAlignment("bundle-align",
                     cl::desc("Alignment of bundle for binary files"),
                     cl::init(1), cl::cat(ClangOffloadBundlerCategory));
-  cl::opt<bool>
-    CheckInputArchive("check-input-archive",
-                      cl::desc("Check if input heterogeneous archive is "
-                               "valid in terms of TargetID rules.\n"),
-                      cl::init(false), cl::cat(ClangOffloadBundlerCategory));
+  cl::opt<bool> CheckInputArchive(
+      "check-input-archive",
+      cl::desc("Check if input heterogeneous archive is "
+               "valid in terms of TargetID rules.\n"),
+      cl::init(false), cl::cat(ClangOffloadBundlerCategory));
   cl::opt<bool> HipOpenmpCompatible(
     "hip-openmp-compatible",
     cl::desc("Treat hip and hipv4 offload kinds as "
