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

[Justin Bogner via llvm-commits]

================
@@ -400,3 +400,151 @@ 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 data defines the shader's resource interface with Direct3D 12, 
+specifying what resources the shader needs to access and how they're organized 
+and bound to the pipeline. 
+
+The RTS0 part comprises three data structures: ``RootSignatureHeader``, 
+``RootParameters`` and ``StaticSamplers``. The details of each will be described 
+in the following sections. All ``RootParameters`` will be serialized following the 
+order they were defined in the metadata representation.
+
+Root Signature Header
+~~~~~~~~~~~~~~~~~~~~~
+
+The root signature header is 24 bytes long, consisting of six 32 bit values 
+representing the version, number and offset of parameters, number and offset 
+of static samplers, and a flags field for global behaviours:
+
+.. code-block:: c
+
+   struct RootSignatureHeader {
+     uint32_t Version;
+     uint32_t NumParameters;
+     uint32_t ParametersOffset;
+     uint32_t NumStaticSamplers;
+     uint32_t StaticSamplerOffset;
+     uint32_t Flags;
+   }
+
+
+Root Parameters
+~~~~~~~~~~~~~~~
+Root parameters define how resources are bound to the shader pipeline, each 
+type having different size and fields. 
+
+Each slot of root parameters is preceded by 12 bytes, three 32 bit values, 
+representing the parameter type, a flag encoding the pipeline stages where 
+the data is visible, and an offset calculated from the start of RTS0 section.
+
+.. code-block:: c
+
+   struct RootParameterHeader {
+     uint32_t ParameterType;
+     uint32_t ShaderVisibility;
+     uint32_t ParameterOffset;
+   };
+
+The following sections will describe each of the root parameters types and their encodings.
+
+Root Constants
+''''''''''''''
+
+Root constants are values passed directly to shaders without needing a constant
+buffer. It is a 12 bytes long structure, two 32 bit values encoding the register 
+and space the constant is assigned to, and one 32 bit value encoding the constant value.
+
+.. code-block:: c
+
+  struct RootConstants {
+    uint32_t Register;
+    uint32_t Space;
+    uint32_t Value;
+  };
+
+Root Descriptor
+'''''''''''''''
+
+Root descriptors provide direct GPU memory addresses to resources. Version 1.1 of 
+root descriptor is a 12 byte long, the first two 32 bit values encode the register 
+and space being assigned to the descriptor, and the last 32 bit value is an access flag flag. 
+
+Version 1.0 doesn't contain the flags available in version 1.1.
+
+.. code-block:: c
+
+   struct RootDescriptor_V1_0 {
+      uint32_t ShaderRegister;
+      uint32_t RegisterSpace;
+   };
+   
+   struct RootDescriptor_V1_1 {
+      uint32_t ShaderRegister;
+      uint32_t RegisterSpace;      
+      uint32_t Flags;
+   };
+
+Root Descriptor Table
+'''''''''''''''''''''
+Descriptor tables let shaders access multiple resources through a single pointer to a descriptor heap. 
+
+The tables are made of a collection of descriptor ranges. Version 1.1 ranges are 24 bytes long, containing 
+five 32 bit values: The type of register, the number of registers in the range, the starting register number, 
+the register space, an offset in number of descriptors from the start of the table and finally an access flag. 
+
+Version 1.0 ranges are the 20 bytes long, following the same structure without the flags. 
+
+.. code-block:: c
+
+   struct DescriptorRange_V1_0 {
+      uint_32t RangeType;
+      uint32_t NumDescriptors;
+      uint32_t BaseShaderRegister;
+      uint32_t RegisterSpace;
+      uint32_t OffsetInDescriptorsFromTableStart;
+   };
+
+   struct DescriptorRange_V1_1 {
+      dxbc::DescriptorRangeType RangeType;
+      uint32_t NumDescriptors;
+      uint32_t BaseShaderRegister;
+      uint32_t RegisterSpace;
+      uint32_t OffsetInDescriptorsFromTableStart;      
+      // Bitfield of flags from the Flags enum
+      uint32_t Flags;
+   };
+
+Static Samplers
+~~~~~~~~~~~~~~~
+
+Static samplers are predefined filtering settings built into the root signature, avoiding descriptor heap lookups. 
+
+This section also has a variable size. The size is 68 bytes long, containing the following fields: 32 bits for a 
+filter mode, three 32 bit fields for texture address mode, 64 bits for the bias value of minmap level calculation, 
+32 bits for maximum anisotropy level, 32 bits for the comparison function type, 32 bits for the static border colour, 
+two 64 bit fields for the min and max level of detail, two 32 bit fields for the register number and space and finally 
+32 bits for the shader visibility flag.
----------------
bogner wrote:

This doesn't look quite right:

1. You say the section has a variable size, but then describe a fixed layout. Which is it?
2. The description doesn't match the code block - MipLODBias, MinLOD, and MaxLOD are all floats below but listed as 64 bit fields here.

I also think describing each field in a paragraph like this gets a bit muddled. It might be better to simply say that the structure consists of 13 32-byte fields (as it appears to, assuming the 64-bit mentions in the text above are mistakes) of various enum, float, and integer values and let the names of the fields in the code block speak for themselves.

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