Root Signatures

Overview

A root signature is used to describe what resources a shader needs access to and how they’re organized and bound in the pipeline. The DirectX Container (DXContainer) contains a root signature part (RTS0), which stores this information in a binary format. To assist with the construction of, and interaction with, a root signature is represented as metadata (dx.rootsignatures ) in the LLVM IR. The metadata can then be converted to its binary form, as defined in llvm/include/llvm/llvm/Frontend/HLSL/RootSignatureMetadata.h. This document serves as a reference for the metadata representation of a root signature for users to interface with.

Metadata Representation

Consider the reference root signature, then the following sections describe the metadata representation of this root signature and the corresponding operands.

RootFlags(ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT),
RootConstants(b0, space = 1, num32Constants = 3),
CBV(b1, flags = 0),
StaticSampler(
  filter = FILTER_MIN_MAG_POINT_MIP_LINEAR,
  addressU = TEXTURE_ADDRESS_BORDER,
),
DescriptorTable(
  visibility = VISIBILITY_ALL,
  SRV(t0, flags = DATA_STATIC_WHILE_SET_AT_EXECUTE),
  UAV(
    numDescriptors = 5, u1, space = 10, offset = 5,
    flags = DATA_VOLATILE
  )
)

Note

A root signature does not necessarily have a unique metadata representation. Futher, a malformed root signature can be represented in the metadata format, (eg. mixing Sampler and non-Sampler descriptor ranges), and so it is the user’s responsibility to verify that it is a well-formed root signature.

Named Root Signature Table

!dx.rootsignatures = !{!0}

A named metadata node, dx.rootsignatures` is used to identify the root signature table. The table itself is a list of references to function/root signature pairs.

Function/Root Signature Pair

!1 = !{ptr @main, !2, i32 2 }

The function/root signature associates a function (the first operand) with a reference to a root signature (the second operand). The root signature version (the third operand) used for validation logic and binary format follows.

Root Signature

!2 = !{ !3, !4, !5, !6, !7 }

The root signature itself simply consists of a list of references to its root signature elements.

Root Signature Element

A root signature element is identified by the first operand, which is a string. The following root signature elements are defined:

Identifier String	Root Signature Element
“RootFlags”	Root Flags
“RootConstants”	Root Constants
“RootCBV”	Root Descriptor
“RootSRV”	Root Descriptor
“RootUAV”	Root Descriptor
“StaticSampler”	Static Sampler
“DescriptorTable”	Descriptor Table

Below is listed the representation for each type of root signature element.

Root Flags

!3 = { !"RootFlags", i32 1 }

Description	Type
Root Signature Flags	i32

Root Constants

!4 = { !"RootConstants", i32 0, i32 1, i32 2, i32 3 }

Description	Type
Shader Visibility	i32
Shader Register	i32
Register Space	i32
Number 32-bit Values	i32

Root Descriptor

As noted in the table above, the first operand will denote the type of root descriptor.

!5 = { !"RootCBV", i32 0, i32 1, i32 0, i32 0 }

Description	Type
Shader Visibility	i32
Shader Register	i32
Register Space	i32
Root Descriptor Flags	i32

Static Sampler

!6 = !{ !"StaticSampler", i32 1, i32 4, ... }; remaining operands omitted for space

Description	Type
Filter	i32
AddressU	i32
AddressV	i32
AddressW	i32
MipLODBias	float
MaxAnisotropy	i32
ComparisonFunc	i32
BorderColor	i32
MinLOD	float
MaxLOD	float
ShaderRegister	i32
RegisterSpace	i32
Shader Visibility	i32

Descriptor Table

A descriptor table consists of a visibility and the remaining operands are a list of references to its descriptor ranges.

Note

The term Descriptor Table Clause is synonymous with Descriptor Range when referencing the implementation details.

!7 = { !"DescriptorTable", i32 0, !8, !9 }

Description	Type
Shader Visibility	i32
Descriptor Range Elements	Descriptor Range

Descriptor Range

Similar to a root descriptor, the first operand will denote the type of descriptor range. It is one of the following types:

• “CBV”

• “SRV”

• “UAV”

• “Sampler”

!8 = !{ !"SRV", i32 1, i32 0, i32 0, i32 -1, i32 4 }
!9 = !{ !"UAV", i32 5, i32 1, i32 10, i32 5, i32 2 }

Description	Type
Number of Descriptors in Range	i32
Shader Register	i32
Register Space	i32
Offset	i32
Descriptor Range Flags	i32