[DirectX] Adding root constant documentation

[joaosaffran]

This PR adds the documentation about Root signature binary format into DirectX.rst file.

Closes: #129561

[llvmbot]

@llvm/pr-subscribers-backend-directx

Author: None (joaosaffran)

Changes

This PR adds the documentation about Root signature binary format into DirectX.rst file.

Closes: #129561

---

Full diff: https://github.com/llvm/llvm-project/pull/129569.diff

1 Files Affected:

• (modified) llvm/docs/DirectX/DXContainer.rst (+72)

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 <https://github.com/llvm/llvm-project/blob/main/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.

[github-actions]

⚠️ We detected that you are using a GitHub private e-mail address to contribute to the repo.
Please turn off Keep my email addresses private setting in your account.
See LLVM Discourse for more information.

[llvm-beanz]

This can't be a union. They're different sized and the size of each parameter varies.

[bogner]

We usually wrap the text in .rst files so that they're easier to read when not rendered, as we do elsewhere in this file where it's wrapped at column 80.

[bogner]

Is this an enum as well, or is it a flags object?

[joaosaffran]

Shader visibility is an enum, here is the spec link proving more details.

[damyanp]

I think we should aim at this point to document how all the parts of the root signature work. What we have here is a good start for the type of documentation we need.

[damyanp]

Byte offset from the beginning to the array of root parameters header.

If all the offsets are from the beginning (I think they're all offset from the beginning of the RST0 part rather than the beginning of the container?) then maybe we can get away with just mentioning this once?

[inbelic]

nit: the two lines used here and elsewhere creates a different formatting from the rest of the document

[inbelic]

nit: do we also enforce 80 char lines here?

[bogner]

While I'm generally all for smaller PRs and breaking work up into pieces, I feel like splitting up the PR for documentation like this is making it harder to review. It would be much easier to understand this if I could read the whole document at once, and I think the fact that some of the PR comments on the follow up PRs are referring to each other and to this one are evidence that others feel the same.

Do you think it makes sense to combine #129759, #129797, and #131011 into this PR so we can review the whole description of the root constants at once?

[joaosaffran]

Sure @bogner, I will send a single PR with all the docs then.