[llvm] [HLSL][Docs] Add metadata description of semantic signatures (PR #206804)
Finn Plummer via llvm-commits
llvm-commits at lists.llvm.org
Wed Jul 15 15:01:20 PDT 2026
https://github.com/inbelic updated https://github.com/llvm/llvm-project/pull/206804
>From 4f7b01e2efbd87a146324abe0afe7b93806e7c63 Mon Sep 17 00:00:00 2001
From: Finn Plummer <mail at inbelic.dev>
Date: Mon, 29 Jun 2026 21:57:42 +0000
Subject: [PATCH 1/2] [HLSL][Docs] Add metadata description of semantic
signatures
Adds docs of semantic signatures from the proposal
---
llvm/docs/DirectX/SemanticSignatures.md | 124 ++++++++++++++++++++++++
llvm/docs/DirectXUsage.rst | 1 +
2 files changed, 125 insertions(+)
create mode 100644 llvm/docs/DirectX/SemanticSignatures.md
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
============
>From 1c8391dd45914e0934201876db7da4097a78e705 Mon Sep 17 00:00:00 2001
From: Finn Plummer <mail at inbelic.dev>
Date: Wed, 15 Jul 2026 21:57:51 +0000
Subject: [PATCH 2/2] review: use out of line links
---
llvm/docs/DirectX/SemanticSignatures.md | 13 +++++++++----
1 file changed, 9 insertions(+), 4 deletions(-)
diff --git a/llvm/docs/DirectX/SemanticSignatures.md b/llvm/docs/DirectX/SemanticSignatures.md
index 1c39f756b33cf..a8630b948c8ef 100644
--- a/llvm/docs/DirectX/SemanticSignatures.md
+++ b/llvm/docs/DirectX/SemanticSignatures.md
@@ -10,10 +10,12 @@ 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).
+[SemanticSignatures.h].
This document serves as a reference for the metadata representation of a
semantic signature for users to interface with.
+[SemanticSignatures.h]: https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Frontend/HLSL/SemanticSignatures.h
+
## Metadata Representation
Consider the reference shaders below, then the following sections describe the
@@ -89,10 +91,10 @@ retains all information needed to serialize into `ISG1`, `OSG1` and `PSV0`.
|------------------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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) |
+| Component Type | i32 | component type; see [`llvm::dxil::ElementType`][ElementType]. |
+| Semantic Kind | i32 | semantic kind; `Arbitrary` (0) for user-defined semantics, the corresponding `SV_*` value otherwise. See [`SEMANTIC_KIND`][DXContainerConstants] |
| 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) |
+| Interpolation Mode | i32 | interpolation mode; see [`INTERPOLATION_MODE`][DXContainerConstants] |
| 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 |
@@ -112,6 +114,9 @@ The following container fields are derived from the operands above:
inputs; for outputs `NeverWrites = ~UsageMask & DeclaredMask`.
- **MinPrecision**: from `CompType` plus the `UseMinPrecision` module flag.
+[ElementType]: https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Support/DXILABI.h
+[DXContainerConstants]: https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def
+
## Semantic Indices
```LLVM
More information about the llvm-commits
mailing list