Skip to content

Commit 6925cae

Browse files
inbelicinbelic
authored
[Docs][DirectX] Add relevant documentation of Root Signature (#149608)
This pr adds documentation of root signatures for reference of an LLVM user. The target audience is an LLVM user that wants to build a custom tool, or front-end, that requires constructing a root signature part (RTS0) for a `DXContainer`. With that in mind, this pr adds documentation of the metadata representation of root signatures implemented in LLVM and utilized in Clang.
1 parent 4db2f3a commit 6925cae

File tree

2 files changed

+246
-0
lines changed

2 files changed

+246
-0
lines changed

‎llvm/docs/DirectX/RootSignatures.rst

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
===============
2+
Root Signatures
3+
===============
4+
5+
.. contents::
6+
:local:
7+
8+
.. toctree::
9+
:hidden:
10+
11+
Overview
12+
========
13+
14+
A root signature is used to describe what resources a shader needs access to
15+
and how they're organized and bound in the pipeline. The DirectX Container
16+
(DXContainer) contains a root signature part (RTS0), which stores this
17+
information in a binary format. To assist with the construction of, and
18+
interaction with, a root signature is represented as metadata
19+
(``dx.rootsignatures`` ) in the LLVM IR. The metadata can then be converted to
20+
its binary form, as defined in
21+
`llvm/include/llvm/llvm/Frontend/HLSL/RootSignatureMetadata.h
22+
<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Frontend/HLSL/RootSignatureMetadata.h>`_.
23+
This document serves as a reference for the metadata representation of a root
24+
signature for users to interface with.
25+
26+
Metadata Representation
27+
=======================
28+
29+
Consider the reference root signature, then the following sections describe the
30+
metadata representation of this root signature and the corresponding operands.
31+
32+
.. code-block:: HLSL
33+
34+
RootFlags(ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT),
35+
RootConstants(b0, space = 1, num32Constants = 3),
36+
CBV(b1, flags = 0),
37+
StaticSampler(
38+
filter = FILTER_MIN_MAG_POINT_MIP_LINEAR,
39+
addressU = TEXTURE_ADDRESS_BORDER,
40+
),
41+
DescriptorTable(
42+
visibility = VISIBILITY_ALL,
43+
SRV(t0, flags = DATA_STATIC_WHILE_SET_AT_EXECUTE),
44+
UAV(
45+
numDescriptors = 5, u1, space = 10, offset = 5,
46+
flags = DATA_VOLATILE
47+
)
48+
)
49+
50+
.. note::
51+
52+
A root signature does not necessarily have a unique metadata representation.
53+
Futher, a malformed root signature can be represented in the metadata format,
54+
(eg. mixing Sampler and non-Sampler descriptor ranges), and so it is the
55+
user's responsibility to verify that it is a well-formed root signature.
56+
57+
Named Root Signature Table
58+
==========================
59+
60+
.. code-block:: LLVM
61+
62+
!dx.rootsignatures = !{!0}
63+
64+
A named metadata node, ``dx.rootsignatures``` is used to identify the root
65+
signature table. The table itself is a list of references to function/root
66+
signature pairs.
67+
68+
Function/Root Signature Pair
69+
============================
70+
71+
.. code-block:: LLVM
72+
73+
!1 = !{ptr @main, !2, i32 2 }
74+
75+
The function/root signature associates a function (the first operand) with a
76+
reference to a root signature (the second operand). The root signature version
77+
(the third operand) used for validation logic and binary format follows.
78+
79+
Root Signature
80+
==============
81+
82+
.. code-block:: LLVM
83+
84+
!2 = !{ !3, !4, !5, !6, !7 }
85+
86+
The root signature itself simply consists of a list of references to its root
87+
signature elements.
88+
89+
Root Signature Element
90+
======================
91+
92+
A root signature element is identified by the first operand, which is a string.
93+
The following root signature elements are defined:
94+
95+
================= ======================
96+
Identifier String Root Signature Element
97+
================= ======================
98+
"RootFlags" Root Flags
99+
"RootConstants" Root Constants
100+
"RootCBV" Root Descriptor
101+
"RootSRV" Root Descriptor
102+
"RootUAV" Root Descriptor
103+
"StaticSampler" Static Sampler
104+
"DescriptorTable" Descriptor Table
105+
================= ======================
106+
107+
Below is listed the representation for each type of root signature element.
108+
109+
Root Flags
110+
==========
111+
112+
.. code-block:: LLVM
113+
114+
!3 = { !"RootFlags", i32 1 }
115+
116+
======================= ====
117+
Description Type
118+
======================= ====
119+
`Root Signature Flags`_ i32
120+
======================= ====
121+
122+
.. _Root Signature Flags: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_root_signature_flags
123+
124+
Root Constants
125+
==============
126+
127+
.. code-block:: LLVM
128+
129+
!4 = { !"RootConstants", i32 0, i32 1, i32 2, i32 3 }
130+
131+
==================== ====
132+
Description Type
133+
==================== ====
134+
`Shader Visibility`_ i32
135+
Shader Register i32
136+
Register Space i32
137+
Number 32-bit Values i32
138+
==================== ====
139+
140+
.. _Shader Visibility: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_shader_visibility
141+
142+
Root Descriptor
143+
===============
144+
145+
As noted in the table above, the first operand will denote the type of
146+
root descriptor.
147+
148+
.. code-block:: LLVM
149+
150+
!5 = { !"RootCBV", i32 0, i32 1, i32 0, i32 0 }
151+
152+
======================== ====
153+
Description Type
154+
======================== ====
155+
`Shader Visibility`_ i32
156+
Shader Register i32
157+
Register Space i32
158+
`Root Descriptor Flags`_ i32
159+
======================== ====
160+
161+
.. _Root Descriptor Flags: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_root_descriptor_flags
162+
163+
Static Sampler
164+
==============
165+
166+
.. code-block:: LLVM
167+
168+
!6 = !{ !"StaticSampler", i32 1, i32 4, ... }; remaining operands omitted for space
169+
170+
==================== =====
171+
Description Type
172+
==================== =====
173+
`Filter`_ i32
174+
`AddressU`_ i32
175+
`AddressV`_ i32
176+
`AddressW`_ i32
177+
MipLODBias float
178+
MaxAnisotropy i32
179+
`ComparisonFunc`_ i32
180+
`BorderColor`_ i32
181+
MinLOD float
182+
MaxLOD float
183+
ShaderRegister i32
184+
RegisterSpace i32
185+
`Shader Visibility`_ i32
186+
==================== =====
187+
188+
.. _Filter: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_filter
189+
.. _AddressU: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode
190+
.. _AddressV: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode
191+
.. _AddressW: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode
192+
.. _ComparisonFunc: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_comparison_func>
193+
.. _BorderColor: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_static_border_color>
194+
195+
Descriptor Table
196+
================
197+
198+
A descriptor table consists of a visibility and the remaining operands are a
199+
list of references to its descriptor ranges.
200+
201+
.. note::
202+
203+
The term Descriptor Table Clause is synonymous with Descriptor Range when
204+
referencing the implementation details.
205+
206+
.. code-block:: LLVM
207+
208+
!7 = { !"DescriptorTable", i32 0, !8, !9 }
209+
210+
========================= ================
211+
Description Type
212+
========================= ================
213+
`Shader Visibility`_ i32
214+
Descriptor Range Elements Descriptor Range
215+
========================= ================
216+
217+
218+
Descriptor Range
219+
================
220+
221+
Similar to a root descriptor, the first operand will denote the type of
222+
descriptor range. It is one of the following types:
223+
224+
- "CBV"
225+
- "SRV"
226+
- "UAV"
227+
- "Sampler"
228+
229+
.. code-block:: LLVM
230+
231+
!8 = !{ !"SRV", i32 1, i32 0, i32 0, i32 -1, i32 4 }
232+
!9 = !{ !"UAV", i32 5, i32 1, i32 10, i32 5, i32 2 }
233+
234+
============================== ====
235+
Description Type
236+
============================== ====
237+
Number of Descriptors in Range i32
238+
Shader Register i32
239+
Register Space i32
240+
`Offset`_ i32
241+
`Descriptor Range Flags`_ i32
242+
============================== ====
243+
244+
.. _Offset: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_descriptor_range
245+
.. _Descriptor Range Flags: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_descriptor_range_flags

‎llvm/docs/DirectXUsage.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ User Guide for the DirectX Target
1717
DirectX/DXILArchitecture
1818
DirectX/DXILOpTableGenDesign
1919
DirectX/DXILResources
20+
DirectX/RootSignatures
2021

2122
Introduction
2223
============

0 commit comments

Comments
 (0)