Update cl_arm_scheduling_controls to v0.5.0 (#823)

* Update cl_arm_scheduling_controls to v0.5.0

- Add support for warp throttling
- Add support to control the size of compute unit batch queues

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

* Add missing CL_DEVICE_SCHEDULING_COMPUTE_UNIT_BATCH_QUEUE_SIZE_ARM

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

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

Author: kpet

extensions/cl_arm_scheduling_controls.asciidoc

@@ -2,6 +2,7 @@
 :data-uri:
 :icons: font
 include::../config/attribs.txt[]
+include::{generated}/api/api-dictionary-no-links.asciidoc[]
 :source-highlighter: coderay
 
 = cl_arm_scheduling_controls
@@ -16,7 +17,8 @@ Kevin Petit (kevin.petit 'at' arm.com)
 
 == Contributors
 
-Kevin Petit, Arm Ltd.
+Kevin Petit, Arm Ltd. +
+Radek Szymanski, Arm Ltd. +
 
 == Notice
 
@@ -29,7 +31,7 @@ Shipping
 == Version
 
 Built On: {docdate} +
-Version: 0.3.0
+Version: 0.5.0
 
 == Dependencies
 
@@ -55,16 +57,22 @@ CL_DEVICE_SCHEDULING_WORKGROUP_BATCH_SIZE_ARM           (1 << 1)
 CL_DEVICE_SCHEDULING_WORKGROUP_BATCH_SIZE_MODIFIER_ARM  (1 << 2)
 CL_DEVICE_SCHEDULING_DEFERRED_FLUSH_ARM                 (1 << 3)
 CL_DEVICE_SCHEDULING_REGISTER_ALLOCATION_ARM            (1 << 4)
+CL_DEVICE_SCHEDULING_WARP_THROTTLING_ARM                (1 << 5)
+CL_DEVICE_SCHEDULING_COMPUTE_UNIT_BATCH_QUEUE_SIZE_ARM  (1 << 6)
 
 CL_DEVICE_SUPPORTED_REGISTER_ALLOCATIONS_ARM              0x41EB
+
+CL_DEVICE_MAX_WARP_COUNT_ARM                             0x41EA
 ----
 
 Accepted value for the _param_name_ parameter to *clSetKernelExecInfo*:
 
 [source,c]
 ----
-CL_KERNEL_EXEC_INFO_WORKGROUP_BATCH_SIZE_ARM           0x41E5
-CL_KERNEL_EXEC_INFO_WORKGROUP_BATCH_SIZE_MODIFIER_ARM  0x41E6
+CL_KERNEL_EXEC_INFO_WORKGROUP_BATCH_SIZE_ARM            0x41E5
+CL_KERNEL_EXEC_INFO_WORKGROUP_BATCH_SIZE_MODIFIER_ARM   0x41E6
+CL_KERNEL_EXEC_INFO_WARP_COUNT_LIMIT_ARM                0x41E8
+CL_KERNEL_EXEC_INFO_COMPUTE_UNIT_MAX_QUEUED_BATCHES_ARM 0x41F1
 ----
 
 Accepted value for the _properties_ parameter to *clCreateCommandQueueWithProperties*:
@@ -75,6 +83,13 @@ CL_QUEUE_KERNEL_BATCHING_ARM 0x41E7
 CL_QUEUE_DEFERRED_FLUSH_ARM  0x41EC
 ----
 
+Accepted value for the _param_name_ parameter to *clGetKernelInfo*:
+
+[source,c]
+----
+CL_KERNEL_MAX_WARP_COUNT_ARM 0x41E9
+----
+
 == New build options
 
 This extension adds a build option to control the number of registers allocated
@@ -121,11 +136,28 @@ NOTE: Missing before version 0.3.0
 - `CL_DEVICE_SCHEDULING_REGISTER_ALLOCATION_ARM` is set when the device compiler
   supports the `-fregister-allocation` option.
 
+- {CL_DEVICE_SCHEDULING_WARP_THROTTLING_ARM} is set when the device supports
+  {CL_KERNEL_EXEC_INFO_WARP_COUNT_LIMIT_ARM}, {CL_KERNEL_MAX_WARP_COUNT_ARM}
+  and {CL_DEVICE_MAX_WARP_COUNT_ARM}. +
+  Missing before version 0.4.
+
+- {CL_DEVICE_SCHEDULING_COMPUTE_UNIT_BATCH_QUEUE_SIZE_ARM} is set when the
+  device supports {CL_KERNEL_EXEC_INFO_COMPUTE_UNIT_MAX_QUEUED_BATCHES_ARM}. +
+  Missing before version 0.5.
+
 | `CL_DEVICE_SUPPORTED_REGISTER_ALLOCATIONS_ARM`
 | `cl_int[]`
 | Returns an array of valid register allocations for this device. Each of the
   returned values can be passed to the `-fregister-allocation` build option. +
   Missing before version 0.3.
+
+| {CL_DEVICE_MAX_WARP_COUNT_ARM}
+| {cl_uint_TYPE}
+| Returns the maximum number of warps per compute unit a kernel may use. The
+  value returned is an upper bound for any possible kernel. When
+  {CL_DEVICE_SCHEDULING_CONTROLS_CAPABILITIES_ARM} is not set, the call to
+  {clGetDeviceInfo} returns {CL_INVALID_VALUE}. +
+  Missing before version 0.4.
 |====
 
 --
@@ -225,9 +257,44 @@ or multiply (positive value) the batch size by 2. If the requested modification
 is not possible due to hardware constraints, the greatest possible modification
 will be used.
 
+| {CL_KERNEL_EXEC_INFO_WARP_COUNT_LIMIT_ARM}
+| {cl_uint_TYPE}
+| Limit the number of warps allowed to run in each compute unit for this kernel. +
+  The value passed must be greater than 0 and smaller than or equal to
+  {CL_KERNEL_MAX_WARP_COUNT_ARM}, otherwise the call to {clSetKernelExecInfo}
+  will fail and return {CL_INVALID_VALUE}. +
+  Missing before version 0.4.
+
+| {CL_KERNEL_EXEC_INFO_COMPUTE_UNIT_MAX_QUEUED_BATCHES_ARM}
+| {cl_uint_TYPE}
+| Limit the number of workgroup batches each compute unit can have in its queue. +
+  Acceptable values depend on the device. If a value not supported by the device
+  is passed, the call to {clSetKernelExecInfo} will fail and return {CL_INVALID_VALUE}.
+  All devices that support this functionality accept `0` to let the implementation
+  select the max number of queued workgroup batches. +
+  Missing before version 0.5.
 |====
 
 --
+
+(Add the following to Table 32, _List of supported param_names by *clGetKernelInfo*_) ::
++
+--
+
+[cols="1,1,4",options="header"]
+|====
+| Kernel Info
+| Return type
+| Description
+
+| {CL_KERNEL_MAX_WARP_COUNT_ARM}
+| {cl_uint_TYPE}
+| Returns the maximum number of warps this kernel can use per compute unit. +
+  Missing before version 0.4.
+|====
+
+--
+
 --
 
 == Interactions with Other Extensions
@@ -251,6 +318,8 @@ None.
 [options="header"]
 |====
 | Version | Date       | Author       | Changes
+| 0.5.0   | 2022-06-29 | Kévin Petit  | Add support for compute unit batch size queue control
+| 0.4.0   | 2022-02-28 | Kévin Petit  | Add support for warp throttling
 | 0.3.0   | 2021-01-19 | Kévin Petit  | Add support for register allocation control
 | 0.2.0   | 2020-09-14 | Kévin Petit  | Add support for deferred queue flush control
 | 0.1.0   | 2020-08-28 | Kévin Petit  | Initial version

xml/cl.xml

@@ -1232,7 +1232,9 @@ server's OpenCL/api-docs repository.
         <enum bitpos="2"            name="CL_DEVICE_SCHEDULING_WORKGROUP_BATCH_SIZE_MODIFIER_ARM"/>
         <enum bitpos="3"            name="CL_DEVICE_SCHEDULING_DEFERRED_FLUSH_ARM"/>
         <enum bitpos="4"            name="CL_DEVICE_SCHEDULING_REGISTER_ALLOCATION_ARM"/>
-            <unused start="5" end="63"/>
+        <enum bitpos="5"            name="CL_DEVICE_SCHEDULING_WARP_THROTTLING_ARM"/>
+        <enum bitpos="6"            name="CL_DEVICE_SCHEDULING_COMPUTE_UNIT_BATCH_QUEUE_SIZE_ARM"/>
+            <unused start="7" end="63"/>
     </enums>
 
     <enums name="cl_command_termination_reason_arm" vendor="Arm">
@@ -2151,14 +2153,17 @@ server's OpenCL/api-docs repository.
         <enum value="0x41E5"        name="CL_KERNEL_EXEC_INFO_WORKGROUP_BATCH_SIZE_ARM"/>
         <enum value="0x41E6"        name="CL_KERNEL_EXEC_INFO_WORKGROUP_BATCH_SIZE_MODIFIER_ARM"/>
         <enum value="0x41E7"        name="CL_QUEUE_KERNEL_BATCHING_ARM"/>
-            <unused start="0x41E8" end="0x41EA"/>
+        <enum value="0x41E8"        name="CL_KERNEL_EXEC_INFO_WARP_COUNT_LIMIT_ARM"/>
+        <enum value="0x41E9"        name="CL_KERNEL_MAX_WARP_COUNT_ARM"/>
+        <enum value="0x41EA"        name="CL_DEVICE_MAX_WARP_COUNT_ARM"/>
         <enum value="0x41EB"        name="CL_DEVICE_SUPPORTED_REGISTER_ALLOCATIONS_ARM"/>
         <enum value="0x41EC"        name="CL_QUEUE_DEFERRED_FLUSH_ARM"/>
         <enum value="0x41ED"        name="CL_EVENT_COMMAND_TERMINATION_REASON_ARM"/>
         <enum value="0x41EE"        name="CL_DEVICE_CONTROLLED_TERMINATION_CAPABILITIES_ARM"/>
         <enum value="0x41EF"        name="CL_IMPORT_ANDROID_HARDWARE_BUFFER_PLANE_INDEX_ARM"/>
         <enum value="0x41F0"        name="CL_IMPORT_ANDROID_HARDWARE_BUFFER_LAYER_INDEX_ARM"/>
-            <unused start="0x41F1" end="0x41FF"/>
+        <enum value="0x41F1"        name="CL_KERNEL_EXEC_INFO_COMPUTE_UNIT_MAX_QUEUED_BATCHES_ARM"/>
+            <unused start="0x41F2" end="0x41FF"/>
     </enums>
 
     <enums start="0x4200" end="0x420F" name="enums.4200" vendor="Intel">
@@ -6568,14 +6573,22 @@ server's OpenCL/api-docs repository.
                 <enum name="CL_DEVICE_SCHEDULING_WORKGROUP_BATCH_SIZE_MODIFIER_ARM"/>
                 <enum name="CL_DEVICE_SCHEDULING_DEFERRED_FLUSH_ARM"/>
                 <enum name="CL_DEVICE_SCHEDULING_REGISTER_ALLOCATION_ARM"/>
+                <enum name="CL_DEVICE_SCHEDULING_WARP_THROTTLING_ARM"/>
+                <enum name="CL_DEVICE_SCHEDULING_COMPUTE_UNIT_BATCH_QUEUE_SIZE_ARM"/>
             </require>
             <require comment="cl_device_info">
                 <enum name="CL_DEVICE_SCHEDULING_CONTROLS_CAPABILITIES_ARM"/>
                 <enum name="CL_DEVICE_SUPPORTED_REGISTER_ALLOCATIONS_ARM"/>
+                <enum name="CL_DEVICE_MAX_WARP_COUNT_ARM"/>
             </require>
             <require comment="cl_kernel_exec_info">
                 <enum name="CL_KERNEL_EXEC_INFO_WORKGROUP_BATCH_SIZE_ARM"/>
                 <enum name="CL_KERNEL_EXEC_INFO_WORKGROUP_BATCH_SIZE_MODIFIER_ARM"/>
+                <enum name="CL_KERNEL_EXEC_INFO_WARP_COUNT_LIMIT_ARM"/>
+                <enum name="CL_KERNEL_EXEC_INFO_COMPUTE_UNIT_MAX_QUEUED_BATCHES_ARM"/>
+            </require>
+            <require comment="cl_kernel_info">
+                <enum name="CL_KERNEL_MAX_WARP_COUNT_ARM"/>
             </require>
             <require comment="cl_queue_properties">
                 <enum name="CL_QUEUE_KERNEL_BATCHING_ARM"/>