Add experimental extension to query mem properties of sorting kernels

scripts/core/EXT_Exp_GroupAlgorithmMemory.rst

@@ -0,0 +1,71 @@
+<%
+import re
+from templates import helper as th
+%><%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+:orphan:
+
+.. _ZE_experimental_device_group_algorithm_memory_properties:
+
+========================================================
+Group Algorithm Memory Properties Experimental Extension
+========================================================
+
+API
+----
+
+* Enumerations
+
+    * ${x}_device_group_algorithm_memory_properties_exp_version_t
+    * ${x}_group_algorithm_type_exp_t
+    * ${x}_group_algorithm_memory_scope_exp_t
+
+* Structures
+
+
+    * ${x}_device_group_algorithm_memory_exp_properties_t
+
+* Functions
+
+
+    * ${x}DeviceGetGroupAlgorithmMemoryPropertiesExp
+
+
+Group Algorithm Memory Properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This extension allows applications to query for memory requirements of
+the underlying compiler when selecting a particular group algorithm in
+their kernels. Specifically, this extension returns the global memory
+size and shared local memory size that applications need to allocate
+and pass as a parameter to a group algorithm that requires additional
+memory.
+
+Three types of algorithms are available:
+
+${X}_GROUP_ALGORITHM_TYPE_EXP_SORT: sorting algorithm
+
+${X}_GROUP_ALGORITHM_TYPE_EXP_SCAN: scan algorithm
+
+${X}_GROUP_ALGORITHM_TYPE_EXP_REDUCE: reduce algorithm
+
+To know what amount of memory, application would call this extension as
+follows:
+
+.. parsed-literal::
+
+        ${x}_device_group_algorithm_memory_exp_properties_t groupAlgorithmMemoryProperties {};
+        groupAlgorithmMemoryProperties.stype = ${X}_STRUCTURE_TYPE_DEVICE_GROUP_ALGORITHM_MEMORY_EXP_PROPERTIES;
+        groupAlgorithmMemoryProperties.algorithm = ${X}_GROUP_ALGORITHM_TYPE_EXP_SORT;
+        groupAlgorithmMemoryProperties.memoryScope = ${X}_GROUP_ALGORITHM_MEMORY_SCOPE_EXP_SUBGROUP;
+
+        ${x}_result_t res = ${x}DeviceGetGroupAlgorithmMemoryPropertiesExp(hDevice, numOfElements, &groupAlgorithmMemoryProperties);
+
+
+Upon return, groupAlgorithmMemoryProperties will contain in
+globalMemorySize and sharedLocalMemorySize the global and
+shared local memory needed, respectively, for executing the selected
+algorithm in the target device.

scripts/core/common.yml

@@ -471,6 +471,10 @@ etors:
       desc: $x_memory_sub_allocations_exp_properties_t
       version: "1.5"
       value: "0x0002000D"
+    - name: DEVICE_GROUP_ALGORITHM_MEMORY_EXP_PROPERTIES
+      desc: $x_device_group_algorithm_memory_exp_properties_t
+      version: "1.6"
+      value: "0x0002000E"
     - name: COMMAND_GRAPH_EXP_DESC
       desc: $x_command_graph_exp_desc_t
       version: "2.0"

scripts/core/groupalgorithmmemory.yml

@@ -0,0 +1,93 @@
+#
+# Copyright (C) 2023 Intel Corporation
+#
+# SPDX-License-Identifier: MIT
+#
+# See YaML.md for syntax definition
+#
+--- #--------------------------------------------------------------------------
+type: header
+desc: "Intel $OneApi Level-Zero Extension APIs for Querying Memory Properties of Group Algorithms"
+version: "1.6"
+--- #--------------------------------------------------------------------------
+type: macro
+desc: "Group Algorithm Memory Properties Extension Name"
+version: "1.6"
+name: $X_DEVICE_GROUP_ALGORITHM_MEMORY_PROPERTIES_EXP_NAME
+value: '"$X_experimental_device_group_algorithm_memory_properties"'
+--- #--------------------------------------------------------------------------
+type: enum
+desc: "Group Algorithm Memory Properties version(s)"
+version: "1.6"
+name: $x_device_group_algorithm_memory_properties_exp_version_t
+etors:
+    - name: "1_0"
+      value: "$X_MAKE_VERSION( 1, 0 )"
+      desc: "version 1.0"
+--- #--------------------------------------------------------------------------
+type: enum
+desc: "Supported group algorithms to be used with $xDeviceGetGroupAlgorithmMemoryPropertiesExp"
+version: "1.6"
+class: $xDevice
+name: $x_group_algorithm_type_exp_t
+etors:
+    - name: SORT
+      value: "0"
+      desc: "sorting algorithm"
+    - name: SCAN
+      desc: "scan algorithm"
+    - name: REDUCE
+      desc: "reduce algorithm"
+--- #--------------------------------------------------------------------------
+type: enum
+desc: "Supported scopes in group algorithms to be used with $xDeviceGetGroupAlgorithmMemoryPropertiesExp"
+version: "1.6"
+class: $xDevice
+name: $x_group_algorithm_memory_scope_exp_t
+etors:
+    - name: SUBGROUP
+      value: "0"
+      desc: "memory scope limited to subgroup"
+    - name: WORKGROUP
+      desc: "memory scope limited to workgroup"
+--- #--------------------------------------------------------------------------
+type: struct
+desc: "Device Group Algorithm Memory Properties"
+version: "1.6"
+class: $xDevice
+name: $x_device_group_algorithm_memory_exp_properties_t
+base: $x_base_properties_t
+members:
+    - type: $x_group_algorithm_type_exp_t
+      name: "algorithm"
+      desc: "[in] Type of group algorithm"
+    - type: $x_group_algorithm_memory_scope_exp_t
+      name: "memoryScope"
+      desc: "[in] Memory scope of group algorithm"
+    - type: size_t
+      name: "globalMemorySize"
+      desc: "[out] global memory size"
+    - type: size_t
+      name: "sharedLocalMemorySize"
+      desc: "[out] shared local memory size"
+details:
+    - "This structure must be passed to $xDeviceGetGroupAlgorithmMemoryPropertiesExp to obtain the memory properties of a group algorithm."
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Retrieves memory properties of a group algorithm for the target device."
+class: $xDevice
+version: "1.6"
+name: GetGroupAlgorithmMemoryPropertiesExp
+details:
+    - "The application may call this function from simultaneous threads."
+    - "The implementation of this function should be lock-free."
+params:
+    - type: $x_device_handle_t
+      name: hDevice
+      desc: "[in] handle of the device"
+    - type: size_t
+      name: size
+      desc: "[in] number of elements to process"
+    - type: "$x_device_group_algorithm_memory_exp_properties_t*"
+      name: pGroupAlgorithmMemoryProperties
+      desc: "[in,out] query result for group algorithm memory properties"