[llvm] [clang-tools-extra] [clang] [DirectX][docs] Architecture and design philosophy of DXIL support (PR #78221)

[Justin Bogner via cfe-commits]

https://github.com/bogner updated https://github.com/llvm/llvm-project/pull/78221

>From 8903229f71503c1c4291254c355b1692d9d908a3 Mon Sep 17 00:00:00 2001
From: Justin Bogner <mail at justinbogner.com>
Date: Mon, 15 Jan 2024 18:14:07 -0800
Subject: [PATCH 1/2] =?UTF-8?q?[=F0=9D=98=80=F0=9D=97=BD=F0=9D=97=BF]=20in?=
 =?UTF-8?q?itial=20version?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Created using spr 1.3.5-bogner
---
 llvm/docs/DirectX/DXILArchitecture.rst | 102 +++++++++++++++++++++++++
 llvm/docs/DirectXUsage.rst             |   2 +
 2 files changed, 104 insertions(+)
 create mode 100644 llvm/docs/DirectX/DXILArchitecture.rst

diff --git a/llvm/docs/DirectX/DXILArchitecture.rst b/llvm/docs/DirectX/DXILArchitecture.rst
new file mode 100644
index 000000000000000..9d1edefc3a76865
--- /dev/null
+++ b/llvm/docs/DirectX/DXILArchitecture.rst
@@ -0,0 +1,102 @@
+===============================================
+Architecture and Design of DXIL Support in LLVM
+===============================================
+
+.. contents::
+   :local:
+
+.. toctree::
+   :hidden:
+
+Introduction
+============
+
+LLVM supports reading and writing the `DirectX Intermediate Language.
+<https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst>`_,
+or DXIL. DXIL is essentially LLVM 3.7 era bitcode with some
+restrictions and various semantically important operations and
+metadata.
+
+LLVM's implementation philosophy for DXIL support is to treat DXIL as
+merely a representation format as much as possible. When reading DXIL,
+we should translate everyting to generic LLVM constructs when
+possible. Similarly, we should introduce DXIL-specific constructs as
+late as possible in the process of lowering to the format.
+
+There are three places to look for DXIL related code in LLVM: The
+`DirectX` backend, for writing DXIL; The `DXILUpgrade` pass, for
+reading; and in library code that is shared between writing and
+reading. We'll describe these in reverse order.
+
+Common Code for Reading and Writing
+===================================
+
+There's quite a bit of logic that needs to be shared between reading
+and writing DXIL in order to avoid code duplication. While we don't
+have a hard and fast rule about where such code should live, there are
+generally three sensible places. Simple definitions of enums and
+values that must stay fixed to match DXIL's ABI can be found in
+`Support/DXILABI.h`, utilities to translate bidirectionally between
+DXIL and modern LLVM constructs live in `lib/Transforms/Utils`, and
+more analyses that are needed to derive or preserve information are
+implemented as typical `lib/Analysis` passes.
+
+The DXILUpgrade Pass
+====================
+
+Translating DXIL to LLVM IR takes advantage of the fact that DXIL is
+compatible with LLVM 3.7 bitcode, and that modern LLVM is capable of
+"upgrading" older bitcode into modern IR. Simply relying on the
+bitcode upgrade process isn't sufficient though, since that leaves a
+number of DXIL specific constructs around. Thus, we have the
+`DXILUpgrade` pass to transform DXIL operations to LLVM operations and
+smooth over differences in metadata representation.
+
+The DirectX Backend
+===================
+
+The DirectX backend lowers LLVM IR into DXIL. As we're transforming to
+an intermediate format rather than a specific ISA, this backend does
+not follow the instruction selection patterns you might be familiar
+with from other backends. There are two parts to lowering DXIL - a set
+of passes that mutate various constructs into a form that matches how
+DXIL represents those constructs, followed by a limited bitcode
+"downgrader pass".
+
+Before emitting DXIL, the DirectX backend needs to modify the LLVM IR
+such that external operations, types, and metadata is represented in
+the way that DXIL expects. For example, `DXILOpLowering` translates
+intrinsics into `dx.op` calls. It's encouraged to implement parts of
+the DXIL lowering as these kinds of IR to IR passes when possible, as
+that means that they can be easily tested with `opt` and `FileCheck`
+without the need for external tooling.
+
+The second part of DXIL emission is more or less an LLVM bitcode
+downgrader. We need to emit bitcode that matches the LLVM 3.7
+representation. For this, we have `DXILWriter`, which is an alternate
+version of LLVM's `BitcodeWriter`. At present, this is able to
+leverage LLVM's current bitcode libraries to do a lot of the work, but
+it's possible that at some point in the future it will need to be
+completely separate as modern LLVM bitcode evolves.
+
+Testing
+=======
+
+A lot of DXIL testing can be one with typical IR to IR tests using
+`opt` and `FileCheck`, since a lot of the support is implemented in
+terms of IR level passes as described in the previous sections. You
+can see examples of this in `llvm/test/CodeGen/DirectX` as well as
+`llvm/test/Transforms/DXILUpgrade`, and this type of testing should be
+leveraged as much as possible.
+
+However, when it comes to testing the DXIL format itself, IR passes
+are insufficient for testing. For now, the best option we have
+available is using the DXC project's tools in order to round trip.
+These tests are currently found in `test/tools/dxil-dis` and are only
+available if the `LLVM_INCLUDE_DXIL_TESTS` cmake option is set. Note
+that we do not currently have the equivalent testing set up for the
+DXIL reading path.
+
+In the future, we will also want to round trip using the DXIL writing
+and reading paths in order to ensure self consistency and to get test
+coverage when `dxil-dis` isn't available.
diff --git a/llvm/docs/DirectXUsage.rst b/llvm/docs/DirectXUsage.rst
index 18b5c6d02cb00e6..79543e19bd34bb4 100644
--- a/llvm/docs/DirectXUsage.rst
+++ b/llvm/docs/DirectXUsage.rst
@@ -13,6 +13,8 @@ User Guide for the DirectX Target
 .. toctree::
    :hidden:
 
+   DirectX/DXILArchitecture
+
 Introduction
 ============
 

>From 2bd4f857a9e6c1cbf931bd48121d674c03c759b5 Mon Sep 17 00:00:00 2001
From: Justin Bogner <mail at justinbogner.com>
Date: Sat, 27 Jan 2024 14:30:43 -0800
Subject: [PATCH 2/2] Update llvm/docs/DirectX/DXILArchitecture.rst

Co-authored-by: S. Bharadwaj Yadavalli <Bharadwaj.Yadavalli at microsoft.com>
---
 llvm/docs/DirectX/DXILArchitecture.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/llvm/docs/DirectX/DXILArchitecture.rst b/llvm/docs/DirectX/DXILArchitecture.rst
index 9d1edefc3a76865..19b61fc7648b670 100644
--- a/llvm/docs/DirectX/DXILArchitecture.rst
+++ b/llvm/docs/DirectX/DXILArchitecture.rst
@@ -82,7 +82,7 @@ completely separate as modern LLVM bitcode evolves.
 Testing
 =======
 
-A lot of DXIL testing can be one with typical IR to IR tests using
+A lot of DXIL testing can be done with typical IR to IR tests using
 `opt` and `FileCheck`, since a lot of the support is implemented in
 terms of IR level passes as described in the previous sections. You
 can see examples of this in `llvm/test/CodeGen/DirectX` as well as