Merge pull request #571 from KseniyaTikhomirova/mem_obj_proposal

[UR] Proposal of new API for memory object properties
oneapi-src · Jun 15, 2023 · 7320835 · 7320835
2 parents aa5d052 + bee29ae
commit 7320835
Show file tree

Hide file tree

Showing 15 changed files with 117 additions and 20 deletions.
diff --git a/include/ur.py b/include/ur.py
@@ -233,6 +233,7 @@ class ur_structure_type_v(IntEnum):
     DEVICE_PARTITION_PROPERTIES = 26                ## ::ur_device_partition_properties_t
     EXP_COMMAND_BUFFER_DESC = 27                    ## ::ur_exp_command_buffer_desc_t
     EXP_SAMPLER_MIP_PROPERTIES = 28                 ## ::ur_exp_sampler_mip_properties_t
+    KERNEL_ARG_MEM_OBJ_PROPERTIES = 29              ## ::ur_kernel_arg_mem_obj_properties_t
 
 class ur_structure_type_t(c_int):
     def __str__(self):
@@ -1513,6 +1514,17 @@ def __str__(self):
         return str(ur_kernel_exec_info_v(self.value))
 
 
+###############################################################################
+## @brief Properties for for ::urKernelSetArgMemObj.
+class ur_kernel_arg_mem_obj_properties_t(Structure):
+    _fields_ = [
+        ("stype", ur_structure_type_t),                                 ## [in] type of this structure, must be
+                                                                        ## ::UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES
+        ("pNext", c_void_p),                                            ## [in,out][optional] pointer to extension-specific structure
+        ("memoryAccess", ur_mem_flags_t)                                ## [in] Memory access flag. Allowed values are: ::UR_MEM_FLAG_READ_WRITE,
+                                                                        ## ::UR_MEM_FLAG_WRITE_ONLY, ::UR_MEM_FLAG_READ_ONLY.
+    ]
+
 ###############################################################################
 ## @brief Properties for for ::urKernelCreateWithNativeHandle.
 class ur_kernel_native_properties_t(Structure):
@@ -2399,9 +2411,9 @@ class ur_program_dditable_t(Structure):
 ###############################################################################
 ## @brief Function-pointer for urKernelSetArgMemObj
 if __use_win_types:
-    _urKernelSetArgMemObj_t = WINFUNCTYPE( ur_result_t, ur_kernel_handle_t, c_ulong, ur_mem_handle_t )
+    _urKernelSetArgMemObj_t = WINFUNCTYPE( ur_result_t, ur_kernel_handle_t, c_ulong, POINTER(ur_kernel_arg_mem_obj_properties_t), ur_mem_handle_t )
 else:
-    _urKernelSetArgMemObj_t = CFUNCTYPE( ur_result_t, ur_kernel_handle_t, c_ulong, ur_mem_handle_t )
+    _urKernelSetArgMemObj_t = CFUNCTYPE( ur_result_t, ur_kernel_handle_t, c_ulong, POINTER(ur_kernel_arg_mem_obj_properties_t), ur_mem_handle_t )
 
 ###############################################################################
 ## @brief Function-pointer for urKernelSetSpecializationConstants

