[Docs] [HLSL] Documenting HLSL Entry Functions

This document describes the basic usage and implementation details for
HLSL entry functions in Clang.

Reviewed By: python3kgae

Differential Revision: https://reviews.llvm.org/D132672

diff --git a/clang/docs/HLSL/EntryFunctions.rst b/clang/docs/HLSL/EntryFunctions.rst
new file mode 100644 (file)
index 0000000..0e547aa
--- /dev/null
+++ b/clang/docs/HLSL/EntryFunctions.rst
@@ -0,0 +1,65 @@
+====================
+HLSL Entry Functions
+====================
+
+.. contents::
+   :local:
+
+Usage
+=====
+
+In HLSL, entry functions denote the starting point for shader execution. They
+must be known at compile time. For all non-library shaders, the compiler assumes
+the default entry function name ``main``, unless the DXC ``/E`` option is
+provided to specify an alternate entry point. For library shaders entry points
+are denoted using the ``[shader(...)]`` attribute.
+
+All scalar parameters to entry functions must have semantic annotations, and all
+struct parameters must have semantic annotations on every field in the struct
+declaration. Additionally if the entry function has a return type, a semantic
+annotation must be provided for the return type as well.
+
+HLSL entry functions can be called from other parts of the shader, which has
+implications on code generation.
+
+Implementation Details
+======================
+
+In Clang, the DXC ``/E`` option is translated to the cc1 flag ``-hlsl-entry``,
+which in turn applies the ``HLSLShader`` attribute to the function with the
+specified name. This allows code generation for entry functions to always key
+off the presence of the ``HLSLShader`` attribute, regardless of what shader
+profile you are compiling.
+
+In code generation, two functions are generated. One is the user defined
+function, which is code generated as a mangled C++ function with internal
+linkage following normal function code generation.
+
+The actual exported entry function which can be called by the GPU driver is a
+``void(void)`` function that isn't name mangled. In code generation we generate
+the unmangled entry function, instantiations of the parameters with their
+semantic values populated, and a call to the user-defined function. After the
+call instruction the return value (if any) is saved using a target-appropriate
+intrinsic for storing outputs (for DirectX, the ``llvm.dx.store.output``).
+
+.. note::
+
+   HLSL support in Clang is currently focused on compute shaders, which do not
+   support output semantics. Support for output semantics will not be
+   implemented until other shader profiles are supported.
+
+Below is example IR that represents the planned implementation, subject to
+change as the ``llvm.dx.store.output`` and ``llvm.dx.load.input`` intrinsics are
+not yet implemented.
+
+.. code-block:: none
+
+   ; Function Attrs: norecurse
+   define void @main() #1 {
+      entry:
+      %0 = call i32 @llvm.dx.load.input.i32(...)
+      %1 = call i32 @"?main@@YAXII@Z"(i32 %0)
+      call @llvm.dx.store.output.i32(%1, ...)
+      ret void
+   }
+

diff --git a/clang/docs/HLSL/HLSLDocs.rst b/clang/docs/HLSL/HLSLDocs.rst
index 0b66e51..2cfe631 100644 (file)
--- a/clang/docs/HLSL/HLSLDocs.rst
+++ b/clang/docs/HLSL/HLSLDocs.rst
@@ -12,3 +12,4 @@ HLSL Design and Implementation
    :maxdepth: 1
 
    ResourceTypes
+   EntryFunctions