Document O1experimental fallback guard

Author: AnastaZIuk

tools/clang/lib/SPIRV/SpirvEmitter.cpp

@@ -1573,6 +1573,32 @@ bool SpirvEmitter::handleNodePayloadArrayType(const ParmVarDecl *decl,
   }
 }
 
+// -O1experimental is intended to bundle three effects:
+//   1. the fast optimizer recipe,
+//   2. the targeted loop-unroll behavior,
+//   3. the narrower SSA / composite-resource cleanup needed after (1) and (2)
+//      change the IR shape.
+//
+// (1) and (2) are the main value of the profile and are generally desirable for
+// every shader compiled with -O1experimental. The trouble is that some HLSL
+// type graphs still require more precise handling in the current "special
+// types" cleanup than SPIRV-Tools provides today. In particular, nested
+// AliasedPointer / BDA wrappers and opaque composite resources can reach the
+// fast path and produce invalid SPIR-V if we let the current cleanup touch
+// them blindly.
+//
+// This producer-side scan is therefore a safety valve: if a risky type appears
+// anywhere in the type graph, we force the module back to the default SPIR-V
+// path instead of letting the experimental fast profile emit invalid code.
+// We are taking this route as a tactical stopgap because there was not enough
+// time to finish a sound, more selective SPIRV-Tools-side implementation of
+// the "special types" cleanup before wiring the profile through the PR stack.
+//
+// The preferred long-term shape is narrower than this guard: keep the fast
+// recipe and loop-unroll behavior for every -O1experimental module, and make
+// the "special types" cleanup in SPIRV-Tools selective enough that only the
+// truly risky part of (3) is disabled. Until that path is sound, this
+// conservative fallback keeps the profile correct.
 void SpirvEmitter::noteExperimentalFastCompileRisk(
     QualType type, bool hasAliasedPointerAttr) {
   if (!spirvOptions.o1ExperimentalFastCompile || type.isNull())
@@ -16757,6 +16783,12 @@ bool SpirvEmitter::spirvToolsOptimize(std::vector<uint32_t> *mod,
 }
 
 bool SpirvEmitter::useSpirvFastCompileProfile() const {
+  // This currently gates the whole experimental profile, not just the narrow
+  // "special types" cleanup. That is intentionally conservative for now:
+  // correctness wins over preserving the fast recipe on unsupported type
+  // shapes. Once SPIRV-Tools can scope the risky part of the cleanup more
+  // precisely, -O1experimental should keep the fast recipe / unroll path and
+  // only disable the problematic subset of the rewrite logic.
   return spirvOptions.o1ExperimentalFastCompile &&
          spirvOptions.optConfig.empty() &&
          !experimentalFastCompileRequiresDefaultPath &&