Allow to define both experimental and non-experimental SPIRV extension support

Allow to define both experimental and non-experimental SPIRV extension support

Author: aratajew

IGC/AdaptorOCL/Utils/IGCCSPIRVSupportTblGen/IGCCSPIRVPlatformSupport.h

@@ -13,6 +13,7 @@ SPDX-License-Identifier: MIT
 
 #include "llvm/ADT/StringRef.h"
 #include "llvm/ADT/SmallVector.h"
+#include "llvm/ADT/StringMap.h"
 #include "llvm/TableGen/Record.h"
 #include "llvm/TableGen/Error.h"
 #include "llvm/Support/SourceMgr.h"
@@ -45,17 +46,17 @@ enum class PlatformSupportKind {
 // Capability entry for an extension.
 struct CapabilityEntry {
   StringRef Name;
-  const Record *Root;              // original capability record
-  const Record *EffectivePlatform; // resolved support (extension or capability)
+  const Record *Root; // original capability record
+  const Record *ProductionSupport = nullptr;
+  const Record *ExperimentalSupport = nullptr;
 };
 
 struct ExtensionEntry {
   StringRef Name;
   StringRef SpecURL;
-  const Record *Root;                 // original extension record
-  const Record *Platforms;            // extension support record (raw)
-  bool IsInheritFromCapabilitiesMode; // true if extSupport == InheritFromCapabilities (aggregated capability mode)
-  bool IsExperimental;                // true if extension is experimental, false if production
+  const Record *Root; // original extension record (first encountered)
+  const Record *ProductionSupport = nullptr;
+  const Record *ExperimentalSupport = nullptr;
   SmallVector<CapabilityEntry, 8> Capabilities;
 };
 
@@ -126,33 +127,91 @@ static void validateExtensionPlatformSupport(const Record *Ext) {
 }
 
 
+// Validate duplicate extension definitions policy: at most two per name,
+// and if two exist, exactly one must be Experimental and one Production.
+static void validateExtensionMultiplicityPolicy(const RecordKeeper &Records) {
+  auto AllExtensions = Records.getAllDerivedDefinitions("SPIRVExtension");
+  llvm::StringMap<SmallVector<const Record *, 4>> Groups;
+  for (const Record *Ext : AllExtensions) {
+    StringRef Name = Ext->getValueAsString("ExtName");
+    Groups[Name].push_back(Ext);
+  }
+
+  for (auto &KV : Groups) {
+    const StringRef ExtName = KV.first();
+    auto &Defs = KV.second;
+    if (Defs.size() > 2) {
+      // Report error on the third definition location as a representative.
+      PrintFatalError(
+          Defs[2]->getLoc(),
+          "Extension '" + ExtName.str() +
+              "' defined more than twice; only one production and one experimental definition are allowed.");
+    }
+    if (Defs.size() == 2) {
+      bool e0 = Defs[0]->getValueAsBit("Experimental");
+      bool e1 = Defs[1]->getValueAsBit("Experimental");
+      if (e0 == e1) {
+        // Both production or both experimental — invalid.
+        PrintFatalError(Defs[1]->getLoc(), "Extension '" + ExtName.str() +
+                                               "' has two definitions with the same Experimental flag; one must be "
+                                               "marked experimental and the other production.");
+      }
+    }
+  }
+}
+
 static SPIRVExtensions collectSPIRVExtensionSupport(const RecordKeeper &Records) {
+  // Enforce duplicate-definition policy before merging.
+  validateExtensionMultiplicityPolicy(Records);
   SPIRVExtensions Result;
   auto AllExtensions = Records.getAllDerivedDefinitions("SPIRVExtension");
   Result.reserve(AllExtensions.size());
+  llvm::StringMap<size_t> ExtIndex; // fast lookup of merged extension entries by name
+
   for (const Record *Ext : AllExtensions) {
     validateExtensionPlatformSupport(Ext);
-    ExtensionEntry Entry;
-    Entry.Name = Ext->getValueAsString("ExtName");
-    Entry.SpecURL = Ext->getValueAsString("ExtSpecURL");
-    Entry.Root = Ext;
-    Entry.Platforms = Ext->getValueAsDef("ExtSupport");
-    Entry.IsInheritFromCapabilitiesMode = Entry.Platforms->getName() == "InheritFromCapabilities";
-    Entry.IsExperimental = Ext->getValueAsBit("Experimental");
-    auto Caps = Ext->getValueAsListOfDefs("ExtCapabilities");
-    for (const Record *Cap : Caps) {
-      CapabilityEntry CapEntry;
-      CapEntry.Name = Cap->getValueAsString("Name");
-      CapEntry.Root = Cap;
-      const Record *CapSupport = Cap->getValueAsDef("Support");
-      if (CapSupport->getName() == "InheritFromExtension" && Entry.Platforms->getName() != "InheritFromCapabilities") {
-        CapEntry.EffectivePlatform = Entry.Platforms;
-      } else {
-        CapEntry.EffectivePlatform = CapSupport; // explicit capability support or InheritFromCapabilities mode
+
+    StringRef ExtName = Ext->getValueAsString("ExtName");
+    const Record *ExtSupport = Ext->getValueAsDef("ExtSupport");
+    bool IsExperimental = Ext->getValueAsBit("Experimental");
+
+    // Look up or create merged extension entry via map
+    if (ExtIndex.find(ExtName) == ExtIndex.end()) {
+      ExtIndex[ExtName] = Result.size();
+      Result.push_back(ExtensionEntry{});
+      Result.back().Name = ExtName;
+      Result.back().SpecURL = Ext->getValueAsString("ExtSpecURL");
+      Result.back().Root = Ext;
+    }
+    ExtensionEntry &Entry = Result[ExtIndex[ExtName]];
+
+    // Assign variant-specific platform support
+    (IsExperimental ? Entry.ExperimentalSupport : Entry.ProductionSupport) = ExtSupport;
+
+    // Merge capabilities by name and set variant-specific effective platform
+    bool ExtAggregateMode = (ExtSupport->getName() == "InheritFromCapabilities");
+    for (const Record *Cap : Ext->getValueAsListOfDefs("ExtCapabilities")) {
+      StringRef CapName = Cap->getValueAsString("Name");
+      CapabilityEntry *CapEntry = nullptr;
+      for (auto &CE : Entry.Capabilities) {
+        if (CE.Name == CapName) {
+          CapEntry = &CE;
+          break;
+        }
       }
-      Entry.Capabilities.push_back(CapEntry);
+      if (!CapEntry) {
+        Entry.Capabilities.push_back(CapabilityEntry{});
+        CapEntry = &Entry.Capabilities.back();
+        CapEntry->Name = CapName;
+        CapEntry->Root = Cap;
+      }
+
+      const Record *CapSupport = Cap->getValueAsDef("Support");
+      const Record *Effective =
+          (CapSupport->getName() == "InheritFromExtension" && !ExtAggregateMode) ? ExtSupport : CapSupport;
+
+      (IsExperimental ? CapEntry->ExperimentalSupport : CapEntry->ProductionSupport) = Effective;
     }
-    Result.push_back(std::move(Entry));
   }
   return Result;
 }

IGC/AdaptorOCL/Utils/IGCCSPIRVSupportTblGen/IGCCSPIRVSupportTblGen.cpp

@@ -62,23 +62,30 @@ void SPIRVSupportDocsEmitter::emit(raw_ostream &OS) {
   OS << "This document lists all SPIR-V extensions supported by IGC and their platform requirements.\n\n";
   for (const auto &Ext : Extensions) {
     OS << "## " << Ext.Name << "\n\n";
-    if (Ext.IsExperimental) {
-      OS << "> **Note**: The support for this extension is experimental. It has been implemented but has not been "
-            "thoroughly tested "
-            "and should not be used in production environments.\n\n";
+    bool HasProd = (Ext.ProductionSupport != nullptr);
+    bool HasExp = (Ext.ExperimentalSupport != nullptr);
+    OS << "**Specification**: " << Ext.SpecURL << "\n\n";
+    // Print explicit extension platform support when not inheriting from capabilities
+    if (HasProd && Ext.ProductionSupport->getName() != "InheritFromCapabilities") {
+      OS << "> **Supported on**: " << formatPlatformSupport(Ext.ProductionSupport) << "\n\n";
     }
-    OS << "**Specification:** " << Ext.SpecURL << "\n\n";
-    if (!Ext.IsInheritFromCapabilitiesMode) {
-      OS << "**Extension Platform Support:** " << formatPlatformSupport(Ext.Platforms) << "\n\n";
+    if (HasExp && Ext.ExperimentalSupport->getName() != "InheritFromCapabilities") {
+      OS << "> **Experimentally supported on**: " << formatPlatformSupport(Ext.ExperimentalSupport) << "\n\n";
     }
-    OS << "**Capabilities:**\n\n";
+    OS << "**Capabilities**:\n\n";
     if (Ext.Capabilities.empty()) {
       OS << "- No capabilities defined\n";
     } else {
       for (const auto &Cap : Ext.Capabilities) {
         OS << "- **" << Cap.Name << "**";
-        if (shouldShowCapabilityPlatformSupport(Ext, Cap))
-          OS << "\n  - Platform Support: " << formatPlatformSupport(Cap.EffectivePlatform);
+        if (shouldShowCapabilityPlatformSupport(Ext, Cap)) {
+          if (Cap.ProductionSupport) {
+            OS << "\n  > **Supported On**: " << formatPlatformSupport(Cap.ProductionSupport);
+          }
+          if (Cap.ExperimentalSupport) {
+            OS << "\n  > **Experimentally supported on**: " << formatPlatformSupport(Cap.ExperimentalSupport);
+          }
+        }
         OS << "\n";
       }
     }
@@ -88,7 +95,11 @@ void SPIRVSupportDocsEmitter::emit(raw_ostream &OS) {
 
 bool SPIRVSupportDocsEmitter::shouldShowCapabilityPlatformSupport(const ExtensionEntry &Ext,
                                                                   const CapabilityEntry &Cap) const {
-  if (Ext.IsInheritFromCapabilitiesMode)
+  // Show capability platform support if extension inherits from capabilities in any variant,
+  // or if the capability specified explicit support (not InheritFromExtension).
+  bool ExtInherit = (Ext.ProductionSupport && Ext.ProductionSupport->getName() == "InheritFromCapabilities") ||
+                    (Ext.ExperimentalSupport && Ext.ExperimentalSupport->getName() == "InheritFromCapabilities");
+  if (ExtInherit)
     return true;
   const Record *OriginalCapSupport = Cap.Root->getValueAsDef("Support");
   return OriginalCapSupport->getName() != "InheritFromExtension";
@@ -281,7 +292,7 @@ class SPIRVSupportQueriesEmitter {
   void emitGetSupportedInfoFn(raw_ostream &OS);
   std::string buildPredicate(const Record *Support, StringRef platformVar);
   void emitSingleExtensionSupportIf(raw_ostream &OS, const ExtensionEntry &Ext);
-  void emitSingleCapabilitySupportIf(raw_ostream &OS, StringRef CapName, const Record *Support);
+  void emitSingleCapabilitySupportIf(raw_ostream &OS, const CapabilityEntry &Cap);
   std::string buildAutoExtensionPredicate(const ExtensionEntry &Ext);
 
 public:
@@ -321,14 +332,15 @@ void SPIRVSupportQueriesEmitter::emitSPIRVExtensionStructures(raw_ostream &OS) {
   OS << "  std::string Name;\n";
   OS << "  std::string SpecURL;\n";
   OS << "  std::vector<SPIRVCapability> Capabilities;\n";
-  OS << "  bool IsExperimental;\n";
   OS << "};\n\n";
 }
 
 void SPIRVSupportQueriesEmitter::emitForwardDecls(raw_ostream &OS) {
   OS << "// Forward declarations\n";
-  OS << "inline bool isExtensionSupported(const std::string& ExtensionName, PLATFORM Platform);\n";
-  OS << "inline bool isCapabilitySupported(const std::string& CapabilityName, PLATFORM Platform);\n\n";
+  OS << "inline bool isExtensionSupported(const std::string& ExtensionName, PLATFORM Platform, bool "
+        "includeExperimental);\n";
+  OS << "inline bool isCapabilitySupported(const std::string& CapabilityName, PLATFORM Platform, bool "
+        "includeExperimental);\n\n";
 }
 
 void SPIRVSupportQueriesEmitter::emitExtensionsVector(raw_ostream &OS) {
@@ -346,8 +358,7 @@ void SPIRVSupportQueriesEmitter::emitExtensionsVector(raw_ostream &OS) {
         OS << ",";
       OS << "\n";
     }
-    OS << "    },\n";
-    OS << "    " << (Ext.IsExperimental ? "true" : "false") << "\n";
+    OS << "    }\n";
     OS << "  }" << (std::next(It) != Extensions.end() ? "," : "") << "\n";
   }
   OS << "};\n\n";
@@ -361,49 +372,64 @@ std::string SPIRVSupportQueriesEmitter::buildAutoExtensionPredicate(const Extens
   for (const auto &Cap : Ext.Capabilities) {
     if (!First)
       Expr += " || ";
-    Expr += "isCapabilitySupported(\"" + Cap.Name.str() + "\", Platform)";
+    Expr += "isCapabilitySupported(\"" + Cap.Name.str() + "\", Platform, includeExperimental)";
     First = false;
   }
   return Expr;
 }
 
 void SPIRVSupportQueriesEmitter::emitSingleExtensionSupportIf(raw_ostream &OS, const ExtensionEntry &Ext) {
   OS << "  if (ExtensionName == \"" << Ext.Name << "\") {\n";
-  if (Ext.IsInheritFromCapabilitiesMode) {
-    OS << "    return " << buildAutoExtensionPredicate(Ext) << ";\n";
-  } else {
-    OS << "    return " << buildPredicate(Ext.Platforms, "Platform") << ";\n";
+  // Experimental variant (gated by includeExperimental)
+  if (Ext.ExperimentalSupport) {
+    OS << "    if (includeExperimental) {\n";
+    if (Ext.ExperimentalSupport->getName() == "InheritFromCapabilities") {
+      OS << "      if (" << buildAutoExtensionPredicate(Ext) << ") return true;\n";
+    } else {
+      OS << "      if (" << buildPredicate(Ext.ExperimentalSupport, "Platform") << ") return true;\n";
+    }
+    OS << "    }\n";
+  }
+  // Production variant
+  if (Ext.ProductionSupport) {
+    if (Ext.ProductionSupport->getName() == "InheritFromCapabilities") {
+      OS << "    if (" << buildAutoExtensionPredicate(Ext) << ") return true;\n";
+    } else {
+      OS << "    if (" << buildPredicate(Ext.ProductionSupport, "Platform") << ") return true;\n";
+    }
   }
   OS << "  }\n";
 }
 
-void SPIRVSupportQueriesEmitter::emitSingleCapabilitySupportIf(raw_ostream &OS, StringRef CapName,
-                                                               const Record *Support) {
-  OS << "  if (CapabilityName == \"" << CapName << "\") {\n";
-  OS << "    return " << buildPredicate(Support, "Platform") << ";\n";
+void SPIRVSupportQueriesEmitter::emitSingleCapabilitySupportIf(raw_ostream &OS, const CapabilityEntry &Cap) {
+  OS << "  if (CapabilityName == \"" << Cap.Name << "\") {\n";
+  if (Cap.ExperimentalSupport) {
+    OS << "    if (includeExperimental) {\n";
+    OS << "      if (" << buildPredicate(Cap.ExperimentalSupport, "Platform") << ") return true;\n";
+    OS << "    }\n";
+  }
+  if (Cap.ProductionSupport) {
+    OS << "    if (" << buildPredicate(Cap.ProductionSupport, "Platform") << ") return true;\n";
+  }
   OS << "  }\n";
 }
 
 void SPIRVSupportQueriesEmitter::emitExtensionSupportFn(raw_ostream &OS) {
   OS << "// Individual extension/capability query functions\n";
-  OS << "inline bool isExtensionSupported(const std::string& ExtensionName, PLATFORM Platform) {\n";
+  OS << "inline bool isExtensionSupported(const std::string& ExtensionName, PLATFORM Platform, bool "
+        "includeExperimental) {\n";
   for (const auto &Ext : Extensions)
     emitSingleExtensionSupportIf(OS, Ext);
   OS << "  return false;\n";
   OS << "}\n\n";
 }
 
 void SPIRVSupportQueriesEmitter::emitCapabilitySupportFn(raw_ostream &OS) {
-  OS << "inline bool isCapabilitySupported(const std::string& CapabilityName, PLATFORM Platform) {\n";
-  SmallSet<StringRef, 32> Seen;
+  OS << "inline bool isCapabilitySupported(const std::string& CapabilityName, PLATFORM Platform, bool "
+        "includeExperimental) {\n";
   for (const auto &Ext : Extensions) {
     for (const auto &Cap : Ext.Capabilities) {
-      if (!Seen.insert(Cap.Name).second) {
-        PrintFatalError(Cap.Root->getLoc(), "Duplicate capability name '" + Cap.Name.str() +
-                                                "' encountered in extension '" + Ext.Name.str() +
-                                                "'. Capability names must be unique.");
-      }
-      emitSingleCapabilitySupportIf(OS, Cap.Name, Cap.EffectivePlatform);
+      emitSingleCapabilitySupportIf(OS, Cap);
     }
   }
   OS << "  return false;\n";
@@ -416,16 +442,12 @@ void SPIRVSupportQueriesEmitter::emitGetSupportedInfoFn(raw_ostream &OS) {
         "false) {\n";
   OS << "  std::vector<SPIRVExtension> SupportedExtensions;\n";
   OS << "  for (const auto& Ext : AllExtensions) {\n";
-  OS << "    if (!includeExperimental && Ext.IsExperimental) {\n";
-  OS << "      continue;\n";
-  OS << "    }\n";
-  OS << "    if (isExtensionSupported(Ext.Name, Platform)) {\n";
+  OS << "    if (isExtensionSupported(Ext.Name, Platform, includeExperimental)) {\n";
   OS << "      SPIRVExtension SupportedExt;\n";
   OS << "      SupportedExt.Name = Ext.Name;\n";
   OS << "      SupportedExt.SpecURL = Ext.SpecURL;\n";
-  OS << "      SupportedExt.IsExperimental = Ext.IsExperimental;\n";
   OS << "      for (const auto& Cap : Ext.Capabilities) {\n";
-  OS << "        if (isCapabilitySupported(Cap.Name, Platform)) {\n";
+  OS << "        if (isCapabilitySupported(Cap.Name, Platform, includeExperimental)) {\n";
   OS << "          SupportedExt.Capabilities.push_back(Cap);\n";
   OS << "        }\n";
   OS << "      }\n";

IGC/AdaptorOCL/ocl_igc_interface/extensions/SPIRVExtensions_Common.td

@@ -96,6 +96,26 @@ SPDX-License-Identifier: MIT
 //    - If you want uniform platform support → use regular extension with explicit platform
 //    - If you want per-capability platform support → use InheritFromCapabilities
 //    - No mixing of the two approaches in a single extension
+//
+// 5. DUAL EXTENSION DEFINITIONS (OFFICIAL + EXPERIMENTAL):
+//
+//    It is valid to describe the same SPIR-V extension name with two
+//    TableGen records when some platforms support it experimentally and
+//    others officially. Example pattern:
+//
+//      def SPV_INTEL_example : Extension<              // official support
+//        "SPV_INTEL_example",
+//        [ Capability<"ExampleCapabilityINTEL"> ],
+//        "https://example.com/spec/SPV_INTEL_example.asciidoc",
+//        SOME_OFFICIAL_PLATFORM_PREDICATE
+//      >;
+//
+//      def SPV_INTEL_example_experimental : ExperimentalExtension< // experimental
+//        "SPV_INTEL_example",   // same SPIR-V extension string
+//        [ Capability<"ExampleCapabilityINTEL"> ],
+//        "https://example.com/spec/SPV_INTEL_example.asciidoc",
+//        SOME_EXPERIMENTAL_PLATFORM_PREDICATE
+//      >;
 
 class Platform<string ProductFamilyEnum> {
   string ProductFamily = ProductFamilyEnum;