From d05083c3a7b333ddb1a2d660354865b0aa5a35f4 Mon Sep 17 00:00:00 2001 From: "Kenneth Benzie (Benie)" Date: Fri, 9 Jun 2023 16:54:18 +0100 Subject: [PATCH] [ur] Imrpove reporting of adapter specific errors Remove the `urGetLastResult()` entry-point and replace it with `urPlatformGetLastError()`. This primary difference is the addition of the `pError` out parameter which returns an error code emitted from a failed driver entry-point which resulted in a Unified Runtime entry-point returning `UR_RESULT_ERROR_ADAPTER_SPECIFIC`. Fixes #500. --- include/ur.py | 20 ++--- include/ur_api.h | 73 ++++++++++++------- include/ur_ddi.h | 15 ++-- scripts/core/platform.yml | 59 ++++++++++----- scripts/core/registry.yml | 6 +- source/adapters/null/ur_nullddi.cpp | 21 +++--- source/common/ur_params.hpp | 50 +++++++------ source/loader/layers/tracing/ur_trcddi.cpp | 34 +++++---- source/loader/layers/validation/ur_valddi.cpp | 27 ++++--- source/loader/ur_ldrddi.cpp | 19 +++-- source/loader/ur_libapi.cpp | 59 ++++++++++----- source/ur_api.cpp | 53 +++++++++----- 12 files changed, 269 insertions(+), 167 deletions(-) diff --git a/include/ur.py b/include/ur.py index 0623ff56c5..5d7f3de79c 100644 --- a/include/ur.py +++ b/include/ur.py @@ -1817,7 +1817,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 @@ -1887,6 +1886,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): @@ -2022,6 +2022,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: @@ -2045,6 +2052,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 ] @@ -3164,13 +3172,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: @@ -3184,7 +3185,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 ] @@ -3315,6 +3315,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) @@ -3563,7 +3564,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 diff --git a/include/ur_api.h b/include/ur_api.h index 5c50c5e83f..3ff0b61ee6 100644 --- a/include/ur_api.h +++ b/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. ); /////////////////////////////////////////////////////////////////////////////// @@ -4768,7 +4786,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 @@ -4838,6 +4855,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 @@ -6951,6 +6969,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; @@ -8486,15 +8514,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; diff --git a/include/ur_ddi.h b/include/ur_ddi.h index a15c64a5e8..106f7deb11 100644 --- a/include/ur_ddi.h +++ b/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; diff --git a/scripts/core/platform.yml b/scripts/core/platform.yml index 6d0b696b9a..9dab95a68a 100644 --- a/scripts/core/platform.yml +++ b/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" diff --git a/scripts/core/registry.yml b/scripts/core/registry.yml index e70ed4d692..71718e5065 100644 --- a/scripts/core/registry.yml +++ b/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' diff --git a/source/adapters/null/ur_nullddi.cpp b/source/adapters/null/ur_nullddi.cpp index 4a6c8eaa84..7514d00516 100644 --- a/source/adapters/null/ur_nullddi.cpp +++ b/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; diff --git a/source/common/ur_params.hpp b/source/common/ur_params.hpp index aa4256dc98..dcd37fb126 100644 --- a/source/common/ur_params.hpp +++ b/source/common/ur_params.hpp @@ -8352,10 +8352,6 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) { os << "UR_FUNCTION_PLATFORM_CREATE_WITH_NATIVE_HANDLE"; break; - case UR_FUNCTION_GET_LAST_RESULT: - os << "UR_FUNCTION_GET_LAST_RESULT"; - break; - case UR_FUNCTION_PROGRAM_CREATE_WITH_IL: os << "UR_FUNCTION_PROGRAM_CREATE_WITH_IL"; break; @@ -8632,6 +8628,10 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) { case UR_FUNCTION_BINDLESS_IMAGES_SIGNAL_EXTERNAL_SEMAPHORE_EXP: os << "UR_FUNCTION_BINDLESS_IMAGES_SIGNAL_EXTERNAL_SEMAPHORE_EXP"; break; + + case UR_FUNCTION_PLATFORM_GET_LAST_ERROR: + os << "UR_FUNCTION_PLATFORM_GET_LAST_ERROR"; + break; default: os << "unknown enumerator"; break; @@ -8880,21 +8880,6 @@ inline std::ostream &operator<<(std::ostream &os, return os; } -inline std::ostream & -operator<<(std::ostream &os, const struct ur_get_last_result_params_t *params) { - - os << ".hPlatform = "; - - ur_params::serializePtr(os, *(params->phPlatform)); - - os << ", "; - os << ".ppMessage = "; - - ur_params::serializePtr(os, *(params->pppMessage)); - - return os; -} - inline std::ostream &operator<<(std::ostream &os, const struct ur_tear_down_params_t *params) { @@ -12201,6 +12186,27 @@ inline std::ostream &operator<<( return os; } +inline std::ostream & +operator<<(std::ostream &os, + const struct ur_platform_get_last_error_params_t *params) { + + os << ".hPlatform = "; + + ur_params::serializePtr(os, *(params->phPlatform)); + + os << ", "; + os << ".ppMessage = "; + + ur_params::serializePtr(os, *(params->pppMessage)); + + os << ", "; + os << ".pError = "; + + ur_params::serializePtr(os, *(params->ppError)); + + return os; +} + inline std::ostream & operator<<(std::ostream &os, const struct ur_platform_get_api_version_params_t *params) { @@ -13347,9 +13353,6 @@ inline int serializeFunctionParams(std::ostream &os, uint32_t function, case UR_FUNCTION_INIT: { os << (const struct ur_init_params_t *)params; } break; - case UR_FUNCTION_GET_LAST_RESULT: { - os << (const struct ur_get_last_result_params_t *)params; - } break; case UR_FUNCTION_TEAR_DOWN: { os << (const struct ur_tear_down_params_t *)params; } break; @@ -13673,6 +13676,9 @@ inline int serializeFunctionParams(std::ostream &os, uint32_t function, os << (const struct ur_platform_create_with_native_handle_params_t *) params; } break; + case UR_FUNCTION_PLATFORM_GET_LAST_ERROR: { + os << (const struct ur_platform_get_last_error_params_t *)params; + } break; case UR_FUNCTION_PLATFORM_GET_API_VERSION: { os << (const struct ur_platform_get_api_version_params_t *)params; } break; diff --git a/source/loader/layers/tracing/ur_trcddi.cpp b/source/loader/layers/tracing/ur_trcddi.cpp index 49503e8eba..637e832a92 100644 --- a/source/loader/layers/tracing/ur_trcddi.cpp +++ b/source/loader/layers/tracing/ur_trcddi.cpp @@ -248,27 +248,31 @@ __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. ) { - auto pfnGetLastResult = context.urDdiTable.Global.pfnGetLastResult; + auto pfnGetLastError = context.urDdiTable.Platform.pfnGetLastError; - if (nullptr == pfnGetLastResult) { + if (nullptr == pfnGetLastError) { return UR_RESULT_ERROR_UNSUPPORTED_FEATURE; } - ur_get_last_result_params_t params = {&hPlatform, &ppMessage}; - uint64_t instance = context.notify_begin(UR_FUNCTION_GET_LAST_RESULT, - "urGetLastResult", ¶ms); + ur_platform_get_last_error_params_t params = {&hPlatform, &ppMessage, + &pError}; + uint64_t instance = context.notify_begin( + UR_FUNCTION_PLATFORM_GET_LAST_ERROR, "urPlatformGetLastError", ¶ms); - ur_result_t result = pfnGetLastResult(hPlatform, ppMessage); + ur_result_t result = pfnGetLastError(hPlatform, ppMessage, pError); - context.notify_end(UR_FUNCTION_GET_LAST_RESULT, "urGetLastResult", ¶ms, - &result, instance); + context.notify_end(UR_FUNCTION_PLATFORM_GET_LAST_ERROR, + "urPlatformGetLastError", ¶ms, &result, instance); return result; } @@ -4955,9 +4959,6 @@ __urdlllocal ur_result_t UR_APICALL urGetGlobalProcAddrTable( dditable.pfnInit = pDdiTable->pfnInit; pDdiTable->pfnInit = ur_tracing_layer::urInit; - dditable.pfnGetLastResult = pDdiTable->pfnGetLastResult; - pDdiTable->pfnGetLastResult = ur_tracing_layer::urGetLastResult; - dditable.pfnTearDown = pDdiTable->pfnTearDown; pDdiTable->pfnTearDown = ur_tracing_layer::urTearDown; @@ -5531,6 +5532,9 @@ __urdlllocal ur_result_t UR_APICALL urGetPlatformProcAddrTable( pDdiTable->pfnCreateWithNativeHandle = ur_tracing_layer::urPlatformCreateWithNativeHandle; + dditable.pfnGetLastError = pDdiTable->pfnGetLastError; + pDdiTable->pfnGetLastError = ur_tracing_layer::urPlatformGetLastError; + dditable.pfnGetApiVersion = pDdiTable->pfnGetApiVersion; pDdiTable->pfnGetApiVersion = ur_tracing_layer::urPlatformGetApiVersion; diff --git a/source/loader/layers/validation/ur_valddi.cpp b/source/loader/layers/validation/ur_valddi.cpp index 52b7e96532..ee116936f0 100644 --- a/source/loader/layers/validation/ur_valddi.cpp +++ b/source/loader/layers/validation/ur_valddi.cpp @@ -267,16 +267,19 @@ __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. ) { - auto pfnGetLastResult = context.urDdiTable.Global.pfnGetLastResult; + auto pfnGetLastError = context.urDdiTable.Platform.pfnGetLastError; - if (nullptr == pfnGetLastResult) { + if (nullptr == pfnGetLastError) { return UR_RESULT_ERROR_UNSUPPORTED_FEATURE; } @@ -288,9 +291,13 @@ __urdlllocal ur_result_t UR_APICALL urGetLastResult( if (NULL == ppMessage) { return UR_RESULT_ERROR_INVALID_NULL_POINTER; } + + if (NULL == pError) { + return UR_RESULT_ERROR_INVALID_NULL_POINTER; + } } - ur_result_t result = pfnGetLastResult(hPlatform, ppMessage); + ur_result_t result = pfnGetLastError(hPlatform, ppMessage, pError); return result; } @@ -6183,9 +6190,6 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetGlobalProcAddrTable( dditable.pfnInit = pDdiTable->pfnInit; pDdiTable->pfnInit = ur_validation_layer::urInit; - dditable.pfnGetLastResult = pDdiTable->pfnGetLastResult; - pDdiTable->pfnGetLastResult = ur_validation_layer::urGetLastResult; - dditable.pfnTearDown = pDdiTable->pfnTearDown; pDdiTable->pfnTearDown = ur_validation_layer::urTearDown; @@ -6774,6 +6778,9 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetPlatformProcAddrTable( pDdiTable->pfnCreateWithNativeHandle = ur_validation_layer::urPlatformCreateWithNativeHandle; + dditable.pfnGetLastError = pDdiTable->pfnGetLastError; + pDdiTable->pfnGetLastError = ur_validation_layer::urPlatformGetLastError; + dditable.pfnGetApiVersion = pDdiTable->pfnGetApiVersion; pDdiTable->pfnGetApiVersion = ur_validation_layer::urPlatformGetApiVersion; diff --git a/source/loader/ur_ldrddi.cpp b/source/loader/ur_ldrddi.cpp index 366f9c3b52..4c5bf57ae3 100644 --- a/source/loader/ur_ldrddi.cpp +++ b/source/loader/ur_ldrddi.cpp @@ -308,20 +308,23 @@ __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. ) { ur_result_t result = UR_RESULT_SUCCESS; // extract platform's function pointer table auto dditable = reinterpret_cast(hPlatform)->dditable; - auto pfnGetLastResult = dditable->ur.Global.pfnGetLastResult; - if (nullptr == pfnGetLastResult) { + auto pfnGetLastError = dditable->ur.Platform.pfnGetLastError; + if (nullptr == pfnGetLastError) { return UR_RESULT_ERROR_UNINITIALIZED; } @@ -329,7 +332,7 @@ __urdlllocal ur_result_t UR_APICALL urGetLastResult( hPlatform = reinterpret_cast(hPlatform)->handle; // forward to device-platform - result = pfnGetLastResult(hPlatform, ppMessage); + result = pfnGetLastError(hPlatform, ppMessage, pError); return result; } @@ -6087,7 +6090,6 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetGlobalProcAddrTable( ur_loader::context->forceIntercept) { // return pointers to loader's DDIs pDdiTable->pfnInit = ur_loader::urInit; - pDdiTable->pfnGetLastResult = ur_loader::urGetLastResult; pDdiTable->pfnTearDown = ur_loader::urTearDown; } else { // return pointers directly to platform's DDIs @@ -6641,6 +6643,7 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetPlatformProcAddrTable( ur_loader::urPlatformGetNativeHandle; pDdiTable->pfnCreateWithNativeHandle = ur_loader::urPlatformCreateWithNativeHandle; + pDdiTable->pfnGetLastError = ur_loader::urPlatformGetLastError; pDdiTable->pfnGetApiVersion = ur_loader::urPlatformGetApiVersion; pDdiTable->pfnGetBackendOption = ur_loader::urPlatformGetBackendOption; diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp index 7cd7619951..bb2509cbee 100644 --- a/source/loader/ur_libapi.cpp +++ b/source/loader/ur_libapi.cpp @@ -325,22 +325,37 @@ ur_result_t UR_APICALL 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 @@ -350,18 +365,22 @@ ur_result_t UR_APICALL urPlatformGetBackendOption( /// + `NULL == hPlatform` /// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER /// + `NULL == ppMessage` -ur_result_t UR_APICALL urGetLastResult( +/// + `NULL == pError` +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 { - auto pfnGetLastResult = ur_lib::context->urDdiTable.Global.pfnGetLastResult; - if (nullptr == pfnGetLastResult) { + auto pfnGetLastError = ur_lib::context->urDdiTable.Platform.pfnGetLastError; + if (nullptr == pfnGetLastError) { return UR_RESULT_ERROR_UNINITIALIZED; } - return pfnGetLastResult(hPlatform, ppMessage); + return pfnGetLastError(hPlatform, ppMessage, pError); } catch (...) { return exceptionToResult(std::current_exception()); } diff --git a/source/ur_api.cpp b/source/ur_api.cpp index d1850ebfd1..ea6c71bf09 100644 --- a/source/ur_api.cpp +++ b/source/ur_api.cpp @@ -261,22 +261,37 @@ ur_result_t UR_APICALL 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 @@ -286,11 +301,15 @@ ur_result_t UR_APICALL urPlatformGetBackendOption( /// + `NULL == hPlatform` /// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER /// + `NULL == ppMessage` -ur_result_t UR_APICALL urGetLastResult( +/// + `NULL == pError` +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. ) { ur_result_t result = UR_RESULT_SUCCESS; return result;