Merge pull request #589 from kbenzie/benie/platform-get-last-error

[ur] Improve reporting of adapter specific errors

Author: kbenzie

include/ur.py

@@ -1820,7 +1820,6 @@ class ur_function_v(IntEnum):
     PLATFORM_GET_API_VERSION = 74                   ## Enumerator for ::urPlatformGetApiVersion
     PLATFORM_GET_NATIVE_HANDLE = 75                 ## Enumerator for ::urPlatformGetNativeHandle
     PLATFORM_CREATE_WITH_NATIVE_HANDLE = 76         ## Enumerator for ::urPlatformCreateWithNativeHandle
-    GET_LAST_RESULT = 77                            ## Enumerator for ::urGetLastResult
     PROGRAM_CREATE_WITH_IL = 78                     ## Enumerator for ::urProgramCreateWithIL
     PROGRAM_CREATE_WITH_BINARY = 79                 ## Enumerator for ::urProgramCreateWithBinary
     PROGRAM_BUILD = 80                              ## Enumerator for ::urProgramBuild
@@ -1890,6 +1889,7 @@ class ur_function_v(IntEnum):
     BINDLESS_IMAGES_DESTROY_EXTERNAL_SEMAPHORE_EXP = 147## Enumerator for ::urBindlessImagesDestroyExternalSemaphoreExp
     BINDLESS_IMAGES_WAIT_EXTERNAL_SEMAPHORE_EXP = 148   ## Enumerator for ::urBindlessImagesWaitExternalSemaphoreExp
     BINDLESS_IMAGES_SIGNAL_EXTERNAL_SEMAPHORE_EXP = 149 ## Enumerator for ::urBindlessImagesSignalExternalSemaphoreExp
+    PLATFORM_GET_LAST_ERROR = 150                   ## Enumerator for ::urPlatformGetLastError
 
 class ur_function_t(c_int):
     def __str__(self):
@@ -2025,6 +2025,13 @@ class ur_exp_command_buffer_handle_t(c_void_p):
 else:
     _urPlatformCreateWithNativeHandle_t = CFUNCTYPE( ur_result_t, ur_native_handle_t, POINTER(ur_platform_native_properties_t), POINTER(ur_platform_handle_t) )
 
+###############################################################################
+## @brief Function-pointer for urPlatformGetLastError
+if __use_win_types:
+    _urPlatformGetLastError_t = WINFUNCTYPE( ur_result_t, ur_platform_handle_t, POINTER(c_char_p), POINTER(c_long) )
+else:
+    _urPlatformGetLastError_t = CFUNCTYPE( ur_result_t, ur_platform_handle_t, POINTER(c_char_p), POINTER(c_long) )
+
 ###############################################################################
 ## @brief Function-pointer for urPlatformGetApiVersion
 if __use_win_types:
@@ -2048,6 +2055,7 @@ class ur_platform_dditable_t(Structure):
         ("pfnGetInfo", c_void_p),                                       ## _urPlatformGetInfo_t
         ("pfnGetNativeHandle", c_void_p),                               ## _urPlatformGetNativeHandle_t
         ("pfnCreateWithNativeHandle", c_void_p),                        ## _urPlatformCreateWithNativeHandle_t
+        ("pfnGetLastError", c_void_p),                                  ## _urPlatformGetLastError_t
         ("pfnGetApiVersion", c_void_p),                                 ## _urPlatformGetApiVersion_t
         ("pfnGetBackendOption", c_void_p)                               ## _urPlatformGetBackendOption_t
     ]
@@ -3167,13 +3175,6 @@ class ur_command_buffer_exp_dditable_t(Structure):
 else:
     _urInit_t = CFUNCTYPE( ur_result_t, ur_device_init_flags_t )
 
