From 18cfed2080d9f31495afd6a71f6534e12f53a621 Mon Sep 17 00:00:00 2001 From: Helena Kotas Date: Tue, 5 Nov 2024 11:00:55 -0800 Subject: [PATCH 1/7] Initial commit --- proposals/NNNN-constant-buffers.md | 102 +++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 proposals/NNNN-constant-buffers.md diff --git a/proposals/NNNN-constant-buffers.md b/proposals/NNNN-constant-buffers.md new file mode 100644 index 0000000..5970e5e --- /dev/null +++ b/proposals/NNNN-constant-buffers.md @@ -0,0 +1,102 @@ + +# Constant buffers + +* Proposal: [NNNN](NNNN-constant-buffers.md) +* Author(s): [Helena Kotas](https://github.com/hekota) +* Status: **Design In Progress** + +## Introduction + +Shader inputs usually include a number of constants which are stored in one or more buffer resources in memory with specific packing rules. These resources can be organized into two types of buffers: constant buffers and texture buffers. + +From the compiler point of view constant buffers and texture buffers are very similar. The major difference is that constant buffers load from a constant buffer view (CBV) and bind to register `b` while texture buffers load from a typed buffer (SRV) and bind to the `t` register. + +Declaring a constant buffer or a texture buffer looks very much like a structure declaration in C, with the addition of the register and packoffset keywords for manually assigning registers or packing data. + +``` +[cbuffer|tbuffer] ConstBufferName [register(b#)|register(t#)] { + VariableDeclaration [ : packoffset() ]; + ... +} +``` + +Constant buffer variables can be accessed anywhere from a shader using the variable name without referencing the constant buffer name. + +Another way of declaring buffers with constants is via `ConstantBuffer` or `TextureBuffer` resource classes. This document currently focuses on the first style of declaration and primarily on `cbuffer`. + + +## Motivation + +We need to support constant buffers in Clang as they are a fundamental part of the HLSL language. + +## Proposed solution + +### Parsing cbuffer declaration + +In Clang frontend the `cbuffer` declarations will be parsed into a new AST Node called `HLSLConstantBufferDecl`. This class will be based on from `NameDecl` and `DeclContext`. + +Variable declarations inside the `cbuffer` context will be children of this new AST node. If a variable declaration specifies a `packoffset`, this information will be parsed into an attribute `HLSLPackOffsetAttr` and applied to the variable declaration. See [packoffset attribute](0003-packoffset.md). + +In order to make the variables declared in constant buffer exposed into global scope we can take advantage of `DeclContext::isTransparentContext` and make sure it is true for `HLSLConstantBufferDecl`. + +Because the syntax similarities the`tbuffer` declaration will also be using `HLSLConstantBufferDecl` AST node. The method `isCBuffer()` can be used to determine which kind of constant buffer the declaration represents. + +*Note: This is already implemented in Clang as `HLSLBufferDecl`. Since constant buffers are not the only buffers in HLSL we should rename it to `HLSLConstantBufferDecl`.* + +*Q: Does resource handle with typed attributes come into play here at all?* + +### Lowering cbuffer to LLVM + +Constant buffers will be lowered to LLVM target type `target(dx.CBuffer, ..)`. The LLVM target types can include a list of types and a list of integer constants. Any information needed for lowering to DXIL or SPIRV needs to be encoded using these parameters. + +To encode the shape of the `cbuffer` we can use the type parameter of the LLVM target type to be a struct with all of the `cbuffer` variable declarations. + +To encode the `packoffset` information we can use the list of integer constant on the target type. If there is no `packoffset` specified, the list would be empty. If the `cbuffer` variables have a `packoffset`, then the target type would contain a list of constant integers where `n`-th constant would either be a non-negative number specifying the packoffset of the `n`-th variable. + +**Note: `packoffset` offset must either be specified of all `cbuffer` variable declarations or on none.* + +For example: + +```c++ +cbuffer MyConstants { + float2 a : packoffset(c0.x); + int2 b : packoffset(c1.z); +} +``` + +Would be lowered to LLVM target type: + +``` +target("dx.CBuffer", %struct.MyConstants = type { <2 x float>, <2 x i32> }, 0, 6) +``` + +### Lowering cbuffer variable access + +Access to `cbuffer` variables would be lowered to LLVM in the same way and other resource types handle read-only subscript operator. The constant value access would be translated into a memory access in a specific "resource address space". This would be a simple "resource pointer arithmetic". + +Later, during lowering to DXIL, an LLVM pass would translate these specific "resource address space" memory accesses into `cbufferLoadLegacy` DXIL ops. This pass would take into account specific constant buffer layout rules and `packoffset` data, which are specific to DirectX. + +### Handle initialization + +Constant buffers will be initialized the same way as other resources using the `createHandleFromBinding` intrinsics. Module initialization will need to be updated to initialize all the constant buffers declared in a shader in addition to initialization of resource declared in global variables. + +## Detailed design + +*TBD* + +## Alternatives considered (Optional) + +Should we handle the constant buffer layout and `packoffset` info earlier? + +## Links + +[Shader Constants](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-constants)
+[HLSL Constant Buffer Layout Visualizer](https://maraneshi.github.io/HLSL-ConstantBufferLayoutVisualizer)
+[packoffset attribute](0003-packoffset.md) + +## Acknowledgments (Optional) + +Take a moment to acknowledge the contributions of people other than the author +and sponsor. + + From f5a3fc80bcfa3b1bd028760ebe27f3f8485acc38 Mon Sep 17 00:00:00 2001 From: Helena Kotas Date: Wed, 6 Nov 2024 12:22:20 -0800 Subject: [PATCH 2/7] use offsets always --- proposals/NNNN-constant-buffers.md | 35 ++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/proposals/NNNN-constant-buffers.md b/proposals/NNNN-constant-buffers.md index 5970e5e..57ce5b1 100644 --- a/proposals/NNNN-constant-buffers.md +++ b/proposals/NNNN-constant-buffers.md @@ -47,11 +47,9 @@ Because the syntax similarities the`tbuffer` declaration will also be using `HLS ### Lowering cbuffer to LLVM -Constant buffers will be lowered to LLVM target type `target(dx.CBuffer, ..)`. The LLVM target types can include a list of types and a list of integer constants. Any information needed for lowering to DXIL or SPIRV needs to be encoded using these parameters. +Constant buffers will be lowered to global variables with LLVM target type `target("dx.CBuffer", ..)`. In addition to the type name (`"dx.CBuffer"`) LLVM target types can also include a list of types and a list of integer constants. Any information needed for lowering to DXIL or SPIRV needs to be encoded using these parameters. -To encode the shape of the `cbuffer` we can use the type parameter of the LLVM target type to be a struct with all of the `cbuffer` variable declarations. - -To encode the `packoffset` information we can use the list of integer constant on the target type. If there is no `packoffset` specified, the list would be empty. If the `cbuffer` variables have a `packoffset`, then the target type would contain a list of constant integers where `n`-th constant would either be a non-negative number specifying the packoffset of the `n`-th variable. +To encode the shape of the `cbuffer` we can set the type parameter of the LLVM target type to be a struct with all of the `cbuffer` variable declarations. The list of integer constant can be used to encode the `cbuffer` memory layout where the number of constants in the list would be equal to the number of `cbuffer` variable declarations and `n`-th constant would contain the offset `n`-th variable in bytes. **Note: `packoffset` offset must either be specified of all `cbuffer` variable declarations or on none.* @@ -59,15 +57,31 @@ For example: ```c++ cbuffer MyConstants { - float2 a : packoffset(c0.x); - int2 b : packoffset(c1.z); + float2 a; + float b[2]; + int c; } ``` Would be lowered to LLVM target type: ``` -target("dx.CBuffer", %struct.MyConstants = type { <2 x float>, <2 x i32> }, 0, 6) +target("dx.CBuffer", %struct.MyConstants = type { <2 x float>, [2 x float], int }, 0, 16, 36) +``` + +In this example with `packoffset`: + +```c++ +cbuffer MyConstants { + float2 a : packoffset(c0.y); + int2 b : packoffset(c1.z); +} +``` + +The `cbuffer` type would be lowered to: + +``` +target("dx.CBuffer", %struct.MyConstants = type { <2 x float>, <2 x i32> }, 4, 24) ``` ### Lowering cbuffer variable access @@ -91,12 +105,9 @@ Should we handle the constant buffer layout and `packoffset` info earlier? ## Links [Shader Constants](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-constants)
+[Packing Rules for Constant Variables](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-packing-rules)
[HLSL Constant Buffer Layout Visualizer](https://maraneshi.github.io/HLSL-ConstantBufferLayoutVisualizer)
-[packoffset attribute](0003-packoffset.md) +[`packoffset` Attribute](0003-packoffset.md) ## Acknowledgments (Optional) -Take a moment to acknowledge the contributions of people other than the author -and sponsor. - - From 18114914b41a335dc641ebd2292213a7c0091ab2 Mon Sep 17 00:00:00 2001 From: Helena Kotas Date: Wed, 6 Nov 2024 15:24:53 -0800 Subject: [PATCH 3/7] do not encode offsets in target type --- proposals/NNNN-constant-buffers.md | 31 ++++++++---------------------- 1 file changed, 8 insertions(+), 23 deletions(-) diff --git a/proposals/NNNN-constant-buffers.md b/proposals/NNNN-constant-buffers.md index 57ce5b1..dd4f6da 100644 --- a/proposals/NNNN-constant-buffers.md +++ b/proposals/NNNN-constant-buffers.md @@ -47,11 +47,7 @@ Because the syntax similarities the`tbuffer` declaration will also be using `HLS ### Lowering cbuffer to LLVM -Constant buffers will be lowered to global variables with LLVM target type `target("dx.CBuffer", ..)`. In addition to the type name (`"dx.CBuffer"`) LLVM target types can also include a list of types and a list of integer constants. Any information needed for lowering to DXIL or SPIRV needs to be encoded using these parameters. - -To encode the shape of the `cbuffer` we can set the type parameter of the LLVM target type to be a struct with all of the `cbuffer` variable declarations. The list of integer constant can be used to encode the `cbuffer` memory layout where the number of constants in the list would be equal to the number of `cbuffer` variable declarations and `n`-th constant would contain the offset `n`-th variable in bytes. - -**Note: `packoffset` offset must either be specified of all `cbuffer` variable declarations or on none.* +Constant buffers will be lowered to global variables with LLVM target type `target("dx.CBuffer", ..)`. In addition to the type name (`"dx.CBuffer"`) LLVM target types can also include a list of types and a list of integer constants. Any information needed for lowering to DXIL or SPIRV needs to be encoded using these parameters. To encode the shape of the `cbuffer` we can set the type parameter of the LLVM target type to be a struct with all of the `cbuffer` variable declarations. For example: @@ -66,29 +62,18 @@ cbuffer MyConstants { Would be lowered to LLVM target type: ``` -target("dx.CBuffer", %struct.MyConstants = type { <2 x float>, [2 x float], int }, 0, 16, 36) -``` - -In this example with `packoffset`: - -```c++ -cbuffer MyConstants { - float2 a : packoffset(c0.y); - int2 b : packoffset(c1.z); -} +@MyConstants.cb = global target("dx.CBuffer", %struct.MyConstants = type { <2 x float>, [2 x float], int }) ``` -The `cbuffer` type would be lowered to: +### Lowering cbuffer variable access -``` -target("dx.CBuffer", %struct.MyConstants = type { <2 x float>, <2 x i32> }, 4, 24) -``` +The layout of constant buffers will be calculated during codegen in `CGHLSLRuntime`, which will also take into account `packoffset` attributes. -### Lowering cbuffer variable access +Access to `cbuffer` variables will be lowered to LLVM IR the same way as other resource types lower read-only access via subscript operator, except it will use the calculated layout offset. The constant value access would be translated into a memory access in a specific "resource address space" using the `cbuffer` global variable and offset. -Access to `cbuffer` variables would be lowered to LLVM in the same way and other resource types handle read-only subscript operator. The constant value access would be translated into a memory access in a specific "resource address space". This would be a simple "resource pointer arithmetic". +### DXIL Lowering -Later, during lowering to DXIL, an LLVM pass would translate these specific "resource address space" memory accesses into `cbufferLoadLegacy` DXIL ops. This pass would take into account specific constant buffer layout rules and `packoffset` data, which are specific to DirectX. +Later, during lowering to DXIL, an LLVM pass would translate these specific "resource address space" memory accesses into `cbufferLoadLegacy` DXIL ops. This pass would take into account specific constant buffer layout rules (loading data one row at a time and extracing specific elements). ### Handle initialization @@ -100,7 +85,7 @@ Constant buffers will be initialized the same way as other resources using the ` ## Alternatives considered (Optional) -Should we handle the constant buffer layout and `packoffset` info earlier? +Should we handle the constant buffer layout and `packoffset` later? Should we encode it int into the CBuffer LLVM target type? ## Links From 41329425d88bacd0362f562668297cbd2d67e854 Mon Sep 17 00:00:00 2001 From: Helena Kotas Date: Thu, 7 Nov 2024 11:01:03 -0800 Subject: [PATCH 4/7] add ConstantBuffers --- proposals/NNNN-constant-buffers.md | 54 ++++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 14 deletions(-) diff --git a/proposals/NNNN-constant-buffers.md b/proposals/NNNN-constant-buffers.md index dd4f6da..e1a47cd 100644 --- a/proposals/NNNN-constant-buffers.md +++ b/proposals/NNNN-constant-buffers.md @@ -11,19 +11,27 @@ Shader inputs usually include a number of constants which are stored in one or m From the compiler point of view constant buffers and texture buffers are very similar. The major difference is that constant buffers load from a constant buffer view (CBV) and bind to register `b` while texture buffers load from a typed buffer (SRV) and bind to the `t` register. -Declaring a constant buffer or a texture buffer looks very much like a structure declaration in C, with the addition of the register and packoffset keywords for manually assigning registers or packing data. +Declaring a constant buffer or a texture buffer looks very much like a structure declaration in C, with the addition of the register and packoffset keywords for manually assigning registers or packing data. For example: -``` -[cbuffer|tbuffer] ConstBufferName [register(b#)|register(t#)] { - VariableDeclaration [ : packoffset() ]; - ... +```c++ +cbuffer MyConstant register(b1) { + float4 F; } ``` -Constant buffer variables can be accessed anywhere from a shader using the variable name without referencing the constant buffer name. +Constant buffer variables can be accessed anywhere from a shader using the variable name `F` without referencing the constant buffer name . -Another way of declaring buffers with constants is via `ConstantBuffer` or `TextureBuffer` resource classes. This document currently focuses on the first style of declaration and primarily on `cbuffer`. +Another way of declaring buffers with constants is via `ConstantBuffer` or `TextureBuffer` resource classes: +```c++ +struct MyConstants { + float4 F; +}; + +ConstantBuffer CB; +``` + +In this case the buffer variables are reference as if they were members of the `ConstantBuffer` class: `CB.F`. ## Motivation @@ -31,11 +39,11 @@ We need to support constant buffers in Clang as they are a fundamental part of t ## Proposed solution -### Parsing cbuffer declaration +### Parsing cbuffer/tbuffer declaration -In Clang frontend the `cbuffer` declarations will be parsed into a new AST Node called `HLSLConstantBufferDecl`. This class will be based on from `NameDecl` and `DeclContext`. +In Clang frontend the `cbuffer` and `tbuffer` declarations will be parsed into a new AST Node called `HLSLConstantBufferDecl`. This class will be based on from `NameDecl` and `DeclContext`. -Variable declarations inside the `cbuffer` context will be children of this new AST node. If a variable declaration specifies a `packoffset`, this information will be parsed into an attribute `HLSLPackOffsetAttr` and applied to the variable declaration. See [packoffset attribute](0003-packoffset.md). +Variable declarations inside the `cbuffer` or `tbuffer` context will be children of this new AST node. If a variable declaration specifies a `packoffset`, this information will be parsed into an attribute `HLSLPackOffsetAttr` and applied to the variable declaration. See [packoffset attribute](0003-packoffset.md). In order to make the variables declared in constant buffer exposed into global scope we can take advantage of `DeclContext::isTransparentContext` and make sure it is true for `HLSLConstantBufferDecl`. @@ -45,9 +53,15 @@ Because the syntax similarities the`tbuffer` declaration will also be using `HLS *Q: Does resource handle with typed attributes come into play here at all?* -### Lowering cbuffer to LLVM +### Parsing ConstantBuffer/TextureBuffer declaration + +`ConstantBuffer`/`TextureBuffer` will be added to the `HLSLExternalSemaSource` the same way other resource buffers are added. At the same time Clang needs to recognize these classes represents constant buffers. + +One way to do that is to create `HLSLConstantBufferDecl` instance in addition to the `ConstantBuffer`, basically treating `ConstantBuffer CB;` as `cbuffer CB { MyConstants CB; }`. The constant buffer declaration would need to keep track that is it based on `ConstantBuffer` declaration. -Constant buffers will be lowered to global variables with LLVM target type `target("dx.CBuffer", ..)`. In addition to the type name (`"dx.CBuffer"`) LLVM target types can also include a list of types and a list of integer constants. Any information needed for lowering to DXIL or SPIRV needs to be encoded using these parameters. To encode the shape of the `cbuffer` we can set the type parameter of the LLVM target type to be a struct with all of the `cbuffer` variable declarations. +### Lowering cbuffer to LLVM IR + +Constant buffers will be lowered to global variables with LLVM target type `target("dx.CBuffer", ..)`. In addition to the type name (`"dx.CBuffer"`) LLVM target types can also include a list of types and a list of integer constants. Any information needed for lowering to DXIL or SPIRV needs to be encoded using these parameters. To encode the shape of the constant buffers we can set the type parameter of the LLVM target type to be a struct with all of the buffer variable declarations. For example: @@ -65,7 +79,15 @@ Would be lowered to LLVM target type: @MyConstants.cb = global target("dx.CBuffer", %struct.MyConstants = type { <2 x float>, [2 x float], int }) ``` -### Lowering cbuffer variable access +### Lowering ConstantBuffer to LLVM IR + +The result of codegen for `cbuffer` and `ConstantBuffer` should be identical, or at least very close. + +### Lowering `tbuffer` and `TextureBuffer` to LLVM IR + +These should be lowered to `target("dx.TypedBuffer", ..)`.Detailed design TBD. + +### Lowering constant buffer variable access The layout of constant buffers will be calculated during codegen in `CGHLSLRuntime`, which will also take into account `packoffset` attributes. @@ -77,7 +99,11 @@ Later, during lowering to DXIL, an LLVM pass would translate these specific "res ### Handle initialization -Constant buffers will be initialized the same way as other resources using the `createHandleFromBinding` intrinsics. Module initialization will need to be updated to initialize all the constant buffers declared in a shader in addition to initialization of resource declared in global variables. +Constant buffers will be initialized the same way as other resources using the `createHandleFromBinding` intrinsics. Module initialization will need to be updated to initialize all the constant buffers declared in a shader in addition to initialization of resources declared in global variables. + +### Constant buffers metadata + +TBD ## Detailed design From 2d1b1f55ecbc5435b343e24ec9058164e6cadf02 Mon Sep 17 00:00:00 2001 From: Helena Kotas Date: Tue, 26 Nov 2024 14:51:16 -0800 Subject: [PATCH 5/7] Update doc after design meeting discussion; still many open questions --- proposals/NNNN-constant-buffers.md | 86 ++++++++++++++++-------------- 1 file changed, 47 insertions(+), 39 deletions(-) diff --git a/proposals/NNNN-constant-buffers.md b/proposals/NNNN-constant-buffers.md index e1a47cd..44ed2f3 100644 --- a/proposals/NNNN-constant-buffers.md +++ b/proposals/NNNN-constant-buffers.md @@ -7,21 +7,19 @@ ## Introduction -Shader inputs usually include a number of constants which are stored in one or more buffer resources in memory with specific packing rules. These resources can be organized into two types of buffers: constant buffers and texture buffers. +Shader inputs usually include a number of constants which are stored in one or more buffer resources in memory with specific packing rules. These resources can be organized into two types of buffers: constant buffers and texture buffers. This document describes design decisions related to constant buffers. -From the compiler point of view constant buffers and texture buffers are very similar. The major difference is that constant buffers load from a constant buffer view (CBV) and bind to register `b` while texture buffers load from a typed buffer (SRV) and bind to the `t` register. - -Declaring a constant buffer or a texture buffer looks very much like a structure declaration in C, with the addition of the register and packoffset keywords for manually assigning registers or packing data. For example: +Constant buffer loads from a constant buffer view (CBV) and binds to register `b`. It can be declared using the `cbuffer` keyword and it looks very much like a structure declaration in C, with the addition of the register and packoffset keywords for manually assigning registers or packing data. For example: ```c++ -cbuffer MyConstant register(b1) { +cbuffer MyConstant : register(b1) { float4 F; } ``` -Constant buffer variables can be accessed anywhere from a shader using the variable name `F` without referencing the constant buffer name . +Constant buffer variables declared within the `cbuffer` scope can be accessed anywhere from a shader by directly using the variable name (`F`) without referencing the name of the constant buffer. -Another way of declaring buffers with constants is via `ConstantBuffer` or `TextureBuffer` resource classes: +Another way of declaring constant buffers is with via `ConstantBuffer` class: ```c++ struct MyConstants { @@ -31,39 +29,41 @@ struct MyConstants { ConstantBuffer CB; ``` -In this case the buffer variables are reference as if they were members of the `ConstantBuffer` class: `CB.F`. +In this case the buffer variables are referenced as if they were members of the `ConstantBuffer` class: `CB.F`. ## Motivation We need to support constant buffers in Clang as they are a fundamental part of the HLSL language. -## Proposed solution - -### Parsing cbuffer/tbuffer declaration +## Proposed Solution -In Clang frontend the `cbuffer` and `tbuffer` declarations will be parsed into a new AST Node called `HLSLConstantBufferDecl`. This class will be based on from `NameDecl` and `DeclContext`. +### Parsing `cbuffer` Declaration -Variable declarations inside the `cbuffer` or `tbuffer` context will be children of this new AST node. If a variable declaration specifies a `packoffset`, this information will be parsed into an attribute `HLSLPackOffsetAttr` and applied to the variable declaration. See [packoffset attribute](0003-packoffset.md). +In Clang frontend the `cbuffer` declaration will be parsed into a new AST Node called `HLSLConstantBufferDecl`. This class will be based on from `NameDecl` and `DeclContext`. -In order to make the variables declared in constant buffer exposed into global scope we can take advantage of `DeclContext::isTransparentContext` and make sure it is true for `HLSLConstantBufferDecl`. +Variable declarations inside the `cbuffer` context will be children of this new AST node. If a variable declaration specifies a `packoffset`, this information will be parsed into an attribute `HLSLPackOffsetAttr` and applied to the variable declaration. See [packoffset attribute](0003-packoffset.md). -Because the syntax similarities the`tbuffer` declaration will also be using `HLSLConstantBufferDecl` AST node. The method `isCBuffer()` can be used to determine which kind of constant buffer the declaration represents. +In order to make the variables declared in constant buffer exposed into global scope we can take advantage of `DeclContext::isTransparentContext` method and overload it to return true for `HLSLConstantBufferDecl`. This is the same way variables declared in `export` declaration context are exposed at the global scope. *Note: This is already implemented in Clang as `HLSLBufferDecl`. Since constant buffers are not the only buffers in HLSL we should rename it to `HLSLConstantBufferDecl`.* -*Q: Does resource handle with typed attributes come into play here at all?* +### Parsing `ConstantBuffer` declaration + +`ConstantBuffer` definition will be added to the `HLSLExternalSemaSource` the same way as other resource classes. It will have a resource handle with `CBuffer` resource class and the contained type would be the template type argument. It will be handled as other resources classes, for example it can be passed into a function. -### Parsing ConstantBuffer/TextureBuffer declaration +At the same time Clang needs to recognize this class represents a constant buffer and the contained type fields are accessed using the `.` operator on `ConstantBuffer` instance. In other words treating `ConstantBuffer CB;` as if it was declared as `cbuffer __CB { MyConstants CB; }`. The exact way how to do this is TBD. -`ConstantBuffer`/`TextureBuffer` will be added to the `HLSLExternalSemaSource` the same way other resource buffers are added. At the same time Clang needs to recognize these classes represents constant buffers. +### Lowering Constant Buffers to LLVM IR -One way to do that is to create `HLSLConstantBufferDecl` instance in addition to the `ConstantBuffer`, basically treating `ConstantBuffer CB;` as `cbuffer CB { MyConstants CB; }`. The constant buffer declaration would need to keep track that is it based on `ConstantBuffer` declaration. +During CodeGen constant buffers will be lowered to global variables with LLVM target type `target("dx.CBuffer", ..)` which will include type information about constants, the buffer size and its memory layout. -### Lowering cbuffer to LLVM IR +Note: LLVM target types can optionally include a list of one or more types and a list of one or more integer constants. We can use these lists to encode any information needed for lowering from LLVM IR to DXIL and SPIRV. -Constant buffers will be lowered to global variables with LLVM target type `target("dx.CBuffer", ..)`. In addition to the type name (`"dx.CBuffer"`) LLVM target types can also include a list of types and a list of integer constants. Any information needed for lowering to DXIL or SPIRV needs to be encoded using these parameters. To encode the shape of the constant buffers we can set the type parameter of the LLVM target type to be a struct with all of the buffer variable declarations. +To encode the shape of the constant buffer the LLVM target type will include a structure type that represents the constant buffer variable declarations. -For example: +The size of the constant buffer will be included as the first item in the list of integer constants. The rest of the list will be used to encode the constant buffer layout. The layout will always be included whether the constant buffer uses any `packoffset` attributes or not. The exact way how the layout will be encoded is TBD and will be covered in a separate design document. + +For simplicity, let's assume the layout will be encoded as a list of offsets of all cbuffer declarations. In that case this example: ```c++ cbuffer MyConstants { @@ -76,49 +76,57 @@ cbuffer MyConstants { Would be lowered to LLVM target type: ``` -@MyConstants.cb = global target("dx.CBuffer", %struct.MyConstants = type { <2 x float>, [2 x float], int }) +@MyConstants.cb = global target("dx.CBuffer", { <2 x float>, [2 x float], i32}, 40, 0, 16, 32, 36) ``` -### Lowering ConstantBuffer to LLVM IR +This layout encoding can obviously get very long and unwieldy for more complicated cbuffers, and especially since target type parameters are all included in the name mangling for function overloads. We need to investigate how to make it smaller, or at least more manageable. -The result of codegen for `cbuffer` and `ConstantBuffer` should be identical, or at least very close. +One possibility is compressing the list of offsets into a smaller number of integers - taking advantage of the fact that outside of `packoffset` use the difference between two adjancent offsets is never more than 16. The compression could also include repetition construct that would help with encoding of array offset. But, as with any compressions, there's always the chance of degenerate cases that will end up with the compressed shape being the same size or larger than the original. -### Lowering `tbuffer` and `TextureBuffer` to LLVM IR +> Note: The most tricky part of the layout encoding are probably arrays of structures because the structure-specific layout gets repeated many times and might not be easy to compress. One idea how to solve this could be translating structures embedded in `cbuffer` into separate target types with their own encoded layout and including them in the `cbuffer` target type. It is not clear though if this is possible (probably yes) or if it would actually make things easier or not. -These should be lowered to `target("dx.TypedBuffer", ..)`.Detailed design TBD. +Another way could be introducing a typedef concept into the LLVM IR textual representation so that the full LLVM target type with long layout representation could occur just once. -### Lowering constant buffer variable access +### Lowering ConstantBuffer to LLVM IR -The layout of constant buffers will be calculated during codegen in `CGHLSLRuntime`, which will also take into account `packoffset` attributes. +The result of codegen for `cbuffer` and `ConstantBuffer` code should be identical. -Access to `cbuffer` variables will be lowered to LLVM IR the same way as other resource types lower read-only access via subscript operator, except it will use the calculated layout offset. The constant value access would be translated into a memory access in a specific "resource address space" using the `cbuffer` global variable and offset. +### Lowering Constant Buffer Variable Access + +Accesses to `cbuffer` variables will be lowered to LLVM IR as memory accesses in specific "resource address space" using the standard C++ structure layout rules. ### DXIL Lowering -Later, during lowering to DXIL, an LLVM pass would translate these specific "resource address space" memory accesses into `cbufferLoadLegacy` DXIL ops. This pass would take into account specific constant buffer layout rules (loading data one row at a time and extracing specific elements). +LLVM pass `DXILResourceAccess` will translate these specific "resource address space" memory accesses into cbuffer DXIL ops adjusting the offsets using the cbuffer layout information encoded in `target("dx.CBuffer", ..)`. That means translating standand C++ structure layout offsets to cbuffer layout offsets and replacing the memory accesses with `llvm.dx.cbufferBufferLoad`, `llvm.dx.cbufferBufferStore`, and `extractelement ` instructions. The load and store instructions will be later lowered to `cbufferLoadLegacy` and `cbufferStoreLegacy` DXIL ops. ### Handle initialization -Constant buffers will be initialized the same way as other resources using the `createHandleFromBinding` intrinsics. Module initialization will need to be updated to initialize all the constant buffers declared in a shader in addition to initialization of resources declared in global variables. - -### Constant buffers metadata - -TBD +Constant buffers will be initialized the same way as other resources using the `createHandleFromBinding` intrinsics. Module initialization code need to be updated to include all constant buffers declared in a shader. ## Detailed design *TBD* -## Alternatives considered (Optional) +## Alternatives considered + +- Generate access to `cbuffer` varibles as memory accesses with the offset based on cbuffer layout and treat cbuffers as one big type-less memory blob in LLVM IR. + - There is a concern that losing the type information could lead to unnecessary copying of values. + +- Using type annotations to store cbuffer layout information. Subtypes would have its own layout annotations. + - This is something we can fall back to if encoding the cbuffer layout on LLVM target type turns out to be too unwieldy, especially when it comes to encoding the layout of an array of structures. -Should we handle the constant buffer layout and `packoffset` later? Should we encode it int into the CBuffer LLVM target type? +## Open issues +- How to encode the cbuffer layout into LLVM target type +- How to implement `ConstantBuffer` member access +- Handling of `$Globals` constant buffer +- Nested `cbuffer` declarations ## Links [Shader Constants](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-constants)
[Packing Rules for Constant Variables](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-packing-rules)
[HLSL Constant Buffer Layout Visualizer](https://maraneshi.github.io/HLSL-ConstantBufferLayoutVisualizer)
-[`packoffset` Attribute](0003-packoffset.md) +[`packoffset` Attribute](0003-packoffset.md)
## Acknowledgments (Optional) From 61a0ec6d6cd14a28cf6ce78cbc9cb8f0be3e0d49 Mon Sep 17 00:00:00 2001 From: Helena Kotas Date: Tue, 26 Nov 2024 15:54:55 -0800 Subject: [PATCH 6/7] wrap to 80 --- proposals/NNNN-constant-buffers.md | 144 ++++++++++++++++++++++------- 1 file changed, 110 insertions(+), 34 deletions(-) diff --git a/proposals/NNNN-constant-buffers.md b/proposals/NNNN-constant-buffers.md index 44ed2f3..e0711d3 100644 --- a/proposals/NNNN-constant-buffers.md +++ b/proposals/NNNN-constant-buffers.md @@ -7,9 +7,15 @@ ## Introduction -Shader inputs usually include a number of constants which are stored in one or more buffer resources in memory with specific packing rules. These resources can be organized into two types of buffers: constant buffers and texture buffers. This document describes design decisions related to constant buffers. +Shader inputs usually include a number of constants which are stored in one or +more buffer resources in memory with specific packing rules. These resources can +be organized into two types of buffers: constant buffers and texture buffers. +This document describes design decisions related to constant buffers. -Constant buffer loads from a constant buffer view (CBV) and binds to register `b`. It can be declared using the `cbuffer` keyword and it looks very much like a structure declaration in C, with the addition of the register and packoffset keywords for manually assigning registers or packing data. For example: +Constant buffer loads from a constant buffer view (CBV) and binds to register +`b`. It can be declared using the `cbuffer` keyword and it looks very much like +a structure declaration in C, with the addition of the register and packoffset +keywords for manually assigning registers or packing data. For example: ```c++ cbuffer MyConstant : register(b1) { @@ -17,7 +23,9 @@ cbuffer MyConstant : register(b1) { } ``` -Constant buffer variables declared within the `cbuffer` scope can be accessed anywhere from a shader by directly using the variable name (`F`) without referencing the name of the constant buffer. +Constant buffer variables declared within the `cbuffer` scope can be accessed +anywhere from a shader by directly using the variable name (`F`) without +referencing the name of the constant buffer. Another way of declaring constant buffers is with via `ConstantBuffer` class: @@ -29,41 +37,72 @@ struct MyConstants { ConstantBuffer CB; ``` -In this case the buffer variables are referenced as if they were members of the `ConstantBuffer` class: `CB.F`. +In this case the buffer variables are referenced as if they were members of the +`ConstantBuffer` class: `CB.F`. ## Motivation -We need to support constant buffers in Clang as they are a fundamental part of the HLSL language. +We need to support constant buffers in Clang as they are a fundamental part of +the HLSL language. ## Proposed Solution ### Parsing `cbuffer` Declaration -In Clang frontend the `cbuffer` declaration will be parsed into a new AST Node called `HLSLConstantBufferDecl`. This class will be based on from `NameDecl` and `DeclContext`. +In Clang frontend the `cbuffer` declaration will be parsed into a new AST Node +called `HLSLConstantBufferDecl`. This class will be based on from `NameDecl` and +`DeclContext`. -Variable declarations inside the `cbuffer` context will be children of this new AST node. If a variable declaration specifies a `packoffset`, this information will be parsed into an attribute `HLSLPackOffsetAttr` and applied to the variable declaration. See [packoffset attribute](0003-packoffset.md). +Variable declarations inside the `cbuffer` context will be children of this new +AST node. If a variable declaration specifies a `packoffset`, this information +will be parsed into an attribute `HLSLPackOffsetAttr` and applied to the +variable declaration. See [packoffset attribute](0003-packoffset.md). -In order to make the variables declared in constant buffer exposed into global scope we can take advantage of `DeclContext::isTransparentContext` method and overload it to return true for `HLSLConstantBufferDecl`. This is the same way variables declared in `export` declaration context are exposed at the global scope. +In order to make the variables declared in constant buffer exposed into global +scope we can take advantage of `DeclContext::isTransparentContext` method and +overload it to return true for `HLSLConstantBufferDecl`. This is the same way +variables declared in `export` declaration context are exposed at the global +scope. -*Note: This is already implemented in Clang as `HLSLBufferDecl`. Since constant buffers are not the only buffers in HLSL we should rename it to `HLSLConstantBufferDecl`.* +*Note: This is already implemented in Clang as `HLSLBufferDecl`. Since constant +buffers are not the only buffers in HLSL we should rename it to +`HLSLConstantBufferDecl`.* ### Parsing `ConstantBuffer` declaration -`ConstantBuffer` definition will be added to the `HLSLExternalSemaSource` the same way as other resource classes. It will have a resource handle with `CBuffer` resource class and the contained type would be the template type argument. It will be handled as other resources classes, for example it can be passed into a function. +`ConstantBuffer` definition will be added to the `HLSLExternalSemaSource` the +same way as other resource classes. It will have a resource handle with +`CBuffer` resource class and the contained type would be the template type +argument. It will be handled as other resources classes, for example it can be +passed into a function. -At the same time Clang needs to recognize this class represents a constant buffer and the contained type fields are accessed using the `.` operator on `ConstantBuffer` instance. In other words treating `ConstantBuffer CB;` as if it was declared as `cbuffer __CB { MyConstants CB; }`. The exact way how to do this is TBD. +At the same time Clang needs to recognize this class represents a constant +buffer and the contained type fields are accessed using the `.` operator on +`ConstantBuffer` instance. In other words treating `ConstantBuffer +CB;` as if it was declared as `cbuffer __CB { MyConstants CB; }`. The exact way +how to do this is TBD. ### Lowering Constant Buffers to LLVM IR -During CodeGen constant buffers will be lowered to global variables with LLVM target type `target("dx.CBuffer", ..)` which will include type information about constants, the buffer size and its memory layout. +During CodeGen constant buffers will be lowered to global variables with LLVM +target type `target("dx.CBuffer", ..)` which will include type information about +constants, the buffer size and its memory layout. -Note: LLVM target types can optionally include a list of one or more types and a list of one or more integer constants. We can use these lists to encode any information needed for lowering from LLVM IR to DXIL and SPIRV. +Note: LLVM target types can optionally include a list of one or more types and a +list of one or more integer constants. We can use these lists to encode any +information needed for lowering from LLVM IR to DXIL and SPIRV. -To encode the shape of the constant buffer the LLVM target type will include a structure type that represents the constant buffer variable declarations. +To encode the shape of the constant buffer the LLVM target type will include a +structure type that represents the constant buffer variable declarations. -The size of the constant buffer will be included as the first item in the list of integer constants. The rest of the list will be used to encode the constant buffer layout. The layout will always be included whether the constant buffer uses any `packoffset` attributes or not. The exact way how the layout will be encoded is TBD and will be covered in a separate design document. +The size of the constant buffer will be included as the first item in the list +of integer constants. The rest of the list will be used to encode the constant +buffer layout. The layout will always be included whether the constant buffer +uses any `packoffset` attributes or not. The exact way how the layout will be +encoded is TBD and will be covered in a separate design document. -For simplicity, let's assume the layout will be encoded as a list of offsets of all cbuffer declarations. In that case this example: +For simplicity, let's assume the layout will be encoded as a list of offsets of +all cbuffer declarations. In that case this example: ```c++ cbuffer MyConstants { @@ -79,29 +118,57 @@ Would be lowered to LLVM target type: @MyConstants.cb = global target("dx.CBuffer", { <2 x float>, [2 x float], i32}, 40, 0, 16, 32, 36) ``` -This layout encoding can obviously get very long and unwieldy for more complicated cbuffers, and especially since target type parameters are all included in the name mangling for function overloads. We need to investigate how to make it smaller, or at least more manageable. - -One possibility is compressing the list of offsets into a smaller number of integers - taking advantage of the fact that outside of `packoffset` use the difference between two adjancent offsets is never more than 16. The compression could also include repetition construct that would help with encoding of array offset. But, as with any compressions, there's always the chance of degenerate cases that will end up with the compressed shape being the same size or larger than the original. - -> Note: The most tricky part of the layout encoding are probably arrays of structures because the structure-specific layout gets repeated many times and might not be easy to compress. One idea how to solve this could be translating structures embedded in `cbuffer` into separate target types with their own encoded layout and including them in the `cbuffer` target type. It is not clear though if this is possible (probably yes) or if it would actually make things easier or not. - -Another way could be introducing a typedef concept into the LLVM IR textual representation so that the full LLVM target type with long layout representation could occur just once. +This layout encoding can obviously get very long and unwieldy for more +complicated cbuffers, and especially since target type parameters are all +included in the name mangling for function overloads. We need to investigate how +to make it smaller, or at least more manageable. + +One possibility is compressing the list of offsets into a smaller number of +integers - taking advantage of the fact that outside of `packoffset` use the +difference between two adjancent offsets is never more than 16. The compression +could also include repetition construct that would help with encoding of array +offset. But, as with any compressions, there's always the chance of degenerate +cases that will end up with the compressed shape being the same size or larger +than the original. + +> Note: The most tricky part of the layout encoding are probably arrays of +> structures because the structure-specific layout gets repeated many times and +> might not be easy to compress. One idea how to solve this could be translating +> structures embedded in `cbuffer` into separate target types with their own +> encoded layout and including them in the `cbuffer` target type. It is not +> clear though if this is possible (probably yes) or if it would actually make +> things easier or not. + +Another way could be introducing a typedef concept into the LLVM IR textual +representation so that the full LLVM target type with long layout representation +could occur just once. ### Lowering ConstantBuffer to LLVM IR -The result of codegen for `cbuffer` and `ConstantBuffer` code should be identical. +The result of codegen for `cbuffer` and `ConstantBuffer` code should be +identical. ### Lowering Constant Buffer Variable Access -Accesses to `cbuffer` variables will be lowered to LLVM IR as memory accesses in specific "resource address space" using the standard C++ structure layout rules. +Accesses to `cbuffer` variables will be lowered to LLVM IR as memory accesses in +specific "resource address space" using the standard C++ structure layout rules. ### DXIL Lowering -LLVM pass `DXILResourceAccess` will translate these specific "resource address space" memory accesses into cbuffer DXIL ops adjusting the offsets using the cbuffer layout information encoded in `target("dx.CBuffer", ..)`. That means translating standand C++ structure layout offsets to cbuffer layout offsets and replacing the memory accesses with `llvm.dx.cbufferBufferLoad`, `llvm.dx.cbufferBufferStore`, and `extractelement ` instructions. The load and store instructions will be later lowered to `cbufferLoadLegacy` and `cbufferStoreLegacy` DXIL ops. +LLVM pass `DXILResourceAccess` will translate these specific "resource address +space" memory accesses into cbuffer DXIL ops adjusting the offsets using the +cbuffer layout information encoded in `target("dx.CBuffer", ..)`. That means +translating standand C++ structure layout offsets to cbuffer layout offsets and +replacing the memory accesses with `llvm.dx.cbufferBufferLoad`, +`llvm.dx.cbufferBufferStore`, and `extractelement ` instructions. The load and +store instructions will be later lowered to `cbufferLoadLegacy` and +`cbufferStoreLegacy` DXIL ops. ### Handle initialization -Constant buffers will be initialized the same way as other resources using the `createHandleFromBinding` intrinsics. Module initialization code need to be updated to include all constant buffers declared in a shader. +Constant buffers will be initialized the same way as other resources using the +`createHandleFromBinding` intrinsics. Module initialization code need to be +updated to include all constant buffers declared in a shader. ## Detailed design @@ -109,11 +176,17 @@ Constant buffers will be initialized the same way as other resources using the ` ## Alternatives considered -- Generate access to `cbuffer` varibles as memory accesses with the offset based on cbuffer layout and treat cbuffers as one big type-less memory blob in LLVM IR. - - There is a concern that losing the type information could lead to unnecessary copying of values. +- Generate access to `cbuffer` varibles as memory accesses with the offset based + on cbuffer layout and treat cbuffers as one big type-less memory blob in LLVM + IR. + - There is a concern that losing the type information could lead to + unnecessary copying of values. -- Using type annotations to store cbuffer layout information. Subtypes would have its own layout annotations. - - This is something we can fall back to if encoding the cbuffer layout on LLVM target type turns out to be too unwieldy, especially when it comes to encoding the layout of an array of structures. +- Using type annotations to store cbuffer layout information. Subtypes would + have its own layout annotations. + - This is something we can fall back to if encoding the cbuffer layout on LLVM + target type turns out to be too unwieldy, especially when it comes to + encoding the layout of an array of structures. ## Open issues - How to encode the cbuffer layout into LLVM target type @@ -123,9 +196,12 @@ Constant buffers will be initialized the same way as other resources using the ` ## Links -[Shader Constants](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-constants)
-[Packing Rules for Constant Variables](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-packing-rules)
-[HLSL Constant Buffer Layout Visualizer](https://maraneshi.github.io/HLSL-ConstantBufferLayoutVisualizer)
+[Shader +Constants](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-constants)
+[Packing Rules for Constant +Variables](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-packing-rules)
+[HLSL Constant Buffer Layout +Visualizer](https://maraneshi.github.io/HLSL-ConstantBufferLayoutVisualizer)
[`packoffset` Attribute](0003-packoffset.md)
## Acknowledgments (Optional) From 20fef57d5f6080b36284b23e7cb85816bf0695cd Mon Sep 17 00:00:00 2001 From: Helena Kotas Date: Mon, 2 Dec 2024 11:11:42 -0800 Subject: [PATCH 7/7] cr feedback - fix wording --- proposals/NNNN-constant-buffers.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/proposals/NNNN-constant-buffers.md b/proposals/NNNN-constant-buffers.md index e0711d3..b7ae73b 100644 --- a/proposals/NNNN-constant-buffers.md +++ b/proposals/NNNN-constant-buffers.md @@ -37,8 +37,8 @@ struct MyConstants { ConstantBuffer CB; ``` -In this case the buffer variables are referenced as if they were members of the -`ConstantBuffer` class: `CB.F`. +In this case the buffer variables are referenced as if `CB` was of type +`MyConstants` and the fields are members of that object. ## Motivation @@ -50,7 +50,7 @@ the HLSL language. ### Parsing `cbuffer` Declaration In Clang frontend the `cbuffer` declaration will be parsed into a new AST Node -called `HLSLConstantBufferDecl`. This class will be based on from `NameDecl` and +called `HLSLConstantBufferDecl`. This class will be based on `NameDecl` and `DeclContext`. Variable declarations inside the `cbuffer` context will be children of this new @@ -76,11 +76,11 @@ same way as other resource classes. It will have a resource handle with argument. It will be handled as other resources classes, for example it can be passed into a function. -At the same time Clang needs to recognize this class represents a constant -buffer and the contained type fields are accessed using the `.` operator on -`ConstantBuffer` instance. In other words treating `ConstantBuffer -CB;` as if it was declared as `cbuffer __CB { MyConstants CB; }`. The exact way -how to do this is TBD. +Clang needs to recognize that this class represents a constant buffer and the +contained type fields are accessed using the `.` operator on `ConstantBuffer` +instance. In other words treating `ConstantBuffer CB;` as if it was +declared as `cbuffer __CB { MyConstants CB; }`. The exact way how to do this is +TBD. ### Lowering Constant Buffers to LLVM IR