From de7e82c0e0b99e67ec4b8fbe3fef6bf07cefd0da Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 16 Jul 2025 21:32:02 +0000 Subject: [PATCH 01/23] [0002] Proposal: Add Root Signature related driver options This pr documents the expected behaviours of different root signature related command line options that exist in DXC and will implemented in Clang --- proposals/0002-root-signature-in-clang.md | 147 ++++++++++++++++++++++ 1 file changed, 147 insertions(+) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 041888d..d3c696f 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -936,6 +936,153 @@ Operands: * Does this require additional hardware/software/human resources? --> +### Root Signature Driver Options + +A user can compile and use a root signature for a shader using the different +command line options. Below lists the options available in DXC that will be +carried forward to Clang and their expected behaviour. + +(Design notes and unplanned options will be removed after being resolved) + +#### Option `-force-rootsig-ver` + +Compiles the root signatures with a specific root signature version. + +Usage: + +``` + -force-rootsig-ver rootsig_1_0 + -force-rootsig-ver rootsig_1_1 +``` + +Behaviour: + + - Validation logic that is specific to the version will be followed, as +described above + - Serialized root signature in DXIL container will be compliant with specified +version + +Design Notes: Required for backwards compatibility. Implemented in Clang. + +#### Option `-rootsig-define`: + +Sets the root signature attribute for the entry function to be the root +signature defined by the given macro expansion. + +Usage: + +Given a defined macro in the source file (`#define RS "CBV(b0)"`) + +``` + -rootsig-define RS +``` + +Behaviour: + + - If the entry function does not have a root signature attribute, it will use +the one defined by the macro expansion + + - If the entry function has a root signature attribute, it will overwrite to +use the one defined by the macro expansion + +Design Notes: Commonly used. Planned in Clang. + +#### Target Root Signature Version + +Compiles the "entry" root signature, specified by the given macro expansion, to +a DXIL Container with just the (version specific) RTS0 part. + +Usage: + +Given a defined macro in the source file (`#define RS "CBV(b0)"`) + +``` + -T -E ` + -T rootsig_1_0 -E RS /Fo RS.bin + -T rootsig_1_1 -E RS /Fo RS.bin +``` + +Behaviour: + + - Parse and perform syntactic validations of "entry" root signature + - Perform the 'basic' sub-set of validations that are available without access +to resource bindings + - Produces a DXIL container with only the serialized "entry" root signature +as the only part + + - Note: It is not possible to use `-rootsig-define` to overwrite which root +signature will be used as the "entry" root signature. + +Design Notes: Commonly used. Planned in Clang. + +#### Option `-Qstrip-rootsignature` + +Strips the root signature attribute from the entry function. + +Usage: + +``` + -Qstrip-rootsignature +``` + +Behaviour: + + - Parse and perform syntactic validations of "entry" root signature + - Perform the 'basic' sub-set of validations that are available without access +to resource bindings + - Produces the DXIL container with the root signature part (RTS0) omitted + +Design Notes: Usable within .hlsl source files. Planned in Clang unless there is +a signal of it being unused. + +Design Notes: Plan to match DXC behaviour directly such that we still do +the parsing and basic validations of the root signataure. + +#### Option `-setrootsignature` + +Overwrite the root signature part (RTS0) with the serialized root signature +given in the file. + +Usage: + +``` + -setrootsignature +``` + +Behaviour: + + - Insert/overwrite the RTS0 part of the compiled DXIL Container with the RST0 +contents of the input container + - Does not perform any validation with the input root signature + - Requires input to be a valid DXIL container with or without an RST0 part + +Design Notes: Planned in Clang. If compiling a stand-alone DXIL Container with +just the RTS0 is useful then this is presumably also required in that workflow. + +#### Option `-extractrootsignature` + +Specifies to compile the shader as normal but will only output the RTS0 part +into the produced DXIL Container. + +Usage: + +``` + -extractrootsignature /Fo +``` + +Behaviour: + + - Behaviour is the same as the +[root signature target option](#target-root-signature-version), with the +exception that it will run all validations with the resource bindings in the +shader code + +Design Notes: Not planned in Clang, as it seems shadowed. + +#### Option `-verifyrootsignature` + +Design Notes: Not planned in Clang. Appears to be broken in DXC, so no users. + ## Alternatives considered (Optional) ### Store Root Signatures as Strings From b5dd0fc99e7cb5c57c3813b7d0c3c61e4067eb75 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 16 Jul 2025 22:27:00 +0000 Subject: [PATCH 02/23] review: mention command line define --- proposals/0002-root-signature-in-clang.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index d3c696f..0a84364 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -971,7 +971,9 @@ signature defined by the given macro expansion. Usage: -Given a defined macro in the source file (`#define RS "CBV(b0)"`) +Given a defined macro either provided in the source file +(`#define RS "CBV(b0)"`), or, as a command line define +(`-D RS="CBV(b0)"`) ``` -rootsig-define RS From 5859de694322d49ff8bc371d8edf9e6447c9cb6d Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 16 Jul 2025 22:27:07 +0000 Subject: [PATCH 03/23] review: update wording --- proposals/0002-root-signature-in-clang.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 0a84364..349ee5d 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -1019,7 +1019,7 @@ Design Notes: Commonly used. Planned in Clang. #### Option `-Qstrip-rootsignature` -Strips the root signature attribute from the entry function. +Omits the root signature part (RTS0) from the produced DXIL Container. Usage: @@ -1032,7 +1032,7 @@ Behaviour: - Parse and perform syntactic validations of "entry" root signature - Perform the 'basic' sub-set of validations that are available without access to resource bindings - - Produces the DXIL container with the root signature part (RTS0) omitted + - Produces the DXIL container with the RTS0 omitted Design Notes: Usable within .hlsl source files. Planned in Clang unless there is a signal of it being unused. From 7c5faf06595bd7ea252234b2d80327dfcc138e39 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 16 Jul 2025 22:27:24 +0000 Subject: [PATCH 04/23] review: clarify 'shadow' --- proposals/0002-root-signature-in-clang.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 349ee5d..1639680 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -1079,7 +1079,9 @@ Behaviour: exception that it will run all validations with the resource bindings in the shader code -Design Notes: Not planned in Clang, as it seems shadowed. +Design Notes: Not planned in Clang. This is on the assumption that running the +additional validations doesn't provide additional utility over the root +signature target option and compiling the shader regularly. #### Option `-verifyrootsignature` From 50d458a16f5faccacabc4b39d344f7dffd63a266 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 16 Jul 2025 22:37:22 +0000 Subject: [PATCH 05/23] review: clarify what is validated --- proposals/0002-root-signature-in-clang.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 1639680..a51e2b6 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -1057,6 +1057,8 @@ Behaviour: contents of the input container - Does not perform any validation with the input root signature - Requires input to be a valid DXIL container with or without an RST0 part + - Note: Even when provided, this will parse/validate a root signature +specified as an attribute (or another above) before dropping it. Design Notes: Planned in Clang. If compiling a stand-alone DXIL Container with just the RTS0 is useful then this is presumably also required in that workflow. From 7281f3530b13ebb171ceab7dce9252038f747439 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 16 Jul 2025 22:37:37 +0000 Subject: [PATCH 06/23] self-review: use consistent language --- proposals/0002-root-signature-in-clang.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index a51e2b6..e28f8c1 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -1042,8 +1042,8 @@ the parsing and basic validations of the root signataure. #### Option `-setrootsignature` -Overwrite the root signature part (RTS0) with the serialized root signature -given in the file. +Overwrite the root signature part (RTS0) with the RTS0 of provided DXIL +Container. Usage: @@ -1055,7 +1055,7 @@ Behaviour: - Insert/overwrite the RTS0 part of the compiled DXIL Container with the RST0 contents of the input container - - Does not perform any validation with the input root signature + - Does not perform any validation with RTS0 of the provided DXIL Container - Requires input to be a valid DXIL container with or without an RST0 part - Note: Even when provided, this will parse/validate a root signature specified as an attribute (or another above) before dropping it. From 351421b1b1e68f358ca2d38eaa41c6c0bcad3a63 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 16 Jul 2025 23:09:55 +0000 Subject: [PATCH 07/23] self-review: add missed /Frs option --- proposals/0002-root-signature-in-clang.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index e28f8c1..2105434 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -1089,6 +1089,26 @@ signature target option and compiling the shader regularly. Design Notes: Not planned in Clang. Appears to be broken in DXC, so no users. +#### Option `/Frs` + +Specifies to compile the shader as normal but will also output the RTS0 part +into a separate DXIL Container. + +Usage: + +``` + /Frs +``` + +Behaviour: + + - Behaviour is the same as `-extractrootsignature`. Except that it will still +output the complete DXIL Container as normal, and, produce an additional DXIL +container with just the RTS0 part. + +Design Notes: Not planned in Clang. For similar motivations as +`extractrootsignature`. + ## Alternatives considered (Optional) ### Store Root Signatures as Strings From 2ff6d16e5ad12f98c0466340c80d5f38cae48808 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 16 Jul 2025 23:17:08 +0000 Subject: [PATCH 08/23] self-review: properly document `setrootsignature` --- proposals/0002-root-signature-in-clang.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 2105434..b7b36ba 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -1087,7 +1087,26 @@ signature target option and compiling the shader regularly. #### Option `-verifyrootsignature` -Design Notes: Not planned in Clang. Appears to be broken in DXC, so no users. +Given a shader defined from a DXIL Container, perform validations with the +root signature part (RTS0) of the other DXIL Container + +Usage: + +``` + -dumpbin -verifyrootsignatures +``` + +Note: `dumpbin` is required to load a binary instead of performing compilation + +Behaviour: + + - Performs validation that require resource binding information from the +input DXIL Container with the provided RTS0. + +Design Notes: Not planned in Clang. We don't want to provide non-compilation +options. + +Design Notes: Maybe these validations will be part of `setrootsignature`. #### Option `/Frs` From 75029be744c231250fd49e04742c7ad55e580ecf Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 16 Jul 2025 16:26:15 -0700 Subject: [PATCH 09/23] review: fix wording Co-authored-by: Tex Riddell --- proposals/0002-root-signature-in-clang.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index b7b36ba..20d3d53 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -946,7 +946,8 @@ carried forward to Clang and their expected behaviour. #### Option `-force-rootsig-ver` -Compiles the root signatures with a specific root signature version. +When compiling a shader with a root signature, this option overrides the root +signature version used, where the default is `rootsig_1_1`. Usage: From 0f6cc2f9e825c09ec5d4c98ed9c162d8b1ba1fc5 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Thu, 17 Jul 2025 08:53:52 -0700 Subject: [PATCH 10/23] review: clarify about use -E Co-authored-by: Tex Riddell --- proposals/0002-root-signature-in-clang.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 20d3d53..0ba3aa8 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -1014,7 +1014,8 @@ to resource bindings as the only part - Note: It is not possible to use `-rootsig-define` to overwrite which root -signature will be used as the "entry" root signature. +signature will be used as the "entry" root signature, because this is specified +using the `-E` option when compiling directly to a root signature target. Design Notes: Commonly used. Planned in Clang. From 0a9f430d90f861e021f7026b49b2a322ff641195 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Thu, 17 Jul 2025 08:55:18 -0700 Subject: [PATCH 11/23] review: fix typo Co-authored-by: Tex Riddell --- proposals/0002-root-signature-in-clang.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 0ba3aa8..c975c08 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -1095,7 +1095,7 @@ root signature part (RTS0) of the other DXIL Container Usage: ``` - -dumpbin -verifyrootsignatures + -dumpbin -verifyrootsignature ``` Note: `dumpbin` is required to load a binary instead of performing compilation From 93ac67444c6478c6b4b7596b18238b81325b3507 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Thu, 17 Jul 2025 16:01:01 +0000 Subject: [PATCH 12/23] reivew: clarify validations done in rootsig-define and setrootsignature --- proposals/0002-root-signature-in-clang.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index c975c08..80769b6 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -984,12 +984,16 @@ Behaviour: - If the entry function does not have a root signature attribute, it will use the one defined by the macro expansion - - If the entry function has a root signature attribute, it will overwrite to use the one defined by the macro expansion + - Note: Even when provided, this will parse and do non-resource binding +validations of the root signature specified as an attribute before dropping it Design Notes: Commonly used. Planned in Clang. +Design Notes: Should we diverge from DXC behaviour to just ignore the original +root signature specified? + #### Target Root Signature Version Compiles the "entry" root signature, specified by the given macro expansion, to @@ -1057,14 +1061,19 @@ Behaviour: - Insert/overwrite the RTS0 part of the compiled DXIL Container with the RST0 contents of the input container - - Does not perform any validation with RTS0 of the provided DXIL Container + - This will only perform the resource binding validations with the compiled +shader and RTS0 of the provided DXIL Container - Requires input to be a valid DXIL container with or without an RST0 part - - Note: Even when provided, this will parse/validate a root signature -specified as an attribute (or another above) before dropping it. + - Note: Even when provided, this will parse and do non-resource binding +validations of the root signature specified as an attribute (or another way +above) before dropping it Design Notes: Planned in Clang. If compiling a stand-alone DXIL Container with just the RTS0 is useful then this is presumably also required in that workflow. +Design Notes: Should we diverge from DXC behaviour to just ignore the original +root signature specified? + #### Option `-extractrootsignature` Specifies to compile the shader as normal but will only output the RTS0 part From d9f67e41d28594bbc60a555fd2655008c2e2dca2 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Thu, 17 Jul 2025 16:11:26 +0000 Subject: [PATCH 13/23] review: add information about `dumpbin` into heading section --- proposals/0002-root-signature-in-clang.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 80769b6..ebd6796 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -944,6 +944,17 @@ carried forward to Clang and their expected behaviour. (Design notes and unplanned options will be removed after being resolved) +Design Notes: In the context of using root signature with DXC, there is the +`-dumpbin` option which allows the user to specify a DXIL Container object as +the input file and use this for an operation, rather than invoke the compiler. +Many of the below options also have a `dumpbin` variant of the options that +provide similar functionality. So note that below, we will only consider the +context of compiling a shader. + +In this sense, we are proposing to not bring the `dumpbin` variants of these +options forward to clang. And an open question is: where do we plan to provide +these options, or, if we plan to provide them. (Possibly in `dxv` or `dxa`?) + #### Option `-force-rootsig-ver` When compiling a shader with a root signature, this option overrides the root From c9223ce1068751a7073665816316b5615a3e45e8 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Thu, 17 Jul 2025 16:12:02 +0000 Subject: [PATCH 14/23] review: clarify input in `setrootsignature` --- proposals/0002-root-signature-in-clang.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index ebd6796..685dc46 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -1074,7 +1074,8 @@ Behaviour: contents of the input container - This will only perform the resource binding validations with the compiled shader and RTS0 of the provided DXIL Container - - Requires input to be a valid DXIL container with or without an RST0 part + - Requires the option argument to be a valid DXIL container with or without an +RST0 part - Note: Even when provided, this will parse and do non-resource binding validations of the root signature specified as an attribute (or another way above) before dropping it From b51e3fa64a23bb8df6b7096cd866cdf8e94156cd Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Thu, 17 Jul 2025 16:13:53 +0000 Subject: [PATCH 15/23] review: note for Frs --- proposals/0002-root-signature-in-clang.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 685dc46..0b7be3a 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -1148,6 +1148,8 @@ Behaviour: output the complete DXIL Container as normal, and, produce an additional DXIL container with just the RTS0 part. + - Note: this does not have any `dumpbin` functionality + Design Notes: Not planned in Clang. For similar motivations as `extractrootsignature`. From 7008429dc29347496ce6da9434c4fe8f1c406910 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Thu, 17 Jul 2025 16:18:30 +0000 Subject: [PATCH 16/23] self-review: clean-up for consistent language --- proposals/0002-root-signature-in-clang.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 0b7be3a..2895ad7 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -1023,8 +1023,7 @@ Given a defined macro in the source file (`#define RS "CBV(b0)"`) Behaviour: - Parse and perform syntactic validations of "entry" root signature - - Perform the 'basic' sub-set of validations that are available without access -to resource bindings + - Perform the non-resource binding sub-set of validations - Produces a DXIL container with only the serialized "entry" root signature as the only part @@ -1047,15 +1046,14 @@ Usage: Behaviour: - Parse and perform syntactic validations of "entry" root signature - - Perform the 'basic' sub-set of validations that are available without access -to resource bindings + - Perform the non-resource binding sub-set of validations - Produces the DXIL container with the RTS0 omitted Design Notes: Usable within .hlsl source files. Planned in Clang unless there is a signal of it being unused. -Design Notes: Plan to match DXC behaviour directly such that we still do -the parsing and basic validations of the root signataure. +Design Notes: Should we diverge from DXC behaviour to just ignore the original +root signature specified? #### Option `-setrootsignature` @@ -1065,12 +1063,12 @@ Container. Usage: ``` - -setrootsignature + -setrootsignature ``` Behaviour: - - Insert/overwrite the RTS0 part of the compiled DXIL Container with the RST0 + - Insert/overwrite the RTS0 part of the compiled DXIL Container with the RTS0 contents of the input container - This will only perform the resource binding validations with the compiled shader and RTS0 of the provided DXIL Container From adfe5041eec4878e444b84f426592292cd71949c Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Fri, 18 Jul 2025 18:23:18 +0000 Subject: [PATCH 17/23] review: update from design meeting notes --- proposals/0002-root-signature-in-clang.md | 156 +++++----------------- 1 file changed, 35 insertions(+), 121 deletions(-) diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 2895ad7..3224307 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -938,22 +938,23 @@ Operands: ### Root Signature Driver Options -A user can compile and use a root signature for a shader using the different -command line options. Below lists the options available in DXC that will be -carried forward to Clang and their expected behaviour. +A user can compile and use a root signature for a shader using a variety of +different command line options. This section lists the options available in DXC +that will be carried forward to Clang and their expected behaviour. -(Design notes and unplanned options will be removed after being resolved) +Options implemented in Clang follow the guiding principle to validate as much +as possible on the smallest set of root signatures. Practically, this means +that if a root signature will not be used, then it will not be parsed or +validated. -Design Notes: In the context of using root signature with DXC, there is the -`-dumpbin` option which allows the user to specify a DXIL Container object as -the input file and use this for an operation, rather than invoke the compiler. -Many of the below options also have a `dumpbin` variant of the options that -provide similar functionality. So note that below, we will only consider the -context of compiling a shader. +DXC also provided numerous options that (alongside `-dumpbin`) were intended to +to modify the compiled DXIL Container with respect to the root signature (RTS0) +part. It has been decided that these options will not be implemented in Clang +as a driver option. Instead they will have their functionality implemented +separately within an object manipulation tool. -In this sense, we are proposing to not bring the `dumpbin` variants of these -options forward to clang. And an open question is: where do we plan to provide -these options, or, if we plan to provide them. (Possibly in `dxv` or `dxa`?) +Concretely, these DXC options are: `setrootsignature`, `extractrootsignature`, +and, `verifyrootsignature`. #### Option `-force-rootsig-ver` @@ -970,15 +971,12 @@ Usage: Behaviour: - Validation logic that is specific to the version will be followed, as -described above - - Serialized root signature in DXIL container will be compliant with specified -version - -Design Notes: Required for backwards compatibility. Implemented in Clang. +described in the [validations section](#validations-in-sema) + - The serialized RTS0 format will be compliant with specified version #### Option `-rootsig-define`: -Sets the root signature attribute for the entry function to be the root +Overrides the root signature attribute for the entry function to be the root signature defined by the given macro expansion. Usage: @@ -997,13 +995,9 @@ Behaviour: the one defined by the macro expansion - If the entry function has a root signature attribute, it will overwrite to use the one defined by the macro expansion - - Note: Even when provided, this will parse and do non-resource binding -validations of the root signature specified as an attribute before dropping it - -Design Notes: Commonly used. Planned in Clang. -Design Notes: Should we diverge from DXC behaviour to just ignore the original -root signature specified? +_Note_: Behaviour differs from DXC as it will not parse the function's root +signature attribute, if it exists #### Target Root Signature Version @@ -1015,7 +1009,8 @@ Usage: Given a defined macro in the source file (`#define RS "CBV(b0)"`) ``` - -T -E ` + -T -E + -T -E -D ="..." -T rootsig_1_0 -E RS /Fo RS.bin -T rootsig_1_1 -E RS /Fo RS.bin ``` @@ -1024,110 +1019,34 @@ Behaviour: - Parse and perform syntactic validations of "entry" root signature - Perform the non-resource binding sub-set of validations - - Produces a DXIL container with only the serialized "entry" root signature -as the only part + - Produces a DXIL container with just the RTS0 part - - Note: It is not possible to use `-rootsig-define` to overwrite which root +_Note_: It is not possible to use `-rootsig-define` to overwrite which root signature will be used as the "entry" root signature, because this is specified using the `-E` option when compiling directly to a root signature target. -Design Notes: Commonly used. Planned in Clang. +_Note_: It is possible to specify the root signature using the `-D` option. +This then should not require providing a source file. DXC still requires an +input file, so it will be left as an implementation detail of whether or not it +is feasible to have an optional source file. -#### Option `-Qstrip-rootsignature` +#### Option `-Qstrip_rootsignature` Omits the root signature part (RTS0) from the produced DXIL Container. Usage: ``` - -Qstrip-rootsignature + -Qstrip_rootsignature ``` Behaviour: - - Parse and perform syntactic validations of "entry" root signature - - Perform the non-resource binding sub-set of validations + - Parse and perform validations of used root signature - Produces the DXIL container with the RTS0 omitted -Design Notes: Usable within .hlsl source files. Planned in Clang unless there is -a signal of it being unused. - -Design Notes: Should we diverge from DXC behaviour to just ignore the original -root signature specified? - -#### Option `-setrootsignature` - -Overwrite the root signature part (RTS0) with the RTS0 of provided DXIL -Container. - -Usage: - -``` - -setrootsignature -``` - -Behaviour: - - - Insert/overwrite the RTS0 part of the compiled DXIL Container with the RTS0 -contents of the input container - - This will only perform the resource binding validations with the compiled -shader and RTS0 of the provided DXIL Container - - Requires the option argument to be a valid DXIL container with or without an -RST0 part - - Note: Even when provided, this will parse and do non-resource binding -validations of the root signature specified as an attribute (or another way -above) before dropping it - -Design Notes: Planned in Clang. If compiling a stand-alone DXIL Container with -just the RTS0 is useful then this is presumably also required in that workflow. - -Design Notes: Should we diverge from DXC behaviour to just ignore the original -root signature specified? - -#### Option `-extractrootsignature` - -Specifies to compile the shader as normal but will only output the RTS0 part -into the produced DXIL Container. - -Usage: - -``` - -extractrootsignature /Fo -``` - -Behaviour: - - - Behaviour is the same as the -[root signature target option](#target-root-signature-version), with the -exception that it will run all validations with the resource bindings in the -shader code - -Design Notes: Not planned in Clang. This is on the assumption that running the -additional validations doesn't provide additional utility over the root -signature target option and compiling the shader regularly. - -#### Option `-verifyrootsignature` - -Given a shader defined from a DXIL Container, perform validations with the -root signature part (RTS0) of the other DXIL Container - -Usage: - -``` - -dumpbin -verifyrootsignature -``` - -Note: `dumpbin` is required to load a binary instead of performing compilation - -Behaviour: - - - Performs validation that require resource binding information from the -input DXIL Container with the provided RTS0. - -Design Notes: Not planned in Clang. We don't want to provide non-compilation -options. - -Design Notes: Maybe these validations will be part of `setrootsignature`. +_Note_: Behaviour differs from DXC as it will perform resource binding +validations since this information is available. #### Option `/Frs` @@ -1142,14 +1061,9 @@ Usage: Behaviour: - - Behaviour is the same as `-extractrootsignature`. Except that it will still -output the complete DXIL Container as normal, and, produce an additional DXIL -container with just the RTS0 part. - - - Note: this does not have any `dumpbin` functionality - -Design Notes: Not planned in Clang. For similar motivations as -`extractrootsignature`. + - Creates a separate compiler action to output a DXIL Container with just RTS0 +part into the file specified. + - Parses and validates the entry function's root signature. ## Alternatives considered (Optional) From 9c5ee9784a17ff8d3ffec965cdb8117f2240327c Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Fri, 18 Jul 2025 18:27:13 +0000 Subject: [PATCH 18/23] review: move to separate proposal --- proposals/0002-root-signature-in-clang.md | 129 ----------------- .../NNNN-root-signature-driver-options.md | 136 ++++++++++++++++++ 2 files changed, 136 insertions(+), 129 deletions(-) create mode 100644 proposals/NNNN-root-signature-driver-options.md diff --git a/proposals/0002-root-signature-in-clang.md b/proposals/0002-root-signature-in-clang.md index 3224307..041888d 100644 --- a/proposals/0002-root-signature-in-clang.md +++ b/proposals/0002-root-signature-in-clang.md @@ -936,135 +936,6 @@ Operands: * Does this require additional hardware/software/human resources? --> -### Root Signature Driver Options - -A user can compile and use a root signature for a shader using a variety of -different command line options. This section lists the options available in DXC -that will be carried forward to Clang and their expected behaviour. - -Options implemented in Clang follow the guiding principle to validate as much -as possible on the smallest set of root signatures. Practically, this means -that if a root signature will not be used, then it will not be parsed or -validated. - -DXC also provided numerous options that (alongside `-dumpbin`) were intended to -to modify the compiled DXIL Container with respect to the root signature (RTS0) -part. It has been decided that these options will not be implemented in Clang -as a driver option. Instead they will have their functionality implemented -separately within an object manipulation tool. - -Concretely, these DXC options are: `setrootsignature`, `extractrootsignature`, -and, `verifyrootsignature`. - -#### Option `-force-rootsig-ver` - -When compiling a shader with a root signature, this option overrides the root -signature version used, where the default is `rootsig_1_1`. - -Usage: - -``` - -force-rootsig-ver rootsig_1_0 - -force-rootsig-ver rootsig_1_1 -``` - -Behaviour: - - - Validation logic that is specific to the version will be followed, as -described in the [validations section](#validations-in-sema) - - The serialized RTS0 format will be compliant with specified version - -#### Option `-rootsig-define`: - -Overrides the root signature attribute for the entry function to be the root -signature defined by the given macro expansion. - -Usage: - -Given a defined macro either provided in the source file -(`#define RS "CBV(b0)"`), or, as a command line define -(`-D RS="CBV(b0)"`) - -``` - -rootsig-define RS -``` - -Behaviour: - - - If the entry function does not have a root signature attribute, it will use -the one defined by the macro expansion - - If the entry function has a root signature attribute, it will overwrite to -use the one defined by the macro expansion - -_Note_: Behaviour differs from DXC as it will not parse the function's root -signature attribute, if it exists - -#### Target Root Signature Version - -Compiles the "entry" root signature, specified by the given macro expansion, to -a DXIL Container with just the (version specific) RTS0 part. - -Usage: - -Given a defined macro in the source file (`#define RS "CBV(b0)"`) - -``` - -T -E - -T -E -D ="..." - -T rootsig_1_0 -E RS /Fo RS.bin - -T rootsig_1_1 -E RS /Fo RS.bin -``` - -Behaviour: - - - Parse and perform syntactic validations of "entry" root signature - - Perform the non-resource binding sub-set of validations - - Produces a DXIL container with just the RTS0 part - -_Note_: It is not possible to use `-rootsig-define` to overwrite which root -signature will be used as the "entry" root signature, because this is specified -using the `-E` option when compiling directly to a root signature target. - -_Note_: It is possible to specify the root signature using the `-D` option. -This then should not require providing a source file. DXC still requires an -input file, so it will be left as an implementation detail of whether or not it -is feasible to have an optional source file. - -#### Option `-Qstrip_rootsignature` - -Omits the root signature part (RTS0) from the produced DXIL Container. - -Usage: - -``` - -Qstrip_rootsignature -``` - -Behaviour: - - - Parse and perform validations of used root signature - - Produces the DXIL container with the RTS0 omitted - -_Note_: Behaviour differs from DXC as it will perform resource binding -validations since this information is available. - -#### Option `/Frs` - -Specifies to compile the shader as normal but will also output the RTS0 part -into a separate DXIL Container. - -Usage: - -``` - /Frs -``` - -Behaviour: - - - Creates a separate compiler action to output a DXIL Container with just RTS0 -part into the file specified. - - Parses and validates the entry function's root signature. - ## Alternatives considered (Optional) ### Store Root Signatures as Strings diff --git a/proposals/NNNN-root-signature-driver-options.md b/proposals/NNNN-root-signature-driver-options.md new file mode 100644 index 0000000..2e7a244 --- /dev/null +++ b/proposals/NNNN-root-signature-driver-options.md @@ -0,0 +1,136 @@ + + +# Root Signature Driver Options + +* Proposal: [NNNN](NNNN-root-signture-driver-options.md) +* Author(s): [Finn Plummer](https//github.com/inbelic) +* Status: **Accepted** +* Impacted Project(s): Clang + +## Introduction + +A user can compile and use a root signature for a shader using a variety of +different command line options. This section lists the options available in DXC +that will be carried forward to Clang and their expected behaviour. + +Options implemented in Clang follow the guiding principle to validate as much +as possible on the smallest set of root signatures. Practically, this means +that if a root signature will not be used, then it will not be parsed or +validated. + +DXC also provided numerous options that (alongside `-dumpbin`) were intended to +to modify the compiled DXIL Container with respect to the root signature (RTS0) +part. It has been decided that these options will not be implemented in Clang +as a driver option. Instead they will have their functionality implemented +separately within an object manipulation tool. + +Concretely, these DXC options are: `setrootsignature`, `extractrootsignature`, +and, `verifyrootsignature`. + +### Option `-force-rootsig-ver` + +When compiling a shader with a root signature, this option overrides the root +signature version used, where the default is `rootsig_1_1`. + +Usage: + +``` + -force-rootsig-ver rootsig_1_0 + -force-rootsig-ver rootsig_1_1 +``` + +Behaviour: + + - Validation logic that is specific to the version will be followed + - The serialized RTS0 format will be compliant with specified version + +### Option `-rootsig-define`: + +Overrides the root signature attribute for the entry function to be the root +signature defined by the given macro expansion. + +Usage: + +Given a defined macro either provided in the source file +(`#define RS "CBV(b0)"`), or, as a command line define +(`-D RS="CBV(b0)"`) + +``` + -rootsig-define RS +``` + +Behaviour: + + - If the entry function does not have a root signature attribute, it will use +the one defined by the macro expansion + - If the entry function has a root signature attribute, it will overwrite to +use the one defined by the macro expansion + +_Note_: Behaviour differs from DXC as it will not parse the function's root +signature attribute, if it exists + +### Target Root Signature Version + +Compiles the "entry" root signature, specified by the given macro expansion, to +a DXIL Container with just the (version specific) RTS0 part. + +Usage: + +Given a defined macro in the source file (`#define RS "CBV(b0)"`) + +``` + -T -E + -T -E -D ="..." + -T rootsig_1_0 -E RS /Fo RS.bin + -T rootsig_1_1 -E RS /Fo RS.bin +``` + +Behaviour: + + - Parse and perform syntactic validations of "entry" root signature + - Perform the non-resource binding sub-set of validations + - Produces a DXIL container with just the RTS0 part + +_Note_: It is not possible to use `-rootsig-define` to overwrite which root +signature will be used as the "entry" root signature, because this is specified +using the `-E` option when compiling directly to a root signature target. + +_Note_: It is possible to specify the root signature using the `-D` option. +This then should not require providing a source file. DXC still requires an +input file, so it will be left as an implementation detail of whether or not it +is feasible to have an optional source file. + +### Option `-Qstrip_rootsignature` + +Omits the root signature part (RTS0) from the produced DXIL Container. + +Usage: + +``` + -Qstrip_rootsignature +``` + +Behaviour: + + - Parse and perform validations of used root signature + - Produces the DXIL container with the RTS0 omitted + +_Note_: Behaviour differs from DXC as it will perform resource binding +validations since this information is available. + +### Option `/Frs` + +Specifies to compile the shader as normal but will also output the RTS0 part +into a separate DXIL Container. + +Usage: + +``` + /Frs +``` + +Behaviour: + + - Creates a separate compiler action to output a DXIL Container with just RTS0 +part into the file specified. + - Parses and validates the entry function's root signature. From 6f78d846c0adfda0b757f6be3cf17b6c7c9ad615 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Fri, 18 Jul 2025 18:28:33 +0000 Subject: [PATCH 19/23] add footer --- proposals/NNNN-root-signature-driver-options.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/NNNN-root-signature-driver-options.md b/proposals/NNNN-root-signature-driver-options.md index 2e7a244..716ba3b 100644 --- a/proposals/NNNN-root-signature-driver-options.md +++ b/proposals/NNNN-root-signature-driver-options.md @@ -134,3 +134,7 @@ Behaviour: - Creates a separate compiler action to output a DXIL Container with just RTS0 part into the file specified. - Parses and validates the entry function's root signature. + +## Acknowledgments (Optional) + + From ad18e8cf3a5c8011d61434b67e73ea75d93dbd83 Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Fri, 18 Jul 2025 18:49:39 +0000 Subject: [PATCH 20/23] self-review: update non-compile options from design meeting --- .../NNNN-root-signature-driver-options.md | 63 ++++++++++++++++++- 1 file changed, 61 insertions(+), 2 deletions(-) diff --git a/proposals/NNNN-root-signature-driver-options.md b/proposals/NNNN-root-signature-driver-options.md index 716ba3b..4c2ba8f 100644 --- a/proposals/NNNN-root-signature-driver-options.md +++ b/proposals/NNNN-root-signature-driver-options.md @@ -24,8 +24,7 @@ part. It has been decided that these options will not be implemented in Clang as a driver option. Instead they will have their functionality implemented separately within an object manipulation tool. -Concretely, these DXC options are: `setrootsignature`, `extractrootsignature`, -and, `verifyrootsignature`. +## Compilation Options ### Option `-force-rootsig-ver` @@ -135,6 +134,66 @@ Behaviour: part into the file specified. - Parses and validates the entry function's root signature. +## Object Maniupulation Options + +For all of the following options it is defined that the produced container +will have its contents re-hashed for validility. When describing the option +usage, it is assumed that the DXIL Container to be modified is the input file. +This will be referred to as the input DXIL Container. The argument to the +option is referred to as the provided DXIL Container. + +#### Option `-setrootsignature` + +Produce a copy of input DXIL Container with the RTS0 part of provided DXIL +Container. Perform resource binding validations on produced DXIL Container. + +Usage: + +``` + -setrootsignature +``` + +Behaviour: + + - Performs resource binding validations with input shader bytecode and RTS0 +of provided DXIL Container + - Produces a copy of input DXIL Container with the RTS0 part of provided DXIL +Container + - Requires the provided DXIL Container to be a valid DXIL container with an +RST0 part + +#### Option `-extractrootsignature` + +Produce a DXIL Container containing only the input DXIL Container RTS0 part. + +Usage: + +``` + -extractrootsignature /Fo +``` + +Behaviour: + + - As described above. + +#### Option `-verifyrootsignature` + +Perform resource binding validations of input DXIL Container with the RTS0 part +of provided DXIL Container. + +Usage: + +``` + -verifyrootsignature +``` + +Behaviour: + + - Performs resource binding validations with input shader bytecode and RTS0 +of provided DXIL Container + - Requires the provided DXIL Container to be a valid DXIL container with an +RST0 part + ## Acknowledgments (Optional) From d9aae3a69229b2a0794ec6643e1279aaac177bad Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 23 Jul 2025 17:10:23 +0000 Subject: [PATCH 21/23] review: fix small errors --- proposals/NNNN-root-signature-driver-options.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/proposals/NNNN-root-signature-driver-options.md b/proposals/NNNN-root-signature-driver-options.md index 4c2ba8f..7b078d8 100644 --- a/proposals/NNNN-root-signature-driver-options.md +++ b/proposals/NNNN-root-signature-driver-options.md @@ -115,7 +115,7 @@ Behaviour: - Produces the DXIL container with the RTS0 omitted _Note_: Behaviour differs from DXC as it will perform resource binding -validations since this information is available. +validations when this information is available. ### Option `/Frs` @@ -194,6 +194,4 @@ of provided DXIL Container - Requires the provided DXIL Container to be a valid DXIL container with an RST0 part -## Acknowledgments (Optional) - From c21a2d3219dbb2d75e65c3a6e399a3df5b51a89f Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 23 Jul 2025 17:11:01 +0000 Subject: [PATCH 22/23] number proposal --- ...re-driver-options.md => 0029-root-signature-driver-options.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{NNNN-root-signature-driver-options.md => 0029-root-signature-driver-options.md} (100%) diff --git a/proposals/NNNN-root-signature-driver-options.md b/proposals/0029-root-signature-driver-options.md similarity index 100% rename from proposals/NNNN-root-signature-driver-options.md rename to proposals/0029-root-signature-driver-options.md From 667fd2e18b941cb3336ec70100415f012a276d2b Mon Sep 17 00:00:00 2001 From: Finn Plummer Date: Wed, 23 Jul 2025 17:12:55 +0000 Subject: [PATCH 23/23] add proposal number in file --- proposals/0029-root-signature-driver-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/0029-root-signature-driver-options.md b/proposals/0029-root-signature-driver-options.md index 7b078d8..484b1aa 100644 --- a/proposals/0029-root-signature-driver-options.md +++ b/proposals/0029-root-signature-driver-options.md @@ -2,7 +2,7 @@ # Root Signature Driver Options -* Proposal: [NNNN](NNNN-root-signture-driver-options.md) +* Proposal: [0029](0029-root-signture-driver-options.md) * Author(s): [Finn Plummer](https//github.com/inbelic) * Status: **Accepted** * Impacted Project(s): Clang