From 879c07be1405b3eadfe3924c1a2b1d3d56fdc9ad Mon Sep 17 00:00:00 2001 From: Lu Jiao Date: Mon, 23 Sep 2024 17:05:12 +0800 Subject: [PATCH 1/4] [dxil] Proposal to add new debug printf dxil op This is a counterpart proposal with similar debug printf feature from the spirv https://github.com/KhronosGroup/SPIRV-Registry/blob/main/nonsemantic/NonSemantic.DebugPrintf.asciidoc. The format string of printf is a const string variable, like OpString in the spirv. --- proposals/NNNN-debug-printf.md | 82 ++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 proposals/NNNN-debug-printf.md diff --git a/proposals/NNNN-debug-printf.md b/proposals/NNNN-debug-printf.md new file mode 100644 index 00000000..38639188 --- /dev/null +++ b/proposals/NNNN-debug-printf.md @@ -0,0 +1,82 @@ +# Dxil Debug Printf + +* Proposal: [NNNN](NNNN-debug-printf.md) +* Author(s): [Jiao Lu](https://github.com/jiaolu) +* Sponsor: TBD +* Status: **Under Consideration** + +## Introduction + +Add new dxil op to allow c/c++ like *printf* intrinsic instructions can be +generated in the dxil sourced from hlsl. + +## Motivation + +As the new shader models, i.e. RayTracing, RayQuery, Workgraph, and more complex +algorithms and structure emerges in recent time, we meet many more requirements of +debugging capabilities of hlsl coding in game, application and driver development. + +The dxil counterpart spirv has a similar feature, +[NonSemantic.DebugPrintf extention](https://github.com/KhronosGroup/SPIRV-Registry/blob/main/nonsemantic/NonSemantic.DebugPrintf.asciidoc) +to generate DebugPrintf spirvOp souced from hlsl/glsl. Based on the spirvOp +extention, some vendor drivers and Valve lunarG has +[debug printf layer](https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/debug_printf.md) +to dump printf expression, "hlsl/glsl variables" into stdio or file. + +## Proposed solution + +The printf expression in hlsl mostly like this example. +```c++ hlsl: + +const string str0= "str0"; +string str1 = "str1"; + +void main() { + printf(str0); + printf(str1); + printf("Variables are: %d %d %.2f", 1u, 2u, 1.5f); +} + +``` + +The format specifier generally follow the c/c++ format specifiers as here, https://www.geeksforgeeks.org/format-specifiers-in-c/, +Though how the final string representation after printf output is implementation dependent. + + +DirectXCompiler at present can parse "printf" statement in hlsl as dx.hl.op +instructions, +``` +dx.hl.op..void (i32, i8*, ...); +``` +The printf format string, the second argument of the printf instruction of +dx.hl.op is a global *constant* variable or a GEP constant expression. + +The parsing is called from ast frontend into the +HandleTranslationUnit-->TranslatePrintf.The function *TranslatePrintf* itself + is empty implementation. + +The implementation of debug printf dxil op will be + +1) assign new dxil op code to the debug printf. +2) Finished the TranslatePrintf implementation, create dxil op instruction with +a proper dxil op code, and replace dx.hl.op. the dxil op instruction function +will be a variable arguments function. + + +## Detailed design + +1. The printf dxil op will be non-semantic, it does not affect final hlsl code/algorithm. +Non-semantic dxil op code can be counted down from 0xffff, or 0xffffffff, it will give a hint to the client api +to remove the non semantic dxil safely +2. Add a option to enable printf dxil op generation to dxc, try to separate hlsl code for debugging +and for production, if printf option is disabled, the printf in hlsl will be report a error +3. We should not support dynamic string variable, a string variable content. +retrieved from buffer. The string variable should be explicited defined and can +be retrieved directly/indirectly from global constant variable. +4. The format string input to the dx.hl.op..void, could be llvm constant +expression, we need to retrieve global variable from the constant expression. +5. The validation for the dxil overloading checking should be ignored. Because +of printf variable arguments, there is no definite function type can be validated. +6. dxc does not valiate format specifier to the c/c++ format speicifer standard, or the matching relation between +format specifier and argument. If the number and type don't match, they will produce undefined result from +client api, e.g. driver. From cbb7831c0d478d186172ea9fab18ae8f5f58e360 Mon Sep 17 00:00:00 2001 From: Jiao Date: Tue, 1 Oct 2024 21:53:01 +0800 Subject: [PATCH 2/4] Address review points --- proposals/NNNN-debug-printf.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/proposals/NNNN-debug-printf.md b/proposals/NNNN-debug-printf.md index 38639188..d0c35904 100644 --- a/proposals/NNNN-debug-printf.md +++ b/proposals/NNNN-debug-printf.md @@ -65,9 +65,13 @@ will be a variable arguments function. ## Detailed design -1. The printf dxil op will be non-semantic, it does not affect final hlsl code/algorithm. -Non-semantic dxil op code can be counted down from 0xffff, or 0xffffffff, it will give a hint to the client api -to remove the non semantic dxil safely +1. The printf dxil op will be purely for debug purpose, it does not affect final hlsl +code/algorithm in any way. +To separate this kind of debug-purpose dxil ops to the normal non-debug dxil il ops, +the debug printf dxil op code can be counted down from 0xffff, or 0xffffffff, +e.g. op code is 0xfffe. +So it will give a hint to the d3d debug layer to pick up debug printf dxil easily, +or a underlying d3d driver to remove these dxil op codes safely. 2. Add a option to enable printf dxil op generation to dxc, try to separate hlsl code for debugging and for production, if printf option is disabled, the printf in hlsl will be report a error 3. We should not support dynamic string variable, a string variable content. @@ -79,4 +83,4 @@ expression, we need to retrieve global variable from the constant expression. of printf variable arguments, there is no definite function type can be validated. 6. dxc does not valiate format specifier to the c/c++ format speicifer standard, or the matching relation between format specifier and argument. If the number and type don't match, they will produce undefined result from -client api, e.g. driver. +a underlying d3d driver or a debug driver From b8291c06989987c07742a12f14324d8039603574 Mon Sep 17 00:00:00 2001 From: Jiao Date: Thu, 3 Oct 2024 20:40:33 +0800 Subject: [PATCH 3/4] Address reviewer points --- proposals/NNNN-debug-printf.md | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/proposals/NNNN-debug-printf.md b/proposals/NNNN-debug-printf.md index d0c35904..c0a80eef 100644 --- a/proposals/NNNN-debug-printf.md +++ b/proposals/NNNN-debug-printf.md @@ -18,7 +18,7 @@ debugging capabilities of hlsl coding in game, application and driver developmen The dxil counterpart spirv has a similar feature, [NonSemantic.DebugPrintf extention](https://github.com/KhronosGroup/SPIRV-Registry/blob/main/nonsemantic/NonSemantic.DebugPrintf.asciidoc) -to generate DebugPrintf spirvOp souced from hlsl/glsl. Based on the spirvOp +to generate DebugPrintf spirvOp sourced from hlsl/glsl. Based on the spirvOp extention, some vendor drivers and Valve lunarG has [debug printf layer](https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/debug_printf.md) to dump printf expression, "hlsl/glsl variables" into stdio or file. @@ -65,22 +65,16 @@ will be a variable arguments function. ## Detailed design -1. The printf dxil op will be purely for debug purpose, it does not affect final hlsl -code/algorithm in any way. -To separate this kind of debug-purpose dxil ops to the normal non-debug dxil il ops, -the debug printf dxil op code can be counted down from 0xffff, or 0xffffffff, -e.g. op code is 0xfffe. -So it will give a hint to the d3d debug layer to pick up debug printf dxil easily, -or a underlying d3d driver to remove these dxil op codes safely. -2. Add a option to enable printf dxil op generation to dxc, try to separate hlsl code for debugging -and for production, if printf option is disabled, the printf in hlsl will be report a error -3. We should not support dynamic string variable, a string variable content. -retrieved from buffer. The string variable should be explicited defined and can +1. Add a option to enable printf dxil op generation to dxc, try to separate hlsl code +for debugging purpose and for production purpose. The printf option is disabled by default, +and the printf instructions in hlsl will be report a error without a printf option. +2. We should not support dynamic string variable, a string variable content. +retrieved from buffer. The string variable should be explicitly defined and can be retrieved directly/indirectly from global constant variable. -4. The format string input to the dx.hl.op..void, could be llvm constant +3. The format string input to the dx.hl.op..void, could be llvm constant expression, we need to retrieve global variable from the constant expression. -5. The validation for the dxil overloading checking should be ignored. Because +4. The validation for the dxil overloading checking should be ignored. Because of printf variable arguments, there is no definite function type can be validated. -6. dxc does not valiate format specifier to the c/c++ format speicifer standard, or the matching relation between -format specifier and argument. If the number and type don't match, they will produce undefined result from -a underlying d3d driver or a debug driver +5. dxc will validate matching relation between format specifiers and arguments. +If the number of arguments and number of format specifiers mismatch, dxc will +produce error messages, If their types mismatch, dxc will report a warning messages. From 9719a107c39be027a78aa3e7f2207d6ea320d506 Mon Sep 17 00:00:00 2001 From: Jiao Date: Sat, 5 Oct 2024 21:03:30 +0800 Subject: [PATCH 4/4] Remove cstring referenced in the printf example. --- proposals/NNNN-debug-printf.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/proposals/NNNN-debug-printf.md b/proposals/NNNN-debug-printf.md index c0a80eef..4c78fff2 100644 --- a/proposals/NNNN-debug-printf.md +++ b/proposals/NNNN-debug-printf.md @@ -28,12 +28,9 @@ to dump printf expression, "hlsl/glsl variables" into stdio or file. The printf expression in hlsl mostly like this example. ```c++ hlsl: -const string str0= "str0"; -string str1 = "str1"; void main() { - printf(str0); - printf(str1); + printf("hello"); printf("Variables are: %d %d %.2f", 1u, 2u, 1.5f); }