diff --git a/llvm/docs/DirectX/SemanticSignatures.md b/llvm/docs/DirectX/SemanticSignatures.md new file mode 100644 index 0000000000000..6860d9519221a --- /dev/null +++ b/llvm/docs/DirectX/SemanticSignatures.md @@ -0,0 +1,127 @@ +# 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 [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 +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`][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`][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 | +| 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 | + +[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 + +### 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 ============