[llvm] [Docs][DirectX] Add relevant documentation of Root Signature (PR #149608)
Finn Plummer via llvm-commits
llvm-commits at lists.llvm.org
Wed Jul 23 11:57:07 PDT 2025
https://github.com/inbelic updated https://github.com/llvm/llvm-project/pull/149608
>From 7c51346200560136c6ceea5be437a20e3aaa8d2a Mon Sep 17 00:00:00 2001
From: Finn Plummer <canadienfinn at gmail.com>
Date: Fri, 18 Jul 2025 22:41:29 +0000
Subject: [PATCH 1/7] [Docs][DirectX] Add documentation of root signature
metadata representation
---
llvm/docs/DirectX/RootSignatures.rst | 231 +++++++++++++++++++++++++++
1 file changed, 231 insertions(+)
create mode 100644 llvm/docs/DirectX/RootSignatures.rst
diff --git a/llvm/docs/DirectX/RootSignatures.rst b/llvm/docs/DirectX/RootSignatures.rst
new file mode 100644
index 0000000000000..7a5e4d3e8fc27
--- /dev/null
+++ b/llvm/docs/DirectX/RootSignatures.rst
@@ -0,0 +1,231 @@
+===============
+Root Signatures
+===============
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Overview
+========
+
+A root signature is used to describe what resources a shader needs to access to
+and how they're organized and bound in the pipeline. The DirectX Container
+(DXContainer) contains a root signature part (RTS0), which stores this
+information in a binary format. To assist with the construction of, and
+interaction with, a root signature is represented as metadata
+(``dx.rootsignatures`` ) in the LLVM IR. The metadata can then be converted to
+its binary form, as defined in
+`llvm/include/llvm/llvm/Frontend/HLSL/RootSignatureMetadata.h
+<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Frontend/HLSL/RootSignatureMetadata.h>`_.
+This document serves as a reference for the metadata representation of a root
+signature for users to interface with.
+
+Metadata Representation
+=======================
+
+Consider the reference root signature, then the following sections describe the
+metadata representation of this root signature and the corresponding operands.
+
+.. code-block:: C
+
+ #define DemoRootSignature \
+ "RootFlags(ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT)," \
+ "RootConstants(b0, space = 1, num32Constants = 3)," \
+ "CBV(b1, flags = 0)," \
+ "StaticSampler(" \
+ " filter = FILTER_MIN_MAG_POINT_MIP_LINEAR," \
+ " addressU = TEXTURE_ADDRESS_BORDER," \
+ ")," \
+ "DescriptorTable(" \
+ " visibility = VISIBILITY_ALL," \
+ " SRV(t0, flags = DATA_STATIC_WHILE_SET_AT_EXECUTE)," \
+ " UAV(" \
+ " numDescriptors = 5, u1, space = 10, offset = 5," \
+ " flags = DATA_VOLATILE" \
+ " )" \
+ ")"
+
+.. note::
+
+ A root signature does not necessarily have a unique metadata representation.
+ Futher, a malformed root signature can be represented in the metadata format,
+ (eg. mixing Sampler and non-Sampler descriptor ranges), and so it is the
+ user's responsibility to verify that it is a well-formed root signature.
+
+Named Root Signature Table
+==========================
+
+.. code-block:: LLVM
+
+ !dx.rootsignatures = !{!0}
+
+A named metadata node, ``dx.rootsignatures``` is used to identify the root
+signature table. The table itself is a list of references to function/root
+signature pairs.
+
+Function/Root Signature Pair
+============================
+
+.. code-block:: LLVM
+
+ !1 = !{ptr @main, !2, i32 2 }
+
+The function/root signature associates a function (the first operand) with a
+reference to a root signature (the second operand). The root signature version
+(the third operand) used for validation logic and binary format follows.
+
+Root Signature
+==============
+
+.. code-block:: LLVM
+
+ !2 = !{ !3, !4, !5, !6, !7 }
+
+The root signature itself simply consists of a list of references to its root
+signature elements.
+
+Root Signature Element
+======================
+
+A root signature element is identified by the first operand, which is a string.
+The following root signature elements are defined:
+
+.. csv-table::
+
+ Identifier String, Root Signature Element
+
+ \"RootFlags\", Root Flags
+ \"RootConstants\", Root Constants
+ \"RootCBV\", Root Descriptor
+ \"RootSRV\", Root Descriptor
+ \"RootUAV\", Root Descriptor
+ \"StaticSampler\", Static Sampler
+ \"DescriptorTable\", Descriptor Table
+
+Below is listed the representation for each type of root signature element.
+
+Root Flags
+==========
+
+.. code-block:: LLVM
+
+ !3 = { !"RootFlags", i32 1 }
+
+.. csv-table::
+
+ Description, Type
+
+ `Root Signature Flags <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_root_signature_flags>`_, i32
+
+
+Root Constants
+==============
+
+.. code-block:: LLVM
+
+ !4 = { !"RootConstants", i32 0, i32 1, i32 2, i32 3 }
+
+.. csv-table::
+
+ Description, Type
+
+ `Shader Visibility <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_shader_visibility>`_, i32
+ Shader Register, i32
+ Register Space, i32
+ Number 32-bit Values, i32
+
+Root Descriptor
+===============
+
+As noted in the table above, the first operand will denote the type of
+root descriptor.
+
+.. code-block:: LLVM
+
+ !5 = { !"RootCBV", i32 0, i32 1, i32 0, i32 0 }
+
+.. csv-table::
+
+ Description, Type
+
+ `Shader Visibility`_, i32
+ Shader Register, i32
+ Register Space, i32
+ `Root Descriptor Flags <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_root_descriptor_flags>`_, i32
+
+Static Sampler
+==============
+
+.. code-block:: LLVM
+
+ !6 = !{ !"StaticSampler", i32 1, i32 4, ... }; remaining operands omitted for space
+
+.. csv-table::
+
+ Description, Type
+
+ `Filter <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_filter>`_, i32
+ `AddressU <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode>`_, i32
+ `AddressV <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode>`_, i32
+ `AddressW <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode>`_, i32
+ MipLODBias, float
+ MaxAnisotropy, i32
+ `ComparisonFunc <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_comparison_func>`_, i32
+ `BorderColor <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_static_border_color>`_, i32
+ MinLOD, float
+ MaxLOD, float
+ ShaderRegister, i32
+ RegisterSpace, i32
+ `Shader Visibility`_, i32
+
+Descriptor Table
+================
+
+A descriptor table consists of a visibility and the remaining operands are a
+list of references to its descriptor ranges.
+
+.. note::
+
+ The term Descriptor Table Clause is synonymous with Descriptor Range when
+ referencing the implementation details.
+
+.. code-block:: LLVM
+
+ !7 = { !"DescriptorTable", i32 0, !8, !9 }
+
+.. csv-table::
+
+ Description, Type
+
+ `Shader Visibility`_, i32
+ Descriptor Range Elements, Descriptor Range
+
+
+Descriptor Range
+================
+
+Similar to a root descriptor, the first operand will denote the type of
+descriptor range. It is one of the following types:
+
+- "CBV"
+- "SRV"
+- "UAV"
+- "Sampler"
+
+.. code-block:: LLVM
+
+ !8 = !{ !"SRV", i32 1, i32 0, i32 0, i32 -1, i32 4 }
+ !9 = !{ !"UAV", i32 5, i32 1, i32 10, i32 5, i32 2 }
+
+.. csv-table::
+
+ Description, Type
+
+ Number of Descriptors in Range, i32
+ Shader Register, i32
+ Register Space, i32
+ `Offset <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_descriptor_range>`_, i32
+ `Descriptor Range Flags <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_descriptor_range_flags>`_, i32
>From 42e6657afcd9f7ee2019f331f748fe82ce624e91 Mon Sep 17 00:00:00 2001
From: Finn Plummer <canadienfinn at gmail.com>
Date: Fri, 18 Jul 2025 22:51:33 +0000
Subject: [PATCH 2/7] add to doc tree
---
llvm/docs/DirectXUsage.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/llvm/docs/DirectXUsage.rst b/llvm/docs/DirectXUsage.rst
index 4d8f49bd224cb..efbab391f6bd4 100644
--- a/llvm/docs/DirectXUsage.rst
+++ b/llvm/docs/DirectXUsage.rst
@@ -17,6 +17,7 @@ User Guide for the DirectX Target
DirectX/DXILArchitecture
DirectX/DXILOpTableGenDesign
DirectX/DXILResources
+ DirectX/DXILRootSignatures
Introduction
============
>From 0c419be38f9fe7e633c31bfc1774153ce00277e4 Mon Sep 17 00:00:00 2001
From: Finn Plummer <canadienfinn at gmail.com>
Date: Sat, 19 Jul 2025 01:57:14 +0000
Subject: [PATCH 3/7] correct doc tree
---
llvm/docs/DirectXUsage.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/docs/DirectXUsage.rst b/llvm/docs/DirectXUsage.rst
index efbab391f6bd4..1d964e6d54dae 100644
--- a/llvm/docs/DirectXUsage.rst
+++ b/llvm/docs/DirectXUsage.rst
@@ -17,7 +17,7 @@ User Guide for the DirectX Target
DirectX/DXILArchitecture
DirectX/DXILOpTableGenDesign
DirectX/DXILResources
- DirectX/DXILRootSignatures
+ DirectX/RootSignatures
Introduction
============
>From f20706cae665c5e7283b37583088d148cfb22096 Mon Sep 17 00:00:00 2001
From: Finn Plummer <finn.c.plum at gmail.com>
Date: Mon, 21 Jul 2025 11:26:32 -0700
Subject: [PATCH 4/7] review: fix typo
Co-authored-by: Ashley Coleman <ascoleman at microsoft.com>
---
llvm/docs/DirectX/RootSignatures.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/docs/DirectX/RootSignatures.rst b/llvm/docs/DirectX/RootSignatures.rst
index 7a5e4d3e8fc27..e86d270b20637 100644
--- a/llvm/docs/DirectX/RootSignatures.rst
+++ b/llvm/docs/DirectX/RootSignatures.rst
@@ -11,7 +11,7 @@ Root Signatures
Overview
========
-A root signature is used to describe what resources a shader needs to access to
+A root signature is used to describe what resources a shader needs access to
and how they're organized and bound in the pipeline. The DirectX Container
(DXContainer) contains a root signature part (RTS0), which stores this
information in a binary format. To assist with the construction of, and
>From e82b737609842a189739cad2d1e02d4519a0f844 Mon Sep 17 00:00:00 2001
From: Finn Plummer <canadienfinn at gmail.com>
Date: Wed, 23 Jul 2025 18:36:20 +0000
Subject: [PATCH 5/7] review: update demo root signature
---
llvm/docs/DirectX/RootSignatures.rst | 35 ++++++++++++++--------------
1 file changed, 17 insertions(+), 18 deletions(-)
diff --git a/llvm/docs/DirectX/RootSignatures.rst b/llvm/docs/DirectX/RootSignatures.rst
index e86d270b20637..55619b7ca2464 100644
--- a/llvm/docs/DirectX/RootSignatures.rst
+++ b/llvm/docs/DirectX/RootSignatures.rst
@@ -29,24 +29,23 @@ Metadata Representation
Consider the reference root signature, then the following sections describe the
metadata representation of this root signature and the corresponding operands.
-.. code-block:: C
-
- #define DemoRootSignature \
- "RootFlags(ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT)," \
- "RootConstants(b0, space = 1, num32Constants = 3)," \
- "CBV(b1, flags = 0)," \
- "StaticSampler(" \
- " filter = FILTER_MIN_MAG_POINT_MIP_LINEAR," \
- " addressU = TEXTURE_ADDRESS_BORDER," \
- ")," \
- "DescriptorTable(" \
- " visibility = VISIBILITY_ALL," \
- " SRV(t0, flags = DATA_STATIC_WHILE_SET_AT_EXECUTE)," \
- " UAV(" \
- " numDescriptors = 5, u1, space = 10, offset = 5," \
- " flags = DATA_VOLATILE" \
- " )" \
- ")"
+.. code-block:: HLSL
+
+RootFlags(ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT),
+RootConstants(b0, space = 1, num32Constants = 3),
+CBV(b1, flags = 0),
+StaticSampler(
+ filter = FILTER_MIN_MAG_POINT_MIP_LINEAR,
+ addressU = TEXTURE_ADDRESS_BORDER,
+),
+DescriptorTable(
+ visibility = VISIBILITY_ALL,
+ SRV(t0, flags = DATA_STATIC_WHILE_SET_AT_EXECUTE),
+ UAV(
+ numDescriptors = 5, u1, space = 10, offset = 5,
+ flags = DATA_VOLATILE
+ )
+)
.. note::
>From 71d84cae8ecd7414e8b43fc015b1bb202d000f2e Mon Sep 17 00:00:00 2001
From: Finn Plummer <canadienfinn at gmail.com>
Date: Wed, 23 Jul 2025 18:53:34 +0000
Subject: [PATCH 6/7] review: use simply tables and out of line links
---
llvm/docs/DirectX/RootSignatures.rst | 137 +++++++++++++++------------
1 file changed, 77 insertions(+), 60 deletions(-)
diff --git a/llvm/docs/DirectX/RootSignatures.rst b/llvm/docs/DirectX/RootSignatures.rst
index 55619b7ca2464..1e585256e8c44 100644
--- a/llvm/docs/DirectX/RootSignatures.rst
+++ b/llvm/docs/DirectX/RootSignatures.rst
@@ -92,17 +92,17 @@ Root Signature Element
A root signature element is identified by the first operand, which is a string.
The following root signature elements are defined:
-.. csv-table::
-
- Identifier String, Root Signature Element
-
- \"RootFlags\", Root Flags
- \"RootConstants\", Root Constants
- \"RootCBV\", Root Descriptor
- \"RootSRV\", Root Descriptor
- \"RootUAV\", Root Descriptor
- \"StaticSampler\", Static Sampler
- \"DescriptorTable\", Descriptor Table
+================= ======================
+Identifier String Root Signature Element
+================= ======================
+"RootFlags" Root Flags
+"RootConstants" Root Constants
+"RootCBV" Root Descriptor
+"RootSRV" Root Descriptor
+"RootUAV" Root Descriptor
+"StaticSampler" Static Sampler
+"DescriptorTable" Descriptor Table
+================= ======================
Below is listed the representation for each type of root signature element.
@@ -113,12 +113,13 @@ Root Flags
!3 = { !"RootFlags", i32 1 }
-.. csv-table::
-
- Description, Type
-
- `Root Signature Flags <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_root_signature_flags>`_, i32
+======================= ====
+Description Type
+======================= ====
+`Root Signature Flags`_ i32
+======================= ====
+.. _Root Signature Flags: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_root_signature_flags
Root Constants
==============
@@ -127,14 +128,16 @@ Root Constants
!4 = { !"RootConstants", i32 0, i32 1, i32 2, i32 3 }
-.. csv-table::
-
- Description, Type
+==================== ====
+Description Type
+==================== ====
+`Shader Visibility`_ i32
+Shader Register i32
+Register Space i32
+Number 32-bit Values i32
+==================== ====
- `Shader Visibility <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_shader_visibility>`_, i32
- Shader Register, i32
- Register Space, i32
- Number 32-bit Values, i32
+.. _Shader Visibility: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_shader_visibility
Root Descriptor
===============
@@ -146,14 +149,16 @@ root descriptor.
!5 = { !"RootCBV", i32 0, i32 1, i32 0, i32 0 }
-.. csv-table::
-
- Description, Type
+======================== ====
+Description Type
+======================== ====
+`Shader Visibility`_ i32
+Shader Register i32
+Register Space i32
+`Root Descriptor Flags`_ i32
+======================== ====
- `Shader Visibility`_, i32
- Shader Register, i32
- Register Space, i32
- `Root Descriptor Flags <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_root_descriptor_flags>`_, i32
+.. _Root Descriptor Flags: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_root_descriptor_flags
Static Sampler
==============
@@ -162,23 +167,30 @@ Static Sampler
!6 = !{ !"StaticSampler", i32 1, i32 4, ... }; remaining operands omitted for space
-.. csv-table::
-
- Description, Type
-
- `Filter <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_filter>`_, i32
- `AddressU <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode>`_, i32
- `AddressV <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode>`_, i32
- `AddressW <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode>`_, i32
- MipLODBias, float
- MaxAnisotropy, i32
- `ComparisonFunc <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_comparison_func>`_, i32
- `BorderColor <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_static_border_color>`_, i32
- MinLOD, float
- MaxLOD, float
- ShaderRegister, i32
- RegisterSpace, i32
- `Shader Visibility`_, i32
+==================== =====
+Description Type
+==================== =====
+`Filter`_ i32
+`AddressU`_ i32
+`AddressV`_ i32
+`AddressW`_ i32
+MipLODBias float
+MaxAnisotropy i32
+`ComparisonFunc`_ i32
+`BorderColor`_ i32
+MinLOD float
+MaxLOD float
+ShaderRegister i32
+RegisterSpace i32
+`Shader Visibility`_ i32
+==================== =====
+
+.. _Filter: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_filter
+.. _AddressU: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode
+.. _AddressV: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode
+.. _AddressW: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode
+.. _ComparisonFunc: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_comparison_func>
+.. _BorderColor: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_static_border_color>
Descriptor Table
================
@@ -195,12 +207,12 @@ list of references to its descriptor ranges.
!7 = { !"DescriptorTable", i32 0, !8, !9 }
-.. csv-table::
-
- Description, Type
-
- `Shader Visibility`_, i32
- Descriptor Range Elements, Descriptor Range
+========================= ================
+Description Type
+========================= ================
+`Shader Visibility`_ i32
+Descriptor Range Elements Descriptor Range
+========================= ================
Descriptor Range
@@ -221,10 +233,15 @@ descriptor range. It is one of the following types:
.. csv-table::
- Description, Type
-
- Number of Descriptors in Range, i32
- Shader Register, i32
- Register Space, i32
- `Offset <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_descriptor_range>`_, i32
- `Descriptor Range Flags <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_descriptor_range_flags>`_, i32
+============================== ====
+Description Type
+============================== ====
+Number of Descriptors in Range i32
+Shader Register i32
+Register Space i32
+`Offset`_ i32
+`Descriptor Range Flags`_ i32
+============================== ====
+
+.. _Offset: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_descriptor_range
+.. _Descriptor Range Flags: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_descriptor_range_flags
>From 8fa5896919955a229cecb25d18c79bff68554a84 Mon Sep 17 00:00:00 2001
From: Finn Plummer <canadienfinn at gmail.com>
Date: Wed, 23 Jul 2025 18:56:52 +0000
Subject: [PATCH 7/7] fix code formatting
---
llvm/docs/DirectX/RootSignatures.rst | 28 ++++++++++++++--------------
1 file changed, 14 insertions(+), 14 deletions(-)
diff --git a/llvm/docs/DirectX/RootSignatures.rst b/llvm/docs/DirectX/RootSignatures.rst
index 1e585256e8c44..16ac112c9be53 100644
--- a/llvm/docs/DirectX/RootSignatures.rst
+++ b/llvm/docs/DirectX/RootSignatures.rst
@@ -31,20 +31,20 @@ metadata representation of this root signature and the corresponding operands.
.. code-block:: HLSL
-RootFlags(ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT),
-RootConstants(b0, space = 1, num32Constants = 3),
-CBV(b1, flags = 0),
-StaticSampler(
- filter = FILTER_MIN_MAG_POINT_MIP_LINEAR,
- addressU = TEXTURE_ADDRESS_BORDER,
-),
-DescriptorTable(
- visibility = VISIBILITY_ALL,
- SRV(t0, flags = DATA_STATIC_WHILE_SET_AT_EXECUTE),
- UAV(
- numDescriptors = 5, u1, space = 10, offset = 5,
- flags = DATA_VOLATILE
- )
+ RootFlags(ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT),
+ RootConstants(b0, space = 1, num32Constants = 3),
+ CBV(b1, flags = 0),
+ StaticSampler(
+ filter = FILTER_MIN_MAG_POINT_MIP_LINEAR,
+ addressU = TEXTURE_ADDRESS_BORDER,
+ ),
+ DescriptorTable(
+ visibility = VISIBILITY_ALL,
+ SRV(t0, flags = DATA_STATIC_WHILE_SET_AT_EXECUTE),
+ UAV(
+ numDescriptors = 5, u1, space = 10, offset = 5,
+ flags = DATA_VOLATILE
+ )
)
.. note::
More information about the llvm-commits
mailing list