[llvm-branch-commits] [llvm] [docs] Finish MyST migration for PDB, DirectX, and GlobalISel docs (PR #217159)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Wed Aug 19 11:55:46 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-llvm-globalisel
Author: Reid Kleckner (rnk)
<details>
<summary>Changes</summary>
Tracking issue: #<!-- -->201242
See the [migration guide] for more information.
[migration guide]: https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines
This is a stacked PR based on #<!-- -->217157 , which will be a standalone commit that
renames *.rst -> *.md before this PR lands for history preservation purposes.
This was prepared with rst2myst plus LLM-assisted cleanup.
I rendered the HTML and ran a pixel differ over it, and all the diffs look intended, but I have *not* gone over the markup in detail. I encourage reviewers to try to spot check content they care about, or look at complex constructs and prioritize reviewing those, rather than fixating on markup nits.
-----
Before/after validation links:
| Source file | Before HTML | After HTML |
| --- | --- | --- |
| `llvm/docs/DirectX/DXContainer.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/DirectX/DXContainer.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/DirectX/DXContainer.html) |
| `llvm/docs/DirectX/DXILArchitecture.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/DirectX/DXILArchitecture.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/DirectX/DXILArchitecture.html) |
| `llvm/docs/DirectX/DXILOpTableGenDesign.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/DirectX/DXILOpTableGenDesign.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/DirectX/DXILOpTableGenDesign.html) |
| `llvm/docs/DirectX/DXILResources.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/DirectX/DXILResources.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/DirectX/DXILResources.html) |
| `llvm/docs/DirectX/RootSignatures.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/DirectX/RootSignatures.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/DirectX/RootSignatures.html) |
| `llvm/docs/GlobalISel/GMIR.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/GMIR.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/GMIR.html) |
| `llvm/docs/GlobalISel/GenericOpcode.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/GenericOpcode.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/GenericOpcode.html) |
| `llvm/docs/GlobalISel/IRTranslator.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/IRTranslator.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/IRTranslator.html) |
| `llvm/docs/GlobalISel/InstructionSelect.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/InstructionSelect.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/InstructionSelect.html) |
| `llvm/docs/GlobalISel/KnownBits.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/KnownBits.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/KnownBits.html) |
| `llvm/docs/GlobalISel/Legalizer.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/Legalizer.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/Legalizer.html) |
| `llvm/docs/GlobalISel/MIRPatterns.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/MIRPatterns.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/MIRPatterns.html) |
| `llvm/docs/GlobalISel/Pipeline.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/Pipeline.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/Pipeline.html) |
| `llvm/docs/GlobalISel/Porting.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/Porting.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/Porting.html) |
| `llvm/docs/GlobalISel/RegBankSelect.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/RegBankSelect.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/RegBankSelect.html) |
| `llvm/docs/GlobalISel/Resources.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/Resources.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/Resources.html) |
| `llvm/docs/GlobalISel/index.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/GlobalISel/index.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/GlobalISel/index.html) |
| `llvm/docs/PDB/CodeViewSymbols.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/PDB/CodeViewSymbols.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/PDB/CodeViewSymbols.html) |
| `llvm/docs/PDB/CodeViewTypes.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/PDB/CodeViewTypes.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/PDB/CodeViewTypes.html) |
| `llvm/docs/PDB/DbiStream.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/PDB/DbiStream.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/PDB/DbiStream.html) |
| `llvm/docs/PDB/GlobalStream.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/PDB/GlobalStream.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/PDB/GlobalStream.html) |
| `llvm/docs/PDB/HashTable.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/PDB/HashTable.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/PDB/HashTable.html) |
| `llvm/docs/PDB/ModiStream.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/PDB/ModiStream.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/PDB/ModiStream.html) |
| `llvm/docs/PDB/MsfFile.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/PDB/MsfFile.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/PDB/MsfFile.html) |
| `llvm/docs/PDB/PdbStream.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/PDB/PdbStream.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/PDB/PdbStream.html) |
| `llvm/docs/PDB/PublicStream.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/PDB/PublicStream.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/PDB/PublicStream.html) |
| `llvm/docs/PDB/TpiStream.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/PDB/TpiStream.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/PDB/TpiStream.html) |
---
Patch is 438.06 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/217159.diff
27 Files Affected:
- (modified) llvm/docs/DirectX/DXContainer.md (+572-571)
- (modified) llvm/docs/DirectX/DXILArchitecture.md (+49-59)
- (modified) llvm/docs/DirectX/DXILOpTableGenDesign.md (+323-323)
- (modified) llvm/docs/DirectX/DXILResources.md (+396-383)
- (modified) llvm/docs/DirectX/RootSignatures.md (+141-174)
- (modified) llvm/docs/GlobalISel/GMIR.md (+106-112)
- (modified) llvm/docs/GlobalISel/GenericOpcode.md (+441-600)
- (modified) llvm/docs/GlobalISel/IRTranslator.md (+67-77)
- (modified) llvm/docs/GlobalISel/InstructionSelect.md (+46-54)
- (modified) llvm/docs/GlobalISel/KnownBits.md (+63-62)
- (modified) llvm/docs/GlobalISel/Legalizer.md (+158-170)
- (modified) llvm/docs/GlobalISel/MIRPatterns.md (+478-486)
- (modified) llvm/docs/GlobalISel/Pipeline.md (+78-75)
- (modified) llvm/docs/GlobalISel/Porting.md (+12-14)
- (modified) llvm/docs/GlobalISel/RegBankSelect.md (+26-33)
- (modified) llvm/docs/GlobalISel/Resources.md (+8-9)
- (modified) llvm/docs/GlobalISel/index.md (+55-59)
- (modified) llvm/docs/PDB/CodeViewSymbols.md (+258-331)
- (modified) llvm/docs/PDB/CodeViewTypes.md (+129-180)
- (modified) llvm/docs/PDB/DbiStream.md (+284-317)
- (modified) llvm/docs/PDB/GlobalStream.md (+2-3)
- (modified) llvm/docs/PDB/HashTable.md (+57-67)
- (modified) llvm/docs/PDB/ModiStream.md (+41-52)
- (modified) llvm/docs/PDB/MsfFile.md (+90-96)
- (modified) llvm/docs/PDB/PdbStream.md (+89-96)
- (modified) llvm/docs/PDB/PublicStream.md (+2-3)
- (modified) llvm/docs/PDB/TpiStream.md (+186-223)
``````````diff
diff --git a/llvm/docs/DirectX/DXContainer.md b/llvm/docs/DirectX/DXContainer.md
index d35a2333deff9..69837b55ab0aa 100644
--- a/llvm/docs/DirectX/DXContainer.md
+++ b/llvm/docs/DirectX/DXContainer.md
@@ -1,13 +1,10 @@
-=================
-DirectX Container
-=================
+# DirectX Container
+```{toctree}
+:hidden: true
+```
-.. toctree::
- :hidden:
-
-Overview
-========
+## Overview
The DirectX Container (DXContainer) file format is the binary file format for
compiled shaders targeting the DirectX runtime. The file format is also called
@@ -20,8 +17,7 @@ the DirectX runtime, profiling tools and other users. This document serves as a
companion to the implementation in LLVM to more completely document the file
format for its many users.
-Basic Structure
-===============
+## Basic Structure
A DXContainer file begins with a header, and is then followed by a sequence of
"parts", which are analogous to object file sections. Each part contains a part
@@ -31,189 +27,189 @@ DX Container data structures are encoded little-endian in the binary file.
The LLVM versions of all data structures described and/or referenced in this
file are defined in
-`llvm/include/llvm/BinaryFormat/DXContainer.h
-<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainer.h>`_.
+[llvm/include/llvm/BinaryFormat/DXContainer.h](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainer.h).
Some pseudo code is provided in blocks below to ease understanding of this
document, but reading it with the header available will provide the most
clarity.
-File Header
------------
-
-.. code-block:: c
+### File Header
- struct Header {
- uint8_t Magic[4];
- uint8_t Digest[16];
- uint16_t MajorVersion;
- uint16_t MinorVersion;
- uint32_t FileSize;
- uint32_t PartCount;
- };
+```c
+struct Header {
+ uint8_t Magic[4];
+ uint8_t Digest[16];
+ uint16_t MajorVersion;
+ uint16_t MinorVersion;
+ uint32_t FileSize;
+ uint32_t PartCount;
+};
+```
The DXContainer header matches the pseudo-definition above. It begins with a
-four character code (magic number) with the value ``DXBC`` to denote the file
+four character code (magic number) with the value `DXBC` to denote the file
format.
-The ``Digest`` is a 128bit hash digest computed with a proprietary algorithm and
+The `Digest` is a 128bit hash digest computed with a proprietary algorithm and
encoded in the binary by the bytecode validator.
-The ``MajorVersion`` and ``MinorVersion`` encode the file format version
-``1.0``.
+The `MajorVersion` and `MinorVersion` encode the file format version
+`1.0`.
The remaining fields encode 32-bit unsigned integers for the file size and
number of parts.
-Following the part header is an array of ``PartCount`` 32-bit unsigned integers
+Following the part header is an array of `PartCount` 32-bit unsigned integers
specifying the offsets of each part header.
-Part Data
----------
-
-.. code-block:: c
+### Part Data
- struct PartHeader {
- uint8_t Name[4];
- uint32_t Size;
- }
+```c
+struct PartHeader {
+ uint8_t Name[4];
+ uint32_t Size;
+}
+```
Each part begins with a part header. A part header includes the 4-character part
name, and a 32-bit unsigned integer specifying the size of the part data. The
-part header is followed by ``Size`` bytes of data comprising the part. The
+part header is followed by `Size` bytes of data comprising the part. The
format does not explicitly require 32-bit alignment of parts, although LLVM does
implement this restriction in the writer code (because it's a good idea). The
LLVM object reader code does not assume inputs are correctly aligned to avoid
undefined behavior caused by misaligned inputs generated by other compilers.
-The :ref:`PRIV <PRIV>` part is an exception: DXContainer writer code in LLVM may
+The {ref}`PRIV <PRIV>` part is an exception: DXContainer writer code in LLVM may
produce a PRIV part with size which is not a multiple of four bytes.
-Part Formats
-============
+## Part Formats
The part name indicates the format of the part data. There are 24 part headers
used by DXC and FXC. Not all compiled shaders contain all parts. In the list
below parts generated only by DXC are marked with †, and parts generated only by
FXC are marked with \*.
-#. `DXIL`_† - Stores the DXIL bytecode.
-#. `HASH`_† - Stores the shader MD5 hash.
-#. `ILDB`_† - Stores the DXIL bytecode with LLVM Debug Information embedded in the module.
-#. `ILDN`_† - Stores shader debug name for external debug information.
-#. `ISG1`_ - Stores the input signature for Shader Model 5.1+.
-#. ISGN\* - Stores the input signature for Shader Model 4 and earlier.
-#. `OSG1`_ - Stores the output signature for Shader Model 5.1+.
-#. OSG5\* - Stores the output signature for Shader Model 5.
-#. OSGN\* - Stores the output signature for Shader Model 4 and earlier.
-#. PCSG\* - Stores the patch constant signature for Shader Model 5.1 and earlier.
-#. PDBI† - Stores PDB information.
-#. `PRIV`_† - Stores private data, including embedded companion PDB files.
-#. `PSG1`_ - Stores the patch constant signature for Shader Model 6+.
-#. `PSV0`_ - Stores Pipeline State Validation data.
-#. RDAT† - Stores Runtime Data.
-#. RDEF\* - Stores resource definitions.
-#. `RTS0`_ - Stores compiled root signature.
-#. `SFI0`_ - Stores shader feature flags.
-#. SHDR\* - Stores compiled DXBC bytecode.
-#. SHEX\* - Stores compiled DXBC bytecode.
-#. DXBC\* - Stores compiled DXBC bytecode.
-#. `SRCI`_† - Stores shader source information.
-#. STAT† - Stores shader statistics.
-#. `VERS`_† - Stores shader compiler version information.
-
-DXIL Part
----------
-.. _DXIL:
-
-The DXIL part is comprised of three data structures: the ``ProgramHeader``, the
-``BitcodeHeader`` and the bitcode serialized LLVM 3.7 IR Module.
-
-The ``ProgramHeader`` contains the shader model version and pipeline stage
+01. {ref}`DXIL <DXIL>`† - Stores the DXIL bytecode.
+02. {ref}`HASH <HASH>`† - Stores the shader MD5 hash.
+03. {ref}`ILDB <ILDB>`† - Stores the DXIL bytecode with LLVM Debug Information embedded in the module.
+04. {ref}`ILDN <ILDN>`† - Stores shader debug name for external debug information.
+05. {ref}`ISG1 <ISG1>` - Stores the input signature for Shader Model 5.1+.
+06. ISGN\* - Stores the input signature for Shader Model 4 and earlier.
+07. {ref}`OSG1 <OSG1>` - Stores the output signature for Shader Model 5.1+.
+08. OSG5\* - Stores the output signature for Shader Model 5.
+09. OSGN\* - Stores the output signature for Shader Model 4 and earlier.
+10. PCSG\* - Stores the patch constant signature for Shader Model 5.1 and earlier.
+11. PDBI† - Stores PDB information.
+12. {ref}`PRIV <PRIV>`† - Stores private data, including embedded companion PDB files.
+13. {ref}`PSG1 <PSG1>` - Stores the patch constant signature for Shader Model 6+.
+14. {ref}`PSV0 <PSV0>` - Stores Pipeline State Validation data.
+15. RDAT† - Stores Runtime Data.
+16. RDEF\* - Stores resource definitions.
+17. {ref}`RTS0 <RTS0>` - Stores compiled root signature.
+18. {ref}`SFI0 <SFI0>` - Stores shader feature flags.
+19. SHDR\* - Stores compiled DXBC bytecode.
+20. SHEX\* - Stores compiled DXBC bytecode.
+21. DXBC\* - Stores compiled DXBC bytecode.
+22. {ref}`SRCI <SRCI>`† - Stores shader source information.
+23. STAT† - Stores shader statistics.
+24. {ref}`VERS <VERS>`† - Stores shader compiler version information.
+
+### DXIL Part
+
+(DXIL)=
+
+The DXIL part is comprised of three data structures: the `ProgramHeader`, the
+`BitcodeHeader` and the bitcode serialized LLVM 3.7 IR Module.
+
+The `ProgramHeader` contains the shader model version and pipeline stage
enumeration value. This identifies the target profile of the contained shader
bitcode.
-The ``BitcodeHeader`` contains the DXIL version information and refers to the
+The `BitcodeHeader` contains the DXIL version information and refers to the
start of the bitcode data.
-HASH Part
----------
-.. _HASH:
+### HASH Part
+
+(HASH)=
The HASH part contains a 32-bit unsigned integer with the shader hash flags, and
-a 128-bit MD5 hash digest. The flags field can either have the value ``0`` to
-indicate no flags, or ``1`` to indicate that the file hash was computed
-including the source code that produced the binary. See :ref:`Compiler Flags
-<compiler_flags>` for how ``/Zss`` and ``/Zsb`` select the hashed bitcode.
+a 128-bit MD5 hash digest. The flags field can either have the value `0` to
+indicate no flags, or `1` to indicate that the file hash was computed
+including the source code that produced the binary. See {ref}`Compiler Flags
+<compiler_flags>` for how `/Zss` and `/Zsb` select the hashed bitcode.
+
+### ILDB Part
-ILDB Part
----------
-.. _ILDB:
+(ILDB)=
-The ILDB part follows the structure of the `DXIL`_ part. It stores the
+The ILDB part follows the structure of the {ref}`DXIL <DXIL>` part. It stores the
unstripped DXIL bitcode module with debug information embedded.
The ILDB part is emitted when the shader is compiled with full debug information
-(``/Zi``). It is omitted from all outputs when slim debug (``/Zs``) is used.
-See :ref:`Compiler Flags <compiler_flags>` for how ``/Qembed_debug``,
-``/Qstrip_debug``, ``/Fd``, and ``/Zs`` control whether it appears in the main
+(`/Zi`). It is omitted from all outputs when slim debug (`/Zs`) is used.
+See {ref}`Compiler Flags <compiler_flags>` for how `/Qembed_debug`,
+`/Qstrip_debug`, `/Fd`, and `/Zs` control whether it appears in the main
output, the companion PDB, or both.
-The stripped `DXIL`_ part has the ``Dwarf Version`` and ``Debug Info Version``
-module flags removed, and ``dx.source`` metadata nodes are stripped from it.
-Those nodes are preserved in the ILDB module when ``/Qsource_in_debug_module``
+The stripped {ref}`DXIL <DXIL>` part has the `Dwarf Version` and `Debug Info Version`
+module flags removed, and `dx.source` metadata nodes are stripped from it.
+Those nodes are preserved in the ILDB module when `/Qsource_in_debug_module`
is used; otherwise they are replaced with empty placeholder values in the ILDB
module written to the companion PDB file.
-.. rubric:: Reading this part
+```{rubric} Reading this part
+```
-When the ILDB part is present in a DXContainer file, :program:`obj2yaml` prints
-it under a ``Program`` mapping with the embedded DXIL bitcode. Use
-:program:`llvm-objcopy` to extract the raw bitcode, then :program:`llvm-dis` to
-disassemble it::
+When the ILDB part is present in a DXContainer file, {program}`obj2yaml` prints
+it under a `Program` mapping with the embedded DXIL bitcode. Use
+{program}`llvm-objcopy` to extract the raw bitcode, then {program}`llvm-dis` to
+disassemble it:
- llvm-objcopy --dump-section=ILDB=shader.bc shader.dxbc
- llvm-dis shader.bc
+```
+llvm-objcopy --dump-section=ILDB=shader.bc shader.dxbc
+llvm-dis shader.bc
+```
-When the ILDB part is stored in a companion PDB file, use :program:`llvm-pdbutil`
-to access it (see :doc:`llvm-pdbutil <../CommandGuide/llvm-pdbutil>`).
+When the ILDB part is stored in a companion PDB file, use {program}`llvm-pdbutil`
+to access it (see {doc}`llvm-pdbutil <../CommandGuide/llvm-pdbutil>`).
-ILDN Part
----------
-.. _ILDN:
+### ILDN Part
+
+(ILDN)=
The ILDN part stores the name of the companion PDB file used for external
debug information. It is always emitted when the shader is compiled with debug
information, and is included in both the main DXContainer output and the
companion PDB file.
-The part begins with a ``DebugNameHeader`` followed by a null-terminated UTF-8
+The part begins with a `DebugNameHeader` followed by a null-terminated UTF-8
string containing the debug file name:
-.. code-block:: c
-
- struct DebugNameHeader {
- uint16_t Flags;
- uint16_t NameLength;
- };
+```c
+struct DebugNameHeader {
+ uint16_t Flags;
+ uint16_t NameLength;
+};
+```
-The ``Flags`` field is reserved and must be zero. ``NameLength`` is the length
+The `Flags` field is reserved and must be zero. `NameLength` is the length
of the debug file name in bytes, not including the null terminator.
If no PDB output path is specified, the debug file name defaults to
-``<MD5 hash>.pdb``, where ``<MD5 hash>`` is the stringified MD5 digest from the
-`HASH`_ part. See :ref:`Compiler Flags <compiler_flags>` for how ``/Fd``, ``/Zss``,
-and ``/Zsb`` affect the debug file name and hash computation.
+`<MD5 hash>.pdb`, where `<MD5 hash>` is the stringified MD5 digest from the
+{ref}`HASH <HASH>` part. See {ref}`Compiler Flags <compiler_flags>` for how `/Fd`, `/Zss`,
+and `/Zsb` affect the debug file name and hash computation.
+
+```{rubric} Reading this part
+```
-.. rubric:: Reading this part
+When the ILDN part is present in a DXContainer file, {program}`obj2yaml` prints
+it under a `DebugName` mapping.
-When the ILDN part is present in a DXContainer file, :program:`obj2yaml` prints
-it under a ``DebugName`` mapping.
+### PRIV Part
-PRIV Part
----------
-.. _PRIV:
+(PRIV)=
-The PRIV part stores opaque binary data. DXC may emit it when the ``/Qpdb_in_private``
+The PRIV part stores opaque binary data. DXC may emit it when the `/Qpdb_in_private`
flag is used to embed the companion debug info PDB file in the main DXContainer output.
The part data may also hold arbitrary user-provided binary blobs attached by
@@ -224,127 +220,127 @@ Unlike most other parts, the PRIV part data does not need to be padded to a
container. LLVM enforces this constraint in both the object reader and the
ObjectYAML writer. A DXContainer may contain at most one PRIV part.
-.. rubric:: Reading this part
+```{rubric} Reading this part
+```
-When the PRIV part is present in a DXContainer file, :program:`obj2yaml` prints
-it under a ``PrivateData`` mapping.
+When the PRIV part is present in a DXContainer file, {program}`obj2yaml` prints
+it under a `PrivateData` mapping.
-Use :program:`llvm-objcopy` to extract the raw part data::
+Use {program}`llvm-objcopy` to extract the raw part data:
- llvm-objcopy --dump-section=PRIV=output.priv shader.dxbc
+```
+llvm-objcopy --dump-section=PRIV=output.priv shader.dxbc
+```
+### SRCI Part
-SRCI Part
----------
-.. _SRCI:
+(SRCI)=
-The SRCI part stores shader source information extracted from ``dx.source``
+The SRCI part stores shader source information extracted from `dx.source`
metadata in the LLVM module. It is emitted when source information is available.
-See :ref:`Compiler Flags <compiler_flags>` for output placement and related flags.
+See {ref}`Compiler Flags <compiler_flags>` for output placement and related flags.
The SRCI part is written only to the companion PDB file. It consists of a part
header followed by three 4-byte aligned sections. Each section begins with a
-``SectionHeader`` and is followed by section-specific data:
-
-.. code-block:: c
-
- struct Header {
- uint32_t AlignedSizeInBytes;
- uint16_t Flags;
- uint16_t SectionCount;
- };
-
- struct SectionHeader {
- uint32_t AlignedSizeInBytes;
- uint16_t Flags;
- uint16_t Type;
- };
-
-The part ``Flags`` field is reserved and must be zero. ``SectionCount`` must be
-``3``. Each section ``Flags`` field is reserved and must be zero. The
-``Type`` field identifies the section. The section type values are:
-
-.. code-block:: c
-
- SOURCE_INFO_TYPE(0, SourceContents)
- SOURCE_INFO_TYPE(1, SourceNames)
- SOURCE_INFO_TYPE(2, Args)
-
-Source Names Section
-~~~~~~~~~~~~~~~~~~~~~~~~~
+`SectionHeader` and is followed by section-specific data:
+
+```c
+struct Header {
+ uint32_t AlignedSizeInBytes;
+ uint16_t Flags;
+ uint16_t SectionCount;
+};
+
+struct SectionHeader {
+ uint32_t AlignedSizeInBytes;
+ uint16_t Flags;
+ uint16_t Type;
+};
+```
+
+The part `Flags` field is reserved and must be zero. `SectionCount` must be
+`3`. Each section `Flags` field is reserved and must be zero. The
+`Type` field identifies the section. The section type values are:
+
+```c
+SOURCE_INFO_TYPE(0, SourceContents)
+SOURCE_INFO_TYPE(1, SourceNames)
+SOURCE_INFO_TYPE(2, Args)
+```
+
+#### Source Names Section
The source names section stores the file names of the HLSL translation units
that contributed source to the shader. It begins with a section header of type
-``SourceNames``, followed by a section-specific header and a sequence of name
+`SourceNames`, followed by a section-specific header and a sequence of name
entries:
-.. code-block:: c
-
- struct SourceNamesHeader {
- uint32_t Flags;
- uint32_t Count;
- uint16_t EntriesSizeInBytes;
- };
-
- struct SourceNamesEntry {
- uint32_t AlignedSizeInBytes;
- uint32_t Flags;
- uint32_t NameSizeInBytes;
- uint32_t ContentSizeInBytes;
- };
-
-The section-specific ``Flags`` field is reserved and must be zero. ``Count`` is
-the number of entries that follow. ``EntriesSizeInBytes`` is the total size of
+```c
+struct SourceNamesHeader {
+ uint32_t Flags;
+ uint32_t Count;
+ uint16_t EntriesSizeInBytes;
+};
+
+struct SourceNamesEntry {
+ uint32_t AlignedSizeInBytes;
+ uint32_t Flags;
+ uint32_t NameSizeInBytes;
+ uint32_t ContentSizeInBytes;
+};
+```
+
+The section-specific `Flags` field is reserved and must be zero. `Count` is
+the number of entries that follow. `EntriesSizeInBytes` is the total size of
the entry data following the section-specific header, including entry padding.
Each entry is 4-byte aligned. The first entry is usually the main shader source
file, and the remaining entries are sorted by file name.
Each entry is followed by a null-terminated UTF-8 file name of length
-``NameSizeInBytes``. The ``ContentSizeInBytes`` field records the size of the
+`NameSizeInBytes`. The `ContentSizeInBytes` field records the size of the
corresponding source content entry in the source contents section, including its
null terminator.
-Source Contents Section
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Source Contents Section
The source contents section stores the HLSL source text for each file named in
the source names section. It begins with a section header of type
-``SourceContents``, followed by a section-specific header and the (optionally
+`SourceContents`, followed by a section-specific header and the (optionally
compressed) entry data:
-.. code-block:: c
-
- struct SourceContentsHeader {
- uint32_t AlignedSizeInBytes;
- uint16_t Flags;
- uint16_t Type;
- uint32_t EntriesSizeInBytes;
- uint32_t UncompressedEntriesSizeInBytes;
- uint32_t Count;
- };
-
- struct SourceContentsEntry {
- uint32_t AlignedSizeInBytes;
- uint32_t Flags;
- uint32_t ContentSizeInBytes;
- };
-
-The section-specific ``Flags`` field is reserved and must be zero. The
-``Type`` field specifies the compression applied to the entry data. The
+```c
+struct SourceContentsHeader {
+ uint32_t AlignedSizeInBytes;
+ uint16_t Flags;
+ uint16_t Type;
+ uint32_t EntriesSizeInBytes;
+ uint32_t UncompressedEntriesSizeInBytes;
+ uint32_t Count;
+};
+
+struct SourceContentsEntry {
+ uint32_t AlignedSizeInBytes;
+ uint32_t Flags;
+ uint32_t ContentSizeInBytes;
+};
+```
+
+The section-specific `Flags` field is reserved and must be zero. The
+`Type` field specifies the compression applied to the entry data. The
compression type values are:
-.. code-block:: c
+```c
+COMPRESSION_TYPE(0, None)
+COMPRESSION_TYPE(1, Zlib)
+```
- COMPRESSION_TYPE(0, None)
- COMPRESSION_TYPE(1, Zlib)
-
-When no compression is used, ``EntriesSizeInBytes`` and
-``UncompressedEntriesSizeInBytes`` are equal.
+When no compression is used, `EntriesSizeInBytes` and
+`UncompressedEntriesSizeInBytes` are equal.
When Zlib compression is used, the bytes following the section-specific header
contain the compressed aggregate of all entries. After decompression, the data is
-a sequence of ``Count`` entries.
+a sequence of `Count` entries.
Each uncompressed entry is 4-byte aligned and is followed by a null-terminated
UTF-8 string containing the file source text.
@@ -352,125 +348,128 @@ UTF-8 string containing the file source text.
The entries must appear in the same order as the entries in the source names
section.
-Args Section
-~~~~~~~~~~~~~~~~~
+#### Args Section
The args section stores the HLSL compiler command-line arguments used to produce
-the shader. It begins with a section header of type ``Args``, followed by a
+the shader. It begins with a section header of type `Ar...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/217159
More information about the llvm-branch-commits
mailing list