Merge pull request #1846 from kbenzie/benie/fix-native-command-phevent

Make phEvent optional in urEnqueueNativeCommandExp

Author: kbenzie

include/ur_api.h

@@ -9578,7 +9578,6 @@ typedef void (*ur_exp_enqueue_native_command_function_t)(
 ///         + `NULL == hQueue`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pfnNativeEnqueue`
-///         + `NULL == phEvent`
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
 ///         + `NULL != pProperties && ::UR_EXP_ENQUEUE_NATIVE_COMMAND_FLAGS_MASK & pProperties->flags`
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
@@ -9598,7 +9597,7 @@ urEnqueueNativeCommandExp(
     const ur_event_handle_t *phEventWaitList,                      ///< [in][optional][range(0, numEventsInWaitList)] pointer to a list of
                                                                    ///< events that must be complete before the kernel execution.
                                                                    ///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
-    ur_event_handle_t *phEvent                                     ///< [in,out] return an event object that identifies the work that has
+    ur_event_handle_t *phEvent                                     ///< [out][optional] return an event object that identifies the work that has
                                                                    ///< been enqueued in nativeEnqueueFunc.
 );
 

scripts/core/EXP-NATIVE-ENQUEUE.rst

@@ -65,11 +65,13 @@ Functions
 Changelog
 --------------------------------------------------------------------------------
 
-+-----------+------------------------+
-| Revision  | Changes                |
-+===========+========================+
-| 1.0       | Initial Draft          |
-+-----------+------------------------+
++-----------+-------------------------+
+| Revision  | Changes                 |
++===========+=========================+
+| 1.0       | Initial Draft           |
++-----------+-------------------------+
+| 1.1       | Make `phEvent` optional |
++-----------+-------------------------+
 
 
 Support
@@ -83,3 +85,4 @@ Contributors
 --------------------------------------------------------------------------------
 
 * Hugh Delaney `[email protected] <[email protected]>`_
+* Kenneth Benzie (Benie) `[email protected] <[email protected]>`_

scripts/core/enqueue.yml

@@ -1128,8 +1128,7 @@ class: $xEnqueue
 name: USMPrefetch
 ordinal: "0"
 details:
-    - "Prefetching may not be supported for all devices or allocation types. If memory prefetching 
-    is not supported, the prefetch hint will be ignored."
+    - "Prefetching may not be supported for all devices or allocation types. If memory prefetching is not supported, the prefetch hint will be ignored."
 params:
     - type: $x_queue_handle_t
       name: hQueue
@@ -1177,8 +1176,7 @@ class: $xEnqueue
 name: USMAdvise
 ordinal: "0"
 details:
-    - "Not all memory advice hints may be supported for all devices or allocation types. 
-    If a memory advice hint is not supported, it will be ignored."
+    - "Not all memory advice hints may be supported for all devices or allocation types. If a memory advice hint is not supported, it will be ignored."
 params:
     - type: $x_queue_handle_t
       name: hQueue

scripts/core/exp-native-enqueue.yml

@@ -111,7 +111,7 @@ params:
     - type: $x_event_handle_t*
       name: phEvent
       desc: |
-            [in,out] return an event object that identifies the work that has
+            [out][optional] return an event object that identifies the work that has
             been enqueued in nativeEnqueueFunc.
 returns:
     - $X_RESULT_ERROR_INVALID_NULL_HANDLE

source/adapters/null/ur_nullddi.cpp

@@ -5896,8 +5896,8 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueNativeCommandExp(
     ///< events that must be complete before the kernel execution.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
     ur_event_handle_t *
-        phEvent ///< [in,out] return an event object that identifies the work that has
-                ///< been enqueued in nativeEnqueueFunc.
+        phEvent ///< [out][optional] return an event object that identifies the work that has
+    ///< been enqueued in nativeEnqueueFunc.
     ) try {
     ur_result_t result = UR_RESULT_SUCCESS;
 
@@ -5910,7 +5910,9 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueNativeCommandExp(
             pProperties, numEventsInWaitList, phEventWaitList, phEvent);
     } else {
         // generic implementation
-        *phEvent = reinterpret_cast<ur_event_handle_t>(d_context.get());
+        if (nullptr != phEvent) {
+            *phEvent = reinterpret_cast<ur_event_handle_t>(d_context.get());
+        }
     }
 
     return result;

source/loader/layers/tracing/ur_trcddi.cpp

@@ -7880,8 +7880,8 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueNativeCommandExp(
     ///< events that must be complete before the kernel execution.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
     ur_event_handle_t *
-        phEvent ///< [in,out] return an event object that identifies the work that has
-                ///< been enqueued in nativeEnqueueFunc.
+        phEvent ///< [out][optional] return an event object that identifies the work that has
+    ///< been enqueued in nativeEnqueueFunc.
 ) {
     auto pfnNativeCommandExp =
         context.urDdiTable.EnqueueExp.pfnNativeCommandExp;

source/loader/layers/validation/ur_valddi.cpp

@@ -9555,8 +9555,8 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueNativeCommandExp(
     ///< events that must be complete before the kernel execution.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
     ur_event_handle_t *
-        phEvent ///< [in,out] return an event object that identifies the work that has
-                ///< been enqueued in nativeEnqueueFunc.
+        phEvent ///< [out][optional] return an event object that identifies the work that has
+    ///< been enqueued in nativeEnqueueFunc.
 ) {
     auto pfnNativeCommandExp =
         context.urDdiTable.EnqueueExp.pfnNativeCommandExp;
@@ -9574,10 +9574,6 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueNativeCommandExp(
             return UR_RESULT_ERROR_INVALID_NULL_POINTER;
         }
 
-        if (NULL == phEvent) {
-            return UR_RESULT_ERROR_INVALID_NULL_POINTER;
-        }
-
         if (NULL != pProperties &&
             UR_EXP_ENQUEUE_NATIVE_COMMAND_FLAGS_MASK & pProperties->flags) {
             return UR_RESULT_ERROR_INVALID_ENUMERATION;

source/loader/ur_ldrddi.cpp

@@ -8130,8 +8130,8 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueNativeCommandExp(
     ///< events that must be complete before the kernel execution.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
     ur_event_handle_t *
-        phEvent ///< [in,out] return an event object that identifies the work that has
-                ///< been enqueued in nativeEnqueueFunc.
+        phEvent ///< [out][optional] return an event object that identifies the work that has
+    ///< been enqueued in nativeEnqueueFunc.
 ) {
     ur_result_t result = UR_RESULT_SUCCESS;
 
@@ -8171,8 +8171,10 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueNativeCommandExp(
 
     try {
         // convert platform handle to loader handle
-        *phEvent = reinterpret_cast<ur_event_handle_t>(
-            ur_event_factory.getInstance(*phEvent, dditable));
+        if (nullptr != phEvent) {
+            *phEvent = reinterpret_cast<ur_event_handle_t>(
+                ur_event_factory.getInstance(*phEvent, dditable));
+        }
     } catch (std::bad_alloc &) {
         result = UR_RESULT_ERROR_OUT_OF_HOST_MEMORY;
     }

source/loader/ur_libapi.cpp

@@ -8965,7 +8965,6 @@ ur_result_t UR_APICALL urUsmP2PPeerAccessGetInfoExp(
 ///         + `NULL == hQueue`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pfnNativeEnqueue`
-///         + `NULL == phEvent`
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
 ///         + `NULL != pProperties && ::UR_EXP_ENQUEUE_NATIVE_COMMAND_FLAGS_MASK & pProperties->flags`
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
@@ -8989,8 +8988,8 @@ ur_result_t UR_APICALL urEnqueueNativeCommandExp(
     ///< events that must be complete before the kernel execution.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
     ur_event_handle_t *
-        phEvent ///< [in,out] return an event object that identifies the work that has
-                ///< been enqueued in nativeEnqueueFunc.
+        phEvent ///< [out][optional] return an event object that identifies the work that has
+    ///< been enqueued in nativeEnqueueFunc.
     ) try {
     auto pfnNativeCommandExp =
         ur_lib::context->urDdiTable.EnqueueExp.pfnNativeCommandExp;

source/ur_api.cpp

@@ -7593,7 +7593,6 @@ ur_result_t UR_APICALL urUsmP2PPeerAccessGetInfoExp(
 ///         + `NULL == hQueue`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pfnNativeEnqueue`
-///         + `NULL == phEvent`
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
 ///         + `NULL != pProperties && ::UR_EXP_ENQUEUE_NATIVE_COMMAND_FLAGS_MASK & pProperties->flags`
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
@@ -7617,8 +7616,8 @@ ur_result_t UR_APICALL urEnqueueNativeCommandExp(
     ///< events that must be complete before the kernel execution.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
     ur_event_handle_t *
-        phEvent ///< [in,out] return an event object that identifies the work that has
-                ///< been enqueued in nativeEnqueueFunc.
+        phEvent ///< [out][optional] return an event object that identifies the work that has
+    ///< been enqueued in nativeEnqueueFunc.
 ) {
     ur_result_t result = UR_RESULT_SUCCESS;
     return result;