From e26ef1838d0e3349abe1f4d14fbe62da49c0e38d Mon Sep 17 00:00:00 2001 From: joaosaffran <126493771+joaosaffran@users.noreply.github.com> Date: Mon, 3 Mar 2025 10:21:31 -0800 Subject: [PATCH 1/7] Adding root constant documentation --- llvm/docs/DirectX/DXContainer.rst | 72 +++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst index 36e670a1c164d..601982d60cd8f 100644 --- a/llvm/docs/DirectX/DXContainer.rst +++ b/llvm/docs/DirectX/DXContainer.rst @@ -400,3 +400,75 @@ SFI0 Part The SFI0 part encodes a 64-bit unsigned integer bitmask of the feature flags. This denotes which optional features the shader requires. The flag values are defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def `_. + + +Root Signature (RST0) Part +--------- +.. _RST0: + +The Root Signature defines the interface between the shader and the pipeline, specifying which resources are bound to the shader and how they are accessed. This structure serves as a contract between the application and the GPU, establishing a layout for resource binding that both the shader compiler and the runtime can understand. + +The Root Signature consists of a header followed by a collection of root parameters and static samplers. The structure uses a versioned design with offset-based references to allow for flexible serialization and deserialization. + +Root Signature Header +~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + struct RootSignatureHeader { + uint32_t Version; + uint32_t NumParameters; + uint32_t ParametersOffset; + uint32_t NumStaticSamplers; + uint32_t StaticSamplerOffset; + uint32_t Flags; + } + + +The `RootSignatureHeader` structure contains the top-level information about a root signature: + +- **Version**: Specifies the version of the root signature format. This allows for backward compatibility as the format evolves. +- **NumParameters**: The number of root parameters contained in this root signature. +- **ParametersOffset**: Byte offset from the beginning to the array of root parameters header. +- **NumStaticSamplers**: The number of static samplers defined in the root signature. +- **StaticSamplerOffset**: Byte offset from the beginning to the array of static samplers. +- **Flags**: Bit flags that define global behaviors for the root signature, such as whether to deny vertex shader access to certain resources. + +This header allows readers to navigate the binary representation of the root signature by providing counts and offsets to locate each component within the serialized data. + +Root Parameter Header +~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + struct RootParameterHeader { + dxbc::RootParameterType ParameterType; + dxbc::ShaderVisibility ShaderVisibility; + uint32_t ParameterOffset; + }; + + +Each root parameter in the signature is preceded by a `RootParameterHeader` that describes the parameter's basic attributes: + +- **ParameterType**: Enumeration indicating what type of parameter this is (e.g., descriptor table, constants, CBV, SRV, UAV). +- **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages, vertex shader only, pixel shader only). +- **ParameterOffset**: Byte offset from the beginning to the specific parameter data structure for this entry. + +The header uses a parameter type field rather than encoding the version of the parameter through size, allowing for a more explicit representation of the parameter's nature. + +Root Parameters +~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + union RootParameter { + RootConstants Constants; + }; + +The `RootParameter` union represents the various types of parameters that can be specified in a root signature. Such includes: + +- **Constants**: Represents inline root constants that are directly embedded in the root signature and passed to the shader without requiring a constant buffer resource. + +Each specific parameter type will have its own structure with fields relevant to that parameter type. For example, `RootConstants` would include information about the register binding, count of 32-bit values, and other properties specific to constant parameters. + +When processing root parameters, readers should first check the `ParameterType` field in the corresponding header to determine which member of the union to access. From 4f3930a56d0355813a264156010aa6e6129fb3e0 Mon Sep 17 00:00:00 2001 From: joaosaffran <126493771+joaosaffran@users.noreply.github.com> Date: Mon, 3 Mar 2025 11:01:27 -0800 Subject: [PATCH 2/7] Removing union, fix typos --- llvm/docs/DirectX/DXContainer.rst | 33 +++++++++++++++++++------------ 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst index 601982d60cd8f..1f46b6ccb9599 100644 --- a/llvm/docs/DirectX/DXContainer.rst +++ b/llvm/docs/DirectX/DXContainer.rst @@ -111,7 +111,7 @@ FXC are marked with \*. #. `PSV0`_ - Stores Pipeline State Validation data. #. RDAT† - Stores Runtime Data. #. RDEF\* - Stores resource definitions. -#. RTS0 - Stores compiled root signature. +#. `RTS0`_ - Stores compiled root signature. #. `SFI0`_ - Stores shader feature flags. #. SHDR\* - Stores compiled DXBC bytecode. #. SHEX\* - Stores compiled DXBC bytecode. @@ -402,9 +402,9 @@ This denotes which optional features the shader requires. The flag values are defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def `_. -Root Signature (RST0) Part ---------- -.. _RST0: +Root Signature (RTS0) Part +-------------------------- +.. _RTS0: The Root Signature defines the interface between the shader and the pipeline, specifying which resources are bound to the shader and how they are accessed. This structure serves as a contract between the application and the GPU, establishing a layout for resource binding that both the shader compiler and the runtime can understand. @@ -457,18 +457,25 @@ Each root parameter in the signature is preceded by a `RootParameterHeader` that The header uses a parameter type field rather than encoding the version of the parameter through size, allowing for a more explicit representation of the parameter's nature. Root Parameters -~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~ -.. code-block:: c +The Root Parameters section contains structured definitions for each type of root parameter that can be included in a root signature. Each structure corresponds to a specific parameter type as identified by the ``ParameterType`` field in the ``RootParameterHeader``. - union RootParameter { - RootConstants Constants; - }; +Root Constants +~~~~~~~~~~~~~~ + +.. code-block:: cpp -The `RootParameter` union represents the various types of parameters that can be specified in a root signature. Such includes: + struct RootConstants { + uint32_t ShaderRegister; + uint32_t RegisterSpace; + uint32_t Num32BitValues; + }; -- **Constants**: Represents inline root constants that are directly embedded in the root signature and passed to the shader without requiring a constant buffer resource. +The ``RootConstants`` structure represents inline root constants that are directly embedded in the root signature and passed to the shader without requiring a constant buffer resource: -Each specific parameter type will have its own structure with fields relevant to that parameter type. For example, `RootConstants` would include information about the register binding, count of 32-bit values, and other properties specific to constant parameters. +- **ShaderRegister**: The shader register (b#) where these constants are bound. +- **RegisterSpace**: The register space used for the binding. +- **Num32BitValues**: The number of 32-bit values included in this constant buffer. -When processing root parameters, readers should first check the `ParameterType` field in the corresponding header to determine which member of the union to access. +Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead of creating and binding a constant buffer resource. From 8fae269b1543ff49ff4960cd205661ed73388653 Mon Sep 17 00:00:00 2001 From: joaosaffran <126493771+joaosaffran@users.noreply.github.com> Date: Mon, 3 Mar 2025 11:06:02 -0800 Subject: [PATCH 3/7] Wrapping text --- llvm/docs/DirectX/DXContainer.rst | 44 ++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst index 1f46b6ccb9599..4aea201b02eb3 100644 --- a/llvm/docs/DirectX/DXContainer.rst +++ b/llvm/docs/DirectX/DXContainer.rst @@ -399,16 +399,23 @@ SFI0 Part The SFI0 part encodes a 64-bit unsigned integer bitmask of the feature flags. This denotes which optional features the shader requires. The flag values are -defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def `_. +defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def +`_. Root Signature (RTS0) Part -------------------------- .. _RTS0: -The Root Signature defines the interface between the shader and the pipeline, specifying which resources are bound to the shader and how they are accessed. This structure serves as a contract between the application and the GPU, establishing a layout for resource binding that both the shader compiler and the runtime can understand. +The Root Signature defines the interface between the shader and the pipeline, +specifying which resources are bound to the shader and how they are accessed. +This structure serves as a contract between the application and the GPU, +establishing a layout for resource binding that both the shader compiler and +the runtime can understand. -The Root Signature consists of a header followed by a collection of root parameters and static samplers. The structure uses a versioned design with offset-based references to allow for flexible serialization and deserialization. +The Root Signature consists of a header followed by a collection of root parameters +and static samplers. The structure uses a versioned design with offset-based references +to allow for flexible serialization and deserialization. Root Signature Header ~~~~~~~~~~~~~~~~~~~~~~~ @@ -427,14 +434,17 @@ Root Signature Header The `RootSignatureHeader` structure contains the top-level information about a root signature: -- **Version**: Specifies the version of the root signature format. This allows for backward compatibility as the format evolves. +- **Version**: Specifies the version of the root signature format. This allows for +backward compatibility as the format evolves. - **NumParameters**: The number of root parameters contained in this root signature. - **ParametersOffset**: Byte offset from the beginning to the array of root parameters header. - **NumStaticSamplers**: The number of static samplers defined in the root signature. - **StaticSamplerOffset**: Byte offset from the beginning to the array of static samplers. -- **Flags**: Bit flags that define global behaviors for the root signature, such as whether to deny vertex shader access to certain resources. +- **Flags**: Bit flags that define global behaviors for the root signature, such as whether +to deny vertex shader access to certain resources. -This header allows readers to navigate the binary representation of the root signature by providing counts and offsets to locate each component within the serialized data. +This header allows readers to navigate the binary representation of the root signature by +providing counts and offsets to locate each component within the serialized data. Root Parameter Header ~~~~~~~~~~~~~~~~~~~~~~~ @@ -448,18 +458,25 @@ Root Parameter Header }; -Each root parameter in the signature is preceded by a `RootParameterHeader` that describes the parameter's basic attributes: +Each root parameter in the signature is preceded by a `RootParameterHeader` that describes +the parameter's basic attributes: -- **ParameterType**: Enumeration indicating what type of parameter this is (e.g., descriptor table, constants, CBV, SRV, UAV). -- **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages, vertex shader only, pixel shader only). -- **ParameterOffset**: Byte offset from the beginning to the specific parameter data structure for this entry. +- **ParameterType**: Enumeration indicating what type of parameter this is (e.g., descriptor +table, constants, CBV, SRV, UAV). +- **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages, +vertex shader only, pixel shader only). +- **ParameterOffset**: Byte offset from the beginning to the specific parameter data structure +for this entry. -The header uses a parameter type field rather than encoding the version of the parameter through size, allowing for a more explicit representation of the parameter's nature. +The header uses a parameter type field rather than encoding the version of the parameter through +size, allowing for a more explicit representation of the parameter's nature. Root Parameters ~~~~~~~~~~~~~~~ -The Root Parameters section contains structured definitions for each type of root parameter that can be included in a root signature. Each structure corresponds to a specific parameter type as identified by the ``ParameterType`` field in the ``RootParameterHeader``. +The Root Parameters section contains structured definitions for each type of root parameter that can +be included in a root signature. Each structure corresponds to a specific parameter type as identified +by the ``ParameterType`` field in the ``RootParameterHeader``. Root Constants ~~~~~~~~~~~~~~ @@ -472,7 +489,8 @@ Root Constants uint32_t Num32BitValues; }; -The ``RootConstants`` structure represents inline root constants that are directly embedded in the root signature and passed to the shader without requiring a constant buffer resource: +The ``RootConstants`` structure represents inline root constants that are directly embedded in the root +signature and passed to the shader without requiring a constant buffer resource: - **ShaderRegister**: The shader register (b#) where these constants are bound. - **RegisterSpace**: The register space used for the binding. From 7ad5d2b42cf61cc38f278630f4f9d51a9ebf9265 Mon Sep 17 00:00:00 2001 From: joaosaffran <126493771+joaosaffran@users.noreply.github.com> Date: Mon, 3 Mar 2025 11:08:34 -0800 Subject: [PATCH 4/7] Removing redundant byte offset reference --- llvm/docs/DirectX/DXContainer.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst index 4aea201b02eb3..509d273e2c38f 100644 --- a/llvm/docs/DirectX/DXContainer.rst +++ b/llvm/docs/DirectX/DXContainer.rst @@ -437,9 +437,10 @@ The `RootSignatureHeader` structure contains the top-level information about a r - **Version**: Specifies the version of the root signature format. This allows for backward compatibility as the format evolves. - **NumParameters**: The number of root parameters contained in this root signature. -- **ParametersOffset**: Byte offset from the beginning to the array of root parameters header. +- **ParametersOffset**: Byte offset from the beginning of RST0 section to the array of root +parameters header. - **NumStaticSamplers**: The number of static samplers defined in the root signature. -- **StaticSamplerOffset**: Byte offset from the beginning to the array of static samplers. +- **StaticSamplerOffset**: Byte offset to the array of static samplers. - **Flags**: Bit flags that define global behaviors for the root signature, such as whether to deny vertex shader access to certain resources. @@ -465,7 +466,7 @@ the parameter's basic attributes: table, constants, CBV, SRV, UAV). - **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages, vertex shader only, pixel shader only). -- **ParameterOffset**: Byte offset from the beginning to the specific parameter data structure +- **ParameterOffset**: Byte offset to the specific parameter data structure for this entry. The header uses a parameter type field rather than encoding the version of the parameter through From 93116c0070e23ccae03d490a598621ccc54fffc4 Mon Sep 17 00:00:00 2001 From: joaosaffran <126493771+joaosaffran@users.noreply.github.com> Date: Mon, 3 Mar 2025 11:22:42 -0800 Subject: [PATCH 5/7] Try fix test --- llvm/docs/DirectX/DXContainer.rst | 36 +++++++++++++++---------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst index 509d273e2c38f..ffef94c1e1edd 100644 --- a/llvm/docs/DirectX/DXContainer.rst +++ b/llvm/docs/DirectX/DXContainer.rst @@ -434,15 +434,15 @@ Root Signature Header The `RootSignatureHeader` structure contains the top-level information about a root signature: -- **Version**: Specifies the version of the root signature format. This allows for -backward compatibility as the format evolves. -- **NumParameters**: The number of root parameters contained in this root signature. -- **ParametersOffset**: Byte offset from the beginning of RST0 section to the array of root -parameters header. -- **NumStaticSamplers**: The number of static samplers defined in the root signature. -- **StaticSamplerOffset**: Byte offset to the array of static samplers. -- **Flags**: Bit flags that define global behaviors for the root signature, such as whether -to deny vertex shader access to certain resources. +#. **Version**: Specifies the version of the root signature format. This allows for backward + compatibility as the format evolves. +#. **NumParameters**: The number of root parameters contained in this root signature. +#. **ParametersOffset**: Byte offset from the beginning of RST0 section to the array of root + parameters header. +#. **NumStaticSamplers**: The number of static samplers defined in the root signature. +#. **StaticSamplerOffset**: Byte offset to the array of static samplers. +#. **Flags**: Bit flags that define global behaviors for the root signature, such as whether + to deny vertex shader access to certain resources. This header allows readers to navigate the binary representation of the root signature by providing counts and offsets to locate each component within the serialized data. @@ -462,12 +462,12 @@ Root Parameter Header Each root parameter in the signature is preceded by a `RootParameterHeader` that describes the parameter's basic attributes: -- **ParameterType**: Enumeration indicating what type of parameter this is (e.g., descriptor -table, constants, CBV, SRV, UAV). -- **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages, -vertex shader only, pixel shader only). -- **ParameterOffset**: Byte offset to the specific parameter data structure -for this entry. +#. **ParameterType**: Enumeration indicating what type of parameter this is (e.g., descriptor + table, constants, CBV, SRV, UAV). +#. **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages, + vertex shader only, pixel shader only). +#. **ParameterOffset**: Byte offset to the specific parameter data structure + for this entry. The header uses a parameter type field rather than encoding the version of the parameter through size, allowing for a more explicit representation of the parameter's nature. @@ -493,8 +493,8 @@ Root Constants The ``RootConstants`` structure represents inline root constants that are directly embedded in the root signature and passed to the shader without requiring a constant buffer resource: -- **ShaderRegister**: The shader register (b#) where these constants are bound. -- **RegisterSpace**: The register space used for the binding. -- **Num32BitValues**: The number of 32-bit values included in this constant buffer. +#. **ShaderRegister**: The shader register (b#) where these constants are bound. +#. **RegisterSpace**: The register space used for the binding. +#. **Num32BitValues**: The number of 32-bit values included in this constant buffer. Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead of creating and binding a constant buffer resource. From e1d385a599450e50e2af203073c88555aa6ea2a6 Mon Sep 17 00:00:00 2001 From: joaosaffran <126493771+joaosaffran@users.noreply.github.com> Date: Mon, 3 Mar 2025 11:38:56 -0800 Subject: [PATCH 6/7] Fix git error --- llvm/docs/DirectX/DXContainer.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst index ffef94c1e1edd..0e7026b03a606 100644 --- a/llvm/docs/DirectX/DXContainer.rst +++ b/llvm/docs/DirectX/DXContainer.rst @@ -399,8 +399,7 @@ SFI0 Part The SFI0 part encodes a 64-bit unsigned integer bitmask of the feature flags. This denotes which optional features the shader requires. The flag values are -defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def -`_. +defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def `_. Root Signature (RTS0) Part From 3da10bdd38df23cd582cf796f975621355f39b3a Mon Sep 17 00:00:00 2001 From: joaosaffran <126493771+joaosaffran@users.noreply.github.com> Date: Tue, 11 Mar 2025 14:19:10 -0700 Subject: [PATCH 7/7] Addressing comments --- llvm/docs/DirectX/DXContainer.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst index 0e7026b03a606..c4f976f5920ee 100644 --- a/llvm/docs/DirectX/DXContainer.rst +++ b/llvm/docs/DirectX/DXContainer.rst @@ -401,7 +401,6 @@ The SFI0 part encodes a 64-bit unsigned integer bitmask of the feature flags. This denotes which optional features the shader requires. The flag values are defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def `_. - Root Signature (RTS0) Part -------------------------- .. _RTS0: @@ -417,7 +416,7 @@ and static samplers. The structure uses a versioned design with offset-based ref to allow for flexible serialization and deserialization. Root Signature Header -~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~ .. code-block:: c @@ -447,7 +446,7 @@ This header allows readers to navigate the binary representation of the root sig providing counts and offsets to locate each component within the serialized data. Root Parameter Header -~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~ .. code-block:: c @@ -496,4 +495,5 @@ signature and passed to the shader without requiring a constant buffer resource: #. **RegisterSpace**: The register space used for the binding. #. **Num32BitValues**: The number of 32-bit values included in this constant buffer. -Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead of creating and binding a constant buffer resource. +Root constants provide a fast way to pass small amounts of data directly to the shader without the +overhead of creating and binding a constant buffer resource.