beanz created this revision.
beanz added reviewers: tschuett, aaron.ballman, jaebaek, antiagainst, kuhar.
Herald added a subscriber: arphaman.
Herald added a project: All.
beanz requested review of this revision.
Herald added a project: clang.
Herald added a subscriber: cfe-commits.
This document is a first-stab at addressing some of the questions about
HLSL support in Clang.
Repository:
rG LLVM Github Monorepo
https://reviews.llvm.org/D123278
Files:
clang/docs/HLSLSupport.rst
clang/docs/index.rst
Index: clang/docs/index.rst
===================================================================
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -45,6 +45,7 @@
OpenCLSupport
OpenMPSupport
SYCLSupport
+ HLSLSupport
ThinLTO
APINotes
CommandGuide/index
Index: clang/docs/HLSLSupport.rst
===================================================================
--- /dev/null
+++ clang/docs/HLSLSupport.rst
@@ -0,0 +1,197 @@
+============
+HLSL Support
+============
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+HLSL Support is a new initiative underway in the Clang codebase. This document
+describes the high level goals of the project, the guiding principals, as well
+as some of the idiosyncrasies of the HLSL language and how we intend to support
+them in Clang.
+
+Project Goals
+=============
+
+The long term goal of this project is to enable clang to function as a
+replacement for the `DirectXShaderCompiler (DXC)
+<https://github.com/microsoft/DirectXShaderCompiler/>`_. in all its supported
+use cases. Accomplishing that goal will require a high level of source
+compatibility.
+
+Non-Goals
+---------
+
+HLSL ASTs do not need to be compatible between DXC and Clang. We do not expect
+identical code generation or that features will resemble DXC's implementation or
+architecture. In fact, we explicitly expect to deviate from DXC's implementation
+in key ways.
+
+Guiding Principals
+==================
+
+This document lacks precise details for architectural decisions that are not yet
+finalized. Our top priorities are quality, maintainability, and flexibility. In
+accordance with community standards we are expecting a high level of test
+coverage, and we will engineer our solutions with long term maintenance in mind.
+We are also working to limit modifications to the Clang C++ code paths and
+share as much functionality as possible.
+
+Architectural Direction
+=======================
+
+HLSL support in clang is expressed as C++ minus unsupported C and C++ features.
+This is different from how other clang languages are implemented. Most languages
+in Clang are additive on top of C.
+
+HLSL is not a formally or fully specified language, and while our goals require
+a high level of source compatibility, implementations can vary and we have some
+flexibility to be more or less permissive in some cases.
+
+The HLSL effort prioritizes following similar patterns for other languages,
+drivers, runtimes and targets. Specifically, HLSL will create separate
+implementation files to contain the HLSL-specific behavior wherever it makes
+sense (i.e. ParseHLSL.cpp, SemaHLSL.cpp, CGHLSL*.cpp...). We will use inline
+checks on language options where the code is simple and isolated, and prefer
+HLSL-specific implementation files for any code of reasonable complexity.
+
+DXC Driver
+----------
+
+A DXC driver mode will provide command-line compatibility with DXC, supporting
+DXC's options and flags. The DXC driver is HLSL-specific and will create an
+HLSLToolchain which will provide the basis to support targeting both DirectX and
+Vulkan.
+
+Parser
+------
+
+Following the examples of other parser extensions HLSL will add a ParseHLSL.cpp
+file to contain the implementations of HLSL-specific extensions to the clang
+parser.
+
+Sema
+----
+
+HLSL's Sema implementation will also provide an ``ExternalSemaSource``. In DXC,
+an ``ExternalSemaSource`` is used to provide definitions for HLSL built-in data
+types and built-in templates. Clang is already designed to allow an attached
+``ExternalSemaSource`` to lazily complete data types, which is a **huge**
+performance win for HLSL.
+
+CodeGen
+-------
+
+Similar to OpenCL, HLSL relies on capturing a lot of information into IR
+metadata. *hand wave* *hand wave* *hand wave* As a design principle here we want
+our IR to be idiomatic Clang IR as much as possible. We will use IR attributes
+wherever we can, and use metadata as sparingly as possible. One example of a
+difference from DXC already implemented in Clang is the use of target triples to
+communicate shader model versions and shader stages.
+
+Our HLSL CodeGen implementation should also have an eye toward generating IR
+that will map directly to targets other than DXIL. While IR itself is generally
+not re-targetable, we want to share the Clang CodeGen implementation for HLSL
+with other GPU graphics targets like SPIR-V and possibly other GPU and even CPU
+targets.
+
+HLSL Language
+=============
+
+The HLSL language is insufficiently documented, and not formally specified.
+Documentation is available on `Microsoft's website
+<https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl>`_.
+The language syntax is similar enough to C and C++ that carefully written C and
+C++ code is valid HLSL. HLSL has some key differences from C & C++ which we will
+need to handle in Clang.
+
+HLSL is not a conforming or valid extension or superset of C or C++. The
+language has key incompatibilities with C and C++, both syntactically and
+semantically.
+
+Pointers & References
+---------------------
+
+HLSL does not support referring to values by address. Semantically all variables
+are value-types and behave as such. HLSL disallows the pointer dereference
+operators (unary ``*``, and ``->``), as well as the address of operator (unary
+&). While HLSL disallows pointers and references in the syntax, HLSL does use
+reference types in the AST.
+
+HLSL ``this`` Keyword
+---------------------
+
+HLSL does support member functions, and (in HLSL 2021) limited operator
+overloading. With member function support HLSL also has a ``this`` keyword. The
+``this`` keyword is an example of one of the places where HLSL relies on
+references in the AST, because ``this`` is a reference.
+
+Bitshifts
+---------
+
+This is a simple one, but it deviates from C so is worth mentioning. HLSL
+bitshifts are defined to mask the shift count by the size of the type. In DXC,
+the semantics of LLVM IR were altered to accomodate this, in Clang we intend to
+generate the mask explicitly in the IR.
+
+Non-short Circuiting Logical Operators
+--------------------------------------
+
+In HLSL 2018 and earlier, HLSL supported logical operators (and the ternary
+operator) on vector types. This behavior required that operators not short
+circuit.
+
+Precise Qualifier
+-----------------
+
+HLSL has a ``precise`` qualifier that behaves unlike anything else in the C
+language. The support for this qualifier in DXC is buggy, so our bar for
+compatibility is low.
+
+The ``precise`` qualifier applies in the inverse direction from normal
+qualifiers. Rather than signifying that the declaration containing ``precise``
+qualifier be precise, it signifies that the operations contributing to the
+declaration's value be ``precise``. Additionally, ``precise`` is a misnomer:
+values attributed as ``precise`` comply with IEEE-754 floating point semantics,
+and are prevented from optimizations which could decrease *or increase*
+precision.
+
+Differences in Templates
+------------------------
+
+HLSL uses templates to define builtin types and methods, but disallowed
+user-defined templates until HLSL 2021. HLSL also allows omiting empty template
+parameter lists when all template parameters are defaulted. This is an ambiguous
+syntax in C++, however clang detects the case and issues a diagnostic, so
+supporting it is minimally invasive.
+
+Vector Extensions
+-----------------
+
+HLSL uses the OpenCL vector extensions, and also provides C++-style constructors
+for vectors that are not supported by clang.
+
+Unsupported C Features
+----------------------
+
+HLSL does not support the following C features:
+
+* Pointers
+* References
+* ``union`` types `(in progress for HLSL 202x) <https://github.com/microsoft/DirectXShaderCompiler/pull/4132>`_
+* Most features C11 and later
+
+HLSL does not support the following C++ features:
+
+* RTTI
+* Exceptions
+* Multiple inheritance
+* Access specifiers
+* Anonymous namespaces
+* ``new`` & ``delete`` operators
+* Constructors & destructors
+* Any use of the ``virtual`` keyword
+* Most features C++11 and later
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