-###############################################################################
-## @brief Function-pointer for urGetLastResult
-if __use_win_types:
-    _urGetLastResult_t = WINFUNCTYPE( ur_result_t, ur_platform_handle_t, POINTER(c_char_p) )
-else:
-    _urGetLastResult_t = CFUNCTYPE( ur_result_t, ur_platform_handle_t, POINTER(c_char_p) )
-
 ###############################################################################
 ## @brief Function-pointer for urTearDown
 if __use_win_types:
@@ -3187,7 +3188,6 @@ class ur_command_buffer_exp_dditable_t(Structure):
 class ur_global_dditable_t(Structure):
     _fields_ = [
         ("pfnInit", c_void_p),                                          ## _urInit_t
-        ("pfnGetLastResult", c_void_p),                                 ## _urGetLastResult_t
         ("pfnTearDown", c_void_p)                                       ## _urTearDown_t
     ]
 
@@ -3318,6 +3318,7 @@ def __init__(self, version : ur_api_version_t):
         self.urPlatformGetInfo = _urPlatformGetInfo_t(self.__dditable.Platform.pfnGetInfo)
         self.urPlatformGetNativeHandle = _urPlatformGetNativeHandle_t(self.__dditable.Platform.pfnGetNativeHandle)
         self.urPlatformCreateWithNativeHandle = _urPlatformCreateWithNativeHandle_t(self.__dditable.Platform.pfnCreateWithNativeHandle)
+        self.urPlatformGetLastError = _urPlatformGetLastError_t(self.__dditable.Platform.pfnGetLastError)
         self.urPlatformGetApiVersion = _urPlatformGetApiVersion_t(self.__dditable.Platform.pfnGetApiVersion)
         self.urPlatformGetBackendOption = _urPlatformGetBackendOption_t(self.__dditable.Platform.pfnGetBackendOption)
 
@@ -3566,7 +3567,6 @@ def __init__(self, version : ur_api_version_t):
 
         # attach function interface to function address
         self.urInit = _urInit_t(self.__dditable.Global.pfnInit)
-        self.urGetLastResult = _urGetLastResult_t(self.__dditable.Global.pfnGetLastResult)
         self.urTearDown = _urTearDown_t(self.__dditable.Global.pfnTearDown)
 
         # call driver to get function pointers

include/ur_api.h

@@ -598,22 +598,37 @@ urPlatformGetBackendOption(
 );
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Retrieve string representation of the underlying adapter specific
-///        result reported by the the last API that returned
-///        UR_RESULT_ADAPTER_SPECIFIC. Allows for an adapter independent way to
-///        return an adapter specific result.
+/// @brief Get the last adapter specific error.
 ///
 /// @details
-///     - The string returned via the ppMessage is a NULL terminated C style
-///       string.
-///     - The string returned via the ppMessage is thread local.
-///     - The entry point will return UR_RESULT_SUCCESS if the result being
-///       reported is to be considered a warning. Any other result code returned
-///       indicates that the adapter specific result is an error.
-///     - The memory in the string returned via the ppMessage is owned by the
-///       adapter.
-///     - The application may call this function from simultaneous threads.
-///     - The implementation of this function should be lock-free.
+/// To be used after another entry-point has returned
+/// ::UR_RESULT_ERROR_ADAPTER_SPECIFIC in order to retrieve a message describing
+/// the circumstances of the underlying driver error and the error code
+/// returned by the failed driver entry-point.
+///
+/// * Implementations *must* store the message and error code in thread-local
+///   storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
+///
+/// * The message and error code storage is will only be valid if a previously
+///   called entry-point returned ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
+///
+/// * The memory pointed to by the C string returned in `ppMessage` is owned by
+///   the adapter and *must* be null terminated.
+///
+/// * The application *may* call this function from simultaneous threads.
+///
+/// * The implementation of this function *should* be lock-free.
+///
+/// Example usage:
+///
+/// ```cpp
+/// if (::urQueueCreate(hContext, hDevice, nullptr, &hQueue) ==
+///         ::UR_RESULT_ERROR_ADAPTER_SPECIFIC) {
+///     const char* pMessage;
+///     int32_t error;
+///     ::urPlatformGetLastError(hPlatform, &pMessage, &error);
+/// }
+/// ```
 ///
 /// @returns
 ///     - ::UR_RESULT_SUCCESS
