[llvm] [HLSL][Docs] Add metadata description of semantic signatures (PR #206804)
via llvm-commits
llvm-commits at lists.llvm.org
Tue Jun 30 12:55:57 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-backend-directx
Author: Finn Plummer (inbelic)
<details>
<summary>Changes</summary>
Adds docs of semantic signatures from the proposal.
Resolves https://github.com/llvm/llvm-project/issues/204877
---
Full diff: https://github.com/llvm/llvm-project/pull/206804.diff
2 Files Affected:
- (added) llvm/docs/DirectX/SemanticSignatures.md (+124)
- (modified) llvm/docs/DirectXUsage.rst (+1)
``````````diff
diff --git a/llvm/docs/DirectX/SemanticSignatures.md b/llvm/docs/DirectX/SemanticSignatures.md
new file mode 100644
index 0000000000000..1c39f756b33cf
--- /dev/null
+++ b/llvm/docs/DirectX/SemanticSignatures.md
@@ -0,0 +1,124 @@
+# Semantic Signatures
+
+## Overview
+
+A semantic signature describes the inputs and outputs of an HLSL shader entry
+point: the semantics each value carries, its component type, and where it is
+placed in the input/output register space. The DirectX Container (DXContainer)
+stores this information in binary signature parts (`ISG1`, `OSG1`) and in the
+pipeline state validation part (`PSV0`). To assist with the construction of, and
+interaction with, these parts, a semantic signature is represented as metadata
+(`dx.semantic.signatures`) in the LLVM IR. The metadata can then be converted to
+its binary form, as defined in
+[llvm/include/llvm/Frontend/HLSL/SemanticSignatures.h](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Frontend/HLSL/SemanticSignatures.h).
+This document serves as a reference for the metadata representation of a
+semantic signature for users to interface with.
+
+## Metadata Representation
+
+Consider the reference shaders below, then the following sections describe the
+metadata representation of their signatures and the corresponding operands.
+
+```hlsl
+float4 vs_main(float4 pos : POSITION,
+ float4 uv[2] : TEXCOORD0) : SV_Position {
+ return pos + uv[0] + uv[1];
+}
+
+struct PSOut {
+ float4 color : SV_Target0;
+ float4 extra : SV_Target1;
+};
+
+PSOut ps_main(float4 pos : SV_Position,
+ float4 uv0 : TEXCOORD0,
+ float4 uv1 : TEXCOORD1) {
+ PSOut o;
+ o.color = pos + uv0;
+ o.extra = float4(uv1.xyz, 1);
+ return o;
+}
+```
+
+> **Note:** A signature does not necessarily have a unique metadata
+> representation. Further, a malformed signature can be represented in the
+> metadata format, and so it is the user's responsibility to verify that it is a
+> well-formed signature.
+
+## Named Signature Table
+
+```LLVM
+!dx.semantic.signatures = !{!1, !2}
+```
+
+A named metadata node, `dx.semantic.signatures`, is used to identify the table
+of per-entry-point semantic signatures. The table itself is a list of references
+to function/signature triples. If no entry point has a signature, the named
+metadata node may be omitted entirely.
+
+## Function/Signature Triple
+
+```LLVM
+!1 = !{ ptr @vs_main, !3, !4 }
+```
+
+The function/signature triple associates an entry-point function (the first
+operand) with its input signature element list (the second operand) and output
+signature element list (the third operand). Either list may be `null`. An entry
+function may appear at most once.
+
+## Signature Element List
+
+```LLVM
+!3 = !{ !5, !6 }
+```
+
+A signature element list consists of a list of references to signature element
+nodes.
+
+## Signature Element
+
+```LLVM
+!5 = !{ i32 0, !"TEXCOORD", i32 9, i32 0, !50, i32 0, i32 1, i8 4, i32 0, i8 0, i8 0, i8 0, i32 0 }
+```
+
+A signature element describes a single packed range of signature rows. It
+retains all information needed to serialize into `ISG1`, `OSG1` and `PSV0`.
+
+| Name | Type | Description |
+|------------------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Signature ID | i32 | dense 0-based index within the entry function signature list; matches the operand of `llvm.dx.load.input` / `llvm.dx.store.output` |
+| Semantic Name | metadata string | the semantic name (e.g. `!"TEXCOORD"`, `!"SV_Position"`) |
+| Component Type | i32 | component type; see [`llvm::dxil::ElementType`](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Support/DXILABI.h). |
+| Semantic Kind | i32 | semantic kind; `Arbitrary` (0) for user-defined semantics, the corresponding `SV_*` value otherwise. See [`SEMANTIC_KIND`](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def) |
+| Semantic Indices | metadata node | reference to a [semantic indices](#semantic-indices) node |
+| Interpolation Mode | i32 | interpolation mode; see [`INTERPOLATION_MODE`](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def) |
+| Rows | i32 | number of consecutive register rows occupied |
+| Cols | i8 | number of components per row (1–4) |
+| Start Row | i32 | starting register row; `-1` (`0xFFFFFFFF`) if unallocated |
+| Start Column | i8 | starting component column; `-1` (`0xFF`) if unallocated, otherwise 0–3 |
+| Usage Mask | i8 | 4-bit bitmask of components that are always read (input) or may be written (output). |
+| Dynamic Index Mask | i8 | 4-bit bitmask of components that are dynamically indexed |
+| GS Output Stream Index | i32 | GS output stream index; 0 for non-GS stages |
+
+### Derived Container Fields
+
+The following container fields are derived from the operands above:
+
+- **Allocated**: allocated iff `StartRow != -1` and `StartCol != -1` (the
+ sentinels are always set together).
+- **DeclaredMask**: `((1 << Cols) - 1) << StartCol`.
+- **AlwaysReads / NeverWrites**: `UsageMask` is written to `AlwaysReads` for
+ inputs; for outputs `NeverWrites = ~UsageMask & DeclaredMask`.
+- **MinPrecision**: from `CompType` plus the `UseMinPrecision` module flag.
+
+## Semantic Indices
+
+```LLVM
+!50 = !{ i32 0 }
+!51 = !{ i32 0, i32 1 }
+```
+
+A metadata node of one or more semantic indices. Its length must equal the
+`Rows` field of the containing signature element.
+
diff --git a/llvm/docs/DirectXUsage.rst b/llvm/docs/DirectXUsage.rst
index 78f27d89c1f8a..eb5e0a67f1fc8 100644
--- a/llvm/docs/DirectXUsage.rst
+++ b/llvm/docs/DirectXUsage.rst
@@ -18,6 +18,7 @@ User Guide for the DirectX Target
DirectX/DXILOpTableGenDesign
DirectX/DXILResources
DirectX/RootSignatures
+ DirectX/SemanticSignatures
Introduction
============
``````````
</details>
https://github.com/llvm/llvm-project/pull/206804
More information about the llvm-commits
mailing list