beanz created this revision.
beanz added reviewers: aaron.ballman, pow2clk, python3kgae, bogner, MaskRay.
Herald added subscribers: Anastasia, StephenFan, arphaman.
Herald added a project: All.
beanz requested review of this revision.
Herald added a project: clang.
Along with the new documentation this also re-organizes the HLSL docs
to a subdirectory. The hope is to continue to expand this documentation
as the HLSL implementation advances.
Repository:
rG LLVM Github Monorepo
https://reviews.llvm.org/D130794
Files:
clang/docs/HLSL/HLSLDocs.rst
clang/docs/HLSL/HLSLSupport.rst
clang/docs/HLSL/ResourceTypes.rst
clang/docs/HLSLSupport.rst
clang/docs/index.rst
Index: clang/docs/index.rst
===================================================================
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -46,7 +46,7 @@
OpenCLSupport
OpenMPSupport
SYCLSupport
- HLSLSupport
+ HLSL/HLSLDocs
ThinLTO
APINotes
DebuggingCoroutines
Index: clang/docs/HLSL/ResourceTypes.rst
===================================================================
--- /dev/null
+++ clang/docs/HLSL/ResourceTypes.rst
@@ -0,0 +1,34 @@
+============
+HLSL Support
+============
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+HLSL Resources are runtime-bound data that is provided as input, output or both
+to shader programs written in HLSL. Resource Types in HLSL provide key user
+abstractions for reading and writing resource data.
+
+Implementation Details
+======================
+
+In Clang resource types are forward declared by the ``HLSLExternalSemaSource``
+on initialization. They are then lazily completed when ``requiresCompleteType``
+is called later in Sema.
+
+Resource types are templated class declarations. The template parameter
+specifies the expected return type of resource loads, and the expected parameter
+type for stores.
+
+In Clang's AST and code generation, resource types are classes that store a
+pointer of the template parameter type. The pointer is populated from a call to
+``__builtin_hlsl_create_handle``, and treated as a pointer to an array of typed
+data through until lowering in the backend.
+
+Resource types are annotated with the ``HLSLResource`` attribute, which drives
+code generation for resource binding metadata. The ``hlsl`` metadata nodes are
+transformed in the backend to the binding information expected by the target
+runtime.
Index: clang/docs/HLSLSupport.rst
===================================================================
--- /dev/null
+++ clang/docs/HLSLSupport.rst
@@ -1,240 +0,0 @@
-============
-HLSL Support
-============
-
-.. contents::
- :local:
-
-Introduction
-============
-
-HLSL Support is under active development in the Clang codebase. This document
-describes the high level goals of the project, the guiding principles, as well
-as some 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 Clang to be able to process most
-existing HLSL programs with a high degree 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 Principles
-==================
-
-This document lacks 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. For modern HLSL DXC is
-the reference implementation.
-
-The HLSL effort prioritizes following similar patterns for other languages,
-drivers, runtimes and targets. Specifically, We will maintain separation between
-HSLS-specific code and the rest of Clang as much as possible following patterns
-in use in Clang code today (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.
-
-In places where the HLSL language is in conflict with C and C++, we will seek to
-make minimally invasive changes guarded under the HLSL language options. We will
-seek to make HLSL language support as minimal a maintenance burden as possible.
-
-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. The HLSL grammar shares most of its structure with C and C++, so we will
-use the existing C/C++ parsing code paths.
-
-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
--------
-
-Like 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.
-
-An Aside on GPU Languages
--------------------------
-
-Due to HLSL being a GPU targeted language HLSL is a Single Program Multiple Data
-(SPMD) language relying on the implicit parallelism provided by GPU hardware.
-Some language features in HLSL enable programmers to take advantage of the
-parallel nature of GPUs in a hardware abstracted language.
-
-HLSL also prohibits some features of C and C++ which can have catastrophic
-performance or are not widely supportable on GPU hardware or drivers. As an
-example, register spilling is often excessively expensive on GPUs, so HLSL
-requires all functions to be inlined during code generation, and does not
-support a runtime calling convention.
-
-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, and we intend to use pointer decay in the AST in
-the Clang implementation.
-
-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
----------
-
-In deviation from C, 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 accommodate
-this, in Clang we intend to generate the mask explicitly in the IR. In cases
-where the shift value is constant, this will be constant folded appropriately,
-in other cases we can clean it up in the DXIL target.
-
-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. The non-short circuiting behavior applies to all data types until HLSL
-2021. In HLSL 2021, logical and ternary operators do not support vector types
-instead builtin functions ``and``, ``or`` and ``select`` are available, and
-operators short circuit matching C behavior.
-
-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 omitting empty template
-parameter lists when all template parameters are defaulted. This is an ambiguous
-syntax in C++, but Clang detects the case and issues a diagnostic. This makes
-supporting the case in Clang minimally invasive.
-
-Vector Extensions
------------------
-
-HLSL uses the OpenCL vector extensions, and also provides C++-style constructors
-for vectors that are not supported by Clang.
-
-Standard Library
-----------------
-
-HLSL does not support the C or C++ standard libraries. Like OpenCL, HLSL
-describes its own library of built in types, complex data types, and functions.
-
-Unsupported C & C++ Features
-----------------------------
-
-HLSL does not support all features of C and C++. In implementing HLSL in Clang
-use of some C and C++ features will produce diagnostics under HLSL, and others
-will be supported as language extensions. In general, any C or C++ feature that
-can be supported by the DXIL and SPIR-V code generation targets could be treated
-as a clang HLSL extension. Features that cannot be lowered to DXIL or SPIR-V,
-must be diagnosed as errors.
-
-HLSL does not support the following C features:
-
-* Pointers
-* References
-* ``goto`` or labels
-* Variable Length Arrays
-* ``_Complex`` and ``_Imaginary``
-* C Threads or Atomics (or Obj-C blocks)
-* ``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 or inline namespaces
-* ``new`` & ``delete`` operators in all of their forms (array, placement, etc)
-* Constructors and destructors
-* Any use of the ``virtual`` keyword
-* Most features C++11 and later
Index: clang/docs/HLSL/HLSLDocs.rst
===================================================================
--- /dev/null
+++ clang/docs/HLSL/HLSLDocs.rst
@@ -0,0 +1,14 @@
+.. title:: Clang HLSL Documentation
+
+.. toctree::
+ :maxdepth: 1
+
+ HLSLSupport
+
+HLSL Design and Implementation
+==============================
+
+.. toctree::
+ :maxdepth: 1
+
+ ResourceTypes
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
