Skip to content

Commit d05083c

Browse files
kbenziekbenzie
committed
[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.
1 parent 1b3c5ab commit d05083c

File tree

12 files changed

+269
-167
lines changed

12 files changed

+269
-167
lines changed

‎include/ur.py

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1817,7 +1817,6 @@ class ur_function_v(IntEnum):
18171817
PLATFORM_GET_API_VERSION = 74 ## Enumerator for ::urPlatformGetApiVersion
18181818
PLATFORM_GET_NATIVE_HANDLE = 75 ## Enumerator for ::urPlatformGetNativeHandle
18191819
PLATFORM_CREATE_WITH_NATIVE_HANDLE = 76 ## Enumerator for ::urPlatformCreateWithNativeHandle
1820-
GET_LAST_RESULT = 77 ## Enumerator for ::urGetLastResult
18211820
PROGRAM_CREATE_WITH_IL = 78 ## Enumerator for ::urProgramCreateWithIL
18221821
PROGRAM_CREATE_WITH_BINARY = 79 ## Enumerator for ::urProgramCreateWithBinary
18231822
PROGRAM_BUILD = 80 ## Enumerator for ::urProgramBuild
@@ -1887,6 +1886,7 @@ class ur_function_v(IntEnum):
18871886
BINDLESS_IMAGES_DESTROY_EXTERNAL_SEMAPHORE_EXP = 147## Enumerator for ::urBindlessImagesDestroyExternalSemaphoreExp
18881887
BINDLESS_IMAGES_WAIT_EXTERNAL_SEMAPHORE_EXP = 148 ## Enumerator for ::urBindlessImagesWaitExternalSemaphoreExp
18891888
BINDLESS_IMAGES_SIGNAL_EXTERNAL_SEMAPHORE_EXP = 149 ## Enumerator for ::urBindlessImagesSignalExternalSemaphoreExp
1889+
PLATFORM_GET_LAST_ERROR = 150 ## Enumerator for ::urPlatformGetLastError
18901890

18911891
class ur_function_t(c_int):
18921892
def __str__(self):
@@ -2022,6 +2022,13 @@ class ur_exp_command_buffer_handle_t(c_void_p):
20222022
else:
20232023
_urPlatformCreateWithNativeHandle_t = CFUNCTYPE( ur_result_t, ur_native_handle_t, POINTER(ur_platform_native_properties_t), POINTER(ur_platform_handle_t) )
20242024

2025+
###############################################################################
2026+
## @brief Function-pointer for urPlatformGetLastError
2027+
if __use_win_types:
2028+
_urPlatformGetLastError_t = WINFUNCTYPE( ur_result_t, ur_platform_handle_t, POINTER(c_char_p), POINTER(c_long) )
2029+
else:
2030+
_urPlatformGetLastError_t = CFUNCTYPE( ur_result_t, ur_platform_handle_t, POINTER(c_char_p), POINTER(c_long) )
2031+
20252032
###############################################################################
20262033
## @brief Function-pointer for urPlatformGetApiVersion
20272034
if __use_win_types:
@@ -2045,6 +2052,7 @@ class ur_platform_dditable_t(Structure):
20452052
("pfnGetInfo", c_void_p), ## _urPlatformGetInfo_t
20462053
("pfnGetNativeHandle", c_void_p), ## _urPlatformGetNativeHandle_t
20472054
("pfnCreateWithNativeHandle", c_void_p), ## _urPlatformCreateWithNativeHandle_t
2055+
("pfnGetLastError", c_void_p), ## _urPlatformGetLastError_t
20482056
("pfnGetApiVersion", c_void_p), ## _urPlatformGetApiVersion_t
20492057
("pfnGetBackendOption", c_void_p) ## _urPlatformGetBackendOption_t
20502058
]
@@ -3164,13 +3172,6 @@ class ur_command_buffer_exp_dditable_t(Structure):
31643172
else:
31653173
_urInit_t = CFUNCTYPE( ur_result_t, ur_device_init_flags_t )
31663174

3167-
###############################################################################
3168-
## @brief Function-pointer for urGetLastResult
3169-
if __use_win_types:
3170-
_urGetLastResult_t = WINFUNCTYPE( ur_result_t, ur_platform_handle_t, POINTER(c_char_p) )
3171-
else:
3172-
_urGetLastResult_t = CFUNCTYPE( ur_result_t, ur_platform_handle_t, POINTER(c_char_p) )
3173-
31743175
###############################################################################
31753176
## @brief Function-pointer for urTearDown
31763177
if __use_win_types:
@@ -3184,7 +3185,6 @@ class ur_command_buffer_exp_dditable_t(Structure):
31843185
class ur_global_dditable_t(Structure):
31853186
_fields_ = [
31863187
("pfnInit", c_void_p), ## _urInit_t
3187-
("pfnGetLastResult", c_void_p), ## _urGetLastResult_t
31883188
("pfnTearDown", c_void_p) ## _urTearDown_t
31893189
]
31903190