@@ -623,11 +638,14 @@ urPlatformGetBackendOption(
 ///         + `NULL == hPlatform`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == ppMessage`
+///         + `NULL == pError`
 UR_APIEXPORT ur_result_t UR_APICALL
-urGetLastResult(
+urPlatformGetLastError(
     ur_platform_handle_t hPlatform, ///< [in] handle of the platform instance
-    const char **ppMessage          ///< [out] pointer to a string containing adapter specific result in string
-                                    ///< representation.
+    const char **ppMessage,         ///< [out] pointer to a C string where the adapter specific error message
+                                    ///< will be stored.
+    int32_t *pError                 ///< [out] pointer to an integer where the adapter specific error code will
+                                    ///< be stored.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -4771,7 +4789,6 @@ typedef enum ur_function_t {
     UR_FUNCTION_PLATFORM_GET_API_VERSION = 74,                                 ///< Enumerator for ::urPlatformGetApiVersion
     UR_FUNCTION_PLATFORM_GET_NATIVE_HANDLE = 75,                               ///< Enumerator for ::urPlatformGetNativeHandle
     UR_FUNCTION_PLATFORM_CREATE_WITH_NATIVE_HANDLE = 76,                       ///< Enumerator for ::urPlatformCreateWithNativeHandle
-    UR_FUNCTION_GET_LAST_RESULT = 77,                                          ///< Enumerator for ::urGetLastResult
     UR_FUNCTION_PROGRAM_CREATE_WITH_IL = 78,                                   ///< Enumerator for ::urProgramCreateWithIL
     UR_FUNCTION_PROGRAM_CREATE_WITH_BINARY = 79,                               ///< Enumerator for ::urProgramCreateWithBinary
     UR_FUNCTION_PROGRAM_BUILD = 80,                                            ///< Enumerator for ::urProgramBuild
@@ -4841,6 +4858,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_BINDLESS_IMAGES_DESTROY_EXTERNAL_SEMAPHORE_EXP = 147,          ///< Enumerator for ::urBindlessImagesDestroyExternalSemaphoreExp
     UR_FUNCTION_BINDLESS_IMAGES_WAIT_EXTERNAL_SEMAPHORE_EXP = 148,             ///< Enumerator for ::urBindlessImagesWaitExternalSemaphoreExp
     UR_FUNCTION_BINDLESS_IMAGES_SIGNAL_EXTERNAL_SEMAPHORE_EXP = 149,           ///< Enumerator for ::urBindlessImagesSignalExternalSemaphoreExp
+    UR_FUNCTION_PLATFORM_GET_LAST_ERROR = 150,                                 ///< Enumerator for ::urPlatformGetLastError
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -6954,6 +6972,16 @@ typedef struct ur_platform_create_with_native_handle_params_t {
     ur_platform_handle_t **pphPlatform;
 } ur_platform_create_with_native_handle_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urPlatformGetLastError
+/// @details Each entry is a pointer to the parameter passed to the function;
+///     allowing the callback the ability to modify the parameter's value
+typedef struct ur_platform_get_last_error_params_t {
+    ur_platform_handle_t *phPlatform;
+    const char ***pppMessage;
+    int32_t **ppError;
+} ur_platform_get_last_error_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urPlatformGetApiVersion
 /// @details Each entry is a pointer to the parameter passed to the function;
@@ -8489,15 +8517,6 @@ typedef struct ur_init_params_t {
     ur_device_init_flags_t *pdevice_flags;
 } ur_init_params_t;
 
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Function parameters for urGetLastResult
-/// @details Each entry is a pointer to the parameter passed to the function;
-///     allowing the callback the ability to modify the parameter's value
-typedef struct ur_get_last_result_params_t {
-    ur_platform_handle_t *phPlatform;
-    const char ***pppMessage;
-} ur_get_last_result_params_t;
-
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urTearDown
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_ddi.h

@@ -50,6 +50,13 @@ typedef ur_result_t(UR_APICALL *ur_pfnPlatformCreateWithNativeHandle_t)(
     const ur_platform_native_properties_t *,
     ur_platform_handle_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urPlatformGetLastError
+typedef ur_result_t(UR_APICALL *ur_pfnPlatformGetLastError_t)(
+    ur_platform_handle_t,
+    const char **,
+    int32_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urPlatformGetApiVersion
 typedef ur_result_t(UR_APICALL *ur_pfnPlatformGetApiVersion_t)(
@@ -70,6 +77,7 @@ typedef struct ur_platform_dditable_t {
     ur_pfnPlatformGetInfo_t pfnGetInfo;
     ur_pfnPlatformGetNativeHandle_t pfnGetNativeHandle;
     ur_pfnPlatformCreateWithNativeHandle_t pfnCreateWithNativeHandle;
+    ur_pfnPlatformGetLastError_t pfnGetLastError;
     ur_pfnPlatformGetApiVersion_t pfnGetApiVersion;
     ur_pfnPlatformGetBackendOption_t pfnGetBackendOption;
 } ur_platform_dditable_t;
@@ -1664,12 +1672,6 @@ typedef ur_result_t(UR_APICALL *ur_pfnGetCommandBufferExpProcAddrTable_t)(
 typedef ur_result_t(UR_APICALL *ur_pfnInit_t)(
     ur_device_init_flags_t);
 
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urGetLastResult
-typedef ur_result_t(UR_APICALL *ur_pfnGetLastResult_t)(
-    ur_platform_handle_t,
-    const char **);
-
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urTearDown
 typedef ur_result_t(UR_APICALL *ur_pfnTearDown_t)(
@@ -1679,7 +1681,6 @@ typedef ur_result_t(UR_APICALL *ur_pfnTearDown_t)(
 /// @brief Table of Global functions pointers
 typedef struct ur_global_dditable_t {
     ur_pfnInit_t pfnInit;
-    ur_pfnGetLastResult_t pfnGetLastResult;
     ur_pfnTearDown_t pfnTearDown;
 } ur_global_dditable_t;
 

scripts/core/platform.yml

@@ -222,33 +222,54 @@ returns:
       - "If `pFrontendOption` is not a valid frontend option."
 --- #--------------------------------------------------------------------------
 type: function
-desc: "Retrieve string representation of the underlying adapter specific result
-       reported by the the last API that returned UR_RESULT_ADAPTER_SPECIFIC.
-       Allows for an adapter independent way to return an adapter
-       specific result."
-class: $x
-name: GetLastResult
+desc: "Get the last adapter specific error."
+details: |
+    To be used after another entry-point has returned
+    $X_RESULT_ERROR_ADAPTER_SPECIFIC in order to retrieve a message describing
+    the circumstances of the underlying driver error and the error code
+    returned by the failed driver entry-point.
+
+    * Implementations *must* store the message and error code in thread-local
+      storage prior to returning $X_RESULT_ERROR_ADAPTER_SPECIFIC.
+
+    * The message and error code storage is will only be valid if a previously
+      called entry-point returned $X_RESULT_ERROR_ADAPTER_SPECIFIC.
+
+    * The memory pointed to by the C string returned in `ppMessage` is owned by
+      the adapter and *must* be null terminated.
+
+    * The application *may* call this function from simultaneous threads.
+
+    * The implementation of this function *should* be lock-free.
+
+    Example usage:
+
+    ```cpp
+    if ($xQueueCreate(hContext, hDevice, nullptr, &hQueue) ==
+            $X_RESULT_ERROR_ADAPTER_SPECIFIC) {
+        const char* pMessage;
+        int32_t error;
+        $xPlatformGetLastError(hPlatform, &pMessage, &error);
+    }
+    ```
+class: $xPlatform
+name: GetLastError
 decl: static
 ordinal: "0"
-details:
-    - "The string returned via the ppMessage is a NULL terminated C style string."
-    - "The string returned via the ppMessage is thread local."
-    - "The entry point will return UR_RESULT_SUCCESS if the result being
-       reported is to be considered a warning. Any other result code returned
-       indicates that the adapter specific result is an error."
-    -  "The memory in the string returned via the ppMessage is owned by the
-       adapter."
-    - "The application may call this function from simultaneous
-       threads."
-    - "The implementation of this function should be lock-free."
 params:
     - type: $x_platform_handle_t
       name: hPlatform
       desc: "[in] handle of the platform instance"
     - type: const char**
       name: ppMessage
-      desc: "[out] pointer to a string containing adapter specific result
-             in string representation."
+      desc: >
+          [out] pointer to a C string where the adapter specific error message
+          will be stored.
+    - type: int32_t*
+      name: pError
+      desc: >
+          [out] pointer to an integer where the adapter specific error code
+          will be stored.
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Identifies native backend adapters"

scripts/core/registry.yml

@@ -235,9 +235,6 @@ etors:
 - name: PLATFORM_CREATE_WITH_NATIVE_HANDLE
   desc: Enumerator for $xPlatformCreateWithNativeHandle
   value: '76'
-- name: GET_LAST_RESULT
-  desc: Enumerator for $xGetLastResult
-  value: '77'
 - name: PROGRAM_CREATE_WITH_IL
   desc: Enumerator for $xProgramCreateWithIL
   value: '78'
@@ -445,3 +442,6 @@ etors:
 - name: BINDLESS_IMAGES_SIGNAL_EXTERNAL_SEMAPHORE_EXP
   desc: Enumerator for $xBindlessImagesSignalExternalSemaphoreExp
   value: '149'
+- name: PLATFORM_GET_LAST_ERROR
+  desc: Enumerator for $xPlatformGetLastError
+  value: '150'

source/adapters/null/ur_nullddi.cpp

@@ -219,19 +219,22 @@ __urdlllocal ur_result_t UR_APICALL urPlatformGetBackendOption(
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Intercept function for urGetLastResult
-__urdlllocal ur_result_t UR_APICALL urGetLastResult(
+/// @brief Intercept function for urPlatformGetLastError
+__urdlllocal ur_result_t UR_APICALL urPlatformGetLastError(
     ur_platform_handle_t hPlatform, ///< [in] handle of the platform instance
     const char **
-        ppMessage ///< [out] pointer to a string containing adapter specific result in string
-                  ///< representation.
+        ppMessage, ///< [out] pointer to a C string where the adapter specific error message
+                   ///< will be stored.
+    int32_t *
+        pError ///< [out] pointer to an integer where the adapter specific error code will
+               ///< be stored.
     ) 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 pfnGetLastResult = d_context.urDdiTable.Global.pfnGetLastResult;
-    if (nullptr != pfnGetLastResult) {
-        result = pfnGetLastResult(hPlatform, ppMessage);
+    auto pfnGetLastError = d_context.urDdiTable.Platform.pfnGetLastError;
+    if (nullptr != pfnGetLastError) {
+        result = pfnGetLastError(hPlatform, ppMessage, pError);
     } else {
         // generic implementation
     }
@@ -4327,8 +4330,6 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetGlobalProcAddrTable(
 
     pDdiTable->pfnInit = driver::urInit;
 
-    pDdiTable->pfnGetLastResult = driver::urGetLastResult;
-
     pDdiTable->pfnTearDown = driver::urTearDown;
 
     return result;
@@ -4768,6 +4769,8 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetPlatformProcAddrTable(
     pDdiTable->pfnCreateWithNativeHandle =
         driver::urPlatformCreateWithNativeHandle;
 
+    pDdiTable->pfnGetLastError = driver::urPlatformGetLastError;
+
     pDdiTable->pfnGetApiVersion = driver::urPlatformGetApiVersion;
 
     pDdiTable->pfnGetBackendOption = driver::urPlatformGetBackendOption;