[0011] Resource element type validation

proposals/0010-resource-element-type-validation.md

@@ -6,98 +6,87 @@
 * Issues: [#75676](https://github.com/llvm/llvm-project/issues/75676)
 
 ## Introduction
-Resources are often used in HLSL, with various resource element types (RETs).
+Resources are often used in HLSL, with various resource element types.
 
 For example:
 ```
 RWBuffer<float> rwbuf: register(u0);
 ```
-In this code, the RET is `float`, and the resource type is `RWBuffer`.
-All resources can be placed in two categories, raw buffers and typed buffers. 
-Below is a description of all resources and their corresponding categories
-* raw buffers
-  * [Append|Consume|RW|RasterizerOrdered]StructuredBuffer
-  * [RW]ByteAddressBuffer
+In this code, the element type is `float`, and the resource type is `RWBuffer`.
+`RWBuffer`, along with some other buffers and textures, fall under the "typed buffer"
+category. Below is a description of resources that are considered "typed buffers".
 * typed buffers
   * [RW|RasterizerOrdered]Buffer
   * [Feedback]Texture*
 
-There is a distinct set of rules that define valid RETs for raw buffer resources, 
-and a separate set of rules that define valid RETs for typed buffer resources.
+There is a distinct set of rules that define valid element types for typed buffer resources.
 
-RETs for typed buffer resources:
+Element types for typed buffer resources:
 * Are not intangible (e.g., isn't a resource type)
 * Must be vectors or scalars of arithmetic types, not bools nor enums nor arrays
-* The type should be line-vector layout compatible (homogenous, at most 4 elements, and at most 128 bits in size) 
+* Should be a scalar or homogenous vector of a floating-point or integer type, with a maximum of 4 components after translating 64-bit components into pairs of uint32_t components
 
-RETs for raw buffer variants are much less constrained:
-* Are not intangible (e.g., isn't a resource type)
-* All constituent types must be arithmetic types or bools or enums
-
-Resource types are never allowed as RETs (i.e., `RWBuffer<int>` as an RET).
-If someone writes `RWBuffer<MyCustomType>` and MyCustomType is not a 
-valid RET, there should be infrastructure to reject this RET and emit a message 
-explaining why it was rejected as an RET.
+Resource types are never allowed as element types (i.e., `RWBuffer<int>` as an element type).
+If someone writes `RWBuffer<MyCustomType>` and MyCustomType is not a valid element type, 
+there should be infrastructure to reject this element type and emit a message explaining 
+why it was rejected as an element type.
 
 ## Motivation
-Currently, there is an allow list of valid RETs. It must be modified with respect 
-to this spec. Anything that is not a valid RET will be rejected. The allow list isn't
-broad enough, because there is no case where the RET is user-defined for a raw buffer.
-Ideally, a user should be able to determine how any user-defined structure is invalid 
-as an RET. Some system should be in place to more completely enforce the rules for 
-valid and invalid RETs, as well as provide useful information on why they are invalid.
+Currently, there is an allow list of valid element types. It must be modified with respect 
+to this spec. Anything that is not a valid element type will be rejected. The allow list isn't
+broad enough, because user-defined types aren't allowed.
+Ideally, a user should be able to determine exactly how any user-defined type is invalid 
+as an element type. Some system should be in place to more completely enforce the rules for 
+valid and invalid element types, as well as provide useful information on why they are invalid.
 
-For example, when targeting DXIL IR, `RWBuffer<double4> b : register(u4);` will emit
-an error in DXC, but will not in clang-dxc, despite the fact that `double4` is an 
-invalid RET for typed buffers.
+For example, `RWBuffer<double4> b : register(u4);` will emit an error in DXC, but will not in 
+clang-dxc, despite the fact that `double4` is an invalid element type for typed buffers.
 
 ## Proposed solution
 
 The proposed solution is to modify the declaration of each resource declared in 
 `clang\lib\Sema\HLSLExternalSemaSource.cpp` and insert into each representative
 AST node a concept. The AST node will be created as if the C++20 `concept` keyword
 was parsed and applied to the declaration. The concept will be used to validate the
-given RET, and will emit errors when the given RET is invalid. Although concepts are
-not currently supported in HLSL, we expect support to be added at some point in the
-future. Meanwhile, because LLVM does support concepts, we can make use of
-them when constructing the AST in Sema.
-
-A new built-in, `__builtin_hlsl_is_line_vector_layout_compatible`, will be 
-added in order to express the extra typed buffer constraint. This builtin
-will be added to each AST node that requires that constraint. The builtin is 
-described below. Standard clang diagnostics for unsatisfied constraints will be 
-used to report any invalid element types. Concepts required will differ depending
-on whether the resource is a typed buffer or a raw buffer. Until concepts are 
-formally supported by HLSL, the concepts and constraints will be expressed 
-directly in the AST via the HLSL external sema source.
+given element type, and will emit errors when the given element type is invalid. 
+Although concepts are not currently supported in HLSL, we expect support to be 
+added at some point in the future. Meanwhile, because LLVM does support concepts, 
+we can make use of them when constructing the AST in Sema.
+
+A new built-in, `__builtin_hlsl_typed_element_compatible`, will be added in order
+to fully express the typed buffer constraint. This builtin will be placed within a
+concept constraint expression that is added to each AST node representing a typed
+buffer resource. The builtin is described below. Standard clang diagnostics for
+unsatisfied constraints will be used to report any invalid element types. Until 
+concepts are formally supported by HLSL, the concepts and constraints will be 
+expressed only in the AST via the HLSL external sema source.
 
 ## Detailed design
 
 In `clang\lib\Sema\HLSLExternalSemaSource.cpp`, `RWBuffer` is defined, along with 
 `RasterizerOrderedBuffer` and `StructuredBuffer`. It is at this point that the 
 concept would be incorporated into these resource declarations. A concept representing
 the relevant constraints will be applied to each resource declaration. If a concept
-is not true for the given RET, a corresponding error message will be emitted.
+is not true for the given element type, a corresponding error message will be emitted.
 
 The list of builtins to be used as type traits that will be available for
 concept definition are described below:
 | type trait | Description|
 |-|-|
-| `__is_intangible` | An RET should be an arithmetic type, bool, enum, or a vector or matrix or UDT containing such types. This is equivalent to validating that the RET is not intangible. This will error when given an incomplete type. |
-| `__builtin_hlsl_is_line_vector_layout_compatible` | A typed buffer RET should never have two different subelement types. Line vector layout compatible also requires at most 4 elements, and a total size of at most 16 bytes. The builtin will also disallow the RET if any of its constituent types are enums or bools. |
-
-For raw buffers, only `!__is_intangible` needs to be true. 
-For typed buffers, `__builtin_hlsl_is_line_vector_layout_compatible` 
-also needs to be true. This builtin will be used to ensure homogeneity. 
-It will use `BuildFlattenedTypeList` to retrieve a small vector of the subelement types.
-From this subvector, the first element will be compared to all elements in the vector,
-and any mismatches will return false. Typed buffer RETs will 
-also need to have at most 4 subelements, and the total size in bytes cannot exceed 16,
-which will also be verified by `__builtin_hlsl_is_line_vector_layout_compatible`.
-Finally, the builtin will validate that there are no bools or enums present in any 
-component of the type.
-
-### Examples of RET validation results:
+| `!__builtin_hlsl_is_intangible ` | An element type should be an arithmetic type, bool, enum, or a vector or matrix or UDT containing such types. This is equivalent to validating that the element type is not intangible. This will error when given an incomplete type. |
+| `__builtin_hlsl_typed_element_compatible ` | A typed buffer element type should never have two different subelement types. Line vector layout compatible also requires at most 4 elements, and a total size of at most 16 bytes. The builtin will also disallow the element type if any of its constituent types are enums or bools. |
+
+For typed buffers, `__builtin_hlsl_typed_element_compatible` and 
+`!__builtin_hlsl_is_intangible` needs to be true. `__builtin_hlsl_typed_element_compatible`
+will be used to ensure homogeneity. It will use `BuildFlattenedTypeList` to retrieve a small
+vector of the subelement types. From this subvector, the first element will be compared to 
+all elements in the vector, and any mismatches will return false. Typed buffer element types
+will also need to have at most 4 subelements, after splitting 64-bit subelements into two 32-bit
+subelements, which will also be verified by `__builtin_hlsl_is_line_vector_layout_compatible`.
+Finally, the `__builtin_hlsl_typed_element_compatible` will validate that there are no bools or
+enums present in any component of the type.
+
+### Examples of Element Type validation results:
 ```
 struct oneInt {
     int i;
@@ -152,12 +141,12 @@ struct weirdStruct {
   intVec iv;
 };
 
-RWBuffer<double2> r0; // valid - RET fits in 4 32-bit quantities
+RWBuffer<double2> r0; // valid - element type fits in 4 32-bit quantities
 RWBuffer<int> r1; // valid
 RWBuffer<float> r2; // valid
 RWBuffer<float4> r3; // valid
-RWBuffer<notComplete> r4; // invalid - the RET isn't complete, the definition is missing. 
-// the type trait that would catch this is the negation of `__is_intangible`
+RWBuffer<notComplete> r4; // invalid - the element type isn't complete, the definition is missing. 
+// the type trait that would catch this is the negation of `__builtin_hlsl_is_intangible`
 RWBuffer<oneInt> r5; // valid - all leaf types are valid primitive types, and homogenous
 RWBuffer<oneFloat> r6; // valid
 RWBuffer<twoInt> r7; // valid
@@ -173,11 +162,11 @@ RWBuffer<EightHalves> r12; // invalid, > 4 elements, DXC fails
 StructuredBuffer<EightHalves> r12Structured; // valid
 RWBuffer<oneIntWithVec> r13; // valid
 RWBuffer<weirdStruct> r14; // valid
-RWBuffer<RWBuffer<int> > r15; // invalid - the RET has a handle with unknown size, thus it is an intangible RET.
-// the type trait that would catch this is the negation of `__is_intangible`
+RWBuffer<RWBuffer<int> > r15; // invalid - the element type has a handle with unknown size, 
+// thus it is an intangible element type. The type trait that would catch this is the negation of `__builtin_hlsl_is_intangible`
 ```
 
-Below is a sample C++ implementation of the `RWBuffer` resource type, which is a typed buffer variant.
+Below is a sample C++ implementation of the `RWBuffer` resource type.
 This code would exist within an hlsl header, but concepts are not implemented in HLSL. Instead, the AST node
 associated with RWBuffers is constructed as if this code was read and parsed by the compiler.
 ```
@@ -193,13 +182,6 @@ template<typename element_type> requires !__is_intangible(element_type) && is_va
 struct RWBuffer {
     element_type Val;
 };
-
-// doesn't need __builtin_hlsl_is_line_vector_layout_compatible, because this is a raw buffer
-// also, raw buffers allow bools and enums as constituent types
-template<typename T> requires !__is_intangible(T)
-struct StructuredBuffer {
-    T Val;
-};
 }
 
 ```
@@ -209,9 +191,9 @@ We could instead implement a diagnostic function that checks each of these conce
 one place, either in Sema or CodeGen, but this would prevent us from defining a single header where 
 all resource information is localized.
 
-Another alternative considered was creating a builtin called `__is_valid_resource_element_type`, to
-check all possible valid resource element types, rather than just checking that the RET is not intangible.
-This is unneeded because all primitive non-intangible types are valid RETs.
+Another alternative considered was creating a builtin called `__builtin_hlsl_is_valid_resource_element_type`, to
+check all possible valid resource element types, rather than just checking that the element type is not intangible.
+This is unneeded because all primitive non-intangible types are valid element types.
 
 ## Acknowledgments (Optional)
 * Damyan Pepper