diff --git a/include/ur_api.h b/include/ur_api.h
@@ -257,6 +257,7 @@ typedef enum ur_structure_type_t {
     UR_STRUCTURE_TYPE_DEVICE_PARTITION_PROPERTIES = 26,     ///< ::ur_device_partition_properties_t
     UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC = 27,         ///< ::ur_exp_command_buffer_desc_t
     UR_STRUCTURE_TYPE_EXP_SAMPLER_MIP_PROPERTIES = 28,      ///< ::ur_exp_sampler_mip_properties_t
+    UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES = 29,   ///< ::ur_kernel_arg_mem_obj_properties_t
     /// @cond
     UR_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -3893,6 +3894,17 @@ urKernelSetArgSampler(
     ur_sampler_handle_t hArgValue ///< [in] handle of Sampler object.
 );
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Properties for for ::urKernelSetArgMemObj.
+typedef struct ur_kernel_arg_mem_obj_properties_t {
+    ur_structure_type_t stype;   ///< [in] type of this structure, must be
+                                 ///< ::UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES
+    void *pNext;                 ///< [in,out][optional] pointer to extension-specific structure
+    ur_mem_flags_t memoryAccess; ///< [in] Memory access flag. Allowed values are: ::UR_MEM_FLAG_READ_WRITE,
+                                 ///< ::UR_MEM_FLAG_WRITE_ONLY, ::UR_MEM_FLAG_READ_ONLY.
+
+} ur_kernel_arg_mem_obj_properties_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Set a Memory object as the argument value of a Kernel.
 ///
@@ -3910,9 +3922,10 @@ urKernelSetArgSampler(
 ///     - ::UR_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX
 UR_APIEXPORT ur_result_t UR_APICALL
 urKernelSetArgMemObj(
-    ur_kernel_handle_t hKernel, ///< [in] handle of the kernel object
-    uint32_t argIndex,          ///< [in] argument index in range [0, num args - 1]
-    ur_mem_handle_t hArgValue   ///< [in][optional] handle of Memory object.
+    ur_kernel_handle_t hKernel,                            ///< [in] handle of the kernel object
+    uint32_t argIndex,                                     ///< [in] argument index in range [0, num args - 1]
+    const ur_kernel_arg_mem_obj_properties_t *pProperties, ///< [in][optional] pointer to Memory object properties.
+    ur_mem_handle_t hArgValue                              ///< [in][optional] handle of Memory object.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -7432,6 +7445,7 @@ typedef struct ur_kernel_set_arg_sampler_params_t {
 typedef struct ur_kernel_set_arg_mem_obj_params_t {
     ur_kernel_handle_t *phKernel;
     uint32_t *pargIndex;
+    const ur_kernel_arg_mem_obj_properties_t **ppProperties;
     ur_mem_handle_t *phArgValue;
 } ur_kernel_set_arg_mem_obj_params_t;
 

diff --git a/include/ur_ddi.h b/include/ur_ddi.h
@@ -517,6 +517,7 @@ typedef ur_result_t(UR_APICALL *ur_pfnKernelSetArgSampler_t)(
 typedef ur_result_t(UR_APICALL *ur_pfnKernelSetArgMemObj_t)(
     ur_kernel_handle_t,
     uint32_t,
+    const ur_kernel_arg_mem_obj_properties_t *,
     ur_mem_handle_t);
 
 ///////////////////////////////////////////////////////////////////////////////

diff --git a/scripts/core/PROG.rst b/scripts/core/PROG.rst
@@ -216,9 +216,9 @@ explicit and implicit kernel arguments along with data needed for launch.
     // Create kernel object from program
     ${x}_kernel_handle_t hKernel;
     ${x}KernelCreate(hProgram, "addVectors", &hKernel);
-    ${x}KernelSetArgMemObj(hKernel, 0, A);
-    ${x}KernelSetArgMemObj(hKernel, 1, B);
-    ${x}KernelSetArgMemObj(hKernel, 2, C);
+    ${x}KernelSetArgMemObj(hKernel, 0, nullptr, A);
+    ${x}KernelSetArgMemObj(hKernel, 1, nullptr, B);
+    ${x}KernelSetArgMemObj(hKernel, 2, nullptr, C);
 
 Queue and Enqueue
 =================

diff --git a/scripts/core/common.yml b/scripts/core/common.yml
@@ -331,6 +331,8 @@ etors:
       desc: $x_exp_command_buffer_desc_t
     - name: EXP_SAMPLER_MIP_PROPERTIES
       desc: $x_exp_sampler_mip_properties_t
+    - name: KERNEL_ARG_MEM_OBJ_PROPERTIES
+      desc: $x_kernel_arg_mem_obj_properties_t
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Base for all properties types"

diff --git a/scripts/core/kernel.yml b/scripts/core/kernel.yml
@@ -358,6 +358,16 @@ params:
 returns:
     - $X_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX
 --- #--------------------------------------------------------------------------
+type: struct
+desc: "Properties for for $xKernelSetArgMemObj."
+class: $xKernel
+name: $x_kernel_arg_mem_obj_properties_t
+base: $x_base_properties_t
+members:
+    - type: $x_mem_flags_t
+      name: memoryAccess
+      desc: "[in] Memory access flag. Allowed values are: $X_MEM_FLAG_READ_WRITE, $X_MEM_FLAG_WRITE_ONLY, $X_MEM_FLAG_READ_ONLY."
+--- #--------------------------------------------------------------------------
 type: function
 desc: "Set a Memory object as the argument value of a Kernel."
 class: $xKernel
@@ -372,6 +382,9 @@ params:
     - type: "uint32_t"
       name: argIndex
       desc: "[in] argument index in range [0, num args - 1]"
+    - type: "const $x_kernel_arg_mem_obj_properties_t*"
+      name: pProperties
+      desc: "[in][optional] pointer to Memory object properties."
     - type: "$x_mem_handle_t"
       name: hArgValue
       desc: "[in][optional] handle of Memory object."

diff --git a/source/adapters/null/ur_nullddi.cpp b/source/adapters/null/ur_nullddi.cpp
@@ -1955,14 +1955,16 @@ __urdlllocal ur_result_t UR_APICALL urKernelSetArgSampler(
 __urdlllocal ur_result_t UR_APICALL urKernelSetArgMemObj(
     ur_kernel_handle_t hKernel, ///< [in] handle of the kernel object
     uint32_t argIndex, ///< [in] argument index in range [0, num args - 1]
+    const ur_kernel_arg_mem_obj_properties_t
+        *pProperties, ///< [in][optional] pointer to Memory object properties.
     ur_mem_handle_t hArgValue ///< [in][optional] handle of Memory object.
     ) try {
     ur_result_t result = UR_RESULT_SUCCESS;
 
     // if the driver has created a custom function, then call it instead of using the generic path
     auto pfnSetArgMemObj = d_context.urDdiTable.Kernel.pfnSetArgMemObj;
     if (nullptr != pfnSetArgMemObj) {
-        result = pfnSetArgMemObj(hKernel, argIndex, hArgValue);
+        result = pfnSetArgMemObj(hKernel, argIndex, pProperties, hArgValue);
     } else {
         // generic implementation
     }

diff --git a/source/common/ur_params.hpp b/source/common/ur_params.hpp
@@ -310,6 +310,9 @@ inline std::ostream &operator<<(std::ostream &os,
 inline std::ostream &operator<<(std::ostream &os,
                                 enum ur_kernel_exec_info_t value);
 inline std::ostream &
+operator<<(std::ostream &os,
+           const struct ur_kernel_arg_mem_obj_properties_t params);
+inline std::ostream &
 operator<<(std::ostream &os, const struct ur_kernel_native_properties_t params);
 inline std::ostream &operator<<(std::ostream &os, enum ur_queue_info_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_queue_flag_t value);
@@ -757,6 +760,10 @@ inline std::ostream &operator<<(std::ostream &os,
     case UR_STRUCTURE_TYPE_EXP_SAMPLER_MIP_PROPERTIES:
         os << "UR_STRUCTURE_TYPE_EXP_SAMPLER_MIP_PROPERTIES";
         break;
+
+    case UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES:
+        os << "UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -938,6 +945,12 @@ inline void serializeStruct(std::ostream &os, const void *ptr) {
             (const ur_exp_sampler_mip_properties_t *)ptr;
         ur_params::serializePtr(os, pstruct);
     } break;
+
+    case UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES: {
+        const ur_kernel_arg_mem_obj_properties_t *pstruct =
+            (const ur_kernel_arg_mem_obj_properties_t *)ptr;
+        ur_params::serializePtr(os, pstruct);
+    } break;
     default:
         os << "unknown enumerator";
         break;
@@ -7241,6 +7254,28 @@ inline void serializeTagged(std::ostream &os, const void *ptr,
 }
 } // namespace ur_params
 inline std::ostream &
+operator<<(std::ostream &os,
+           const struct ur_kernel_arg_mem_obj_properties_t params) {
+    os << "(struct ur_kernel_arg_mem_obj_properties_t){";
+
+    os << ".stype = ";
+
+    os << (params.stype);
+
+    os << ", ";
+    os << ".pNext = ";
+
+    ur_params::serializeStruct(os, (params.pNext));
+
+    os << ", ";
+    os << ".memoryAccess = ";
+
+    ur_params::serializeFlag<ur_mem_flag_t>(os, (params.memoryAccess));
+
+    os << "}";
+    return os;
+}
+inline std::ostream &
 operator<<(std::ostream &os,
            const struct ur_kernel_native_properties_t params) {
     os << "(struct ur_kernel_native_properties_t){";
@@ -11835,6 +11870,11 @@ operator<<(std::ostream &os,
 
     os << *(params->pargIndex);
 
+    os << ", ";
+    os << ".pProperties = ";
+
+    ur_params::serializePtr(os, *(params->ppProperties));
+
     os << ", ";
     os << ".hArgValue = ";
 

diff --git a/source/loader/layers/tracing/ur_trcddi.cpp b/source/loader/layers/tracing/ur_trcddi.cpp
@@ -2228,6 +2228,8 @@ __urdlllocal ur_result_t UR_APICALL urKernelSetArgSampler(
 __urdlllocal ur_result_t UR_APICALL urKernelSetArgMemObj(
     ur_kernel_handle_t hKernel, ///< [in] handle of the kernel object
     uint32_t argIndex, ///< [in] argument index in range [0, num args - 1]
+    const ur_kernel_arg_mem_obj_properties_t
+        *pProperties, ///< [in][optional] pointer to Memory object properties.
     ur_mem_handle_t hArgValue ///< [in][optional] handle of Memory object.
 ) {
     auto pfnSetArgMemObj = context.urDdiTable.Kernel.pfnSetArgMemObj;
@@ -2237,11 +2239,12 @@ __urdlllocal ur_result_t UR_APICALL urKernelSetArgMemObj(
     }
 
     ur_kernel_set_arg_mem_obj_params_t params = {&hKernel, &argIndex,
-                                                 &hArgValue};
+                                                 &pProperties, &hArgValue};
     uint64_t instance = context.notify_begin(UR_FUNCTION_KERNEL_SET_ARG_MEM_OBJ,
                                              "urKernelSetArgMemObj", &params);
 
-    ur_result_t result = pfnSetArgMemObj(hKernel, argIndex, hArgValue);
+    ur_result_t result =
+        pfnSetArgMemObj(hKernel, argIndex, pProperties, hArgValue);
 
     context.notify_end(UR_FUNCTION_KERNEL_SET_ARG_MEM_OBJ,
                        "urKernelSetArgMemObj", &params, &result, instance);

diff --git a/source/loader/layers/validation/ur_valddi.cpp b/source/loader/layers/validation/ur_valddi.cpp
@@ -2729,6 +2729,8 @@ __urdlllocal ur_result_t UR_APICALL urKernelSetArgSampler(
 __urdlllocal ur_result_t UR_APICALL urKernelSetArgMemObj(
     ur_kernel_handle_t hKernel, ///< [in] handle of the kernel object
     uint32_t argIndex, ///< [in] argument index in range [0, num args - 1]
+    const ur_kernel_arg_mem_obj_properties_t
+        *pProperties, ///< [in][optional] pointer to Memory object properties.
     ur_mem_handle_t hArgValue ///< [in][optional] handle of Memory object.
 ) {
     auto pfnSetArgMemObj = context.urDdiTable.Kernel.pfnSetArgMemObj;
@@ -2743,7 +2745,8 @@ __urdlllocal ur_result_t UR_APICALL urKernelSetArgMemObj(
         }
     }
 
-    ur_result_t result = pfnSetArgMemObj(hKernel, argIndex, hArgValue);
+    ur_result_t result =
+        pfnSetArgMemObj(hKernel, argIndex, pProperties, hArgValue);
 
     return result;
 }

diff --git a/source/loader/ur_ldrddi.cpp b/source/loader/ur_ldrddi.cpp
@@ -2569,6 +2569,8 @@ __urdlllocal ur_result_t UR_APICALL urKernelSetArgSampler(
 __urdlllocal ur_result_t UR_APICALL urKernelSetArgMemObj(
     ur_kernel_handle_t hKernel, ///< [in] handle of the kernel object
     uint32_t argIndex, ///< [in] argument index in range [0, num args - 1]
+    const ur_kernel_arg_mem_obj_properties_t
+        *pProperties, ///< [in][optional] pointer to Memory object properties.
     ur_mem_handle_t hArgValue ///< [in][optional] handle of Memory object.
 ) {
     ur_result_t result = UR_RESULT_SUCCESS;
@@ -2589,7 +2591,7 @@ __urdlllocal ur_result_t UR_APICALL urKernelSetArgMemObj(
                     : nullptr;
 
     // forward to device-platform
-    result = pfnSetArgMemObj(hKernel, argIndex, hArgValue);
+    result = pfnSetArgMemObj(hKernel, argIndex, pProperties, hArgValue);
 
     return result;
 }

diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp
@@ -3039,14 +3039,16 @@ ur_result_t UR_APICALL urKernelSetArgSampler(
 ur_result_t UR_APICALL urKernelSetArgMemObj(
     ur_kernel_handle_t hKernel, ///< [in] handle of the kernel object
     uint32_t argIndex, ///< [in] argument index in range [0, num args - 1]
+    const ur_kernel_arg_mem_obj_properties_t
+        *pProperties, ///< [in][optional] pointer to Memory object properties.
     ur_mem_handle_t hArgValue ///< [in][optional] handle of Memory object.
     ) try {
     auto pfnSetArgMemObj = ur_lib::context->urDdiTable.Kernel.pfnSetArgMemObj;
     if (nullptr == pfnSetArgMemObj) {
         return UR_RESULT_ERROR_UNINITIALIZED;
     }
 
-    return pfnSetArgMemObj(hKernel, argIndex, hArgValue);
+    return pfnSetArgMemObj(hKernel, argIndex, pProperties, hArgValue);
 } catch (...) {
     return exceptionToResult(std::current_exception());
 }

diff --git a/source/ur_api.cpp b/source/ur_api.cpp
@@ -2545,6 +2545,8 @@ ur_result_t UR_APICALL urKernelSetArgSampler(
 ur_result_t UR_APICALL urKernelSetArgMemObj(
     ur_kernel_handle_t hKernel, ///< [in] handle of the kernel object
     uint32_t argIndex, ///< [in] argument index in range [0, num args - 1]
+    const ur_kernel_arg_mem_obj_properties_t
+        *pProperties, ///< [in][optional] pointer to Memory object properties.
     ur_mem_handle_t hArgValue ///< [in][optional] handle of Memory object.
 ) {
     ur_result_t result = UR_RESULT_SUCCESS;

diff --git a/test/conformance/kernel/urKernelSetArgMemObj.cpp b/test/conformance/kernel/urKernelSetArgMemObj.cpp
@@ -26,19 +26,20 @@ struct urKernelSetArgMemObjTest : uur::urKernelTest {
 UUR_INSTANTIATE_KERNEL_TEST_SUITE_P(urKernelSetArgMemObjTest);
 
 TEST_P(urKernelSetArgMemObjTest, Success) {
-    ASSERT_SUCCESS(urKernelSetArgMemObj(kernel, 0, buffer));
+    ASSERT_SUCCESS(urKernelSetArgMemObj(kernel, 0, nullptr, buffer));
 }
 
 TEST_P(urKernelSetArgMemObjTest, InvalidNullHandleKernel) {
     ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_NULL_HANDLE,
-                     urKernelSetArgMemObj(nullptr, 0, buffer));
+                     urKernelSetArgMemObj(nullptr, 0, nullptr, buffer));
 }
 
 TEST_P(urKernelSetArgMemObjTest, InvalidKernelArgumentIndex) {
     size_t num_kernel_args = 0;
     ASSERT_SUCCESS(urKernelGetInfo(kernel, UR_KERNEL_INFO_NUM_ARGS,
                                    sizeof(num_kernel_args), &num_kernel_args,
                                    nullptr));
-    ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX,
-                     urKernelSetArgMemObj(kernel, num_kernel_args + 1, buffer));
+    ASSERT_EQ_RESULT(
+        UR_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX,
+        urKernelSetArgMemObj(kernel, num_kernel_args + 1, nullptr, buffer));
 }
diff --git a/test/conformance/testing/include/uur/fixtures.h b/test/conformance/testing/include/uur/fixtures.h
@@ -696,8 +696,8 @@ struct urKernelExecutionTest : urKernelTest {
                                               sizeof(zero), 0, size, 0, nullptr,
                                               nullptr));
         ASSERT_SUCCESS(urQueueFinish(queue));
-        ASSERT_SUCCESS(
-            urKernelSetArgMemObj(kernel, current_arg_index, mem_handle));
+        ASSERT_SUCCESS(urKernelSetArgMemObj(kernel, current_arg_index, nullptr,
+                                            mem_handle));
 
         // This emulates the offset struct sycl adds for a 1D buffer accessor.
         struct {