From fc470013d13f2b996731c865b921df5a87a40e3f Mon Sep 17 00:00:00 2001
From: Chris Bieneman <chris.bieneman@me.com>
Date: Fri, 29 Jul 2022 14:20:27 -0500
Subject: [PATCH] [Docs] Add HLSL ResourceType documentation

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.

Differential Revision: https://reviews.llvm.org/D130794
---
 clang/docs/HLSL/HLSLDocs.rst          | 14 +++++++++++
 clang/docs/{ => HLSL}/HLSLSupport.rst |  0
 clang/docs/HLSL/ResourceTypes.rst     | 34 +++++++++++++++++++++++++++
 clang/docs/index.rst                  |  2 +-
 4 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 clang/docs/HLSL/HLSLDocs.rst
 rename clang/docs/{ => HLSL}/HLSLSupport.rst (100%)
 create mode 100644 clang/docs/HLSL/ResourceTypes.rst

diff --git a/clang/docs/HLSL/HLSLDocs.rst b/clang/docs/HLSL/HLSLDocs.rst
new file mode 100644
index 000000000000..0b66e517a73a
--- /dev/null
+++ b/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
diff --git a/clang/docs/HLSLSupport.rst b/clang/docs/HLSL/HLSLSupport.rst
similarity index 100%
rename from clang/docs/HLSLSupport.rst
rename to clang/docs/HLSL/HLSLSupport.rst
diff --git a/clang/docs/HLSL/ResourceTypes.rst b/clang/docs/HLSL/ResourceTypes.rst
new file mode 100644
index 000000000000..c537e824758b
--- /dev/null
+++ b/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.
diff --git a/clang/docs/index.rst b/clang/docs/index.rst
index 78a1ed12bcf3..81ffc9d7e5f0 100644
--- a/clang/docs/index.rst
+++ b/clang/docs/index.rst
@@ -46,7 +46,7 @@ Using Clang as a Compiler
    OpenCLSupport
    OpenMPSupport
    SYCLSupport
-   HLSLSupport
+   HLSL/HLSLDocs
    ThinLTO
    APINotes
    DebuggingCoroutines
-- 
2.34.1