[llvm] [DirectX] Documenting Root Signature Binary representation (PR #131011)

[Justin Bogner via llvm-commits]

================
@@ -400,3 +400,273 @@ 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 (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 consists of a header followed by an array of root parameters 
+and an array of static samplers. The structure uses a versioned design with 
+offset-based references to allow for flexible serialization and deserialization. 
+One consequence of using an offset-based reference is that root parameters and 
+static samplers don't need to follow any specific ordering logic.
+
+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 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.
+
+Root Parameters
+~~~~~~~~~~~~~~~
+
+Root signatures parameters are split into a header section containing the parameter type, 
+shader visibility and its offset, and a data section. The parameters don't need to follow 
+any specific order. Root parameters define the interface elements that shaders can access. 
+Each parameter can be one of several types, including descriptor tables, constants, or 
+descriptors for different resource types.
+
+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).
----------------
bogner wrote:

I think it would be helpful to explain the full set of parameter types and possible visibilities in the top level description of root parameters. Then this can simply refer back to that and say we describe the parameter type and visibility and we don't need the "e.g." for each of these.

https://github.com/llvm/llvm-project/pull/131011