[0015] - Mapping Resource Attributes to DXIL and SPIR-V

Introduction

There are a number of objects in HLSL that map to shader model resources. We need to represent these in various ways throughout lowering from the HLSL language to DXIL and SPIR-V program representations suitable for consumption by GPU drivers.

This document tries to summarize the information that’s needed in the various parts of the compiler, survey DXC’s implementation, and ask questions and make recommendations about how we want to handle all of this in clang.

Motivation

There are a number of places where we need to represent resource objects throughout the compiler. From an HLSL language perspective we need to carry sufficient information in the AST to track these types. At the LLVM IR level we need target specific types. Finally, the resulting DXIL and SPIR-V have their own representations.

Proposed solution

We’ll discuss the set of HLSL objects that we need to lower to various types of resources, how they map to DXIL constructs, how DXC represents these in SPIR-V, and finally a set of attributes that’s sufficient to generate the code we need in both DXIL and SPIR-V.

HLSL Objects

The resource objects in HLSL can be divided in a few different ways, but generally the interesting attributes are the layout and dimensionality and whether the objects are writeable.

A few notes:

• Textures and Buffer/RWBuffer have requirements that their elements fit in a scalar or four 4-byte elements, for both historical reasons and because they’re generally mapped to image formats.
• The layouts cbuffer and tbuffer are tied to DXBC’s historical 16-byte row layout rules.
• ByteAddress and Structured buffers aren’t constrained by image format or legacy layout.
• Sampler state is represented by opaque objects that we won’t go into too much detail about here.

DXIL

DXIL represents resources in two different and subtly incompatible ways. All versions of DXIL have metadata resource records, and since shader model 6.6 we also have the resource properties that are bit-packed into the “annotateHandle” DXIL operation. There appears to be have been intent at some point to replace the metadata with the annotation model, but my understanding is that we need to continue to generate both in clang’s DXIL implementation to match DXC.

DXIL Metadata

The DXIL metadata records a resource class, a “shape”, and a few resource class dependent properties:

• The Resource class is SRV (Shader resource view), UAV (Unordered Access View), CBV (Constant buffer view), or Sampler. This is largely only used for determining which register class a resource belongs to, and is mostly valuable in differentiating between (writeable) UAVs and (read-only) SRVs.
• The “shape” is more commonly referred to as “resource kind” outside of the DXIL docs. This covers all of the texture and buffer types, as well as “tbuffer” which maps to the cbuffer layout when the resource class is SRV.
• The resource class dependent properties attempt to cover the variety of possibilities per class but have a few issues. See the footnotes below.

DXIL Binding Annotation

DXIL binding annotations bit-pack information into two integers, as represented by the unions in the DxilResourceProperties class. This format isn’t really documented, and is probably most easily understood by looking at the loadPropsFromResourceBase method, which populates the class’s members.

DirectX Target Extension Types

In LLVM IR we’ll represent all of the DXIL resource types via target extension types, as described in proposal 0006 and the DXILResources docs.

SPIR-V

DXC’s SPIR-V backend treats “Buffer” as a texture and maps DXC textures directly to OpTypeImage. In LLVM IR there is a 1-1 correspondence between the set of SPIR-V target extension types and the resulting OpTypeImage for the simple cases.

Note that dxc generally guesses at the image format for SPIR-V, and there is a vk::image_format attribute in DXC’s HLSL implementation that can be used to choose something in particular. We need to document what we’ll be doing here, considering the many discussions and issues about this over the years in DXC (#4941, #4773, #2498, #3395, #4868, …)

DXC lowers Constant/Texture/Structured/Byte Buffers to OpTypeStruct in SPIR-V with a storage class that depends on the Vulkan version (Uniform or StorageBuffer) and various layout decorations. DXC tracks the necessary information to lower these in side structures, and we’ll likely need to keep track of that information in new SPIR-V target extension types in our implementation.

The “RasterizerOrdered” (or ROV) resources in HLSL don’t map directly to SPIR-V. In DXC, we emulate ROV by treating these the same as their non-ROV counterparts, wrapping accesses to the resource in critical sections using SPV_EXT_fragment_shader_interlock, and then relying on spirv-opt to clean up. We will probably need to extend the SPIR-V target extension types to represent these, and then have the backend do what it needs to do with that information.

Feedback textures aren’t implemented in DXC.

Attributes

From all of this, we’re able to come up with a set of attributes that can represent all of the texture and buffer types. These should carry sufficient information to lower to both of the targets:

Alternatives considered

We could also forgo the large set of specific attributes and boil things down to mostly resource class and resource kind. This is in some ways simpler, but has two main downsides:

1. Not quite everything is represented, so we still need attributes for various numeric values, and some parameters like feedback type.
2. The resource kind ties us fairly tightly to design decisions in DXIL, so may come across as anachronistic as we move to SPIR-V.

For these reasons, I think the broader set of specific attributes is a better approach.