1==================== 2HLSL Entry Functions 3==================== 4 5.. contents:: 6 :local: 7 8Usage 9===== 10 11In HLSL, entry functions denote the starting point for shader execution. They 12must be known at compile time. For all non-library shaders, the compiler assumes 13the default entry function name ``main``, unless the DXC ``/E`` option is 14provided to specify an alternate entry point. For library shaders entry points 15are denoted using the ``[shader(...)]`` attribute. 16 17All scalar parameters to entry functions must have semantic annotations, and all 18struct parameters must have semantic annotations on every field in the struct 19declaration. Additionally if the entry function has a return type, a semantic 20annotation must be provided for the return type as well. 21 22HLSL entry functions can be called from other parts of the shader, which has 23implications on code generation. 24 25Implementation Details 26====================== 27 28In Clang, the DXC ``/E`` option is translated to the cc1 flag ``-hlsl-entry``, 29which in turn applies the ``HLSLShader`` attribute to the function with the 30specified name. This allows code generation for entry functions to always key 31off the presence of the ``HLSLShader`` attribute, regardless of what shader 32profile you are compiling. 33 34In code generation, two functions are generated. One is the user defined 35function, which is code generated as a mangled C++ function with internal 36linkage following normal function code generation. 37 38The actual exported entry function which can be called by the GPU driver is a 39``void(void)`` function that isn't name mangled. In code generation we generate 40the unmangled entry function to serve as the actual shader entry. The shader 41entry function is annotated with the ``hlsl.shader`` function attribute 42identifying the entry's pipeline stage. 43 44The body of the unmangled entry function contains first a call to execute global 45constructors, then instantiations of the user-defined entry parameters with 46their semantic values populated, and a call to the user-defined function. 47After the call instruction the return value (if any) is saved using a 48target-appropriate intrinsic for storing outputs (for DirectX, the 49``llvm.dx.store.output``). Lastly, any present global destructors will be called 50immediately before the return. HLSL does not support C++ ``atexit`` 51registrations, instead calls to global destructors are compile-time generated. 52 53.. note:: 54 55 HLSL support in Clang is currently focused on compute shaders, which do not 56 support output semantics. Support for output semantics will not be 57 implemented until other shader profiles are supported. 58 59Below is example IR that represents the planned implementation, subject to 60change as the ``llvm.dx.store.output`` and ``llvm.dx.load.input`` intrinsics are 61not yet implemented. 62 63.. code-block:: none 64 65 ; Function Attrs: norecurse 66 define void @main() #1 { 67 entry: 68 %0 = call i32 @llvm.dx.load.input.i32(...) 69 %1 = call i32 @"?main@@YAXII@Z"(i32 %0) 70 call @llvm.dx.store.output.i32(%1, ...) 71 ret void 72 } 73 74