@@ -3315,6 +3315,7 @@ def __init__(self, version : ur_api_version_t):
33153315
self.urPlatformGetInfo = _urPlatformGetInfo_t(self.__dditable.Platform.pfnGetInfo)
33163316
self.urPlatformGetNativeHandle = _urPlatformGetNativeHandle_t(self.__dditable.Platform.pfnGetNativeHandle)
33173317
self.urPlatformCreateWithNativeHandle = _urPlatformCreateWithNativeHandle_t(self.__dditable.Platform.pfnCreateWithNativeHandle)
3318+
self.urPlatformGetLastError = _urPlatformGetLastError_t(self.__dditable.Platform.pfnGetLastError)
33183319
self.urPlatformGetApiVersion = _urPlatformGetApiVersion_t(self.__dditable.Platform.pfnGetApiVersion)
33193320
self.urPlatformGetBackendOption = _urPlatformGetBackendOption_t(self.__dditable.Platform.pfnGetBackendOption)
33203321

@@ -3563,7 +3564,6 @@ def __init__(self, version : ur_api_version_t):
35633564

35643565
# attach function interface to function address
35653566
self.urInit = _urInit_t(self.__dditable.Global.pfnInit)
3566-
self.urGetLastResult = _urGetLastResult_t(self.__dditable.Global.pfnGetLastResult)
35673567
self.urTearDown = _urTearDown_t(self.__dditable.Global.pfnTearDown)
35683568

35693569
# call driver to get function pointers

‎include/ur_api.h

Lines changed: 46 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -598,22 +598,37 @@ urPlatformGetBackendOption(
598598
);
599599

