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