Make phEvent optional in urEnqueueNativeCommandExp

When using the valuation layer in the SYCL RT for
intel/llvm#14145 it exposed an issue with
`phEvent` not being optional in the `urEnqueueNativeCommandExp` entry
point, however `nullptr` is passed to the argument in tests. This patch
makes `phEvent` optional, in line with other enqueue entry points.

Author: kbenzie

include/ur_api.h

@@ -9570,7 +9570,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
@@ -9590,7 +9589,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 `hugh.delaney@codeplay.com <hugh.delaney@codeplay.com>`_
+* Kenneth Benzie (Benie) `k.benzie@codeplay.com <k.benzie@codeplay.com>`_

scripts/core/enqueue.yml

@@ -1129,8 +1129,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
@@ -1178,8 +1177,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

@@ -5890,8 +5890,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;
 
@@ -5904,7 +5904,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

@@ -7874,8 +7874,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

@@ -9557,8 +9557,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;
@@ -9576,10 +9576,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

@@ -8128,8 +8128,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;
 
@@ -8169,8 +8169,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

@@ -8951,7 +8951,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
@@ -8975,8 +8974,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

@@ -7585,7 +7585,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
@@ -7609,8 +7608,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;