[llvm] [DirectX][docs] Expand DXILArchitecture documentation (PR #84077)

[Chris B via llvm-commits]

https://github.com/llvm-beanz updated https://github.com/llvm/llvm-project/pull/84077

>From e946c1e5f9c995f37b0ca3b469abc7268fa98313 Mon Sep 17 00:00:00 2001
From: Chris Bieneman <chris.bieneman at me.com>
Date: Tue, 5 Mar 2024 16:05:52 -0600
Subject: [PATCH 1/3] Expand DXILArchitecture documentation

This just seeks to give a high level overview of the current state of
the DirectX backend. It doesn't go in too deep, but should be a starting
point for further documentation.
---
 llvm/docs/DirectX/DXILArchitecture.rst | 46 ++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/llvm/docs/DirectX/DXILArchitecture.rst b/llvm/docs/DirectX/DXILArchitecture.rst
index f47db5413631c5..32eee08f805bae 100644
--- a/llvm/docs/DirectX/DXILArchitecture.rst
+++ b/llvm/docs/DirectX/DXILArchitecture.rst
@@ -89,6 +89,52 @@ 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.
 
+DirectX Backend Flow
+--------------------
+
+The code generation flow for DXIL is broken into a series of passes. The passes
+are grouped into two flows:
+
+#. Generating DXIL IR.
+#. Generating DXIL Binary.
+
+The passes to generate DXIL IR follow the flow:
+
+DXILOpLowering -> DXILPrepare -> DXILTranslateMetadata
+
+Each of these passes has a defined responsibility:
+
+#. DXILOpLowering translates LLVM intrinsic calls to dx.op calls.
+#. DXILPrepare transforms the DXIL IR to be compatible with LLVM 3.7, and
+   inserts bitcasts to allow typed pointers to be inserted.
+#. DXILTranslateMetadata emits the DXIL Metadata structures.
+
+The passes to encode DXIL to binary in the DX Container follow the flow:
+
+DXILEmbedder -> DXContainerGlobals -> AsmPrinter
+
+These passes have defined responsibilities:
+
+#. DXILEmbedder runs the DXIL bitcode writer to generate a bitcode stream and
+   embeds the binary data inside a global in the original module.
+#. DXContainerGlobals generates binary data globals for the other DX Container
+   parts based on computed analysis passes.
+#. AsmPrinter is the standard LLVM infrastructure for emitting object files.
+
+When emitting DXIL into a DX Container file the MC layer is used in a similar
+way to how the Clang ``-fembed-bitcode`` option operates. The DX Container
+object writer knows how to construct the headers and structural fields of the
+container, and reads global variables from the module to fill in the remaining
+part data.
+
+DirectX Container
+-----------------
+
+The DirectX container format is treated in LLVM as an object file format.
+Reading is implemented between the BinaryFormat and Object libraries, and
+writing is implemented in the MC layer. Additional testing and inspection
+support are implemented in the ObjectYAML library and tools.
+
 Testing
 =======
 

>From 0a9ecd72bf4139b4f45c6b32d424dd952b3d0d3b Mon Sep 17 00:00:00 2001
From: Chris Bieneman <chris.bieneman at me.com>
Date: Tue, 5 Mar 2024 16:54:24 -0600
Subject: [PATCH 2/3] Indent the blocks as per @bogner's suggestion.

---
 llvm/docs/DirectX/DXILArchitecture.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/llvm/docs/DirectX/DXILArchitecture.rst b/llvm/docs/DirectX/DXILArchitecture.rst
index 32eee08f805bae..749bd5c5ae4a4f 100644
--- a/llvm/docs/DirectX/DXILArchitecture.rst
+++ b/llvm/docs/DirectX/DXILArchitecture.rst
@@ -100,7 +100,7 @@ are grouped into two flows:
 
 The passes to generate DXIL IR follow the flow:
 
-DXILOpLowering -> DXILPrepare -> DXILTranslateMetadata
+  DXILOpLowering -> DXILPrepare -> DXILTranslateMetadata
 
 Each of these passes has a defined responsibility:
 
@@ -111,7 +111,7 @@ Each of these passes has a defined responsibility:
 
 The passes to encode DXIL to binary in the DX Container follow the flow:
 
-DXILEmbedder -> DXContainerGlobals -> AsmPrinter
+  DXILEmbedder -> DXContainerGlobals -> AsmPrinter
 
 These passes have defined responsibilities:
 

>From 949ba9c53279b562e2560a301d44058693d05053 Mon Sep 17 00:00:00 2001
From: Chris B <cbieneman at microsoft.com>
Date: Tue, 5 Mar 2024 17:15:37 -0600
Subject: [PATCH 3/3] 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 749bd5c5ae4a4f..d6712bea4f7712 100644
--- a/llvm/docs/DirectX/DXILArchitecture.rst
+++ b/llvm/docs/DirectX/DXILArchitecture.rst
@@ -113,7 +113,7 @@ The passes to encode DXIL to binary in the DX Container follow the flow:
 
   DXILEmbedder -> DXContainerGlobals -> AsmPrinter
 
-These passes have defined responsibilities:
+Each of these passes have the following defined responsibilities:
 
 #. DXILEmbedder runs the DXIL bitcode writer to generate a bitcode stream and
    embeds the binary data inside a global in the original module.