[PATCH] D132672: [Docs] [HLSL] Documenting HLSL Entry Functions

[Chris Bieneman via Phabricator via cfe-commits]

beanz created this revision.
beanz added reviewers: tex3d, pow2clk, bob80905, bogner, python3kgae, gracejennings.
Herald added a subscriber: Anastasia.
Herald added a project: All.
beanz requested review of this revision.
Herald added a project: clang.

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


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D132672

Files:
  clang/docs/HLSL/EntryFunctions.rst
  clang/docs/HLSL/HLSLDocs.rst


Index: clang/docs/HLSL/HLSLDocs.rst
===================================================================
--- clang/docs/HLSL/HLSLDocs.rst
+++ clang/docs/HLSL/HLSLDocs.rst
@@ -12,3 +12,4 @@
    :maxdepth: 1
 
    ResourceTypes
+   EntryFunctions
Index: clang/docs/HLSL/EntryFunctions.rst
===================================================================
--- /dev/null
+++ clang/docs/HLSL/EntryFunctions.rst
@@ -0,0 +1,46 @@
+====================
+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 via the appropriate
+intrinsic for its semantic annotation.
+
+During optimization all calls in HLSL are inlined, so this has no impact on
+final code.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D132672.455629.patch
Type: text/x-patch
Size: 2434 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20220825/55540463/attachment.bin>