[clang] [HLSL][docs] Document hlsl.h in the HLSL docs (PR #84081)

[Chris B via cfe-commits]

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.bieneman at 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.bieneman at 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.bieneman at 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