[clang] [Doc][HLSL] Add documentation for root signature. (PR #83933)
Xiang Li via cfe-commits
cfe-commits at lists.llvm.org
Thu Mar 7 08:00:41 PST 2024
https://github.com/python3kgae updated https://github.com/llvm/llvm-project/pull/83933
>From b134854e7e183a1113ee6ae5c5f7b7910270c987 Mon Sep 17 00:00:00 2001
From: Xiang Li <python3kgae at outlook.com>
Date: Mon, 4 Mar 2024 16:39:41 -0800
Subject: [PATCH 01/10] [DOC][HLSL] Add documentation for root signature
This patch adds documentation for the root signature in HLSL.
For issue #55116
---
clang/docs/HLSL/RootSignature.rst | 210 ++++++++++++++++++++++++++++++
1 file changed, 210 insertions(+)
create mode 100644 clang/docs/HLSL/RootSignature.rst
diff --git a/clang/docs/HLSL/RootSignature.rst b/clang/docs/HLSL/RootSignature.rst
new file mode 100644
index 00000000000000..c2f57340dc2730
--- /dev/null
+++ b/clang/docs/HLSL/RootSignature.rst
@@ -0,0 +1,210 @@
+====================
+HLSL Root Signatures
+====================
+
+.. contents::
+ :local:
+
+Usage
+=====
+
+In HLSL, the `root signature
+<https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signatures>`_
+defines what types of resources are bound to the graphics pipeline.
+
+A root signature can be specified in HLSL as a `string
+<https://learn.microsoft.com/en-us/windows/win32/direct3d12/specifying-root-signatures-in-hlsl#an-example-hlsl-root-signature>`_.
+The string contains a collection of comma-separated clauses that describe root
+signature constituent components.
+
+There are two mechanisms to compile an HLSL root signature. First, it is
+possible to attach a root signature string to a particular shader via the
+RootSignature attribute (in the following example, using the MyRS1 entry
+point):
+
+.. code-block:: c++
+
+ [RootSignature(MyRS1)]
+ float4 main(float4 coord : COORD) : SV_Target
+ {
+ …
+ }
+
+The compiler will create and verify the root signature blob for the shader and
+embed it alongside the shader byte code into the shader blob.
+
+The other mechanism is to create a standalone root signature blob, perhaps to
+reuse it with a large set of shaders, saving space. The name of the define
+string is specified via the usual -E argument. For example:
+
+.. code-block:: c++
+ dxc.exe -T rootsig_1_1 MyRS1.hlsl -E MyRS1 -Fo MyRS1.fxo
+
+Note that the root signature string define can also be passed on the command
+line, e.g, -D MyRS1=”…”.
+
+Root Signature Grammar
+======================
+
+.. code-block:: c++
+
+ RootSignature : (RootElement(,RootElement)?)?
+
+ RootElement : RootFlags | RootConstants | RootCBV | RootSRV | RootUAV | DescriptorTable | StaticSampler
+
+ RootFlags : 'RootFlags' '(' (RootFlag(|RootFlag)?)? ')'
+
+ RootFlag : 'ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT' | 'DENY_VERTEX_SHADER_ROOT_ACCESS'
+
+ RootConstants : 'RootConstants' '(' 'num32BitConstants' '=' NUMBER ',' bReg (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? ')'
+
+ RootCBV : 'CBV' '(' bReg (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
+
+ RootSRV : 'SRV' '(' tReg (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
+
+ RootUAV : 'UAV' '(' uReg (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
+
+ DescriptorTable : 'DescriptorTable' '(' (DTClause(|DTClause)?)? (',' 'visibility' '=' SHADER_VISIBILITY)? ')'
+
+ DTClause : CBV | SRV | UAV | Sampler
+
+ CBV : 'CBV' '(' bReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)? (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
+
+ SRV : 'SRV' '(' tReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)? (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
+
+ UAV : 'UAV' '(' uReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)? (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
+
+ Sampler : 'Sampler' '(' sReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)? (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' NUMBER)? ')'
+
+
+ SHADER_VISIBILITY : 'SHADER_VISIBILITY_ALL' | 'SHADER_VISIBILITY_VERTEX' | 'SHADER_VISIBILITY_HULL' | 'SHADER_VISIBILITY_DOMAIN' | 'SHADER_VISIBILITY_GEOMETRY' | 'SHADER_VISIBILITY_PIXEL' | 'SHADER_VISIBILITY_AMPLIFICATION' | 'SHADER_VISIBILITY_MESH'
+
+ DATA_FLAGS : 'DATA_STATIC_WHILE_SET_AT_EXECUTE' | 'DATA_VOLATILE'
+
+ DESCRIPTOR_RANGE_OFFSET : 'DESCRIPTOR_RANGE_OFFSET_APPEND' | NUMBER
+
+ StaticSampler : 'StaticSampler' '(' sReg (',' 'filter' '=' FILTER)? (',' 'addressU' '=' TEXTURE_ADDRESS)? (',' 'addressV' '=' TEXTURE_ADDRESS)? (',' 'addressW' '=' TEXTURE_ADDRESS)? (',' 'mipLODBias' '=' NUMBER)? (',' 'maxAnisotropy' '=' NUMBER)? (',' 'comparisonFunc' '=' COMPARISON_FUNC)? (',' 'borderColor' '=' STATIC_BORDER_COLOR)? (',' 'minLOD' '=' NUMBER)? (',' 'maxLOD' '=' NUMBER)? (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? ')'
+
+ bReg : 'b' NUMBER
+
+ tReg : 't' NUMBER
+
+ uReg : 'u' NUMBER
+
+ sReg : 's' NUMBER
+
+ FILTER : 'FILTER_MIN_MAG_MIP_POINT' | 'FILTER_MIN_MAG_POINT_MIP_LINEAR' | 'FILTER_MIN_POINT_MAG_LINEAR_MIP_POINT' | 'FILTER_MIN_POINT_MAG_MIP_LINEAR' | 'FILTER_MIN_LINEAR_MAG_MIP_POINT' | 'FILTER_MIN_LINEAR_MAG_POINT_MIP_LINEAR' | 'FILTER_MIN_MAG_LINEAR_MIP_POINT' | 'FILTER_MIN_MAG_MIP_LINEAR' | 'FILTER_ANISOTROPIC' | 'FILTER_COMPARISON_MIN_MAG_MIP_POINT' | 'FILTER_COMPARISON_MIN_MAG_POINT_MIP_LINEAR' | 'FILTER_COMPARISON_MIN_POINT_MAG_LINEAR_MIP_POINT' | 'FILTER_COMPARISON_MIN_POINT_MAG_MIP_LINEAR' | 'FILTER_COMPARISON_MIN_LINEAR_MAG_MIP_POINT' | 'FILTER_COMPARISON_MIN_LINEAR_MAG_POINT_MIP_LINEAR' | 'FILTER_COMPARISON_MIN_MAG_LINEAR_MIP_POINT' | 'FILTER_COMPARISON_MIN_MAG_MIP_LINEAR' | 'FILTER_COMPARISON_ANISOTROPIC' | 'FILTER_MINIMUM_MIN_MAG_MIP_POINT' | 'FILTER_MINIMUM_MIN_MAG_POINT_MIP_LINEAR' | 'FILTER_MINIMUM_MIN_POINT_MAG_LINEAR_MIP_POINT' | 'FILTER_MINIMUM_MIN_POINT_MAG_MIP_LINEAR' | 'FILTER_MINIMUM_MIN_LINEAR_MAG_MIP_POINT' | 'FILTER_MINIMUM_MIN_LINEAR_MAG_POINT_MIP_LINEAR' | 'FILTER_MINIMUM_MIN_MAG_LINEAR_MIP_POINT' | 'FILTER_MINIMUM_MIN_MAG_MIP_LINEAR' | 'FILTER_MINIMUM_ANISOTROPIC' | 'FILTER_MAXIMUM_MIN_MAG_MIP_POINT' | 'FILTER_MAXIMUM_MIN_MAG_POINT_MIP_LINEAR' | 'FILTER_MAXIMUM_MIN_POINT_MAG_LINEAR_MIP_POINT' | 'FILTER_MAXIMUM_MIN_POINT_MAG_MIP_LINEAR' | 'FILTER_MAXIMUM_MIN_LINEAR_MAG_MIP_POINT' | 'FILTER_MAXIMUM_MIN_LINEAR_MAG_POINT_MIP_LINEAR' | 'FILTER_MAXIMUM_MIN_MAG_LINEAR_MIP_POINT' | 'FILTER_MAXIMUM_MIN_MAG_MIP_LINEAR' | 'FILTER_MAXIMUM_ANISOTROPIC'
+
+ TEXTURE_ADDRESS : 'TEXTURE_ADDRESS_WRAP' | 'TEXTURE_ADDRESS_MIRROR' | 'TEXTURE_ADDRESS_CLAMP' | 'TEXTURE_ADDRESS_BORDER' | 'TEXTURE_ADDRESS_MIRROR_ONCE'
+
+ COMPARISON_FUNC : 'COMPARISON_NEVER' | 'COMPARISON_LESS' | 'COMPARISON_EQUAL' | 'COMPARISON_LESS_EQUAL' | 'COMPARISON_GREATER' | 'COMPARISON_NOT_EQUAL' | 'COMPARISON_GREATER_EQUAL' | 'COMPARISON_ALWAYS'
+
+ STATIC_BORDER_COLOR : 'STATIC_BORDER_COLOR_TRANSPARENT_BLACK' | 'STATIC_BORDER_COLOR_OPAQUE_BLACK' | 'STATIC_BORDER_COLOR_OPAQUE_WHITE'
+
+
+Serialized format
+======================
+The root signature string is parsed and serialized into a binary format. The
+binary format is a sequence of bytes that can be used to create a root signature
+object in the Direct3D 12 API. The binary format is defined by the
+`D3D12_ROOT_SIGNATURE_DESC (for rootsig_1_0)
+<https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_root_signature_desc>`_
+or `D3D12_ROOT_SIGNATURE_DESC1 (for rootsig_1_1)
+<https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_root_signature_desc1>`_
+structure in the Direct3D 12 API.
+
+
+
+Implementation Details
+======================
+
+The root signature string will be parsed in the HLSL frontend.
+The parsing
+will happened when build HLSLRootSignatureAttr or when build standalone root
+signature blob.
+
+The root signature parsing will generate a VersionedRootSignatureDesc object
+that represents the root signature string.
+VersionedRootSignatureDesc is a struct that contains a RootSignatureVersion
+and a RootSignatureDesc.
+
+.. code-block:: c++
+ struct DescriptorRange {
+ DescriptorRangeType RangeType;
+ uint32_t NumDescriptors = 1;
+ uint32_t BaseShaderRegister;
+ uint32_t RegisterSpace = 0;
+ DescriptorRangeFlags Flags = DescriptorRangeFlags::None;
+ uint32_t OffsetInDescriptorsFromTableStart = DescriptorRangeOffsetAppend;
+ };
+
+ struct RootDescriptorTable {
+ std::vector<DescriptorRange> DescriptorRanges;
+ };
+ struct RootConstants {
+ uint32_t ShaderRegister;
+ uint32_t RegisterSpace = 0;
+ uint32_t Num32BitValues;
+ };
+
+ struct RootDescriptor {
+ uint32_t ShaderRegister;
+ uint32_t RegisterSpace = 0;
+ RootDescriptorFlags Flags = RootDescriptorFlags::None;
+ };
+ struct RootParameter {
+ RootParameterType ParameterType;
+ std::variant<RootDescriptorTable, RootConstants, RootDescriptor>
+ Parameter;
+ ShaderVisibility ShaderVisibility = ShaderVisibility::All;
+ };
+
+ struct StaticSamplerDesc {
+ Filter Filter = Filter::ANISOTROPIC;
+ TextureAddressMode AddressU = TextureAddressMode::Wrap;
+ TextureAddressMode AddressV = TextureAddressMode::Wrap;
+ TextureAddressMode AddressW = TextureAddressMode::Wrap;
+ float MipLODBias = 0.f;
+ uint32_t MaxAnisotropy = 16;
+ ComparisonFunc ComparisonFunc = ComparisonFunc::LessEqual;
+ StaticBorderColor BorderColor = StaticBorderColor::OpaqueWhite;
+ float MinLOD = 0.f;
+ float MaxLOD = MaxLOD;
+ uint32_t ShaderRegister;
+ uint32_t RegisterSpace = 0;
+ ShaderVisibility ShaderVisibility = ShaderVisibility::All;
+ };
+
+ struct RootSignatureDesc {
+ std::vector<RootParameter> Parameters;
+ std::vector<StaticSamplerDesc> StaticSamplers;
+ RootSignatureFlags Flags;
+ };
+
+ struct VersionedRootSignatureDesc {
+ RootSignatureVersion Version;
+ RootSignatureDesc Desc;
+ };
+
+Things like DescriptorRangeType and RootDescriptorFlags will be enums.
+
+After parsing, the VersionedRootSignatureDesc will be translated into a
+constant global variable in the clang AST and save to the
+HLSLRootSignatureAttr.
+
+For case compile to a standalone root signature blob, the global variable will
+be saved in the ASTContext.
+
+The global variable in AST will have a struct type that represents the root signature
+layout and a initializer that contains the values like space and
+numDescriptors of the root signature.
+
+In clang code generation, the global variable in AST will be translated into a global
+variable with cosntant initializer in LLVM IR.
+
+CGHLSLRuntime will generate metadata to link the global variable as root
+signature for given entry function or just nullptr for the standalone root
+signature blob case.
+
+In LLVM DirectX backend, the global variable will be serialized and save into the root
+signature part of dx container when emit DXIL.
>From 47539f7ddfba55b9cfe3584710712e2ba88adf2a Mon Sep 17 00:00:00 2001
From: Xiang Li <python3kgae at outlook.com>
Date: Mon, 4 Mar 2024 18:23:58 -0800
Subject: [PATCH 02/10] Fix format.
---
clang/docs/HLSL/RootSignature.rst | 101 ++++++++++++++++++++++++------
1 file changed, 82 insertions(+), 19 deletions(-)
diff --git a/clang/docs/HLSL/RootSignature.rst b/clang/docs/HLSL/RootSignature.rst
index c2f57340dc2730..bf6037dea8ea34 100644
--- a/clang/docs/HLSL/RootSignature.rst
+++ b/clang/docs/HLSL/RootSignature.rst
@@ -38,6 +38,7 @@ reuse it with a large set of shaders, saving space. The name of the define
string is specified via the usual -E argument. For example:
.. code-block:: c++
+
dxc.exe -T rootsig_1_1 MyRS1.hlsl -E MyRS1 -Fo MyRS1.fxo
Note that the root signature string define can also be passed on the command
@@ -50,40 +51,59 @@ Root Signature Grammar
RootSignature : (RootElement(,RootElement)?)?
- RootElement : RootFlags | RootConstants | RootCBV | RootSRV | RootUAV | DescriptorTable | StaticSampler
+ RootElement : RootFlags | RootConstants | RootCBV | RootSRV | RootUAV |
+ DescriptorTable | StaticSampler
RootFlags : 'RootFlags' '(' (RootFlag(|RootFlag)?)? ')'
RootFlag : 'ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT' | 'DENY_VERTEX_SHADER_ROOT_ACCESS'
- RootConstants : 'RootConstants' '(' 'num32BitConstants' '=' NUMBER ',' bReg (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? ')'
+ RootConstants : 'RootConstants' '(' 'num32BitConstants' '=' NUMBER ','
+ bReg (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? ')'
- RootCBV : 'CBV' '(' bReg (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ RootCBV : 'CBV' '(' bReg (',' 'space' '=' NUMBER)?
+ (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
- RootSRV : 'SRV' '(' tReg (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ RootSRV : 'SRV' '(' tReg (',' 'space' '=' NUMBER)?
+ (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
- RootUAV : 'UAV' '(' uReg (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ RootUAV : 'UAV' '(' uReg (',' 'space' '=' NUMBER)?
+ (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
- DescriptorTable : 'DescriptorTable' '(' (DTClause(|DTClause)?)? (',' 'visibility' '=' SHADER_VISIBILITY)? ')'
+ DescriptorTable : 'DescriptorTable' '(' (DTClause(|DTClause)?)?
+ (',' 'visibility' '=' SHADER_VISIBILITY)? ')'
DTClause : CBV | SRV | UAV | Sampler
- CBV : 'CBV' '(' bReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)? (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ CBV : 'CBV' '(' bReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)?
+ (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
- SRV : 'SRV' '(' tReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)? (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ SRV : 'SRV' '(' tReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)?
+ (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
- UAV : 'UAV' '(' uReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)? (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ UAV : 'UAV' '(' uReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)?
+ (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
- Sampler : 'Sampler' '(' sReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)? (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' NUMBER)? ')'
+ Sampler : 'Sampler' '(' sReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)?
+ (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' NUMBER)? ')'
- SHADER_VISIBILITY : 'SHADER_VISIBILITY_ALL' | 'SHADER_VISIBILITY_VERTEX' | 'SHADER_VISIBILITY_HULL' | 'SHADER_VISIBILITY_DOMAIN' | 'SHADER_VISIBILITY_GEOMETRY' | 'SHADER_VISIBILITY_PIXEL' | 'SHADER_VISIBILITY_AMPLIFICATION' | 'SHADER_VISIBILITY_MESH'
+ SHADER_VISIBILITY : 'SHADER_VISIBILITY_ALL' | 'SHADER_VISIBILITY_VERTEX' |
+ 'SHADER_VISIBILITY_HULL' | 'SHADER_VISIBILITY_DOMAIN' |
+ 'SHADER_VISIBILITY_GEOMETRY' | 'SHADER_VISIBILITY_PIXEL' |
+ 'SHADER_VISIBILITY_AMPLIFICATION' | 'SHADER_VISIBILITY_MESH'
DATA_FLAGS : 'DATA_STATIC_WHILE_SET_AT_EXECUTE' | 'DATA_VOLATILE'
DESCRIPTOR_RANGE_OFFSET : 'DESCRIPTOR_RANGE_OFFSET_APPEND' | NUMBER
- StaticSampler : 'StaticSampler' '(' sReg (',' 'filter' '=' FILTER)? (',' 'addressU' '=' TEXTURE_ADDRESS)? (',' 'addressV' '=' TEXTURE_ADDRESS)? (',' 'addressW' '=' TEXTURE_ADDRESS)? (',' 'mipLODBias' '=' NUMBER)? (',' 'maxAnisotropy' '=' NUMBER)? (',' 'comparisonFunc' '=' COMPARISON_FUNC)? (',' 'borderColor' '=' STATIC_BORDER_COLOR)? (',' 'minLOD' '=' NUMBER)? (',' 'maxLOD' '=' NUMBER)? (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? ')'
+ StaticSampler : 'StaticSampler' '(' sReg (',' 'filter' '=' FILTER)?
+ (',' 'addressU' '=' TEXTURE_ADDRESS)? (',' 'addressV' '=' TEXTURE_ADDRESS)?
+ (',' 'addressW' '=' TEXTURE_ADDRESS)? (',' 'mipLODBias' '=' NUMBER)?
+ (',' 'maxAnisotropy' '=' NUMBER)? (',' 'comparisonFunc' '=' COMPARISON_FUNC)?
+ (',' 'borderColor' '=' STATIC_BORDER_COLOR)? (',' 'minLOD' '=' NUMBER)?
+ (',' 'maxLOD' '=' NUMBER)? (',' 'space' '=' NUMBER)?
+ (',' 'visibility' '=' SHADER_VISIBILITY)? ')'
bReg : 'b' NUMBER
@@ -93,13 +113,55 @@ Root Signature Grammar
sReg : 's' NUMBER
- FILTER : 'FILTER_MIN_MAG_MIP_POINT' | 'FILTER_MIN_MAG_POINT_MIP_LINEAR' | 'FILTER_MIN_POINT_MAG_LINEAR_MIP_POINT' | 'FILTER_MIN_POINT_MAG_MIP_LINEAR' | 'FILTER_MIN_LINEAR_MAG_MIP_POINT' | 'FILTER_MIN_LINEAR_MAG_POINT_MIP_LINEAR' | 'FILTER_MIN_MAG_LINEAR_MIP_POINT' | 'FILTER_MIN_MAG_MIP_LINEAR' | 'FILTER_ANISOTROPIC' | 'FILTER_COMPARISON_MIN_MAG_MIP_POINT' | 'FILTER_COMPARISON_MIN_MAG_POINT_MIP_LINEAR' | 'FILTER_COMPARISON_MIN_POINT_MAG_LINEAR_MIP_POINT' | 'FILTER_COMPARISON_MIN_POINT_MAG_MIP_LINEAR' | 'FILTER_COMPARISON_MIN_LINEAR_MAG_MIP_POINT' | 'FILTER_COMPARISON_MIN_LINEAR_MAG_POINT_MIP_LINEAR' | 'FILTER_COMPARISON_MIN_MAG_LINEAR_MIP_POINT' | 'FILTER_COMPARISON_MIN_MAG_MIP_LINEAR' | 'FILTER_COMPARISON_ANISOTROPIC' | 'FILTER_MINIMUM_MIN_MAG_MIP_POINT' | 'FILTER_MINIMUM_MIN_MAG_POINT_MIP_LINEAR' | 'FILTER_MINIMUM_MIN_POINT_MAG_LINEAR_MIP_POINT' | 'FILTER_MINIMUM_MIN_POINT_MAG_MIP_LINEAR' | 'FILTER_MINIMUM_MIN_LINEAR_MAG_MIP_POINT' | 'FILTER_MINIMUM_MIN_LINEAR_MAG_POINT_MIP_LINEAR' | 'FILTER_MINIMUM_MIN_MAG_LINEAR_MIP_POINT' | 'FILTER_MINIMUM_MIN_MAG_MIP_LINEAR' | 'FILTER_MINIMUM_ANISOTROPIC' | 'FILTER_MAXIMUM_MIN_MAG_MIP_POINT' | 'FILTER_MAXIMUM_MIN_MAG_POINT_MIP_LINEAR' | 'FILTER_MAXIMUM_MIN_POINT_MAG_LINEAR_MIP_POINT' | 'FILTER_MAXIMUM_MIN_POINT_MAG_MIP_LINEAR' | 'FILTER_MAXIMUM_MIN_LINEAR_MAG_MIP_POINT' | 'FILTER_MAXIMUM_MIN_LINEAR_MAG_POINT_MIP_LINEAR' | 'FILTER_MAXIMUM_MIN_MAG_LINEAR_MIP_POINT' | 'FILTER_MAXIMUM_MIN_MAG_MIP_LINEAR' | 'FILTER_MAXIMUM_ANISOTROPIC'
-
- TEXTURE_ADDRESS : 'TEXTURE_ADDRESS_WRAP' | 'TEXTURE_ADDRESS_MIRROR' | 'TEXTURE_ADDRESS_CLAMP' | 'TEXTURE_ADDRESS_BORDER' | 'TEXTURE_ADDRESS_MIRROR_ONCE'
-
- COMPARISON_FUNC : 'COMPARISON_NEVER' | 'COMPARISON_LESS' | 'COMPARISON_EQUAL' | 'COMPARISON_LESS_EQUAL' | 'COMPARISON_GREATER' | 'COMPARISON_NOT_EQUAL' | 'COMPARISON_GREATER_EQUAL' | 'COMPARISON_ALWAYS'
-
- STATIC_BORDER_COLOR : 'STATIC_BORDER_COLOR_TRANSPARENT_BLACK' | 'STATIC_BORDER_COLOR_OPAQUE_BLACK' | 'STATIC_BORDER_COLOR_OPAQUE_WHITE'
+ FILTER : 'FILTER_MIN_MAG_MIP_POINT' |
+ 'FILTER_MIN_MAG_POINT_MIP_LINEAR' |
+ 'FILTER_MIN_POINT_MAG_LINEAR_MIP_POINT' |
+ 'FILTER_MIN_POINT_MAG_MIP_LINEAR' |
+ 'FILTER_MIN_LINEAR_MAG_MIP_POINT' |
+ 'FILTER_MIN_LINEAR_MAG_POINT_MIP_LINEAR' |
+ 'FILTER_MIN_MAG_LINEAR_MIP_POINT' |
+ 'FILTER_MIN_MAG_MIP_LINEAR' |
+ 'FILTER_ANISOTROPIC' |
+ 'FILTER_COMPARISON_MIN_MAG_MIP_POINT' |
+ 'FILTER_COMPARISON_MIN_MAG_POINT_MIP_LINEAR' |
+ 'FILTER_COMPARISON_MIN_POINT_MAG_LINEAR_MIP_POINT' |
+ 'FILTER_COMPARISON_MIN_POINT_MAG_MIP_LINEAR' |
+ 'FILTER_COMPARISON_MIN_LINEAR_MAG_MIP_POINT' |
+ 'FILTER_COMPARISON_MIN_LINEAR_MAG_POINT_MIP_LINEAR' |
+ 'FILTER_COMPARISON_MIN_MAG_LINEAR_MIP_POINT' |
+ 'FILTER_COMPARISON_MIN_MAG_MIP_LINEAR' |
+ 'FILTER_COMPARISON_ANISOTROPIC' |
+ 'FILTER_MINIMUM_MIN_MAG_MIP_POINT' |
+ 'FILTER_MINIMUM_MIN_MAG_POINT_MIP_LINEAR' |
+ 'FILTER_MINIMUM_MIN_POINT_MAG_LINEAR_MIP_POINT' |
+ 'FILTER_MINIMUM_MIN_POINT_MAG_MIP_LINEAR' |
+ 'FILTER_MINIMUM_MIN_LINEAR_MAG_MIP_POINT' |
+ 'FILTER_MINIMUM_MIN_LINEAR_MAG_POINT_MIP_LINEAR' |
+ 'FILTER_MINIMUM_MIN_MAG_LINEAR_MIP_POINT' |
+ 'FILTER_MINIMUM_MIN_MAG_MIP_LINEAR' |
+ 'FILTER_MINIMUM_ANISOTROPIC' |
+ 'FILTER_MAXIMUM_MIN_MAG_MIP_POINT' |
+ 'FILTER_MAXIMUM_MIN_MAG_POINT_MIP_LINEAR' |
+ 'FILTER_MAXIMUM_MIN_POINT_MAG_LINEAR_MIP_POINT' |
+ 'FILTER_MAXIMUM_MIN_POINT_MAG_MIP_LINEAR' |
+ 'FILTER_MAXIMUM_MIN_LINEAR_MAG_MIP_POINT' |
+ 'FILTER_MAXIMUM_MIN_LINEAR_MAG_POINT_MIP_LINEAR' |
+ 'FILTER_MAXIMUM_MIN_MAG_LINEAR_MIP_POINT' |
+ 'FILTER_MAXIMUM_MIN_MAG_MIP_LINEAR' |
+ 'FILTER_MAXIMUM_ANISOTROPIC'
+
+ TEXTURE_ADDRESS : 'TEXTURE_ADDRESS_WRAP' |
+ 'TEXTURE_ADDRESS_MIRROR' | 'TEXTURE_ADDRESS_CLAMP' |
+ 'TEXTURE_ADDRESS_BORDER' | 'TEXTURE_ADDRESS_MIRROR_ONCE'
+
+ COMPARISON_FUNC : 'COMPARISON_NEVER' | 'COMPARISON_LESS' |
+ 'COMPARISON_EQUAL' | 'COMPARISON_LESS_EQUAL' |
+ 'COMPARISON_GREATER' | 'COMPARISON_NOT_EQUAL' |
+ 'COMPARISON_GREATER_EQUAL' | 'COMPARISON_ALWAYS'
+
+ STATIC_BORDER_COLOR : 'STATIC_BORDER_COLOR_TRANSPARENT_BLACK' |
+ 'STATIC_BORDER_COLOR_OPAQUE_BLACK' |
+ 'STATIC_BORDER_COLOR_OPAQUE_WHITE'
Serialized format
@@ -129,6 +191,7 @@ VersionedRootSignatureDesc is a struct that contains a RootSignatureVersion
and a RootSignatureDesc.
.. code-block:: c++
+
struct DescriptorRange {
DescriptorRangeType RangeType;
uint32_t NumDescriptors = 1;
>From b4cd39e536c4f33ddcb1b0405632f6a86dec7fa3 Mon Sep 17 00:00:00 2001
From: Xiang Li <python3kgae at outlook.com>
Date: Mon, 4 Mar 2024 18:29:51 -0800
Subject: [PATCH 03/10] More format fix.
---
clang/docs/HLSL/RootSignature.rst | 72 ++++++++++++++++++++-----------
1 file changed, 47 insertions(+), 25 deletions(-)
diff --git a/clang/docs/HLSL/RootSignature.rst b/clang/docs/HLSL/RootSignature.rst
index bf6037dea8ea34..d6b4ddfb013b58 100644
--- a/clang/docs/HLSL/RootSignature.rst
+++ b/clang/docs/HLSL/RootSignature.rst
@@ -56,52 +56,71 @@ Root Signature Grammar
RootFlags : 'RootFlags' '(' (RootFlag(|RootFlag)?)? ')'
- RootFlag : 'ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT' | 'DENY_VERTEX_SHADER_ROOT_ACCESS'
+ RootFlag : 'ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT' |
+ 'DENY_VERTEX_SHADER_ROOT_ACCESS'
RootConstants : 'RootConstants' '(' 'num32BitConstants' '=' NUMBER ','
- bReg (',' 'space' '=' NUMBER)? (',' 'visibility' '=' SHADER_VISIBILITY)? ')'
+ bReg (',' 'space' '=' NUMBER)?
+ (',' 'visibility' '=' SHADER_VISIBILITY)? ')'
RootCBV : 'CBV' '(' bReg (',' 'space' '=' NUMBER)?
- (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ (',' 'visibility' '=' SHADER_VISIBILITY)?
+ (',' 'flags' '=' DATA_FLAGS)? ')'
RootSRV : 'SRV' '(' tReg (',' 'space' '=' NUMBER)?
- (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ (',' 'visibility' '=' SHADER_VISIBILITY)?
+ (',' 'flags' '=' DATA_FLAGS)? ')'
RootUAV : 'UAV' '(' uReg (',' 'space' '=' NUMBER)?
- (',' 'visibility' '=' SHADER_VISIBILITY)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ (',' 'visibility' '=' SHADER_VISIBILITY)?
+ (',' 'flags' '=' DATA_FLAGS)? ')'
DescriptorTable : 'DescriptorTable' '(' (DTClause(|DTClause)?)?
(',' 'visibility' '=' SHADER_VISIBILITY)? ')'
DTClause : CBV | SRV | UAV | Sampler
- CBV : 'CBV' '(' bReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)?
- (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ CBV : 'CBV' '(' bReg (',' 'numDescriptors' '=' NUMBER)?
+ (',' 'space' '=' NUMBER)?
+ (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)?
+ (',' 'flags' '=' DATA_FLAGS)? ')'
- SRV : 'SRV' '(' tReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)?
- (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ SRV : 'SRV' '(' tReg (',' 'numDescriptors' '=' NUMBER)?
+ (',' 'space' '=' NUMBER)?
+ (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)?
+ (',' 'flags' '=' DATA_FLAGS)? ')'
- UAV : 'UAV' '(' uReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)?
- (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' DATA_FLAGS)? ')'
+ UAV : 'UAV' '(' uReg (',' 'numDescriptors' '=' NUMBER)?
+ (',' 'space' '=' NUMBER)?
+ (',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)?
+ (',' 'flags' '=' DATA_FLAGS)? ')'
- Sampler : 'Sampler' '(' sReg (',' 'numDescriptors' '=' NUMBER)? (',' 'space' '=' NUMBER)?
+ Sampler : 'Sampler' '(' sReg (',' 'numDescriptors' '=' NUMBER)?
+ (',' 'space' '=' NUMBER)?
(',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' NUMBER)? ')'
SHADER_VISIBILITY : 'SHADER_VISIBILITY_ALL' | 'SHADER_VISIBILITY_VERTEX' |
- 'SHADER_VISIBILITY_HULL' | 'SHADER_VISIBILITY_DOMAIN' |
- 'SHADER_VISIBILITY_GEOMETRY' | 'SHADER_VISIBILITY_PIXEL' |
- 'SHADER_VISIBILITY_AMPLIFICATION' | 'SHADER_VISIBILITY_MESH'
+ 'SHADER_VISIBILITY_HULL' |
+ 'SHADER_VISIBILITY_DOMAIN' |
+ 'SHADER_VISIBILITY_GEOMETRY' |
+ 'SHADER_VISIBILITY_PIXEL' |
+ 'SHADER_VISIBILITY_AMPLIFICATION' |
+ 'SHADER_VISIBILITY_MESH'
DATA_FLAGS : 'DATA_STATIC_WHILE_SET_AT_EXECUTE' | 'DATA_VOLATILE'
DESCRIPTOR_RANGE_OFFSET : 'DESCRIPTOR_RANGE_OFFSET_APPEND' | NUMBER
StaticSampler : 'StaticSampler' '(' sReg (',' 'filter' '=' FILTER)?
- (',' 'addressU' '=' TEXTURE_ADDRESS)? (',' 'addressV' '=' TEXTURE_ADDRESS)?
- (',' 'addressW' '=' TEXTURE_ADDRESS)? (',' 'mipLODBias' '=' NUMBER)?
- (',' 'maxAnisotropy' '=' NUMBER)? (',' 'comparisonFunc' '=' COMPARISON_FUNC)?
- (',' 'borderColor' '=' STATIC_BORDER_COLOR)? (',' 'minLOD' '=' NUMBER)?
+ (',' 'addressU' '=' TEXTURE_ADDRESS)?
+ (',' 'addressV' '=' TEXTURE_ADDRESS)?
+ (',' 'addressW' '=' TEXTURE_ADDRESS)?
+ (',' 'mipLODBias' '=' NUMBER)?
+ (',' 'maxAnisotropy' '=' NUMBER)?
+ (',' 'comparisonFunc' '=' COMPARISON_FUNC)?
+ (',' 'borderColor' '=' STATIC_BORDER_COLOR)?
+ (',' 'minLOD' '=' NUMBER)?
(',' 'maxLOD' '=' NUMBER)? (',' 'space' '=' NUMBER)?
(',' 'visibility' '=' SHADER_VISIBILITY)? ')'
@@ -258,16 +277,19 @@ HLSLRootSignatureAttr.
For case compile to a standalone root signature blob, the global variable will
be saved in the ASTContext.
-The global variable in AST will have a struct type that represents the root signature
-layout and a initializer that contains the values like space and
+The global variable in AST will have a struct type that represents the root
+signature layout and a initializer that contains the values like space and
numDescriptors of the root signature.
-In clang code generation, the global variable in AST will be translated into a global
-variable with cosntant initializer in LLVM IR.
+In clang code generation, the global variable in AST will be translated into
+a global variable with constant initializer in LLVM IR.
CGHLSLRuntime will generate metadata to link the global variable as root
signature for given entry function or just nullptr for the standalone root
signature blob case.
-In LLVM DirectX backend, the global variable will be serialized and save into the root
-signature part of dx container when emit DXIL.
+In LLVM DirectX backend, the global variable will be serialized and save into
+ the root signature part of dx container when emit DXIL.
+
+In DXIL validation, the root signature part will be deserialized and check if
+the resource binding in the root signature exists in the resource table.
>From f3504ff4e73ed9156ff5bb752dfcd5c6d4fa5e90 Mon Sep 17 00:00:00 2001
From: Xiang Li <python3kgae at outlook.com>
Date: Mon, 4 Mar 2024 18:37:29 -0800
Subject: [PATCH 04/10] Add example
---
clang/docs/HLSL/RootSignature.rst | 19 ++++++++++++++++++-
1 file changed, 18 insertions(+), 1 deletion(-)
diff --git a/clang/docs/HLSL/RootSignature.rst b/clang/docs/HLSL/RootSignature.rst
index d6b4ddfb013b58..c1a3e48fed4ddf 100644
--- a/clang/docs/HLSL/RootSignature.rst
+++ b/clang/docs/HLSL/RootSignature.rst
@@ -24,7 +24,24 @@ point):
.. code-block:: c++
- [RootSignature(MyRS1)]
+ #define RS "RootFlags( ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT | " \
+ "DENY_VERTEX_SHADER_ROOT_ACCESS), " \
+ "CBV(b0, space = 1, flags = DATA_STATIC), " \
+ "SRV(t0), " \
+ "UAV(u0), " \
+ "DescriptorTable( CBV(b1), " \
+ " SRV(t1, numDescriptors = 8, " \
+ " flags = DESCRIPTORS_VOLATILE), " \
+ " UAV(u1, numDescriptors = unbounded, " \
+ " flags = DESCRIPTORS_VOLATILE)), " \
+ "DescriptorTable(Sampler(s0, space=1, numDescriptors = 4)), " \
+ "RootConstants(num32BitConstants=3, b10), " \
+ "StaticSampler(s1)," \
+ "StaticSampler(s2, " \
+ " addressU = TEXTURE_ADDRESS_CLAMP, " \
+ " filter = FILTER_MIN_MAG_MIP_LINEAR )"
+
+ [RootSignature(RS)]
float4 main(float4 coord : COORD) : SV_Target
{
…
>From 6c35d7308c310e725b1356a88317067fc5dab546 Mon Sep 17 00:00:00 2001
From: Xiang Li <python3kgae at outlook.com>
Date: Tue, 5 Mar 2024 12:45:11 -0800
Subject: [PATCH 05/10] Update per comment.
---
clang/docs/HLSL/RootSignature.rst | 98 +++++--------------------------
1 file changed, 16 insertions(+), 82 deletions(-)
diff --git a/clang/docs/HLSL/RootSignature.rst b/clang/docs/HLSL/RootSignature.rst
index c1a3e48fed4ddf..8d894c50e51540 100644
--- a/clang/docs/HLSL/RootSignature.rst
+++ b/clang/docs/HLSL/RootSignature.rst
@@ -209,104 +209,38 @@ object in the Direct3D 12 API. The binary format is defined by the
<https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_root_signature_desc>`_
or `D3D12_ROOT_SIGNATURE_DESC1 (for rootsig_1_1)
<https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_root_signature_desc1>`_
-structure in the Direct3D 12 API.
-
+structure in the Direct3D 12 API. (With the pointers translated to offsets.)
+DXC implementation of the serialization could be find `here
+<https://github.com/microsoft/DirectXShaderCompiler/blob/main/lib/DxilRootSignature/DxilRootSignatureSerializer.cpp#L41>`_
Implementation Details
======================
-The root signature string will be parsed in the HLSL frontend.
+The root signature string will be parsed in Clang.
The parsing
will happened when build HLSLRootSignatureAttr or when build standalone root
signature blob.
-The root signature parsing will generate a VersionedRootSignatureDesc object
-that represents the root signature string.
-VersionedRootSignatureDesc is a struct that contains a RootSignatureVersion
-and a RootSignatureDesc.
+The root signature parsing will generate a HLSLRootSignatureAttr with member
+represents the root signature string and the parsed information for each
+resource in the root signature. It will bind to the entry function in the AST.
-.. code-block:: c++
+For case compile to a standalone root signature blob, the HLSLRootSignatureAttr
+will be bind to the TU.
- struct DescriptorRange {
- DescriptorRangeType RangeType;
- uint32_t NumDescriptors = 1;
- uint32_t BaseShaderRegister;
- uint32_t RegisterSpace = 0;
- DescriptorRangeFlags Flags = DescriptorRangeFlags::None;
- uint32_t OffsetInDescriptorsFromTableStart = DescriptorRangeOffsetAppend;
- };
-
- struct RootDescriptorTable {
- std::vector<DescriptorRange> DescriptorRanges;
- };
- struct RootConstants {
- uint32_t ShaderRegister;
- uint32_t RegisterSpace = 0;
- uint32_t Num32BitValues;
- };
-
- struct RootDescriptor {
- uint32_t ShaderRegister;
- uint32_t RegisterSpace = 0;
- RootDescriptorFlags Flags = RootDescriptorFlags::None;
- };
- struct RootParameter {
- RootParameterType ParameterType;
- std::variant<RootDescriptorTable, RootConstants, RootDescriptor>
- Parameter;
- ShaderVisibility ShaderVisibility = ShaderVisibility::All;
- };
-
- struct StaticSamplerDesc {
- Filter Filter = Filter::ANISOTROPIC;
- TextureAddressMode AddressU = TextureAddressMode::Wrap;
- TextureAddressMode AddressV = TextureAddressMode::Wrap;
- TextureAddressMode AddressW = TextureAddressMode::Wrap;
- float MipLODBias = 0.f;
- uint32_t MaxAnisotropy = 16;
- ComparisonFunc ComparisonFunc = ComparisonFunc::LessEqual;
- StaticBorderColor BorderColor = StaticBorderColor::OpaqueWhite;
- float MinLOD = 0.f;
- float MaxLOD = MaxLOD;
- uint32_t ShaderRegister;
- uint32_t RegisterSpace = 0;
- ShaderVisibility ShaderVisibility = ShaderVisibility::All;
- };
-
- struct RootSignatureDesc {
- std::vector<RootParameter> Parameters;
- std::vector<StaticSamplerDesc> StaticSamplers;
- RootSignatureFlags Flags;
- };
-
- struct VersionedRootSignatureDesc {
- RootSignatureVersion Version;
- RootSignatureDesc Desc;
- };
-
-Things like DescriptorRangeType and RootDescriptorFlags will be enums.
-
-After parsing, the VersionedRootSignatureDesc will be translated into a
-constant global variable in the clang AST and save to the
-HLSLRootSignatureAttr.
-
-For case compile to a standalone root signature blob, the global variable will
-be saved in the ASTContext.
-
-The global variable in AST will have a struct type that represents the root
-signature layout and a initializer that contains the values like space and
-numDescriptors of the root signature.
-
-In clang code generation, the global variable in AST will be translated into
-a global variable with constant initializer in LLVM IR.
+In clang code generation, the HLSLRootSignatureAttr in AST will be translated into
+a global variable with struct type to express the layout and a constant initializer
+to save things like space and NumDescriptors in LLVM IR.
CGHLSLRuntime will generate metadata to link the global variable as root
signature for given entry function or just nullptr for the standalone root
signature blob case.
-In LLVM DirectX backend, the global variable will be serialized and save into
- the root signature part of dx container when emit DXIL.
+In LLVM DirectX backend, the global variable will be serialized and saved as another
+global variable with section 'RTS0' with the serialized root signature as initializer.
+Then 'RTS0' global variable will be translated to the root signature part of dx
+container.
In DXIL validation, the root signature part will be deserialized and check if
the resource binding in the root signature exists in the resource table.
>From 1596854fd52af8db2bcac5b5a016953bbcb8c778 Mon Sep 17 00:00:00 2001
From: Xiang Li <python3kgae at outlook.com>
Date: Tue, 5 Mar 2024 12:48:32 -0800
Subject: [PATCH 06/10] Add MC ObjectWriter part.
---
clang/docs/HLSL/RootSignature.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/clang/docs/HLSL/RootSignature.rst b/clang/docs/HLSL/RootSignature.rst
index 8d894c50e51540..8756a001f1b5d9 100644
--- a/clang/docs/HLSL/RootSignature.rst
+++ b/clang/docs/HLSL/RootSignature.rst
@@ -239,8 +239,8 @@ signature blob case.
In LLVM DirectX backend, the global variable will be serialized and saved as another
global variable with section 'RTS0' with the serialized root signature as initializer.
-Then 'RTS0' global variable will be translated to the root signature part of dx
-container.
+The MC ObjectWriter for DXContainer will take the global and write it to the correct
+part based on the section name given to the global.
In DXIL validation, the root signature part will be deserialized and check if
the resource binding in the root signature exists in the resource table.
>From a302b608cb59afec312b2a5d4b2274af06170701 Mon Sep 17 00:00:00 2001
From: Xiang Li <python3kgae at outlook.com>
Date: Tue, 5 Mar 2024 14:37:09 -0800
Subject: [PATCH 07/10] Add more detail about validation.
---
clang/docs/HLSL/RootSignature.rst | 26 ++++++++++++++++++--------
1 file changed, 18 insertions(+), 8 deletions(-)
diff --git a/clang/docs/HLSL/RootSignature.rst b/clang/docs/HLSL/RootSignature.rst
index 8756a001f1b5d9..0328d7848f534a 100644
--- a/clang/docs/HLSL/RootSignature.rst
+++ b/clang/docs/HLSL/RootSignature.rst
@@ -229,18 +229,28 @@ resource in the root signature. It will bind to the entry function in the AST.
For case compile to a standalone root signature blob, the HLSLRootSignatureAttr
will be bind to the TU.
-In clang code generation, the HLSLRootSignatureAttr in AST will be translated into
-a global variable with struct type to express the layout and a constant initializer
-to save things like space and NumDescriptors in LLVM IR.
+In clang code generation, the HLSLRootSignatureAttr in AST will be translated
+into a global variable with struct type to express the layout and a constant
+initializer to save things like space and NumDescriptors in LLVM IR.
CGHLSLRuntime will generate metadata to link the global variable as root
signature for given entry function or just nullptr for the standalone root
signature blob case.
-In LLVM DirectX backend, the global variable will be serialized and saved as another
-global variable with section 'RTS0' with the serialized root signature as initializer.
-The MC ObjectWriter for DXContainer will take the global and write it to the correct
-part based on the section name given to the global.
+In LLVM DirectX backend, the global variable will be serialized and saved as
+another global variable with section 'RTS0' with the serialized root signature
+as initializer.
+The MC ObjectWriter for DXContainer will take the global and write it to the
+correct part based on the section name given to the global.
In DXIL validation, the root signature part will be deserialized and check if
-the resource binding in the root signature exists in the resource table.
+resource used in the shader (the information is in pipeline state validation
+part) exists in the root signature.
+
+Same check could be done in Sema as well. But at AST level, it is impossible
+to identify unused resource which will be removed later. And the resource
+binding allocation is not done.
+So the only case could be caught in Sema is for resources that are known to be
+used for sure (like resources used in entry function and not under any control
+flow) and binded by user.
+If the resource is not in root signature, error should be reported in Sema.
>From 6764bb53803496109cf0d576c0ce2d84ee4cf50b Mon Sep 17 00:00:00 2001
From: Xiang Li <python3kgae at outlook.com>
Date: Tue, 5 Mar 2024 14:47:31 -0800
Subject: [PATCH 08/10] Add TODO for detailed serialization format.
---
clang/docs/HLSL/RootSignature.rst | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/clang/docs/HLSL/RootSignature.rst b/clang/docs/HLSL/RootSignature.rst
index 0328d7848f534a..c76ee8e73d1964 100644
--- a/clang/docs/HLSL/RootSignature.rst
+++ b/clang/docs/HLSL/RootSignature.rst
@@ -211,8 +211,9 @@ or `D3D12_ROOT_SIGNATURE_DESC1 (for rootsig_1_1)
<https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_root_signature_desc1>`_
structure in the Direct3D 12 API. (With the pointers translated to offsets.)
-DXC implementation of the serialization could be find `here
-<https://github.com/microsoft/DirectXShaderCompiler/blob/main/lib/DxilRootSignature/DxilRootSignatureSerializer.cpp#L41>`_
+TODO: replace the following link with actual serialized format.
+ DXC implementation of the serialization could be find `here
+ <https://github.com/microsoft/DirectXShaderCompiler/blob/main/lib/DxilRootSignature/DxilRootSignatureSerializer.cpp#L41>`_
Implementation Details
======================
>From 9df07446d45b810f8db036a2d0dea136b13d0b71 Mon Sep 17 00:00:00 2001
From: Xiang Li <python3kgae at outlook.com>
Date: Wed, 6 Mar 2024 12:55:17 -0800
Subject: [PATCH 09/10] Do the check in IR pass for DirectX backend. And add
empty entry for standalone root signature case.
---
clang/docs/HLSL/RootSignature.rst | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/clang/docs/HLSL/RootSignature.rst b/clang/docs/HLSL/RootSignature.rst
index c76ee8e73d1964..62497a628d08cc 100644
--- a/clang/docs/HLSL/RootSignature.rst
+++ b/clang/docs/HLSL/RootSignature.rst
@@ -228,15 +228,14 @@ represents the root signature string and the parsed information for each
resource in the root signature. It will bind to the entry function in the AST.
For case compile to a standalone root signature blob, the HLSLRootSignatureAttr
-will be bind to the TU.
+will be bind to a fake empty entry.
In clang code generation, the HLSLRootSignatureAttr in AST will be translated
into a global variable with struct type to express the layout and a constant
initializer to save things like space and NumDescriptors in LLVM IR.
CGHLSLRuntime will generate metadata to link the global variable as root
-signature for given entry function or just nullptr for the standalone root
-signature blob case.
+signature for given entry function.
In LLVM DirectX backend, the global variable will be serialized and saved as
another global variable with section 'RTS0' with the serialized root signature
@@ -244,9 +243,11 @@ as initializer.
The MC ObjectWriter for DXContainer will take the global and write it to the
correct part based on the section name given to the global.
-In DXIL validation, the root signature part will be deserialized and check if
-resource used in the shader (the information is in pipeline state validation
-part) exists in the root signature.
+In DXIL validation for DXC, the root signature part will be deserialized and
+check if resource used in the shader (the information is in pipeline state
+validation part) exists in the root signature.
+For LLVM DirectX backend, this could be done in IR pass before emit DXIL
+instead of validation.
Same check could be done in Sema as well. But at AST level, it is impossible
to identify unused resource which will be removed later. And the resource
>From a1b2a077859b1ee4b65d85024e7a16550b27a73f Mon Sep 17 00:00:00 2001
From: Xiang Li <python3kgae at outlook.com>
Date: Thu, 7 Mar 2024 08:00:20 -0800
Subject: [PATCH 10/10] Add DXContainerGlobals for create 'RTS0' global.
---
clang/docs/HLSL/RootSignature.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang/docs/HLSL/RootSignature.rst b/clang/docs/HLSL/RootSignature.rst
index 62497a628d08cc..61f81b848e271e 100644
--- a/clang/docs/HLSL/RootSignature.rst
+++ b/clang/docs/HLSL/RootSignature.rst
@@ -239,7 +239,7 @@ signature for given entry function.
In LLVM DirectX backend, the global variable will be serialized and saved as
another global variable with section 'RTS0' with the serialized root signature
-as initializer.
+as initializer in DXContainerGlobals pass.
The MC ObjectWriter for DXContainer will take the global and write it to the
correct part based on the section name given to the global.
More information about the cfe-commits
mailing list