[OMM] Add AllocateRayQuery2 DXIL Op, add validation (microsoft#7124)

bob80905 · github-actions[bot] · web-flow · commit 0a1143572d10 · 2025-02-28T16:05:31.000-08:00
This PR adds AllocateRayQuery2 as a new DXIL Op, which is intended to be the DXIL Op that any rayquery object initialized with the 2nd optional template argument will be lowered to. Additionally, according to the spec here: https://github.com/microsoft/hlsl-specs/blob/main/proposals/0024-opacity-micromaps.md there are new validation rules that should be run against the allocateRayQuery* DXIL Ops. This PR implements these validation rules, and tests them. Fixes microsoft#7113 --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
diff --git a/include/dxc/DXIL/DxilConstants.h b/include/dxc/DXIL/DxilConstants.h
@@ -475,63 +475,62 @@ inline bool IsFeedbackTexture(DXIL::ResourceKind ResourceKind) {
 // Enumeration for operations specified by DXIL
 enum class OpCode : unsigned {
   //
-  AllocateRayQuery2 = 258, // reserved
-  Reserved0 = 226,         // Reserved
-  Reserved1 = 227,         // Reserved
-  Reserved10 = 236,        // Reserved
-  Reserved11 = 237,        // Reserved
-  Reserved2 = 228,         // Reserved
-  Reserved3 = 229,         // Reserved
-  Reserved4 = 230,         // Reserved
-  Reserved5 = 231,         // Reserved
-  Reserved6 = 232,         // Reserved
-  Reserved7 = 233,         // Reserved
-  Reserved8 = 234,         // Reserved
-  Reserved9 = 235,         // Reserved
-  ReservedA0 = 259,        // reserved
-  ReservedA1 = 260,        // reserved
-  ReservedA2 = 261,        // reserved
-  ReservedB0 = 262,        // reserved
-  ReservedB1 = 263,        // reserved
-  ReservedB10 = 272,       // reserved
-  ReservedB11 = 273,       // reserved
-  ReservedB12 = 274,       // reserved
-  ReservedB13 = 275,       // reserved
-  ReservedB14 = 276,       // reserved
-  ReservedB15 = 277,       // reserved
-  ReservedB16 = 278,       // reserved
-  ReservedB17 = 279,       // reserved
-  ReservedB18 = 280,       // reserved
-  ReservedB19 = 281,       // reserved
-  ReservedB2 = 264,        // reserved
-  ReservedB20 = 282,       // reserved
-  ReservedB21 = 283,       // reserved
-  ReservedB22 = 284,       // reserved
-  ReservedB23 = 285,       // reserved
-  ReservedB24 = 286,       // reserved
-  ReservedB25 = 287,       // reserved
-  ReservedB26 = 288,       // reserved
-  ReservedB27 = 289,       // reserved
-  ReservedB28 = 290,       // reserved
-  ReservedB29 = 291,       // reserved
-  ReservedB3 = 265,        // reserved
-  ReservedB30 = 292,       // reserved
-  ReservedB4 = 266,        // reserved
-  ReservedB5 = 267,        // reserved
-  ReservedB6 = 268,        // reserved
-  ReservedB7 = 269,        // reserved
-  ReservedB8 = 270,        // reserved
-  ReservedB9 = 271,        // reserved
-  ReservedC0 = 293,        // reserved
-  ReservedC1 = 294,        // reserved
-  ReservedC2 = 295,        // reserved
-  ReservedC3 = 296,        // reserved
-  ReservedC4 = 297,        // reserved
-  ReservedC5 = 298,        // reserved
-  ReservedC6 = 299,        // reserved
-  ReservedC7 = 300,        // reserved
-  ReservedC8 = 301,        // reserved
-  ReservedC9 = 302,        // reserved
+  Reserved0 = 226,   // Reserved
+  Reserved1 = 227,   // Reserved
+  Reserved10 = 236,  // Reserved
+  Reserved11 = 237,  // Reserved
+  Reserved2 = 228,   // Reserved
+  Reserved3 = 229,   // Reserved
+  Reserved4 = 230,   // Reserved
+  Reserved5 = 231,   // Reserved
+  Reserved6 = 232,   // Reserved
+  Reserved7 = 233,   // Reserved
+  Reserved8 = 234,   // Reserved
+  Reserved9 = 235,   // Reserved
+  ReservedA0 = 259,  // reserved
+  ReservedA1 = 260,  // reserved
+  ReservedA2 = 261,  // reserved
+  ReservedB0 = 262,  // reserved
+  ReservedB1 = 263,  // reserved
+  ReservedB10 = 272, // reserved
+  ReservedB11 = 273, // reserved
+  ReservedB12 = 274, // reserved
+  ReservedB13 = 275, // reserved
+  ReservedB14 = 276, // reserved
+  ReservedB15 = 277, // reserved
+  ReservedB16 = 278, // reserved
+  ReservedB17 = 279, // reserved
+  ReservedB18 = 280, // reserved
+  ReservedB19 = 281, // reserved
+  ReservedB2 = 264,  // reserved
+  ReservedB20 = 282, // reserved
+  ReservedB21 = 283, // reserved
+  ReservedB22 = 284, // reserved
+  ReservedB23 = 285, // reserved
+  ReservedB24 = 286, // reserved
+  ReservedB25 = 287, // reserved
+  ReservedB26 = 288, // reserved
+  ReservedB27 = 289, // reserved
+  ReservedB28 = 290, // reserved
+  ReservedB29 = 291, // reserved
+  ReservedB3 = 265,  // reserved
+  ReservedB30 = 292, // reserved
+  ReservedB4 = 266,  // reserved
+  ReservedB5 = 267,  // reserved
+  ReservedB6 = 268,  // reserved
+  ReservedB7 = 269,  // reserved
+  ReservedB8 = 270,  // reserved
+  ReservedB9 = 271,  // reserved
+  ReservedC0 = 293,  // reserved
+  ReservedC1 = 294,  // reserved
+  ReservedC2 = 295,  // reserved
+  ReservedC3 = 296,  // reserved
+  ReservedC4 = 297,  // reserved
+  ReservedC5 = 298,  // reserved
+  ReservedC6 = 299,  // reserved
+  ReservedC7 = 300,  // reserved
+  ReservedC8 = 301,  // reserved
+  ReservedC9 = 302,  // reserved
 
   // Amplification shader instructions
   DispatchMesh = 173, // Amplification shader intrinsic DispatchMesh
@@ -680,8 +679,9 @@ enum class OpCode : unsigned {
   TraceRay = 157,   // initiates raytrace
 
   // Inline Ray Query
-  AllocateRayQuery = 178, // allocates space for RayQuery and return handle
-  RayQuery_Abort = 181,   // aborts a ray query
+  AllocateRayQuery = 178,  // allocates space for RayQuery and return handle
+  AllocateRayQuery2 = 258, // allocates space for RayQuery and return handle
+  RayQuery_Abort = 181,    // aborts a ray query
   RayQuery_CandidateGeometryIndex = 203, // returns candidate hit geometry index
   RayQuery_CandidateInstanceContributionToHitGroupIndex =
       214, // returns candidate hit InstanceContributionToHitGroupIndex
@@ -1151,6 +1151,7 @@ enum class OpCodeClass : unsigned {
 
   // Inline Ray Query
   AllocateRayQuery,
+  AllocateRayQuery2,
   RayQuery_Abort,
   RayQuery_CommitNonOpaqueTriangleHit,
   RayQuery_CommitProceduralPrimitiveHit,
@@ -1337,7 +1338,7 @@ enum class OpCodeClass : unsigned {
   NumOpClasses_Dxil_1_7 = 153,
   NumOpClasses_Dxil_1_8 = 174,
 
-  NumOpClasses = 174 // exclusive last value of enumeration
+  NumOpClasses = 175 // exclusive last value of enumeration
 };
 // OPCODECLASS-ENUM:END
 
@@ -1819,8 +1820,12 @@ enum class RayFlag : uint32_t {
   CullNonOpaque = 0x80,
   SkipTriangles = 0x100,
   SkipProceduralPrimitives = 0x200,
+  ForceOMM2State = 0x400, // Force 2-state in Opacity Micromaps
 };
 
+// Corresponds to RAYQUERY_FLAG_* in HLSL
+enum class RayQueryFlag : uint32_t { None = 0, AllowOpacityMicromaps = 1 };
+
 // Packing/unpacking intrinsics
 enum class UnpackMode : uint8_t {
   Unsigned = 0, // not sign extended
@@ -2002,7 +2007,9 @@ enum class RaytracingPipelineFlags : uint32_t {
   None = 0x0,
   SkipTriangles = 0x100,
   SkipProceduralPrimitives = 0x200,
-  ValidMask = 0x300,
+  ValidMask_1_8 = 0x300,         // valid mask up through DXIL 1.8
+  AllowOpacityMicromaps = 0x400, // Allow Opacity Micromaps to be used
+  ValidMask = 0x700,             // current valid mask
 };
 
 enum class CommittedStatus : uint32_t {
diff --git a/include/dxc/DXIL/DxilInstructions.h b/include/dxc/DXIL/DxilInstructions.h
@@ -8765,5 +8765,53 @@ struct DxilInst_StartInstanceLocation {
   // Metadata
   bool requiresUniformInputs() const { return false; }
 };
+
+/// This instruction allocates space for RayQuery and return handle
+struct DxilInst_AllocateRayQuery2 {
+  llvm::Instruction *Instr;
+  // Construction and identification
+  DxilInst_AllocateRayQuery2(llvm::Instruction *pInstr) : Instr(pInstr) {}
+  operator bool() const {
+    return hlsl::OP::IsDxilOpFuncCallInst(Instr,
+                                          hlsl::OP::OpCode::AllocateRayQuery2);
+  }
+  // Validation support
+  bool isAllowed() const { return true; }
+  bool isArgumentListValid() const {
+    if (3 != llvm::dyn_cast<llvm::CallInst>(Instr)->getNumArgOperands())
+      return false;
+    return true;
+  }
+  // Metadata
+  bool requiresUniformInputs() const { return false; }
+  // Operand indexes
+  enum OperandIdx {
+    arg_constRayFlags = 1,
+    arg_constRayQueryFlags = 2,
+  };
+  // Accessors
+  llvm::Value *get_constRayFlags() const { return Instr->getOperand(1); }
+  void set_constRayFlags(llvm::Value *val) { Instr->setOperand(1, val); }
+  uint32_t get_constRayFlags_val() const {
+    return (uint32_t)(llvm::dyn_cast<llvm::ConstantInt>(Instr->getOperand(1))
+                          ->getZExtValue());
+  }
+  void set_constRayFlags_val(uint32_t val) {
+    Instr->setOperand(1, llvm::Constant::getIntegerValue(
+                             llvm::IntegerType::get(Instr->getContext(), 32),
+                             llvm::APInt(32, (uint64_t)val)));
+  }
+  llvm::Value *get_constRayQueryFlags() const { return Instr->getOperand(2); }
+  void set_constRayQueryFlags(llvm::Value *val) { Instr->setOperand(2, val); }
+  uint32_t get_constRayQueryFlags_val() const {
+    return (uint32_t)(llvm::dyn_cast<llvm::ConstantInt>(Instr->getOperand(2))
+                          ->getZExtValue());
+  }
+  void set_constRayQueryFlags_val(uint32_t val) {
+    Instr->setOperand(2, llvm::Constant::getIntegerValue(
+                             llvm::IntegerType::get(Instr->getContext(), 32),
+                             llvm::APInt(32, (uint64_t)val)));
+  }
+};
 // INSTR-HELPER:END
 } // namespace hlsl
diff --git a/include/dxc/DxilContainer/RDAT_SubobjectTypes.inl b/include/dxc/DxilContainer/RDAT_SubobjectTypes.inl
@@ -69,9 +69,10 @@ RDAT_DXIL_ENUM_START(hlsl::DXIL::RaytracingPipelineFlags, uint32_t)
   RDAT_ENUM_VALUE_NODEF(SkipProceduralPrimitives)
   // No need to define mask here
   // RDAT_ENUM_VALUE_NODEF(ValidMask)
+  RDAT_ENUM_VALUE_NODEF(AllowOpacityMicromaps)
 #if DEF_RDAT_ENUMS == DEF_RDAT_DUMP_IMPL
   static_assert((unsigned)hlsl::DXIL::RaytracingPipelineFlags::ValidMask ==
-                    0x300,
+                    0x700,
                 "otherwise, RDAT_DXIL_ENUM definition needs updating");
 #endif
 RDAT_ENUM_END()
diff --git a/lib/DXIL/DxilOperations.cpp b/lib/DXIL/DxilOperations.cpp
@@ -2603,16 +2603,19 @@ const OP::OpCodeProperty OP::m_OpCodeProps[(unsigned)OP::OpCode::NumOpCodes] = {
         Attribute::ReadNone,
     },
 
-    //                                                                                                                         void,     h,     f,     d,    i1,    i8,   i16,   i32,   i64,   udt,   obj ,  function attribute
+    // Inline Ray Query void,     h,     f,     d,    i1,    i8,   i16,   i32,
+    // i64,   udt,   obj ,  function attribute
     {
         OC::AllocateRayQuery2,
         "AllocateRayQuery2",
-        OCC::Reserved,
-        "reserved",
+        OCC::AllocateRayQuery2,
+        "allocateRayQuery2",
         {true, false, false, false, false, false, false, false, false, false,
          false},
         Attribute::None,
     },
+
+    //                                                                                                                         void,     h,     f,     d,    i1,    i8,   i16,   i32,   i64,   udt,   obj ,  function attribute
     {
         OC::ReservedA0,
         "ReservedA0",
@@ -3741,6 +3744,12 @@ void OP::GetMinShaderModelAndMask(OpCode C, bool bWithTranslation,
     }
     return;
   }
+  // Instructions: AllocateRayQuery2=258
+  if (op == 258) {
+    major = 6;
+    minor = 9;
+    return;
+  }
   // OPCODE-SMMASK:END
 }
 
@@ -5829,11 +5838,15 @@ Function *OP::GetOpFunc(OpCode opCode, Type *pOverloadType) {
     A(pI32);
     break;
 
-    //
+    // Inline Ray Query
   case OpCode::AllocateRayQuery2:
-    A(pV);
+    A(pI32);
+    A(pI32);
+    A(pI32);
     A(pI32);
     break;
+
+    //
   case OpCode::ReservedA0:
     A(pV);
     A(pI32);
diff --git a/lib/DxilValidation/DxilValidation.cpp b/lib/DxilValidation/DxilValidation.cpp
@@ -1708,6 +1708,41 @@ static void ValidateDxilOperationCallInProfile(CallInst *CI,
     ValidateSignatureDxilOp(CI, opcode, ValCtx);
     break;
   // Special.
+  case DXIL::OpCode::AllocateRayQuery: {
+    // validate flags are immediate and compatible
+    llvm::Value *constRayFlag = CI->getOperand(1);
+    if (!llvm::isa<llvm::Constant>(constRayFlag)) {
+      ValCtx.EmitInstrError(CI,
+                            ValidationRule::DeclAllocateRayQueryFlagsAreConst);
+    }
+    break;
+  }
+  case DXIL::OpCode::AllocateRayQuery2: {
+    // validate flags are immediate and compatible
+    llvm::Value *constRayFlag = CI->getOperand(1);
+    llvm::Value *RayQueryFlag = CI->getOperand(2);
+    if (!llvm::isa<llvm::Constant>(constRayFlag) ||
+        !llvm::isa<llvm::Constant>(RayQueryFlag)) {
+      ValCtx.EmitInstrError(CI,
+                            ValidationRule::DeclAllocateRayQuery2FlagsAreConst);
+      break;
+    }
+    // When the ForceOMM2State ConstRayFlag is given as an argument to
+    // a RayQuery object, AllowOpacityMicromaps is expected
+    // as a RayQueryFlag argument
+    llvm::ConstantInt *Arg1 = llvm::cast<llvm::ConstantInt>(constRayFlag);
+    llvm::ConstantInt *Arg2 = llvm::cast<llvm::ConstantInt>(RayQueryFlag);
+    if ((Arg1->getValue().getSExtValue() &
+         (unsigned)DXIL::RayFlag::ForceOMM2State) &&
+        (Arg2->getValue().getSExtValue() &
+         (unsigned)DXIL::RayQueryFlag::AllowOpacityMicromaps) == 0) {
+      ValCtx.EmitInstrError(
+          CI,
+          ValidationRule::DeclAllowOpacityMicromapsExpectedGivenForceOMM2State);
+    }
+    break;
+  }
+
   case DXIL::OpCode::BufferUpdateCounter: {
     DxilInst_BufferUpdateCounter updateCounter(CI);
     Value *handle = updateCounter.get_uav();
diff --git a/tools/clang/test/DXILValidation/allocateRayQuery.ll b/tools/clang/test/DXILValidation/allocateRayQuery.ll
@@ -0,0 +1,60 @@
+; RUN: not %dxv %s 2>&1 | FileCheck %s
+
+target datalayout = "e-m:e-p:32:32-i1:32-i8:32-i16:32-i32:32-i64:64-f16:32-f32:32-f64:64-n8:16:32:64"
+target triple = "dxil-ms-dx"
+
+%dx.types.Handle = type { i8* }
+%dx.types.ResBind = type { i32, i32, i32, i8 }
+%dx.types.ResourceProperties = type { i32, i32 }
+%struct.RaytracingAccelerationStructure = type { i32 }
+@nonconstVal = global i32 5
+
+define void @main() {
+  %ptr = getelementptr i32, i32* @nonconstVal, i32 0 ; Get the pointer to the global variable
+  %val = load i32, i32* %ptr ; Dereference the pointer to load the value
+
+  ; test that allocateRayQuery requires constant args
+  ; CHECK: error: constRayFlags argument of AllocateRayQuery must be constant
+  ; CHECK: note: at '%1 = call i32 @dx.op.allocateRayQuery(i32 178, i32 %val)' in block '#0' of function 'main'.
+  %1 = call i32 @dx.op.allocateRayQuery(i32 178, i32 %val)  ; AllocateRayQuery(constRayFlags)
+
+  ret void
+}
+
+; Function Attrs: nounwind
+declare i32 @dx.op.allocateRayQuery(i32, i32) #1
+
+attributes #0 = { nounwind readnone }
+attributes #1 = { nounwind }
+
+!llvm.ident = !{!0}
+!dx.version = !{!1}
+!dx.valver = !{!1}
+!dx.shaderModel = !{!2}
+!dx.resources = !{!3}
+!dx.viewIdState = !{!7}
+!dx.entryPoints = !{!8}
+
+!0 = !{!"dxc(private) 1.8.0.4793 (OMM00, ef1472a14a0d-dirty)"}
+!1 = !{i32 1, i32 9}
+!2 = !{!"vs", i32 6, i32 9}
+!3 = !{!4, null, null, null}
+!4 = !{!5}
+!5 = !{i32 0, %struct.RaytracingAccelerationStructure* undef, !"", i32 0, i32 0, i32 1, i32 16, i32 0, !6}
+!6 = !{i32 0, i32 4}
+!7 = !{[2 x i32] [i32 17, i32 0]}
+!8 = !{void ()* @main, !"main", !9, !3, !22}
+!9 = !{!10, null, null}
+!10 = !{!11, !13, !15, !18, !20}
+!11 = !{i32 0, !"IDX", i8 5, i8 0, !12, i8 0, i32 1, i8 1, i32 0, i8 0, null}
+!12 = !{i32 0}
+!13 = !{i32 1, !"RAYDESC", i8 9, i8 0, !12, i8 0, i32 1, i8 3, i32 1, i8 0, !14}
+!14 = !{i32 3, i32 7}
+!15 = !{i32 2, !"RAYDESC", i8 9, i8 0, !16, i8 0, i32 1, i8 1, i32 2, i8 0, !17}
+!16 = !{i32 1}
+!17 = !{i32 3, i32 1}
+!18 = !{i32 3, !"RAYDESC", i8 9, i8 0, !19, i8 0, i32 1, i8 3, i32 3, i8 0, !14}
+!19 = !{i32 2}
+!20 = !{i32 4, !"RAYDESC", i8 9, i8 0, !21, i8 0, i32 1, i8 1, i32 4, i8 0, !17}
+!21 = !{i32 3}
+!22 = !{i32 0, i64 33554432}
diff --git a/tools/clang/test/DXILValidation/allocateRayQuery2.ll b/tools/clang/test/DXILValidation/allocateRayQuery2.ll
diff --git a/utils/hct/hctdb.py b/utils/hct/hctdb.py
