Constant buffers design document

[hekota]

Design document describing how HLSL constant buffers will be handled in Clang. Contains the design for parsing, codegen a lowering of cbuffer declarations, including the default constant buffer $Globals.

Design for the ConstantBuffer<T> resource class is still work in progress.

[s-perron]

I'm trying to understand how the layout rules for SPIR-V will work. The only real problem is cbuffers. There is a problem because cbuffers have a different layout than other buffer types, and I don't know how that will be represented in llvm-ir.

Here is the example I am thinking about: https://godbolt.org/z/f45r7vEoG.

In llvm-ir, will the load from the cbuffer be a single load of an object of type S with the cbuffer layout? Will the store to the structured buffer store an object of type S with the structured buffer layout? If the answer is yes to both, does there need to be a conversion from one to the other in between the load and store?

[hekota]

I have just updated the document. We would like to include the cbuffer layout on the LLVM target type so the backend does not need to know the specific cbuffer layout rules. Alternatively, it could be a type annotation, but we would like to investigate the including in on the target type first. It probably does not answer your question though.

[bogner]

I think that the conversion from one to the other will look like an address space cast, or something like that. We'll need to make sure we aren't mixing raw memory operations between cbuffer memory and other resource memories, but as long as we have each type of thing in its own address space the boundaries themselves should be clear at least.

[s-perron]

@hekota Thanks. That answers part of my question and was in line with what I was thinking. The layout rules are a language feature. This is consistent with what I see in C/C++. The basic types are encoded in the data layout, and then the layout for the structs are set by being explicit with the padding in the struct.

@bogner I'll wait to see what you do. I don't see how the address space cast will work because that works on pointer, but we need to cast after the load. We also want to make sure that whatever we do, it can be easily optimized. In SPIRV there is an OpCopyLogical instruction to do the cast, when it cannot be optimized away.

[tex3d]

I put together a bit of an example that illustrates how cbuffer works in various interesting cases here:
https://godbolt.org/z/E4cdx7xj8

Same shader with FXC:
https://shader-playground.timjones.io/39c0683735c0cd79b5970b5116765940

[hekota]

Thanks Tex! I've created an issue to track this: llvm/llvm-project#118524

[damyanp]

I'd be interested to know why the proposed solution was chosen rather than the type annotation one. What's the downside to using type annotations?

[s-perron]

Is extra metadata requires for the offsets? Can't the layout struct be constructed so that the offsets can be obtained from it? We can add padding elements where needed.

In the SPIR-V backend, we will have to add offset decorations for each member in the constant buffer. I'd like to handle all resource types (ie StructuredBuffers) in the same way. Having a bespoke metadata to get the offsets will create special cases.

[bogner]

I'm not very comfortable with the idea of the layout structure having explicit padding elements - messing with the number of elements is confusing at best. We also do need to have the offsets represented somehow, because if packoffset is used we can't rely on the standard algorithm for cbuffer.

So if we have something like:

cbuffer cb0 {
  int a;
  int b : packoffset(c2.y);
}

We want to encode that element 0 is at offset 0 and element 1 is at offset 36. As you mention elsewhere, in SPIR-V we'll need this later to decorate the members:

OpMemberDecorate %type_cb0 0 Offset 0
OpMemberDecorate %type_cb0 1 Offset 36

I also don't love that we're encoding this separately in metadata and would prefer to include this in the target extension type instead, but most of the obvious schemes to do that have downsides when it comes to clarity and verbosity.

[s-perron]

I'm not very comfortable with the idea of the layout structure having explicit padding elements - messing with the number of elements is confusing at best.

I thought that was a standard llvm-ir solution to problem like that: https://godbolt.org/z/7q9avvdfr.

We also do need to have the offsets represented somehow, because if packoffset is used we can't rely on the standard algorithm for cbuffer.

I don't see why the standard algorithm does not work with appropriate padding: type { i32, [32 x i8], i32}. If we don't want to add the padding, then I agree we need something else.

I'm open to other solutions. The important part to me is that the layout for structured buffers, templated load/store for byte address buffers, and cbuffer be represented the same way. For Vulkan, we have different layout options, and we need to be able to represent all of them.

[bogner]

I suppose we could assume that any array of i8 is padding, but otherwise the problem with type { i32, [32 x i8], i32 } is that the indices get kind of funny. Here we need to know that the third element of the struct (ie, index 2) should be referred to by index 1, as if it's the second element.

[s-perron]

The main disadvantage of adding extra members for padding is that it become impossible to tell if the user added them or the compiler, and they could pollute the DXIL and SPIR-V. Reflection would want to be able to give the offset of each of the original members from the HLSL, but there is no way to filter out the padding from other unused members.

[s-perron]

Note that vulkan has the vk::offset() attribute, which can be used for resource types other than cbuffers. This is why we have issues for all resource types.

[s-perron]

This is not true. The SPIR-V needs to know the offsets to generate valid code. I've mentioned this above.

[s-perron]

What is the signature of this intrinsic? You can see how we generate code at https://godbolt.org/z/eq9E59WcM.

We need to the index of the member to generate the OpAccessChain. If the intrinsic contains the byte offset, then we will have to be able to translate the byte offset to member.

The ideal code pattern for SPIR-V is to access the CBuffers the same way we would access a StructuredBuffer. The only different would be the type for the handle. The index on the resource_getpointer would be the index of the member being accessed.

As I've mentioned in another comment, we would want the method of getting the offset for members of structuredBuffers and cbuffers to be the same.