1============
2HLSL Support
3============
4
5.. contents::
6   :local:
7
8Introduction
9============
10
11HLSL Support is under active development in the Clang codebase. This document
12describes the high level goals of the project, the guiding principles, as well
13as some idiosyncrasies of the HLSL language and how we intend to support them in
14Clang.
15
16Project Goals
17=============
18
19The long term goal of this project is to enable Clang to function as a
20replacement for the `DirectXShaderCompiler (DXC)
21<https://github.com/microsoft/DirectXShaderCompiler/>`_ in all its supported
22use cases. Accomplishing that goal will require Clang to be able to process most
23existing HLSL programs with a high degree of source compatibility.
24
25Non-Goals
26---------
27
28HLSL ASTs do not need to be compatible between DXC and Clang. We do not expect
29identical code generation or that features will resemble DXC's implementation or
30architecture. In fact, we explicitly expect to deviate from DXC's implementation
31in key ways.
32
33Guiding Principles
34==================
35
36This document lacks details for architectural decisions that are not yet
37finalized. Our top priorities are quality, maintainability, and flexibility. In
38accordance with community standards we are expecting a high level of test
39coverage, and we will engineer our solutions with long term maintenance in mind.
40We are also working to limit modifications to the Clang C++ code paths and
41share as much functionality as possible.
42
43Architectural Direction
44=======================
45
46HLSL support in Clang is expressed as C++ minus unsupported C and C++ features.
47This is different from how other Clang languages are implemented. Most languages
48in Clang are additive on top of C.
49
50HLSL is not a formally or fully specified language, and while our goals require
51a high level of source compatibility, implementations can vary and we have some
52flexibility to be more or less permissive in some cases. For modern HLSL DXC is
53the reference implementation.
54
55The HLSL effort prioritizes following similar patterns for other languages,
56drivers, runtimes and targets. Specifically, We will maintain separation between
57HSLS-specific code and the rest of Clang as much as possible following patterns
58in use in Clang code today (i.e. ParseHLSL.cpp, SemaHLSL.cpp, CGHLSL*.cpp...).
59We will use inline checks on language options where the code is simple and
60isolated, and prefer HLSL-specific implementation files for any code of
61reasonable complexity.
62
63In places where the HLSL language is in conflict with C and C++, we will seek to
64make minimally invasive changes guarded under the HLSL language options. We will
65seek to make HLSL language support as minimal a maintenance burden as possible.
66
67DXC Driver
68----------
69
70A DXC driver mode will provide command-line compatibility with DXC, supporting
71DXC's options and flags. The DXC driver is HLSL-specific and will create an
72HLSLToolchain which will provide the basis to support targeting both DirectX and
73Vulkan.
74
75Parser
76------
77
78Following the examples of other parser extensions HLSL will add a ParseHLSL.cpp
79file to contain the implementations of HLSL-specific extensions to the Clang
80parser. The HLSL grammar shares most of its structure with C and C++, so we will
81use the existing C/C++ parsing code paths.
82
83Sema
84----
85
86HLSL's Sema implementation will also provide an ``ExternalSemaSource``. In DXC,
87an ``ExternalSemaSource`` is used to provide definitions for HLSL built-in data
88types and built-in templates. Clang is already designed to allow an attached
89``ExternalSemaSource`` to lazily complete data types, which is a **huge**
90performance win for HLSL.
91
92CodeGen
93-------
94
95Like OpenCL, HLSL relies on capturing a lot of information into IR metadata.
96*hand wave* *hand wave* *hand wave* As a design principle here we want our IR to
97be idiomatic Clang IR as much as possible. We will use IR attributes wherever we
98can, and use metadata as sparingly as possible. One example of a difference from
99DXC already implemented in Clang is the use of target triples to communicate
100shader model versions and shader stages.
101
102Our HLSL CodeGen implementation should also have an eye toward generating IR
103that will map directly to targets other than DXIL. While IR itself is generally
104not re-targetable, we want to share the Clang CodeGen implementation for HLSL
105with other GPU graphics targets like SPIR-V and possibly other GPU and even CPU
106targets.
107
108HLSL Language
109=============
110
111The HLSL language is insufficiently documented, and not formally specified.
112Documentation is available on `Microsoft's website
113<https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl>`_.
114The language syntax is similar enough to C and C++ that carefully written C and
115C++ code is valid HLSL. HLSL has some key differences from C & C++ which we will
116need to handle in Clang.
117
118HLSL is not a conforming or valid extension or superset of C or C++. The
119language has key incompatibilities with C and C++, both syntactically and
120semantically.
121
122An Aside on GPU Languages
123-------------------------
124
125Due to HLSL being a GPU targeted language HLSL is a Single Program Multiple Data
126(SPMD) language relying on the implicit parallelism provided by GPU hardware.
127Some language features in HLSL enable programmers to take advantage of the
128parallel nature of GPUs in a hardware abstracted language.
129
130HLSL also prohibits some features of C and C++ which can have catastrophic
131performance or are not widely supportable on GPU hardware or drivers. As an
132example, register spilling is often excessively expensive on GPUs, so HLSL
133requires all functions to be inlined during code generation, and does not
134support a runtime calling convention.
135
136Pointers & References
137---------------------
138
139HLSL does not support referring to values by address. Semantically all variables
140are value-types and behave as such. HLSL disallows the pointer dereference
141operators (unary ``*``, and ``->``), as well as the address of operator (unary
142&). While HLSL disallows pointers and references in the syntax, HLSL does use
143reference types in the AST, and we intend to use pointer decay in the AST in
144the Clang implementation.
145
146HLSL ``this`` Keyword
147---------------------
148
149HLSL does support member functions, and (in HLSL 2021) limited operator
150overloading. With member function support, HLSL also has a ``this`` keyword. The
151``this`` keyword is an example of one of the places where HLSL relies on
152references in the AST, because ``this`` is a reference.
153
154Bitshifts
155---------
156
157In deviation from C, HLSL bitshifts are defined to mask the shift count by the
158size of the type. In DXC, the semantics of LLVM IR were altered to accommodate
159this, in Clang we intend to generate the mask explicitly in the IR. In cases
160where the shift value is constant, this will be constant folded appropriately,
161in other cases we can clean it up in the DXIL target.
162
163Non-short Circuiting Logical Operators
164--------------------------------------
165
166In HLSL 2018 and earlier, HLSL supported logical operators (and the ternary
167operator) on vector types. This behavior required that operators not short
168circuit. The non-short circuiting behavior applies to all data types until HLSL
1692021. In HLSL 2021, logical and ternary operators do not support vector types
170instead builtin functions ``and``, ``or`` and ``select`` are available, and
171operators short circuit matching C behavior.
172
173Precise Qualifier
174-----------------
175
176HLSL has a ``precise`` qualifier that behaves unlike anything else in the C
177language. The support for this qualifier in DXC is buggy, so our bar for
178compatibility is low.
179
180The ``precise`` qualifier applies in the inverse direction from normal
181qualifiers. Rather than signifying that the declaration containing ``precise``
182qualifier be precise, it signifies that the operations contributing to the
183declaration's value be ``precise``. Additionally, ``precise`` is a misnomer:
184values attributed as ``precise`` comply with IEEE-754 floating point semantics,
185and are prevented from optimizations which could decrease *or increase*
186precision.
187
188Differences in Templates
189------------------------
190
191HLSL uses templates to define builtin types and methods, but disallowed
192user-defined templates until HLSL 2021. HLSL also allows omitting empty template
193parameter lists when all template parameters are defaulted. This is an ambiguous
194syntax in C++, but Clang detects the case and issues a diagnostic. This makes
195supporting the case in Clang minimally invasive.
196
197Vector Extensions
198-----------------
199
200HLSL uses the OpenCL vector extensions, and also provides C++-style constructors
201for vectors that are not supported by Clang.
202
203Standard Library
204----------------
205
206HLSL does not support the C or C++ standard libraries. Like OpenCL, HLSL
207describes its own library of built in types, complex data types, and functions.
208
209Unsupported C & C++ Features
210----------------------------
211
212HLSL does not support all features of C and C++. In implementing HLSL in Clang
213use of some C and C++ features will produce diagnostics under HLSL, and others
214will be supported as language extensions. In general, any C or C++ feature that
215can be supported by the DXIL and SPIR-V code generation targets could be treated
216as a clang HLSL extension. Features that cannot be lowered to DXIL or SPIR-V,
217must be diagnosed as errors.
218
219HLSL does not support the following C features:
220
221* Pointers
222* References
223* ``goto`` or labels
224* Variable Length Arrays
225* ``_Complex`` and ``_Imaginary``
226* C Threads or Atomics (or Obj-C blocks)
227* ``union`` types `(in progress for HLSL 202x) <https://github.com/microsoft/DirectXShaderCompiler/pull/4132>`_
228* Most features C11 and later
229
230HLSL does not support the following C++ features:
231
232* RTTI
233* Exceptions
234* Multiple inheritance
235* Access specifiers
236* Anonymous or inline namespaces
237* ``new`` & ``delete`` operators in all of their forms (array, placement, etc)
238* Constructors and destructors
239* Any use of the ``virtual`` keyword
240* Most features C++11 and later
241