Merge pull request #873 from aarongreig/aaron/miscSpecFixes

Fix a few small spec issues
oneapi-src · Sep 19, 2023 · 1dc6a52 · 1dc6a52
2 parents dcbf226 + d47bd7e
commit 1dc6a52
Show file tree

Hide file tree

Showing 10 changed files with 32 additions and 19 deletions.
diff --git a/include/ur_api.h b/include/ur_api.h
@@ -946,6 +946,7 @@ typedef enum ur_adapter_backend_t {
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phAdapters`
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         + `NumEntries == 0 && phPlatforms != NULL`
 UR_APIEXPORT ur_result_t UR_APICALL
 urPlatformGet(
     ur_adapter_handle_t *phAdapters,   ///< [in][range(0, NumAdapters)] array of adapters to query for platforms.
@@ -5521,6 +5522,8 @@ urEventGetInfo(
 ///         + `NULL == hEvent`
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
 ///         + `::UR_PROFILING_INFO_COMMAND_COMPLETE < propName`
+///     - ::UR_RESULT_ERROR_PROFILING_INFO_NOT_AVAILABLE
+///         + If `hEvent`s associated queue was not created with `UR_QUEUE_FLAG_PROFILING_ENABLE`.
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
 ///         + `pPropValue && propSize == 0`
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT
@@ -6937,7 +6940,6 @@ urEnqueueReadHostPipe(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pipe_symbol`
 ///         + `NULL == pSrc`
-///         + `NULL == phEvent`
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
 ///         + `phEventWaitList == NULL && numEventsInWaitList > 0`
 ///         + `phEventWaitList != NULL && numEventsInWaitList == 0`
@@ -6958,7 +6960,7 @@ urEnqueueWriteHostPipe(
     const ur_event_handle_t *phEventWaitList, ///< [in][optional][range(0, numEventsInWaitList)] pointer to a list of
                                               ///< events that must be complete before the host pipe write.
                                               ///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
-    ur_event_handle_t *phEvent                ///< [out] returns an event object that identifies this write command
+    ur_event_handle_t *phEvent                ///< [out][optional] returns an event object that identifies this write command
                                               ///< and can be used to query or queue a wait for this command to complete.
 );
 

diff --git a/scripts/core/enqueue.yml b/scripts/core/enqueue.yml
@@ -1458,7 +1458,7 @@ params:
     - type: $x_event_handle_t*
       name: phEvent 
       desc: |
-            [out] returns an event object that identifies this write command 
+            [out][optional] returns an event object that identifies this write command
             and can be used to query or queue a wait for this command to complete.
 returns:
   - $X_RESULT_ERROR_INVALID_EVENT_WAIT_LIST:

diff --git a/scripts/core/event.yml b/scripts/core/event.yml
@@ -185,6 +185,8 @@ params:
       name: pPropSizeRet
       desc: "[out][optional] pointer to the actual size in bytes returned in propValue"
 returns:
+    - $X_RESULT_ERROR_PROFILING_INFO_NOT_AVAILABLE:
+      - "If `hEvent`s associated queue was not created with `UR_QUEUE_FLAG_PROFILING_ENABLE`."
     - $X_RESULT_ERROR_INVALID_VALUE:
       - "`pPropValue && propSize == 0`"
     - $X_RESULT_ERROR_INVALID_EVENT

diff --git a/scripts/core/platform.yml b/scripts/core/platform.yml
@@ -46,7 +46,8 @@ params:
       desc: |
             [out][optional] returns the total number of platforms available. 
 returns:
-    - $X_RESULT_ERROR_INVALID_SIZE
+    - $X_RESULT_ERROR_INVALID_SIZE:
+        - "`NumEntries == 0 && phPlatforms != NULL`"
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Supported platform info"

diff --git a/source/adapters/null/ur_nullddi.cpp b/source/adapters/null/ur_nullddi.cpp
@@ -3832,7 +3832,7 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
     ///< events that must be complete before the host pipe write.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
     ur_event_handle_t *
-        phEvent ///< [out] returns an event object that identifies this write command
+        phEvent ///< [out][optional] returns an event object that identifies this write command
     ///< and can be used to query or queue a wait for this command to complete.
     ) try {
     ur_result_t result = UR_RESULT_SUCCESS;
@@ -3845,7 +3845,9 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
                                   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;

diff --git a/source/loader/layers/tracing/ur_trcddi.cpp b/source/loader/layers/tracing/ur_trcddi.cpp
@@ -4338,7 +4338,7 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
     ///< events that must be complete before the host pipe write.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
     ur_event_handle_t *
-        phEvent ///< [out] returns an event object that identifies this write command
+        phEvent ///< [out][optional] returns an event object that identifies this write command
     ///< and can be used to query or queue a wait for this command to complete.
 ) {
     auto pfnWriteHostPipe = context.urDdiTable.Enqueue.pfnWriteHostPipe;

diff --git a/source/loader/layers/validation/ur_valddi.cpp b/source/loader/layers/validation/ur_valddi.cpp
@@ -214,6 +214,10 @@ __urdlllocal ur_result_t UR_APICALL urPlatformGet(
         if (NULL == phAdapters) {
             return UR_RESULT_ERROR_INVALID_NULL_POINTER;
         }
+
+        if (NumEntries == 0 && phPlatforms != NULL) {
+            return UR_RESULT_ERROR_INVALID_SIZE;
+        }
     }
 
     ur_result_t result =
@@ -5520,7 +5524,7 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
     ///< events that must be complete before the host pipe write.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
     ur_event_handle_t *
-        phEvent ///< [out] returns an event object that identifies this write command
+        phEvent ///< [out][optional] returns an event object that identifies this write command
     ///< and can be used to query or queue a wait for this command to complete.
 ) {
     auto pfnWriteHostPipe = context.urDdiTable.Enqueue.pfnWriteHostPipe;
@@ -5546,10 +5550,6 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
             return UR_RESULT_ERROR_INVALID_NULL_POINTER;
         }
 
