https://github.com/llvm-beanz updated https://github.com/llvm/llvm-project/pull/84081
>From 081d397961bd19d37d957d43c67f6a419c338629 Mon Sep 17 00:00:00 2001 From: Chris Bieneman <chris.biene...@me.com> Date: Tue, 5 Mar 2024 16:26:17 -0600 Subject: [PATCH 1/3] [HLSL][docs] Document hlsl.h in the HLSL docs This adds a brief blurb about hlsl.h in the HLSLSupport documentation where a high level view of the architecture is explained. --- clang/docs/HLSL/HLSLSupport.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/clang/docs/HLSL/HLSLSupport.rst b/clang/docs/HLSL/HLSLSupport.rst index b091c17fd2a764..ca1f8faf757529 100644 --- a/clang/docs/HLSL/HLSLSupport.rst +++ b/clang/docs/HLSL/HLSLSupport.rst @@ -114,6 +114,39 @@ not re-targetable, we want to share the Clang CodeGen implementation for HLSL with other GPU graphics targets like SPIR-V and possibly other GPU and even CPU targets. +hlsl.h +------ + +HLSL has an extensive library of built in functionality. This is similar to +OpenCL and CUDA. The implementation approach for the HLSL library functionality +draws from patterns in use by OpenCL and other built-in headers. + +Similar to OpenCL, the HLSL library functionality is implicitly declared in +translation units without needing to include a header to provide declarations. +In Clang this is handled by making ``hlsl.h`` an implicitly included header. + +Similar to OpenCL, HLSL's implicit header will explicitly declare all overloads, +and each overload will map to a corresponding builtin that is used for code +generation. CUDA uses a similar pattern although many CUDA built-in functions +have full definitions in the included headers which in turn call builtins. By +not having bodies we avoid the need for the inliner to clean up and inline the +small library functions. + +HLSL's implicit headers also define some of HLSL's built-in typedefs. This is +consistent with how the AVX vector header is implemented. + +Concerns have been expressed that this approach may result in slower compile +times than the approach DXC uses where built-in functions are treated more like +Clang builtins. While this might be true we have no existing shaders where +parsing is a significant compile-time overhead. Further, by treating these +built-in functions as functions rather than builtins the language behaviors are +more consistent and aligned with user expectation because normal overload +resolution rules and implicit conversions apply as expected. + +It is a feature of this design that clangd-powered "go to declaration" for +library functions will jump to a valid header declaration and all overloads will +be user readable. + HLSL Language ============= >From 647f4836f5c807e42444a2669a0d9425ca500ad5 Mon Sep 17 00:00:00 2001 From: Chris Bieneman <chris.biene...@me.com> Date: Tue, 5 Mar 2024 17:27:33 -0600 Subject: [PATCH 2/3] Clarify use and spelling of the word "builtin" --- clang/docs/HLSL/HLSLSupport.rst | 39 +++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/clang/docs/HLSL/HLSLSupport.rst b/clang/docs/HLSL/HLSLSupport.rst index ca1f8faf757529..12574a54324483 100644 --- a/clang/docs/HLSL/HLSLSupport.rst +++ b/clang/docs/HLSL/HLSLSupport.rst @@ -117,31 +117,36 @@ targets. hlsl.h ------ -HLSL has an extensive library of built in functionality. This is similar to -OpenCL and CUDA. The implementation approach for the HLSL library functionality -draws from patterns in use by OpenCL and other built-in headers. +HLSL has an extensive library of functionality. This is similar to OpenCL and +CUDA. The implementation approach for the HLSL library functionality draws from +patterns in use by OpenCL and other Clang resource headers. Similar to OpenCL, the HLSL library functionality is implicitly declared in translation units without needing to include a header to provide declarations. -In Clang this is handled by making ``hlsl.h`` an implicitly included header. +In Clang this is handled by making ``hlsl.h`` an implicitly included header +distributed as part of the Clang resource directory. Similar to OpenCL, HLSL's implicit header will explicitly declare all overloads, -and each overload will map to a corresponding builtin that is used for code -generation. CUDA uses a similar pattern although many CUDA built-in functions -have full definitions in the included headers which in turn call builtins. By -not having bodies we avoid the need for the inliner to clean up and inline the -small library functions. +and each overload will map to a corresponding ``__builtin_*`` compiler intrinsic +that is handled in ClangCodeGen. CUDA uses a similar pattern although many CUDA +functions have full definitions in the included headers which in turn call +corresponding ``__builtin*`` compiler intrinsics. By not having bodies HLSL +avoids the need for the inliner to clean up and inline large numbers of small +library functions. -HLSL's implicit headers also define some of HLSL's built-in typedefs. This is -consistent with how the AVX vector header is implemented. +HLSL's implicit headers also define some of HLSL's typedefs. This is consistent +with how the AVX vector header is implemented. Concerns have been expressed that this approach may result in slower compile -times than the approach DXC uses where built-in functions are treated more like -Clang builtins. While this might be true we have no existing shaders where -parsing is a significant compile-time overhead. Further, by treating these -built-in functions as functions rather than builtins the language behaviors are -more consistent and aligned with user expectation because normal overload -resolution rules and implicit conversions apply as expected. +times than the approach DXC uses where library functions are treated more like +Clang ``__builtin*`` intrinsics. No real world use cases have been identified +where parsing is a significant compile-time overhead, but the HLSL implicit +headers can be compiled into a module for performance if needed. + +Further, by treating these functions as functions rather than ``__builtin*`` +compiler intrinsics the language behaviors are more consistent and aligned with +user expectation because normal overload resolution rules and implicit +conversions apply as expected. It is a feature of this design that clangd-powered "go to declaration" for library functions will jump to a valid header declaration and all overloads will >From e3a9c5ccf9a16f084e2e45703dd3f50672f2b78a Mon Sep 17 00:00:00 2001 From: Chris Bieneman <chris.biene...@me.com> Date: Mon, 11 Mar 2024 10:55:23 -0500 Subject: [PATCH 3/3] Updates based on review feedback. Also added a note about complex data types being defined in the `HLSLExternalSemaSource`. --- clang/docs/HLSL/HLSLSupport.rst | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/clang/docs/HLSL/HLSLSupport.rst b/clang/docs/HLSL/HLSLSupport.rst index 12574a54324483..2d309ddff2f36a 100644 --- a/clang/docs/HLSL/HLSLSupport.rst +++ b/clang/docs/HLSL/HLSLSupport.rst @@ -91,7 +91,7 @@ performance win for HLSL. If precompiled headers are used when compiling HLSL, the ``ExternalSemaSource`` will be a ``MultiplexExternalSemaSource`` which includes both the ``ASTReader`` -and ``HLSLExternalSemaSource``. For Built-in declarations that are already +and -. For Built-in declarations that are already completed in the serialized AST, the ``HLSLExternalSemaSource`` will reuse the existing declarations and not introduce new declarations. If the built-in types are not completed in the serialized AST, the ``HLSLExternalSemaSource`` will @@ -117,9 +117,19 @@ targets. hlsl.h ------ -HLSL has an extensive library of functionality. This is similar to OpenCL and -CUDA. The implementation approach for the HLSL library functionality draws from -patterns in use by OpenCL and other Clang resource headers. +HLSL has a library of standalone functions. This is similar to OpenCL and CUDA, +and is analogous to C's standard library. The implementation approach for the +HLSL library functionality draws from patterns in use by OpenCL and other Clang +resource headers. All of the clang resource headers are part of the +``ClangHeaders`` component found in the source tree under +`clang/lib/Headers <https://github.com/llvm/llvm-project/tree/main/clang/lib/Headers>`_. + +.. note:: + + HLSL's complex data types are not defined in HLSL's header because many of + the semantics of those data types cannot be expressed in HLSL due to missing + language features. Data types that can't be expressed in HLSL are defined in + code in the ``HLSLExternalSemaSource``. Similar to OpenCL, the HLSL library functionality is implicitly declared in translation units without needing to include a header to provide declarations. @@ -127,7 +137,7 @@ In Clang this is handled by making ``hlsl.h`` an implicitly included header distributed as part of the Clang resource directory. Similar to OpenCL, HLSL's implicit header will explicitly declare all overloads, -and each overload will map to a corresponding ``__builtin_*`` compiler intrinsic +and each overload will map to a corresponding ``__builtin*`` compiler intrinsic that is handled in ClangCodeGen. CUDA uses a similar pattern although many CUDA functions have full definitions in the included headers which in turn call corresponding ``__builtin*`` compiler intrinsics. By not having bodies HLSL @@ -143,10 +153,10 @@ Clang ``__builtin*`` intrinsics. No real world use cases have been identified where parsing is a significant compile-time overhead, but the HLSL implicit headers can be compiled into a module for performance if needed. -Further, by treating these functions as functions rather than ``__builtin*`` -compiler intrinsics the language behaviors are more consistent and aligned with -user expectation because normal overload resolution rules and implicit -conversions apply as expected. +Further, by treating these as functions rather than ``__builtin*`` compiler +intrinsics, the language behaviors are more consistent and aligned with user +expectation because normal overload resolution rules and implicit conversions +apply as expected. It is a feature of this design that clangd-powered "go to declaration" for library functions will jump to a valid header declaration and all overloads will _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
