[llvm-branch-commits] [llvm] [docs] Finish MyST migration for PDB, DirectX, and GlobalISel docs (PR #217159)

[Justin Bogner via llvm-branch-commits]

================
@@ -1,105 +1,105 @@
-======================
-DXIL Resource Handling
-======================
+# DXIL Resource Handling
 
+```{toctree}
+:hidden: true
+```
 
-.. toctree::
-   :hidden:
+## Introduction
 
-Introduction
-============
-
-Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+Resources in DXIL are represented via `TargetExtType` in LLVM IR and
 eventually lowered by the DirectX backend into metadata in DXIL.
 
 In DXC and DXIL, static resources are represented as lists of SRVs (Shader
 Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
 Samplers. This metadata consists of a "resource record ID" which uniquely
 identifies a resource and type information. As of shader model 6.6, there are
 also dynamic resources, which forgo the metadata and are described via
-``annotateHandle`` operations in the instruction stream instead.
+`annotateHandle` operations in the instruction stream instead.
 
 In LLVM we attempt to unify some of the alternative representations that are
 present in DXC, with the aim of making handling of resources in the middle end
 of the compiler simpler and more consistent.
 
-Resource Type Information and Properties
-========================================
+## Resource Type Information and Properties
 
 There are a number of properties associated with a resource in DXIL.
 
 `Resource ID`
-   An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
 
-   In LLVM we don't bother representing this, instead opting to generate it at
-   DXIL lowering time.
+: An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+  In LLVM we don't bother representing this, instead opting to generate it at
+  DXIL lowering time.
 
 `Binding information`
-   Information about where the resource comes from. This is either (a) a
-   register space, lower bound in that space, and size of the binding, or (b)
-   an index into a dynamic resource heap.
 
-   In LLVM we represent binding information in the arguments of the
-   :ref:`handle creation intrinsics <dxil-resources-handles>`. When generating
-   DXIL we transform these calls to metadata, ``dx.op.createHandle``,
-   ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
-   ``dx.op.createHandleForLib`` as needed.
+: Information about where the resource comes from. This is either (a) a
+  register space, lower bound in that space, and size of the binding, or (b)
+  an index into a dynamic resource heap.
+
+  In LLVM we represent binding information in the arguments of the
+  {ref}`handle creation intrinsics <dxil-resources-handles>`. When generating
+  DXIL we transform these calls to metadata, `dx.op.createHandle`,
+  `dx.op.createHandleFromBinding`, `dx.op.createHandleFromHeap`, and
+  `dx.op.createHandleForLib` as needed.
 
 `Type information`
-   The type of data that's accessible via the resource. For buffers and
-   textures this can be a simple type like ``float`` or ``float4``, a struct,
-   or raw bytes. For constant buffers this is just a size. For samplers this is
-   the kind of sampler.
 
-   In LLVM we embed this information as a parameter on the ``target()`` type of
-   the resource. See :ref:`dxil-resources-types-of-resource`.
+: The type of data that's accessible via the resource. For buffers and
+  textures this can be a simple type like `float` or `float4`, a struct,
+  or raw bytes. For constant buffers this is just a size. For samplers this is
+  the kind of sampler.
+
+  In LLVM we embed this information as a parameter on the `target()` type of
+  the resource. See {ref}`dxil-resources-types-of-resource`.
 
 `Resource kind information`
-   The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
-   ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
-   set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
-   certain properties such as ``IsUAV`` and ``IsROV``.
 
-   In LLVM we represent this in the ``target()`` type. We omit information
-   that's deriveable from the type information, but we do have fields to encode
-   ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+: The kind of resource. In HLSL we have things like `ByteAddressBuffer`,
+  `RWTexture2D`, and `RasterizerOrderedStructuredBuffer`. These map to a
+  set of DXIL kinds like `RawBuffer` and `Texture2D` with fields for
+  certain properties such as `IsUAV` and `IsROV`.
 
-.. note:: TODO: There are two fields in the DXIL metadata that are not
-   represented as part of the target type: ``IsGloballyCoherent`` and
-   ``HasCounter``.
+  In LLVM we represent this in the `target()` type. We omit information
+  that's deriveable from the type information, but we do have fields to encode
+  `IsWriteable`, `IsROV`, and `SampleCount` when needed.
 
-   Since these are derived from analysis, storing them on the type would mean
-   we need to change the type during the compiler pipeline. That just isn't
-   practical. It isn't entirely clear to me that we need to serialize this info
-   into the IR during the compiler pipeline anyway - we can probably get away
-   with an analysis pass that can calculate the information when we need it.
+:::{note}
+TODO: There are two fields in the DXIL metadata that are not
+represented as part of the target type: `IsGloballyCoherent` and
+`HasCounter`.
 
-   If analysis is insufficient we'll need something akin to ``annotateHandle``
-   (but limited to these two properties) or to encode these in the handle
-   creation.
+Since these are derived from analysis, storing them on the type would mean
+we need to change the type during the compiler pipeline. That just isn't
+practical. It isn't entirely clear to me that we need to serialize this info
+into the IR during the compiler pipeline anyway - we can probably get away
+with an analysis pass that can calculate the information when we need it.
 
-.. _dxil-resources-types-of-resource:
+If analysis is insufficient we'll need something akin to `annotateHandle`
+(but limited to these two properties) or to encode these in the handle
+creation.
+:::
 
-Types of Resource
-=================
+(dxil-resources-types-of-resource)=
 
-We define a set of ``TargetExtTypes`` that is similar to the HLSL
+## Types of Resource
+
+We define a set of `TargetExtTypes` that is similar to the HLSL
 representations for the various resources, albeit with a few things
 parameterized. This is different than DXIL, as simplifying the types to
 something like "dx.srv" and "dx.uav" types would mean the operations on these
 types would have to be overly generic.
 
-Buffers
--------
-
-.. code-block:: llvm
+### Buffers
 
-   target("dx.TypedBuffer", ElementType, IsWriteable, IsROV, IsSigned)
-   target("dx.RawBuffer", ElementType, IsWriteable, IsROV)
+```llvm
+target("dx.TypedBuffer", ElementType, IsWriteable, IsROV, IsSigned)
+target("dx.RawBuffer", ElementType, IsWriteable, IsROV)
+```
 
 We need two separate buffer types to account for the differences between the
-16-byte `bufferLoad`_ / `bufferStore`_ operations that work on DXIL's
-TypedBuffers and the `rawBufferLoad`_ / `rawBufferStore`_ operations that are
+16-byte [bufferLoad][bufferload] / [bufferStore][bufferstore] operations that work on DXIL's
+TypedBuffers and the [rawBufferLoad][rawbufferload] / [rawBufferStore][rawbufferstore] operations that are
----------------
bogner wrote:

It's pretty strange that it's decided to make an entirely lowercase version of the reference instead of just using `bufferLoad` and the like verbatim here. I would have expected:

```suggestion
16-byte [bufferLoad] / [bufferStore] operations that work on DXIL's
TypedBuffers and the [rawBufferLoad] / [rawBufferStore] operations that are
```


https://github.com/llvm/llvm-project/pull/217159