Add 'IsDebuggerPresent' and detail DebugBreak more (#752)

**HLSL Debugging Intrinsics**

- **Broadened Proposal Scope**: The proposal now covers two new
debugging intrinsics:
  - `DebugBreak()`: Triggers a breakpoint when a debugger is attached.
- `dx::IsDebuggerPresent()`: Returns whether a graphics debugger is
currently attached (DirectX only).

- **Motivation Expanded**: Highlights the need for conditional debug
checks and selective breakpoints, allowing shader authors to perform
expensive debugging operations only when needed.

- **Detailed API & Usage Examples**:  
- Provides updated HLSL signatures and usage snippets for both
intrinsics.
- Demonstrates conditional execution of validation code based on
debugger presence.

- **Implementation Details Added**:
- Specifies DXIL lowering for both intrinsics (`dx.op.debugBreak`,
`dx.op.isDebuggerPresent`).
- Clarifies convergence requirements to prevent optimizations that might
move breakpoints.
  - Notes that both intrinsics are only valid in Shader Model 6.10+.
  - Explains runtime and driver behavior.

- **SPIR-V Targeting**:
- Outlines use of `NonSemantic.DebugBreak` for `DebugBreak()` in SPIR-V.
  - Specifies that `dx::IsDebuggerPresent()` has no SPIR-V equivalent.

- **Testing Section**: Introduces compiler, validation, and execution
testing requirements to ensure correct integration and behavior.

Author: JoeCitizen

proposals/0039-debugbreak.md

@@ -1,23 +1,29 @@
 ---
-title: 0039 - DebugBreak()
+title: 0039 - Debugging Intrinsics
 params:
     authors:
     - llvm-beanz: Chris Bieneman
+    - joecitizen: Jack Elliott
     sponsors:
     - llvm-beanz: Chris Bieneman
     status: Under Consideration
 ---
 
-
 
 * Issue(s): https://github.com/microsoft/hlsl-specs/issues/33
 
 ## Introduction
 
-This proposal specifies a new HLSL function `DebugBreak()` which will lower to a
-new DXIL operation described in this spec for DirectX and to the SPIRV
-[NonSemantic.DebugBreak](https://github.khronos.org/SPIRV-Registry/nonsemantic/NonSemantic.DebugBreak.html)
-for SPIRV targets.
+This proposal specifies two new HLSL debugging intrinsics:
+
+1. **`DebugBreak()`**: Triggers a breakpoint when a debugger is attached,
+   allowing developers to pause execution and inspect shader state.
+2. **`dx::IsDebuggerPresent()`**: Returns whether a graphics debugger is currently
+   attached to the process, enabling conditional debug-only code paths.
+
+`DebugBreak()` will lower to new DXIL operations for DirectX and to appropriate
+SPIR-V instructions for Vulkan targets. `dx::IsDebuggerPresent()` is a DirectX
+extension and has no Vulkan/SPIR-V equivalent.
 
 ## Motivation
 
@@ -29,99 +35,177 @@ millions of times without issue, but in one instance produces a bad result.
 Conditional breakpoints can be a powerful tool for shader authors to narrow down
 and identify these complex rare-occurring problems.
 
-This proposal introduces a `DebugBreak()` intrinsic, which can be combined with
-an `assert()` macro implementation to provide support for conditional
-breakpoints in shader code.
+Additionally, shader authors need a way to conditionally enable expensive debug
+checks only when a debugger is attached, avoiding runtime overhead in production
+scenarios.
+
+This proposal introduces two intrinsics that together provide a debugging
+toolkit for shader development.
 
 ## Proposed solution
 
-This proposal introduces a new HLSL intrinsic `DebugBreak()`, a new header
-`assert.h` which will define the `assert()` macro in a C-compatible interface.
+This proposal introduces two new HLSL intrinsics for debugging shader code.
 
-assert.h will provide the following definitions
-```c
-#if NDEBUG
-#define assert(cond) do { } while(false)
-#else
-#define assert(cond) do { if (!cond) DebugBreak();} while(false)
-#endif
-```
+### Intrinsics
 
-This will enable shader authors to write code such as:
+```hlsl
+void DebugBreak();        // Trigger a breakpoint if debugger attached
+bool dx::IsDebuggerPresent(); // Query if a debugger is attached (DirectX only)
+```
 
-```c++
-#include <assert.h>
+### Example Usage
 
+```hlsl
 [numthreads(8,1,1)]
 void main(uint GI : SV_GroupIndex) {
-    assert(GI < 8);
+    // Conditional expensive debug checks
+  if (dx::IsDebuggerPresent()) {
+        // Expensive validation only when debugging
+        ValidateComplexInvariants();
+    }
+    
+    // Manual breakpoint for debugging specific conditions
+    if (someRareCondition) {
+        DebugBreak();
+    }
 }
 ```
 
 This aligns with C/C++ conventions that our users are already familiar with.
 
 ## Detailed Design
 
-This proposal introduces a new HLSL `DebugBreak` intrinsic which has a
-runtime-defined behavior to facilitate shader debugging workflows. If the
-runtime does not support or is not configured to enable support for the
-corresponding DXIL instruction, it must be treated as a no-op by the driver.
-
 ### HLSL Surface
 
-A new `DebugBreak` function is added with the signature:
+Two new intrinsic functions are added:
 
-```
+#### `DebugBreak()`
+
+```hlsl
 void DebugBreak();
 ```
 
-A new header `assert.h` is added and included with the compiler packaging which
-implements the `assert` macro:
+Triggers a breakpoint if a graphics debugger is attached. If no debugger is
+attached or the runtime does not support this operation, it is treated as a
+no-op. Execution continues after the breakpoint.
 
-```c
-#if NDEBUG
-#define assert(cond) do { } while(false)
-#else
-#define assert(cond) do { if (!cond) DebugBreak();} while(false)
-#endif
+#### `dx::IsDebuggerPresent()`
+
+```hlsl
+bool dx::IsDebuggerPresent();
 ```
 
+Returns `true` if a graphics debugger is currently attached to the process,
+`false` otherwise. This allows shader authors to conditionally execute expensive
+debug validation code only when a debugger is present:
+
+```hlsl
+if (dx::IsDebuggerPresent()) {
+    // Expensive bounds checking, validation, etc.
+    for (uint i = 0; i < arraySize; ++i) {
+        if (data[i] < 0.0f || data[i] > 1.0f) {
+            DebugBreak();
+        }
+    }
+}
+```
+
+The value returned is uniform across all threads in a dispatch/draw and remains
+constant for the duration of shader execution.
+
 ### DXIL Lowering
 
-This change introduces a new DXIL operation:
+This change introduces two new DXIL operations:
 
+#### `dx.op.debugBreak`
 
-``` llvm
+```llvm
 declare void @dx.op.debugBreak(
   immarg i32             ; opcode
-)
+) convergent
+```
+
+Triggers a debugger breakpoint. Must be treated as `convergent` to prevent code
+motion. Should not be marked `readonly` or `readnone`. If no debugger is
+attached, this is a no-op.
+
+#### `dx.op.isDebuggerPresent`
+
+```llvm
+declare i1 @dx.op.isDebuggerPresent(
+  immarg i32             ; opcode
+) readonly
 ```
 
-This DXIL operation must be treated as `convergent` even though it is not to
-prevent code motion. It should also not be marked `readonly` or `readnone` even
-though it technically doesn't read memory.
+Returns `true` (1) if a debugger is attached, `false` (0) otherwise. Marked
+`readonly` as it only queries state. 
 
-This instruction will only be valid in a new shader model.
+### Convergence Requirements
 
-Because it is valid to treat this operation as a no-op, it is a required
-supported feature and does not require a capabilities bit.
+`debugBreak` operations must be treated as `convergent` to prevent
+code motion that could change their observable behavior:
+- `debugBreak`: Must break at the exact location specified by the programmer
 
-### SPIRV Lowering
+These operations should not be hoisted, sunk, or duplicated by optimizers.
 
-This change will utilize the existing `NonSemantic.DebugBreak` instruction.
-While this instruction is not widely supported by Vulkan debuggers, it is
-supported by NVIDIA's NSight and can be safely ignored by Vulkan runtimes.
+### Shader Model Requirements
 
-The SPIRV usage will utilize the following instructions:
+These instructions will only be valid in Shader Model 6.10 or later.
+
+Because `DebugBreak()` can be treated as a no-op when no debugger is present,
+it is a required supported feature and does not require a capability bit.
+
+### Runtime Behavior for DebugBreak
+
+It is valid for the runtime to change the behavior of debug break on a
+per-pipeline basis.
+
+Behavioral changes may include:
+
+- Breaking regardless of a debugger being attached
+- Disabling debug break instructions entirely
+
+It is expected that the driver compiler will alter behavior during lowering 
+based on information provided by the runtime at pipeline creation.
+
+### SPIR-V Lowering
+
+#### DebugBreak
+
+Uses the existing `NonSemantic.DebugBreak` instruction:
 
 ```
 %1 = OpExtInstImport "NonSemantic.DebugBreak"
 %2 = OpExtInst %void %1 DebugBreak
 ```
 
+While this instruction is not widely supported by Vulkan debuggers, it is
+supported by NVIDIA's NSight and can be safely ignored by Vulkan runtimes.
+
+No SPIR-V lowering is defined for `dx::IsDebuggerPresent()`.
+
+## Testing
+
+### Compiler Testing
+
+- Verify correct DXIL generation for both intrinsics
+- Verify correct SPIR-V generation for `DebugBreak()` where applicable
+
+### Validation Testing
+
+- Confirm validation accepts the new operations in SM 6.10+
+- Confirm validation rejects operations in earlier shader models
+- Verify convergence requirements are properly validated
+
+### Execution Testing
+
+- Test `DebugBreak()` triggers breakpoint when debugger attached
+- Test `DebugBreak()` is no-op when no debugger present
+- Test `dx::IsDebuggerPresent()` returns correct value based on debugger state
+
 ## Open Questions
 
 * Consider introducing the `convergent` attribute to DXIL.
   * This should be "cheap" and would potentially address pre-existing bugs.
-  * This would preserve the requirement that this operation not be moved during
-    optimization in the final DXIL.
+  * This would preserve the requirement that these operations not be moved
+    during optimization in the final DXIL.