Preliminary debugBreak support (#2647)

* #include an absolute path didn't work - because paths were taken to always be relative.

* Preliminary support for debug break.

* Add C++ debug break support.
Add details about usage.

* Improve debug break test details.

* Make HLSL output a comment about no support.

* Handle specialize for target assert, without a body if it has spv_instruction/target intrinsic

1 files changed, 15 insertions, 1 deletions

diff --git a/docs/target-compatibility.md b/docs/target-compatibility.md
index 08819ac17..7769fe8db 100644
--- a/docs/target-compatibility.md
+++ b/docs/target-compatibility.md
@@ -42,6 +42,7 @@ Items with ^ means there is some discussion about support later in the document
 | Atomics on RWBuffer         |     Yes      |   Yes        |   Yes      |     No        |    No + 
 | Sampler Feedback            |     No       |   Yes        |   No +     |     No        |    Yes ^
 | RWByteAddressBuffer Atomic  |     No       |   Yes ^      |   Yes ^    |     Yes       |    No +
+| debugBreak                  |     No       |   No         |   Yes      |     Yes       |    Yes
 
 ## Half Type
 
@@ -223,4 +224,17 @@ in the separate [NVAPI Support](nvapi-support.md) document.
 
 On Vulkan, for float the [`GL_EXT_shader_atomic_float`](https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_shader_atomic_float.html) extension is required. For int64 the [`GL_EXT_shader_atomic_int64`](https://raw.githubusercontent.com/KhronosGroup/GLSL/master/extensions/ext/GL_EXT_shader_atomic_int64.txt) extension is required.
 
-CUDA requires SM6.0 or higher for int64 support. 
+CUDA requires SM6.0 or higher for int64 support.
+
+## debugBreak
+
+Slang has preliminary support for `debugBreak()` intrinsic. With the appropriate tooling, when `debugBreak` is hit it will cause execution to halt and display in the attached debugger.
+
+Currently this is supported in all targets except HLSL. Note that on some targets if there isn't an appropriate debugging environment the debugBreak might cause execution to fail or potentially it is ignored. 
+
+On C++ targets debugBreak is implemented using SLANG_BREAKPOINT defined in "slang-cpp-prelude.h". If there isn't a suitable intrinsic, this will default to attempting to write to `nullptr` leading to a crash. 
+
+Some additional details:
+
+* If [slang-llvm](cpu-target.md#slang-llvm) is being used as the downstream compiler (as is typical with `host-callable`), it will crash into the debugger, but may not produce a usable stack trace.
+* For "normal" C++ downstream compilers such as Clang/Gcc/Visual Studio, to break into readable source code, debug information is typically necessary. Disabling optimizations may be useful to break on the appropriate specific line, and have variables inspectable.
\ No newline at end of file