subgroup cluster ops: add safety docs, const assert preconditions

Firestar99 · LegNeato · commit 0080c43a13f7 · 2025-07-05T16:44:24.000Z
diff --git a/crates/spirv-std/src/arch/subgroup.rs b/crates/spirv-std/src/arch/subgroup.rs
@@ -1,5 +1,3 @@
-#![allow(clippy::missing_safety_doc)]
-
 #[cfg(target_arch = "spirv")]
 use crate::arch::barrier;
 use crate::float::Float;
@@ -792,6 +790,16 @@ macro_rules! macro_subgroup_op_clustered {
         pub unsafe fn $name<const CLUSTER_SIZE: u32, I: VectorOrScalar<Scalar = $scalar>>(
             value: I,
         ) -> I {
+            const {
+                assert!(CLUSTER_SIZE >= 1, "`ClusterSize` must be at least 1");
+                assert!(
+                    CLUSTER_SIZE.is_power_of_two(),
+                    "`ClusterSize` must be a power of 2"
+                );
+                // Cannot be verified with static assertions:
+                // `ClusterSize` must not be greater than the size of the group
+            }
+
             let mut result = I::default();
 
             unsafe {
@@ -843,6 +851,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 macro_subgroup_op!(impl Float, "OpGroupNonUniformFAdd", subgroup_f_add, GroupOperation::Reduce, subgroup_inclusive_f_add, GroupOperation::InclusiveScan, subgroup_exclusive_f_add, GroupOperation::ExclusiveScan; r"
 A floating point add group operation of all `value` operands contributed by active invocations in the group.
@@ -871,6 +882,9 @@ The type of `value` must be the same as Result Type. The method used to perform
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 
 // mul
@@ -901,6 +915,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 macro_subgroup_op!(impl Float, "OpGroupNonUniformFMul", subgroup_f_mul, GroupOperation::Reduce, subgroup_inclusive_f_mul, GroupOperation::InclusiveScan, subgroup_exclusive_f_mul, GroupOperation::ExclusiveScan; r"
 A floating point multiply group operation of all `value` operands contributed by active invocations in the group.
@@ -929,6 +946,9 @@ The type of `value` must be the same as Result Type. The method used to perform
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 
 // min
@@ -959,6 +979,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 macro_subgroup_op!(impl UnsignedInteger, "OpGroupNonUniformUMin", subgroup_u_min, GroupOperation::Reduce, subgroup_inclusive_u_min, GroupOperation::InclusiveScan, subgroup_exclusive_u_min, GroupOperation::ExclusiveScan; r"
 An unsigned integer minimum group operation of all `value` operands contributed by active invocations in the group.
@@ -987,6 +1010,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 macro_subgroup_op!(impl Float, "OpGroupNonUniformFMin", subgroup_f_min, GroupOperation::Reduce, subgroup_inclusive_f_min, GroupOperation::InclusiveScan, subgroup_exclusive_f_min, GroupOperation::ExclusiveScan; r"
 A floating point minimum group operation of all `value` operands contributed by active invocations in the group.
@@ -1015,6 +1041,9 @@ The type of `value` must be the same as Result Type. The method used to perform
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 
 // max
@@ -1045,6 +1074,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 macro_subgroup_op!(impl UnsignedInteger, "OpGroupNonUniformUMax", subgroup_u_max, GroupOperation::Reduce, subgroup_inclusive_u_max, GroupOperation::InclusiveScan, subgroup_exclusive_u_max, GroupOperation::ExclusiveScan; r"
 An unsigned integer maximum group operation of all `value` operands contributed by active invocations in the group.
@@ -1073,6 +1105,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 macro_subgroup_op!(impl Float, "OpGroupNonUniformFMax", subgroup_f_max, GroupOperation::Reduce, subgroup_inclusive_f_max, GroupOperation::InclusiveScan, subgroup_exclusive_f_max, GroupOperation::ExclusiveScan; r"
 A floating point maximum group operation of all `value` operands contributed by active invocations in by group.
@@ -1099,6 +1134,9 @@ The identity I for Operation is -INF.
 The type of `value` must be the same as Result Type. The method used to perform the group operation on the contributed Value(s) from active invocations is implementation defined. From the set of Value(s) provided by active invocations within a subgroup, if for any two Values one of them is a NaN, the other is chosen. If all Value(s) that are used by the current invocation are NaN, then the result is an undefined value.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 
 // and
@@ -1129,6 +1167,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 
 // or
@@ -1159,6 +1200,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 
 // xor
@@ -1189,6 +1233,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 
 // logical and
@@ -1219,6 +1266,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 
 // logical or
@@ -1249,6 +1299,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 
 // logical xor
@@ -1279,6 +1332,9 @@ The type of `value` must be the same as Result Type.
 ClusterSize is the size of cluster to use. ClusterSize must be a scalar of integer type, whose Signedness operand is 0. ClusterSize must come from a constant instruction. Behavior is undefined unless ClusterSize is at least 1 and a power of 2. If ClusterSize is greater than the size of the group, executing this instruction results in undefined behavior.
 
 Requires Capability `GroupNonUniformArithmetic` and `GroupNonUniformClustered`.
+
+# Safety
+* `ClusterSize` must not be greater than the size of the group
 ");
 
 /// Result is the `value` of the invocation within the quad with a quad index equal to `index`.
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_ballot.stderr b/tests/compiletests/ui/arch/subgroup/subgroup_ballot.stderr
@@ -1,9 +1,9 @@
 %1 = OpFunction  %2  None %3
 %4 = OpFunctionParameter  %2
 %5 = OpLabel
-OpLine %6 375 8
+OpLine %6 373 8
 %7 = OpGroupNonUniformBallot  %8  %9 %4
-OpLine %6 414 8
+OpLine %6 412 8
 %10 = OpGroupNonUniformInverseBallot  %2  %9 %7
 OpNoLine
 OpReturnValue %10
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_ballot_bit_count.stderr b/tests/compiletests/ui/arch/subgroup/subgroup_ballot_bit_count.stderr
@@ -1,7 +1,7 @@
 %1 = OpFunction  %2  None %3
 %4 = OpFunctionParameter  %5
 %6 = OpLabel
-OpLine %7 514 0
+OpLine %7 512 0
 %8 = OpGroupNonUniformBallotBitCount  %2  %9 Reduce %4
 OpNoLine
 OpReturnValue %8
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_broadcast_first.stderr b/tests/compiletests/ui/arch/subgroup/subgroup_broadcast_first.stderr
@@ -1,7 +1,7 @@
 %1 = OpFunction  %2  None %3
 %4 = OpFunctionParameter  %2
 %5 = OpLabel
-OpLine %6 342 8
+OpLine %6 340 8
 %7 = OpGroupNonUniformBroadcastFirst  %2  %8 %4
 OpNoLine
 OpReturnValue %7
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_cluster_size_0_fail.rs b/tests/compiletests/ui/arch/subgroup/subgroup_cluster_size_0_fail.rs
@@ -0,0 +1,17 @@
+// build-pass
+// compile-flags: -C target-feature=+GroupNonUniform,+GroupNonUniformArithmetic,+GroupNonUniformClustered,+ext:SPV_KHR_vulkan_memory_model
+
+use glam::UVec3;
+use spirv_std::arch::{GroupOperation, SubgroupMask};
+use spirv_std::spirv;
+
+unsafe fn subgroup_test_fail(value: u32) -> u32 {
+    spirv_std::arch::subgroup_clustered_i_add::<0, _>(value)
+}
+
+#[spirv(compute(threads(32, 1, 1)))]
+pub fn main(#[spirv(local_invocation_id)] local_invocation_id: UVec3) {
+    unsafe {
+        subgroup_test_fail(local_invocation_id.x);
+    }
+}
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_cluster_size_0_fail.stderr b/tests/compiletests/ui/arch/subgroup/subgroup_cluster_size_0_fail.stderr
@@ -0,0 +1,37 @@
+error[E0080]: evaluation of `spirv_std::arch::subgroup_clustered_i_add::<0, u32, u32>::{constant#0}` failed
+   --> /home/firestar99/workspace/frameworks/rust-gpu/crates/spirv-std/src/arch/subgroup.rs:840:1
+    |
+840 | / macro_subgroup_op_clustered!(impl Integer, "OpGroupNonUniformIAdd", subgroup_clustered_i_add; r"
+841 | | An integer add group operation of all `value` operands contributed by active invocations in the group.
+842 | |
+843 | | Result Type must be a scalar or vector of integer type.
+...   |
+856 | | * `ClusterSize` must not be greater than the size of the group
+857 | | ");
+    | |__^ the evaluated program panicked at '`ClusterSize` must be at least 1', /home/firestar99/workspace/frameworks/rust-gpu/crates/spirv-std/src/arch/subgroup.rs:840:1
+    |
+    = note: this error originates in the macro `$crate::panic::panic_2021` which comes from the expansion of the macro `macro_subgroup_op_clustered` (in Nightly builds, run with -Z macro-backtrace for more info)
+
+note: erroneous constant encountered
+   --> /home/firestar99/workspace/frameworks/rust-gpu/crates/spirv-std/src/arch/subgroup.rs:840:1
+    |
+840 | / macro_subgroup_op_clustered!(impl Integer, "OpGroupNonUniformIAdd", subgroup_clustered_i_add; r"
+841 | | An integer add group operation of all `value` operands contributed by active invocations in the group.
+842 | |
+843 | | Result Type must be a scalar or vector of integer type.
+...   |
+856 | | * `ClusterSize` must not be greater than the size of the group
+857 | | ");
+    | |__^
+    |
+    = note: this note originates in the macro `macro_subgroup_op_clustered` (in Nightly builds, run with -Z macro-backtrace for more info)
+
+note: the above error was encountered while instantiating `fn spirv_std::arch::subgroup_clustered_i_add::<0, u32, u32>`
+ --> $DIR/subgroup_cluster_size_0_fail.rs:9:5
+  |
+9 |     spirv_std::arch::subgroup_clustered_i_add::<0, _>(value)
+  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: aborting due to 1 previous error
+
+For more information about this error, try `rustc --explain E0080`.
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_cluster_size_non_power_of_two_fail.rs b/tests/compiletests/ui/arch/subgroup/subgroup_cluster_size_non_power_of_two_fail.rs
@@ -0,0 +1,17 @@
+// build-pass
+// compile-flags: -C target-feature=+GroupNonUniform,+GroupNonUniformArithmetic,+GroupNonUniformClustered,+ext:SPV_KHR_vulkan_memory_model
+
+use glam::UVec3;
+use spirv_std::arch::{GroupOperation, SubgroupMask};
+use spirv_std::spirv;
+
+unsafe fn subgroup_test_fail(value: u32) -> u32 {
+    spirv_std::arch::subgroup_clustered_i_add::<5, _>(value)
+}
+
+#[spirv(compute(threads(32, 1, 1)))]
+pub fn main(#[spirv(local_invocation_id)] local_invocation_id: UVec3) {
+    unsafe {
+        subgroup_test_fail(local_invocation_id.x);
+    }
+}
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_cluster_size_non_power_of_two_fail.stderr b/tests/compiletests/ui/arch/subgroup/subgroup_cluster_size_non_power_of_two_fail.stderr
@@ -0,0 +1,37 @@
+error[E0080]: evaluation of `spirv_std::arch::subgroup_clustered_i_add::<5, u32, u32>::{constant#0}` failed
+   --> /home/firestar99/workspace/frameworks/rust-gpu/crates/spirv-std/src/arch/subgroup.rs:840:1
+    |
+840 | / macro_subgroup_op_clustered!(impl Integer, "OpGroupNonUniformIAdd", subgroup_clustered_i_add; r"
+841 | | An integer add group operation of all `value` operands contributed by active invocations in the group.
+842 | |
+843 | | Result Type must be a scalar or vector of integer type.
+...   |
+856 | | * `ClusterSize` must not be greater than the size of the group
+857 | | ");
+    | |__^ the evaluated program panicked at '`ClusterSize` must be a power of 2', /home/firestar99/workspace/frameworks/rust-gpu/crates/spirv-std/src/arch/subgroup.rs:840:1
+    |
+    = note: this error originates in the macro `$crate::panic::panic_2021` which comes from the expansion of the macro `macro_subgroup_op_clustered` (in Nightly builds, run with -Z macro-backtrace for more info)
+
+note: erroneous constant encountered
+   --> /home/firestar99/workspace/frameworks/rust-gpu/crates/spirv-std/src/arch/subgroup.rs:840:1
+    |
+840 | / macro_subgroup_op_clustered!(impl Integer, "OpGroupNonUniformIAdd", subgroup_clustered_i_add; r"
+841 | | An integer add group operation of all `value` operands contributed by active invocations in the group.
+842 | |
+843 | | Result Type must be a scalar or vector of integer type.
+...   |
+856 | | * `ClusterSize` must not be greater than the size of the group
+857 | | ");
+    | |__^
+    |
+    = note: this note originates in the macro `macro_subgroup_op_clustered` (in Nightly builds, run with -Z macro-backtrace for more info)
+
+note: the above error was encountered while instantiating `fn spirv_std::arch::subgroup_clustered_i_add::<5, u32, u32>`
+ --> $DIR/subgroup_cluster_size_non_power_of_two_fail.rs:9:5
+  |
+9 |     spirv_std::arch::subgroup_clustered_i_add::<5, _>(value)
+  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: aborting due to 1 previous error
+
+For more information about this error, try `rustc --explain E0080`.
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_elect.stderr b/tests/compiletests/ui/arch/subgroup/subgroup_elect.stderr
@@ -1,6 +1,6 @@
 %1 = OpFunction  %2  None %3
 %4 = OpLabel
-OpLine %5 172 8
+OpLine %5 170 8
 %6 = OpGroupNonUniformElect  %2  %7
 OpNoLine
 OpReturnValue %6
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_i_add_clustered.stderr b/tests/compiletests/ui/arch/subgroup/subgroup_i_add_clustered.stderr
@@ -1,7 +1,7 @@
 %1 = OpFunction  %2  None %3
 %4 = OpFunctionParameter  %2
 %5 = OpLabel
-OpLine %6 832 0
+OpLine %6 840 0
 %7 = OpGroupNonUniformIAdd  %2  %8 ClusteredReduce %4 %9
 OpNoLine
 OpReturnValue %7
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_i_add_exclusive_scan.stderr b/tests/compiletests/ui/arch/subgroup/subgroup_i_add_exclusive_scan.stderr
@@ -1,7 +1,7 @@
 %1 = OpFunction  %2  None %3
 %4 = OpFunctionParameter  %2
 %5 = OpLabel
-OpLine %6 819 0
+OpLine %6 827 0
 %7 = OpGroupNonUniformIAdd  %2  %8 ExclusiveScan %4
 OpNoLine
 OpReturnValue %7
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_i_add_inclusive_scan.stderr b/tests/compiletests/ui/arch/subgroup/subgroup_i_add_inclusive_scan.stderr
@@ -1,7 +1,7 @@
 %1 = OpFunction  %2  None %3
 %4 = OpFunctionParameter  %2
 %5 = OpLabel
-OpLine %6 819 0
+OpLine %6 827 0
 %7 = OpGroupNonUniformIAdd  %2  %8 InclusiveScan %4
 OpNoLine
 OpReturnValue %7
diff --git a/tests/compiletests/ui/arch/subgroup/subgroup_i_add_reduce.stderr b/tests/compiletests/ui/arch/subgroup/subgroup_i_add_reduce.stderr
@@ -1,7 +1,7 @@
 %1 = OpFunction  %2  None %3
 %4 = OpFunctionParameter  %2
 %5 = OpLabel
-OpLine %6 819 0
+OpLine %6 827 0
 %7 = OpGroupNonUniformIAdd  %2  %8 Reduce %4
 OpNoLine
 OpReturnValue %7
