[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;
----------------
bogner wrote:

We're describing a binary format, not C. An enum in C does not necessarily map to 32 bits, so we should really be explicit about the size of the data here. This is a 32-bit value describing the parameter type (from a binary format point of view), not an enum of type RootParameterType.

Also, as above, I think having a description of what the values in a root paramter header are before we bother showing the example C struct would make this easier to follow.

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