600600
///////////////////////////////////////////////////////////////////////////////
601-
/// @brief Retrieve string representation of the underlying adapter specific
602-
/// result reported by the the last API that returned
603-
/// UR_RESULT_ADAPTER_SPECIFIC. Allows for an adapter independent way to
604-
/// return an adapter specific result.
601+
/// @brief Get the last adapter specific error.
605602
///
606603
/// @details
607-
/// - The string returned via the ppMessage is a NULL terminated C style
608-
/// string.
609-
/// - The string returned via the ppMessage is thread local.
610-
/// - The entry point will return UR_RESULT_SUCCESS if the result being
611-
/// reported is to be considered a warning. Any other result code returned
612-
/// indicates that the adapter specific result is an error.
613-
/// - The memory in the string returned via the ppMessage is owned by the
614-
/// adapter.
615-
/// - The application may call this function from simultaneous threads.
616-
/// - The implementation of this function should be lock-free.
604+
/// To be used after another entry-point has returned
605+
/// ::UR_RESULT_ERROR_ADAPTER_SPECIFIC in order to retrieve a message describing
606+
/// the circumstances of the underlying driver error and the error code
607+
/// returned by the failed driver entry-point.
608+
///
609+
/// * Implementations *must* store the message and error code in thread-local
610+
/// storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
611+
///
612+
/// * The message and error code storage is will only be valid if a previously
613+
/// called entry-point returned ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
614+
///
615+
/// * The memory pointed to by the C string returned in `ppMessage` is owned by
616+
/// the adapter and *must* be null terminated.
617+
///
618+
/// * The application *may* call this function from simultaneous threads.
619+
///
620+
/// * The implementation of this function *should* be lock-free.
621+
///
622+
/// Example usage:
623+
///
624+
/// ```cpp
625+
/// if (::urQueueCreate(hContext, hDevice, nullptr, &hQueue) ==
626+
/// ::UR_RESULT_ERROR_ADAPTER_SPECIFIC) {
627+
/// const char* pMessage;
628+
/// int32_t error;
629+
/// ::urPlatformGetLastError(hPlatform, &pMessage, &error);
630+
/// }
631+
/// ```
617632
///
618633
/// @returns
619634
/// - ::UR_RESULT_SUCCESS
@@ -623,11 +638,14 @@ urPlatformGetBackendOption(
623638
/// + `NULL == hPlatform`
624639
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
625640
/// + `NULL == ppMessage`
641+
/// + `NULL == pError`
626642
UR_APIEXPORT ur_result_t UR_APICALL
627-
urGetLastResult(
643+
urPlatformGetLastError(
628644
ur_platform_handle_t hPlatform, ///< [in] handle of the platform instance
629-
const char **ppMessage ///< [out] pointer to a string containing adapter specific result in string
630-
///< representation.
645+
const char **ppMessage, ///< [out] pointer to a C string where the adapter specific error message
646+
///< will be stored.
647+
int32_t *pError ///< [out] pointer to an integer where the adapter specific error code will
648+
///< be stored.
631649
);
632650

633651
///////////////////////////////////////////////////////////////////////////////
@@ -4768,7 +4786,6 @@ typedef enum ur_function_t {
47684786
UR_FUNCTION_PLATFORM_GET_API_VERSION = 74, ///< Enumerator for ::urPlatformGetApiVersion
47694787
UR_FUNCTION_PLATFORM_GET_NATIVE_HANDLE = 75, ///< Enumerator for ::urPlatformGetNativeHandle
47704788
UR_FUNCTION_PLATFORM_CREATE_WITH_NATIVE_HANDLE = 76, ///< Enumerator for ::urPlatformCreateWithNativeHandle
4771-
UR_FUNCTION_GET_LAST_RESULT = 77, ///< Enumerator for ::urGetLastResult
47724789
UR_FUNCTION_PROGRAM_CREATE_WITH_IL = 78, ///< Enumerator for ::urProgramCreateWithIL
47734790
UR_FUNCTION_PROGRAM_CREATE_WITH_BINARY = 79, ///< Enumerator for ::urProgramCreateWithBinary
47744791
UR_FUNCTION_PROGRAM_BUILD = 80, ///< Enumerator for ::urProgramBuild
@@ -4838,6 +4855,7 @@ typedef enum ur_function_t {
48384855
UR_FUNCTION_BINDLESS_IMAGES_DESTROY_EXTERNAL_SEMAPHORE_EXP = 147, ///< Enumerator for ::urBindlessImagesDestroyExternalSemaphoreExp
48394856
UR_FUNCTION_BINDLESS_IMAGES_WAIT_EXTERNAL_SEMAPHORE_EXP = 148, ///< Enumerator for ::urBindlessImagesWaitExternalSemaphoreExp
48404857
UR_FUNCTION_BINDLESS_IMAGES_SIGNAL_EXTERNAL_SEMAPHORE_EXP = 149, ///< Enumerator for ::urBindlessImagesSignalExternalSemaphoreExp
4858+
UR_FUNCTION_PLATFORM_GET_LAST_ERROR = 150, ///< Enumerator for ::urPlatformGetLastError
48414859
/// @cond
48424860
UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
48434861
/// @endcond
@@ -6951,6 +6969,16 @@ typedef struct ur_platform_create_with_native_handle_params_t {
69516969
ur_platform_handle_t **pphPlatform;
69526970
} ur_platform_create_with_native_handle_params_t;
69536971

6972+
///////////////////////////////////////////////////////////////////////////////
6973+
/// @brief Function parameters for urPlatformGetLastError
6974+
/// @details Each entry is a pointer to the parameter passed to the function;
6975+
/// allowing the callback the ability to modify the parameter's value
6976+
typedef struct ur_platform_get_last_error_params_t {
6977+
ur_platform_handle_t *phPlatform;
6978+
const char ***pppMessage;
6979+
int32_t **ppError;
6980+
} ur_platform_get_last_error_params_t;
6981+
69546982
///////////////////////////////////////////////////////////////////////////////
69556983
/// @brief Function parameters for urPlatformGetApiVersion
69566984
/// @details Each entry is a pointer to the parameter passed to the function;
@@ -8486,15 +8514,6 @@ typedef struct ur_init_params_t {
84868514
ur_device_init_flags_t *pdevice_flags;
84878515
} ur_init_params_t;
84888516

8489-
///////////////////////////////////////////////////////////////////////////////
8490-
/// @brief Function parameters for urGetLastResult
8491-
/// @details Each entry is a pointer to the parameter passed to the function;
8492-
/// allowing the callback the ability to modify the parameter's value
8493-
typedef struct ur_get_last_result_params_t {
8494-
ur_platform_handle_t *phPlatform;
8495-
const char ***pppMessage;
8496-
} ur_get_last_result_params_t;
8497-
84988517
///////////////////////////////////////////////////////////////////////////////
84998518
/// @brief Function parameters for urTearDown
85008519
/// @details Each entry is a pointer to the parameter passed to the function;

‎include/ur_ddi.h

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,13 @@ typedef ur_result_t(UR_APICALL *ur_pfnPlatformCreateWithNativeHandle_t)(
5050
const ur_platform_native_properties_t *,
5151
ur_platform_handle_t *);
5252

53+
///////////////////////////////////////////////////////////////////////////////
54+
/// @brief Function-pointer for urPlatformGetLastError
55+
typedef ur_result_t(UR_APICALL *ur_pfnPlatformGetLastError_t)(
56+
ur_platform_handle_t,
57+
const char **,
58+
int32_t *);
59+
5360
///////////////////////////////////////////////////////////////////////////////
5461
/// @brief Function-pointer for urPlatformGetApiVersion
5562
typedef ur_result_t(UR_APICALL *ur_pfnPlatformGetApiVersion_t)(
@@ -70,6 +77,7 @@ typedef struct ur_platform_dditable_t {
7077
ur_pfnPlatformGetInfo_t pfnGetInfo;
7178
ur_pfnPlatformGetNativeHandle_t pfnGetNativeHandle;
7279
ur_pfnPlatformCreateWithNativeHandle_t pfnCreateWithNativeHandle;
80+
ur_pfnPlatformGetLastError_t pfnGetLastError;
7381
ur_pfnPlatformGetApiVersion_t pfnGetApiVersion;
7482
ur_pfnPlatformGetBackendOption_t pfnGetBackendOption;
7583
} ur_platform_dditable_t;
@@ -1664,12 +1672,6 @@ typedef ur_result_t(UR_APICALL *ur_pfnGetCommandBufferExpProcAddrTable_t)(
16641672
typedef ur_result_t(UR_APICALL *ur_pfnInit_t)(
16651673
ur_device_init_flags_t);
16661674

1667-
///////////////////////////////////////////////////////////////////////////////
1668-
/// @brief Function-pointer for urGetLastResult
1669-
typedef ur_result_t(UR_APICALL *ur_pfnGetLastResult_t)(
1670-
ur_platform_handle_t,
1671-
const char **);
1672-
16731675
///////////////////////////////////////////////////////////////////////////////
16741676
/// @brief Function-pointer for urTearDown
16751677
typedef ur_result_t(UR_APICALL *ur_pfnTearDown_t)(
@@ -1679,7 +1681,6 @@ typedef ur_result_t(UR_APICALL *ur_pfnTearDown_t)(
16791681
/// @brief Table of Global functions pointers
16801682
typedef struct ur_global_dditable_t {
16811683
ur_pfnInit_t pfnInit;
1682-
ur_pfnGetLastResult_t pfnGetLastResult;
16831684
ur_pfnTearDown_t pfnTearDown;
16841685
} ur_global_dditable_t;
16851686

‎scripts/core/platform.yml

Lines changed: 40 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -222,33 +222,54 @@ returns:
222222
- "If `pFrontendOption` is not a valid frontend option."
223223
--- #--------------------------------------------------------------------------
224224
type: function
225-
desc: "Retrieve string representation of the underlying adapter specific result
226-
reported by the the last API that returned UR_RESULT_ADAPTER_SPECIFIC.
227-
Allows for an adapter independent way to return an adapter
228-
specific result."
229-
class: $x
230-
name: GetLastResult
225+
desc: "Get the last adapter specific error."
226+
details: |
227+
To be used after another entry-point has returned
228+
$X_RESULT_ERROR_ADAPTER_SPECIFIC in order to retrieve a message describing
229+
the circumstances of the underlying driver error and the error code
230+
returned by the failed driver entry-point.
231+
232+
* Implementations *must* store the message and error code in thread-local
233+
storage prior to returning $X_RESULT_ERROR_ADAPTER_SPECIFIC.
234+
235+
* The message and error code storage is will only be valid if a previously
236+
called entry-point returned $X_RESULT_ERROR_ADAPTER_SPECIFIC.
237+
238+
* The memory pointed to by the C string returned in `ppMessage` is owned by
239+
the adapter and *must* be null terminated.
240+
241+
* The application *may* call this function from simultaneous threads.
242+
243+
* The implementation of this function *should* be lock-free.
244+
245+
Example usage:
246+
247+
```cpp
248+
if ($xQueueCreate(hContext, hDevice, nullptr, &hQueue) ==
249+
$X_RESULT_ERROR_ADAPTER_SPECIFIC) {
250+
const char* pMessage;
251+
int32_t error;
252+
$xPlatformGetLastError(hPlatform, &pMessage, &error);
253+
}
254+
```
255+
class: $xPlatform
256+
name: GetLastError
231257
decl: static
232258
ordinal: "0"
233-
details:
234-
- "The string returned via the ppMessage is a NULL terminated C style string."
235-
- "The string returned via the ppMessage is thread local."
236-
- "The entry point will return UR_RESULT_SUCCESS if the result being
237-
reported is to be considered a warning. Any other result code returned
238-
indicates that the adapter specific result is an error."
239-
- "The memory in the string returned via the ppMessage is owned by the
240-
adapter."
241-
- "The application may call this function from simultaneous
242-
threads."
243-
- "The implementation of this function should be lock-free."
244259
params:
245260
- type: $x_platform_handle_t
246261
name: hPlatform
247262
desc: "[in] handle of the platform instance"
248263
- type: const char**
249264
name: ppMessage
250-
desc: "[out] pointer to a string containing adapter specific result
251-
in string representation."
265+
desc: >
266+
[out] pointer to a C string where the adapter specific error message
267+
will be stored.
268+
- type: int32_t*
269+
name: pError
270+
desc: >
271+
[out] pointer to an integer where the adapter specific error code
272+
will be stored.
252273
--- #--------------------------------------------------------------------------
253274
type: enum
254275
desc: "Identifies native backend adapters"

‎scripts/core/registry.yml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -235,9 +235,6 @@ etors:
235235
- name: PLATFORM_CREATE_WITH_NATIVE_HANDLE
236236
desc: Enumerator for $xPlatformCreateWithNativeHandle
237237
value: '76'
238-
- name: GET_LAST_RESULT
239-
desc: Enumerator for $xGetLastResult
240-
value: '77'
241238
- name: PROGRAM_CREATE_WITH_IL
242239
desc: Enumerator for $xProgramCreateWithIL
243240
value: '78'
@@ -445,3 +442,6 @@ etors:
445442
- name: BINDLESS_IMAGES_SIGNAL_EXTERNAL_SEMAPHORE_EXP
446443
desc: Enumerator for $xBindlessImagesSignalExternalSemaphoreExp
447444
value: '149'
445+
- name: PLATFORM_GET_LAST_ERROR
446+
desc: Enumerator for $xPlatformGetLastError
447+
value: '150'

‎source/adapters/null/ur_nullddi.cpp

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -219,19 +219,22 @@ __urdlllocal ur_result_t UR_APICALL urPlatformGetBackendOption(
219219
}
220220

221221
///////////////////////////////////////////////////////////////////////////////
222-
/// @brief Intercept function for urGetLastResult
223-
__urdlllocal ur_result_t UR_APICALL urGetLastResult(
222+
/// @brief Intercept function for urPlatformGetLastError
223+
__urdlllocal ur_result_t UR_APICALL urPlatformGetLastError(
224224
ur_platform_handle_t hPlatform, ///< [in] handle of the platform instance
225225
const char **
226-
ppMessage ///< [out] pointer to a string containing adapter specific result in string
227-
///< representation.
226+
ppMessage, ///< [out] pointer to a C string where the adapter specific error message
227+
///< will be stored.
228+
int32_t *
229+
pError ///< [out] pointer to an integer where the adapter specific error code will
230+
///< be stored.
228231
) try {
229232
ur_result_t result = UR_RESULT_SUCCESS;
230233

231234
// if the driver has created a custom function, then call it instead of using the generic path
232-
auto pfnGetLastResult = d_context.urDdiTable.Global.pfnGetLastResult;
233-
if (nullptr != pfnGetLastResult) {
234-
result = pfnGetLastResult(hPlatform, ppMessage);
235+
auto pfnGetLastError = d_context.urDdiTable.Platform.pfnGetLastError;
236+
if (nullptr != pfnGetLastError) {
237+
result = pfnGetLastError(hPlatform, ppMessage, pError);
235238
} else {
236239
// generic implementation
237240
}
@@ -4327,8 +4330,6 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetGlobalProcAddrTable(
43274330

43284331
pDdiTable->pfnInit = driver::urInit;
43294332

4330-
pDdiTable->pfnGetLastResult = driver::urGetLastResult;
4331-
43324333
pDdiTable->pfnTearDown = driver::urTearDown;
43334334

43344335
return result;
@@ -4768,6 +4769,8 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetPlatformProcAddrTable(
47684769
pDdiTable->pfnCreateWithNativeHandle =
47694770
driver::urPlatformCreateWithNativeHandle;
47704771

4772+
pDdiTable->pfnGetLastError = driver::urPlatformGetLastError;
4773+
47714774
pDdiTable->pfnGetApiVersion = driver::urPlatformGetApiVersion;
47724775

47734776
pDdiTable->pfnGetBackendOption = driver::urPlatformGetBackendOption;

0 commit comments

Comments
 (0)