Add specification for cl_khr_subgroup_rotate (#781)

Signed-off-by: Kevin Petit <kevin.petit@arm.com>
Change-Id: I3acf34660b83c65533d244c7ceb17ec5219d1949

Author: kpet

OpenCL_Ext.txt

@@ -103,6 +103,8 @@ include::ext/cl_khr_external_memory.asciidoc[]
 include::ext/cl_khr_command_buffer.asciidoc[]
 include::ext/cl_khr_expect_assume.asciidoc[]
 
+include::ext/cl_khr_subgroup_rotate.asciidoc[]
+
 // NOTE: To keep meaningful section numbers, new
 // extension documents should be added above here!
 

env/extensions.asciidoc

@@ -347,6 +347,14 @@ If the OpenCL environment supports the extension `cl_khr_expect_assume` and use
 
 * *ExpectAssumeKHR*
 
+==== `cl_khr_subgroup_rotate`
+
+If the OpenCL environment supports the extension `cl_khr_subgroup_rotate`,
+then the environment accept modules that require `SPV_KHR_subgroup_rotate` and
+declare the following SPIR-V capabilities:
+
+* *GroupNonUniformRotateKHR*
+
 === Embedded Profile Extensions
 
 ==== `cles_khr_int64`

ext/cl_khr_subgroup_rotate.asciidoc

@@ -0,0 +1,120 @@
+// Copyright 2021 The Khronos Group. This work is licensed under a
+// Creative Commons Attribution 4.0 International License; see
+// http://creativecommons.org/licenses/by/4.0/
+
+[[cl_khr_subgroup_rotate]]
+== Subgroup Rotation
+
+This extension adds support for a new subgroup data exchange operation that
+makes it possible to rotate values through the work items in a subgroup.
+
+=== General Information
+
+==== Name Strings
+
+`cl_khr_subgroup_rotate`
+
+==== Version History
+
+[cols="1,1,3",options="header",]
+|====
+| *Date*     | *Version* | *Description*
+| 2022-04-22 | 1.0.0     | Initial version.
+|====
+
+==== Dependencies
+
+This extension is written against the OpenCL Specification Version 3.0.10,
+and OpenCL C Specification Version 3.0.10 and OpenCL Environment Specification
+Version 3.0.10.
+
+This extension requires OpenCL 2.0.
+
+==== Contributors
+
+Kévin Petit, Arm Ltd. +
+Ben Ashbaugh, Intel +
+Ruihao Zhang, Qualcomm +
+Sven van Haastregt, Arm Ltd. +
+Anastasia Stulova, Arm Ltd. +
+Stuart Brady, Arm Ltd. +
+
+=== New OpenCL C Functions
+
+This extension adds the following built-in function:
+
+[source,c]
+----
+gentype sub_group_rotate(gentype value, int delta)
+gentype sub_group_clustered_rotate(gentype value, int delta, uint clustersize)
+----
+
+=== Modifications to the OpenCL C Specification
+
+(Add a new section 6.15.x, *Subgroup Rotation*) ::
++
+--
+
+The following preprocessor definitions are added:
+
+[source,c]
+----
+#define cl_khr_subgroup_rotate 1
+----
+
+The table below describes a specialized OpenCL C programming language built-in
+function that allow work items in a subgroup to exchange data. This function
+need not be encountered by all work items in a subgroup executing the kernel.
+For the functions below, the generic type name `gentype` may be one of the
+supported built-in scalar data types `char`, `uchar`, `short`, `ushort`, `int`,
+`uint`, `long`, `ulong`, `float`, `double` (if double precision is supported),
+or `half` (if half precision is supported).
+
+[cols="1a,1",options="header",]
+|=======================================================================
+|*Function*
+|*Description*
+
+|[source,c]
+----
+gentype sub_group_rotate(
+    gentype value, int delta)
+----
+| Returns _value_ for the work item with subgroup local ID equal to the remainder
+of the division of the sum of this work item's subgroup local ID and _delta_ by
+the maximum subgroup size. +
+The value of _delta_ is required to be dynamically-uniform for all work items in
+the subgroup, otherwise the behavior is undefined.
+
+The return value is undefined if the work item with subgroup local ID equal to the
+calculated index is inactive.
+
+|[source,c]
+----
+gentype sub_group_clustered_rotate(
+    gentype value, int delta, uint clustersize)
+----
+| Returns _value_ for the work item with subgroup local ID equal to the sum of, the
+remainder of the division of the sum of this work item's ID within the cluster and
+_delta_ by _clustersize_, and the subgroup local ID of the first work-item of the
+cluster to which the work-item executing the function belongs. +
+The value of _delta_ is required to be dynamically-uniform for all work items in
+the subgroup, otherwise the behavior is undefined.
+
+_clustersize_ must be an integer constant expression and a power of two, smaller
+than or equal to the maximum subgroup size, otherwise the behavior is undefined.
+
+The return value is undefined if the work item with subgroup local ID equal to the
+calculated index is inactive.
+|=======================================================================
+--
+
+=== Modifications to the OpenCL SPIR-V Environment Specification
+
+See OpenCL SPIR-V Environment Specification.
+
+=== Interactions with Other Extensions
+
+If `cl_khr_il_program` is supported then the SPIR-V environment specification
+modifications described above apply.
+

ext/quick_reference.asciidoc

@@ -257,6 +257,10 @@
 | Relative Shuffles Among Sub-Groupings of Work Items
 | Extension
 
+| <<cl_khr_subgroup_rotate,cl_khr_subgroup_rotate>>
+| Rotation Among Sub-Groupings of Work Items
+| Extension
+
 | <<cl_khr_suggested_local_work_size,cl_khr_suggested_local_work_size>>
 | Query a Suggested Local Work Size
 | Extension