[llvm-branch-commits] [llvm] [docs] Finish MyST migration for PDB, DirectX, and GlobalISel docs (PR #217159)
Justin Bogner via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Thu Aug 20 11:59:43 PDT 2026
================
@@ -791,153 +793,150 @@ space as 2 32-bit values.
In version 1.1, the root descriptor is 12 bytes. It matches the 1.0 descriptor
but adds a 32-bit access flag.
-.. code-block:: c
+```c
+struct RootDescriptor_V1_0 {
+ uint32_t ShaderRegister;
+ uint32_t RegisterSpace;
+};
- struct RootDescriptor_V1_0 {
- uint32_t ShaderRegister;
- uint32_t RegisterSpace;
- };
-
- struct RootDescriptor_V1_1 {
- uint32_t ShaderRegister;
- uint32_t RegisterSpace;
- uint32_t Flags;
- };
+struct RootDescriptor_V1_1 {
+ uint32_t ShaderRegister;
+ uint32_t RegisterSpace;
+ uint32_t Flags;
+};
+```
-Root Descriptor Table
-'''''''''''''''''''''
+##### Root Descriptor Table
-Descriptor tables let shaders access multiple resources through a single pointer
-to a descriptor heap.
+Descriptor tables let shaders access multiple resources through a single pointer
+to a descriptor heap.
-The tables are made of a collection of descriptor ranges. In Version 1.0, the
+The tables are made of a collection of descriptor ranges. In Version 1.0, the
descriptor range is 20 bytes, containing five 32-bit values. It encodes a range
-of registers, including the register type, range length, register numbers and
+of registers, including the register type, range length, register numbers and
space within range and the offset locating each range inside the table.
In version 1.1, the descriptor range is 24 bytes. It matches the 1.0 descriptor
but adds a 32-bit access flag.
-.. code-block:: c
-
- struct DescriptorRange_V1_0 {
- dxil::ResourceClass RangeType;
- uint32_t NumDescriptors;
- uint32_t BaseShaderRegister;
- uint32_t RegisterSpace;
- uint32_t OffsetInDescriptorsFromTableStart;
- };
-
- struct DescriptorRange_V1_1 {
- dxil::ResourceClass RangeType;
- uint32_t NumDescriptors;
- uint32_t BaseShaderRegister;
- uint32_t RegisterSpace;
- uint32_t Flags;
- uint32_t OffsetInDescriptorsFromTableStart;
- };
-
-Static Samplers
-~~~~~~~~~~~~~~~
-
-Static samplers are predefined filtering settings built into the root signature,
-avoiding descriptor heap lookups.
-
-This section also has a variable size, since it can contain multiple static
-samplers definitions. However, the definition is a fixed sized struct,
-containing 13 32-byte fields of various enum, float, and integer values.
+```c
+struct DescriptorRange_V1_0 {
+ dxil::ResourceClass RangeType;
+ uint32_t NumDescriptors;
+ uint32_t BaseShaderRegister;
+ uint32_t RegisterSpace;
+ uint32_t OffsetInDescriptorsFromTableStart;
+};
+
+struct DescriptorRange_V1_1 {
+ dxil::ResourceClass RangeType;
+ uint32_t NumDescriptors;
+ uint32_t BaseShaderRegister;
+ uint32_t RegisterSpace;
+ uint32_t Flags;
+ uint32_t OffsetInDescriptorsFromTableStart;
+};
+```
+
+#### Static Samplers
+
+Static samplers are predefined filtering settings built into the root signature,
+avoiding descriptor heap lookups.
+
+This section also has a variable size, since it can contain multiple static
+samplers definitions. However, the definition is a fixed sized struct,
+containing 13 32-byte fields of various enum, float, and integer values.
In version 1.2, the static sampler is 17 bytes. It matches the 1.0 static sampler
-but adds a 32-bit access flag. In Version 1.1, it matches static sampler
+but adds a 32-bit access flag. In Version 1.1, it matches static sampler
version 1.0.
-.. code-block:: c
-
- struct StaticSamplerDesc {
- dxbc::FilterMode Filter;
- dxbc::TextureAddressMode AddressU;
- dxbc::TextureAddressMode AddressV;
- dxbc::TextureAddressMode AddressW;
- float MipLODBias;
- uint32_t MaxAnisotropy;
- dxbc::ComparisonFunc ComparisonFunc;
- dxbc::StaticBorderColor BorderColor;
- float MinLOD;
- float MaxLOD;
- uint32_t ShaderRegister;
- uint32_t RegisterSpace;
- dxbc::ShaderVisibility ShaderVisibility;
- };
-
-SFI0 Part
----------
-.. _SFI0:
+```c
+struct StaticSamplerDesc {
+ dxbc::FilterMode Filter;
+ dxbc::TextureAddressMode AddressU;
+ dxbc::TextureAddressMode AddressV;
+ dxbc::TextureAddressMode AddressW;
+ float MipLODBias;
+ uint32_t MaxAnisotropy;
+ dxbc::ComparisonFunc ComparisonFunc;
+ dxbc::StaticBorderColor BorderColor;
+ float MinLOD;
+ float MaxLOD;
+ uint32_t ShaderRegister;
+ uint32_t RegisterSpace;
+ dxbc::ShaderVisibility ShaderVisibility;
+};
+```
+
+### SFI0 Part
+
+(SFI0)=
The SFI0 part encodes a 64-bit unsigned integer bitmask of the feature flags.
This denotes which optional features the shader requires. The flag values are
-defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def <https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def>`_.
+defined in [llvm/include/llvm/BinaryFormat/DXContainerConstants.def](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def).
-Compiler Flags
-==============
+## Compiler Flags
-.. _compiler_flags:
+(compiler_flags)=
-When compiling HLSL with :program:`dxc`, several flags control whether
+When compiling HLSL with {program}`dxc`, several flags control whether
debug information is embedded in the main DXContainer output, written to a
-companion PDB file, or both. Use ``/Zi`` for full debug output or ``/Zs`` for
-slim debug output without an `ILDB`_ part. In :program:`clang-dxc`, most
-dxc-style flags are forwarded to :program:`llc` as ``-mllvm`` options.
+companion PDB file, or both. Use `/Zi` for full debug output or `/Zs` for
+slim debug output without an {ref}`ILDB <ILDB>` part. In {program}`clang-dxc`, most
+dxc-style flags are forwarded to {program}`llc` as `-mllvm` options.
-Debug Output Locations
-----------------------
+### Debug Output Locations
-Debug information is enabled with either ``/Zi`` (full debug) or ``/Zs`` (slim
+Debug information is enabled with either `/Zi` (full debug) or `/Zs` (slim
debug). The two flags are mutually exclusive.
-**Full debug with ``/Zi``**
+**Full debug with `/Zi`**
-When ``/Zi`` is enabled, the `ILDB`_ part can appear in the main DXContainer
+When `/Zi` is enabled, the {ref}`ILDB <ILDB>` part can appear in the main DXContainer
output, in a companion PDB, or both:
-* **Embedded in the main DXContainer output.** The `ILDB`_ part holds the
+- **Embedded in the main DXContainer output.** The {ref}`ILDB <ILDB>` part holds the
unstripped DXIL module with debug information. It is included when
- ``/Qembed_debug`` is used. The main output always contains the stripped `DXIL`_
- part alongside other parts such as `HASH`_, `ILDN`_, and `VERS`_.
-* **Omitted from the main DXContainer output.** When ``/Qstrip_debug`` is used,
- the `ILDB`_ part is not written to the main output. Other debug-related parts
- such as `ILDN`_ are still emitted. If ``/Fd`` is also specified, the `ILDB`_
- part is still written to the companion PDB. ``/Qstrip_debug`` takes precedence
- over the default ``/Qembed_debug`` behavior when ``/Zi`` is used without
- ``/Fd``. If both ``/Qstrip_debug`` and ``/Qembed_debug`` are specified,
- ``/Qstrip_debug`` is ignored and the `ILDB`_ part is embedded.
-* **In a companion PDB file.** A sidecar ``.pdb`` stores a DXContainer stream
- with debug-related parts including `ILDB`_, `SRCI`_, and `VERS`_. This is
- produced when ``/Fd`` names an output path. Use :program:`llvm-pdbutil` to
+ `/Qembed_debug` is used. The main output always contains the stripped {ref}`DXIL <DXIL>`
+ part alongside other parts such as {ref}`HASH <HASH>`, {ref}`ILDN <ILDN>`, and {ref}`VERS <VERS>`.
+- **Omitted from the main DXContainer output.** When `/Qstrip_debug` is used,
+ the {ref}`ILDB <ILDB>` part is not written to the main output. Other debug-related parts
+ such as {ref}`ILDN <ILDN>` are still emitted. If `/Fd` is also specified, the {ref}`ILDB <ILDB>`
+ part is still written to the companion PDB. `/Qstrip_debug` takes precedence
+ over the default `/Qembed_debug` behavior when `/Zi` is used without
+ `/Fd`. If both `/Qstrip_debug` and `/Qembed_debug` are specified,
+ `/Qstrip_debug` is ignored and the {ref}`ILDB <ILDB>` part is embedded.
+- **In a companion PDB file.** A sidecar `.pdb` stores a DXContainer stream
+ with debug-related parts including {ref}`ILDB <ILDB>`, {ref}`SRCI <SRCI>`, and {ref}`VERS <VERS>`. This is
+ produced when `/Fd` names an output path. Use {program}`llvm-pdbutil` to
inspect or extract that stream (see
- :doc:`llvm-pdbutil <../CommandGuide/llvm-pdbutil>`).
-* **Embedded in the private data of the main output.** When
- ``/Qpdb_in_private`` is used, a copy of the companion PDB file is stored as
- opaque bytes in `PRIV`_. This can be used with or without ``/Fd``; without
- ``/Fd``, the PDB is not retained as a separate file on disk. After extraction,
- tools treat the bytes as a standalone ``.pdb`` file.
-
-``/Fd`` can be combined with ``/Qembed_debug`` or ``/Qpdb_in_private`` to
+ {doc}`llvm-pdbutil <../CommandGuide/llvm-pdbutil>`).
+- **Embedded in the private data of the main output.** When
+ `/Qpdb_in_private` is used, a copy of the companion PDB file is stored as
+ opaque bytes in {ref}`PRIV <PRIV>`. This can be used with or without `/Fd`; without
+ `/Fd`, the PDB is not retained as a separate file on disk. After extraction,
+ tools treat the bytes as a standalone `.pdb` file.
+
+`/Fd` can be combined with `/Qembed_debug` or `/Qpdb_in_private` to
write full debug information to more than one location.
-**Slim debug with ``/Zs``**
+**Slim debug with `/Zs`**
-When ``/Zs`` is enabled, slim debug information is emitted. The `ILDB`_ part is
-omitted from the main DXContainer output and from any companion PDB or `PRIV`_
-embedding, but other debug-related parts such as `HASH`_, `ILDN`_, `SRCI`_, and
-`VERS`_ are still emitted. A companion PDB from ``/Fd`` or a `PRIV`_ embedding
-from ``/Qpdb_in_private`` therefore contains slim debug data only.
+When `/Zs` is enabled, slim debug information is emitted. The {ref}`ILDB <ILDB>` part is
+omitted from the main DXContainer output and from any companion PDB or {ref}`PRIV <PRIV>`
+embedding, but other debug-related parts such as {ref}`HASH <HASH>`, {ref}`ILDN <ILDN>`, {ref}`SRCI <SRCI>`, and
+{ref}`VERS <VERS>` are still emitted. A companion PDB from `/Fd` or a {ref}`PRIV <PRIV>` embedding
+from `/Qpdb_in_private` therefore contains slim debug data only.
-``/Zs`` cannot be combined with ``/Qembed_debug`` or ``/Qsource_in_debug_module``.
+`/Zs` cannot be combined with `/Qembed_debug` or `/Qsource_in_debug_module`.
-The table below summarizes the :program:`dxc` flags that affect this behavior.
-The **llc flag** column lists the ``-mllvm`` option the driver forwards when
+The table below summarizes the {program}`dxc` flags that affect this behavior.
+The **llc flag** column lists the `-mllvm` option the driver forwards when
invoking the backend.
+```{eval-rst}
.. list-table::
:header-rows: 1
:widths: 20 20 20 40
----------------
bogner wrote:
and then, despite the converter clearly knowing about `:::{list-table}`, it seems to give up and fall back to `eval-rst` here. I assume we don't really want `eval-rst` in our docs going forward, so I guess this should be along the lines of:
```suggestion
:::{list-table}
:widths: 20 20 20 40
:header-rows: 1
```
However, this does leave the contents of the block unconverted. Can we fix this easily with your tooling or would it be easier for me to follow up afterwards to fix it manually? This comes up again later in this file and there are quite a few instances of this problem in `DXILResources.md`.
https://github.com/llvm/llvm-project/pull/217159
More information about the llvm-branch-commits
mailing list