-        if (NULL == phEvent) {
-            return UR_RESULT_ERROR_INVALID_NULL_POINTER;
-        }
-
         if (phEventWaitList == NULL && numEventsInWaitList > 0) {
             return UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST;
         }

diff --git a/source/loader/ur_ldrddi.cpp b/source/loader/ur_ldrddi.cpp
@@ -5271,7 +5271,7 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
     ///< events that must be complete before the host pipe write.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
     ur_event_handle_t *
-        phEvent ///< [out] returns an event object that identifies this write command
+        phEvent ///< [out][optional] returns an event object that identifies this write command
     ///< and can be used to query or queue a wait for this command to complete.
 ) {
     ur_result_t result = UR_RESULT_SUCCESS;
@@ -5308,8 +5308,10 @@ __urdlllocal ur_result_t UR_APICALL urEnqueueWriteHostPipe(
 
     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;
     }

diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp
@@ -453,6 +453,7 @@ ur_result_t UR_APICALL urAdapterGetInfo(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phAdapters`
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         + `NumEntries == 0 && phPlatforms != NULL`
 ur_result_t UR_APICALL urPlatformGet(
     ur_adapter_handle_t *
         phAdapters, ///< [in][range(0, NumAdapters)] array of adapters to query for platforms.
@@ -4332,6 +4333,8 @@ ur_result_t UR_APICALL urEventGetInfo(
 ///         + `NULL == hEvent`
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
 ///         + `::UR_PROFILING_INFO_COMMAND_COMPLETE < propName`
+///     - ::UR_RESULT_ERROR_PROFILING_INFO_NOT_AVAILABLE
+///         + If `hEvent`s associated queue was not created with `UR_QUEUE_FLAG_PROFILING_ENABLE`.
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
 ///         + `pPropValue && propSize == 0`
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT
@@ -6089,7 +6092,6 @@ ur_result_t UR_APICALL urEnqueueReadHostPipe(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pipe_symbol`
 ///         + `NULL == pSrc`
-///         + `NULL == phEvent`
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
 ///         + `phEventWaitList == NULL && numEventsInWaitList > 0`
 ///         + `phEventWaitList != NULL && numEventsInWaitList == 0`
@@ -6116,7 +6118,7 @@ ur_result_t UR_APICALL urEnqueueWriteHostPipe(
     ///< events that must be complete before the host pipe write.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
     ur_event_handle_t *
-        phEvent ///< [out] returns an event object that identifies this write command
+        phEvent ///< [out][optional] returns an event object that identifies this write command
     ///< and can be used to query or queue a wait for this command to complete.
     ) try {
     auto pfnWriteHostPipe =

diff --git a/source/ur_api.cpp b/source/ur_api.cpp
@@ -398,6 +398,7 @@ ur_result_t UR_APICALL urAdapterGetInfo(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phAdapters`
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         + `NumEntries == 0 && phPlatforms != NULL`
 ur_result_t UR_APICALL urPlatformGet(
     ur_adapter_handle_t *
         phAdapters, ///< [in][range(0, NumAdapters)] array of adapters to query for platforms.
@@ -3664,6 +3665,8 @@ ur_result_t UR_APICALL urEventGetInfo(
 ///         + `NULL == hEvent`
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
 ///         + `::UR_PROFILING_INFO_COMMAND_COMPLETE < propName`
+///     - ::UR_RESULT_ERROR_PROFILING_INFO_NOT_AVAILABLE
+///         + If `hEvent`s associated queue was not created with `UR_QUEUE_FLAG_PROFILING_ENABLE`.
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
 ///         + `pPropValue && propSize == 0`
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT
@@ -5181,7 +5184,6 @@ ur_result_t UR_APICALL urEnqueueReadHostPipe(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pipe_symbol`
 ///         + `NULL == pSrc`
-///         + `NULL == phEvent`
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
 ///         + `phEventWaitList == NULL && numEventsInWaitList > 0`
 ///         + `phEventWaitList != NULL && numEventsInWaitList == 0`
@@ -5208,7 +5210,7 @@ ur_result_t UR_APICALL urEnqueueWriteHostPipe(
     ///< events that must be complete before the host pipe write.
     ///< If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.
     ur_event_handle_t *
-        phEvent ///< [out] returns an event object that identifies this write command
+        phEvent ///< [out][optional] returns an event object that identifies this write command
     ///< and can be used to query or queue a wait for this command to complete.
 ) {
     ur_result_t result = UR_RESULT_SUCCESS;