Skip to content

Commit 7ebe716

Browse files
martygrantkbenzie
martygrant
and
kbenzie
committed
Added new output sink to the logger which is a user configurable callback function.
Configurable through two new entry points with adapter implementations: urAdapterSetLoggerCallback() and urAdapterSetLoggerCallbackLevel(). Moved logger::level enum to the spec, named ur_logger_level_t. Added new unit test suite for these entry points. Co-authored-by: Kenneth Benzie (Benie) <[email protected]>
1 parent 7e38d0a commit 7ebe716

39 files changed

+1654
-378
lines changed

‎include/ur_api.h‎

Lines changed: 127 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -381,54 +381,58 @@ typedef enum ur_function_t {
381381
UR_FUNCTION_COMMAND_BUFFER_GET_INFO_EXP = 221,
382382
/// Enumerator for ::urEnqueueTimestampRecordingExp
383383
UR_FUNCTION_ENQUEUE_TIMESTAMP_RECORDING_EXP = 223,
384-
/// Enumerator for ::urEnqueueKernelLaunchCustomExp
385-
UR_FUNCTION_ENQUEUE_KERNEL_LAUNCH_CUSTOM_EXP = 224,
384+
/// Enumerator for ::urLoaderConfigSetMockingEnabled
385+
UR_FUNCTION_LOADER_CONFIG_SET_MOCKING_ENABLED = 224,
386+
/// Enumerator for ::urAdapterSetLoggerCallback
387+
UR_FUNCTION_ADAPTER_SET_LOGGER_CALLBACK = 225,
388+
/// Enumerator for ::urAdapterSetLoggerCallbackLevel
389+
UR_FUNCTION_ADAPTER_SET_LOGGER_CALLBACK_LEVEL = 226,
386390
/// Enumerator for ::urKernelGetSuggestedLocalWorkSize
387-
UR_FUNCTION_KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE = 225,
391+
UR_FUNCTION_KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE = 227,
388392
/// Enumerator for ::urBindlessImagesImportExternalMemoryExp
389-
UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_MEMORY_EXP = 226,
390-
/// Enumerator for ::urBindlessImagesImportExternalSemaphoreExp
391-
UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_SEMAPHORE_EXP = 227,
392-
/// Enumerator for ::urEnqueueNativeCommandExp
393-
UR_FUNCTION_ENQUEUE_NATIVE_COMMAND_EXP = 228,
394-
/// Enumerator for ::urLoaderConfigSetMockingEnabled
395-
UR_FUNCTION_LOADER_CONFIG_SET_MOCKING_ENABLED = 229,
393+
UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_MEMORY_EXP = 228,
394+
/// Enumerator for ::urBindlessImagesMapExternalLinearMemoryExp
395+
UR_FUNCTION_BINDLESS_IMAGES_MAP_EXTERNAL_LINEAR_MEMORY_EXP = 229,
396396
/// Enumerator for ::urBindlessImagesReleaseExternalMemoryExp
397397
UR_FUNCTION_BINDLESS_IMAGES_RELEASE_EXTERNAL_MEMORY_EXP = 230,
398+
/// Enumerator for ::urBindlessImagesImportExternalSemaphoreExp
399+
UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_SEMAPHORE_EXP = 231,
398400
/// Enumerator for ::urCommandBufferAppendUSMMemcpyExp
399-
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_MEMCPY_EXP = 231,
401+
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_MEMCPY_EXP = 232,
400402
/// Enumerator for ::urCommandBufferAppendUSMFillExp
401-
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_FILL_EXP = 232,
403+
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_FILL_EXP = 233,
402404
/// Enumerator for ::urCommandBufferAppendMemBufferCopyExp
403-
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_COPY_EXP = 233,
405+
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_COPY_EXP = 234,
404406
/// Enumerator for ::urCommandBufferAppendMemBufferWriteExp
405-
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_WRITE_EXP = 234,
407+
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_WRITE_EXP = 235,
406408
/// Enumerator for ::urCommandBufferAppendMemBufferReadExp
407-
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_READ_EXP = 235,
409+
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_READ_EXP = 236,
408410
/// Enumerator for ::urCommandBufferAppendMemBufferCopyRectExp
409-
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_COPY_RECT_EXP = 236,
411+
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_COPY_RECT_EXP = 237,
410412
/// Enumerator for ::urCommandBufferAppendMemBufferWriteRectExp
411-
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_WRITE_RECT_EXP = 237,
413+
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_WRITE_RECT_EXP = 238,
412414
/// Enumerator for ::urCommandBufferAppendMemBufferReadRectExp
413-
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_READ_RECT_EXP = 238,
415+
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_READ_RECT_EXP = 239,
414416
/// Enumerator for ::urCommandBufferAppendMemBufferFillExp
415-
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_FILL_EXP = 239,
417+
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_FILL_EXP = 240,
416418
/// Enumerator for ::urCommandBufferAppendUSMPrefetchExp
417-
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP = 240,
419+
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP = 241,
418420
/// Enumerator for ::urCommandBufferAppendUSMAdviseExp
419-
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 241,
421+
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 242,
420422
/// Enumerator for ::urCommandBufferEnqueueExp
421-
UR_FUNCTION_COMMAND_BUFFER_ENQUEUE_EXP = 242,
423+
UR_FUNCTION_COMMAND_BUFFER_ENQUEUE_EXP = 243,
422424
/// Enumerator for ::urCommandBufferUpdateSignalEventExp
423-
UR_FUNCTION_COMMAND_BUFFER_UPDATE_SIGNAL_EVENT_EXP = 243,
425+
UR_FUNCTION_COMMAND_BUFFER_UPDATE_SIGNAL_EVENT_EXP = 244,
424426
/// Enumerator for ::urCommandBufferUpdateWaitEventsExp
425-
UR_FUNCTION_COMMAND_BUFFER_UPDATE_WAIT_EVENTS_EXP = 244,
426-
/// Enumerator for ::urBindlessImagesMapExternalLinearMemoryExp
427-
UR_FUNCTION_BINDLESS_IMAGES_MAP_EXTERNAL_LINEAR_MEMORY_EXP = 245,
428-
/// Enumerator for ::urEnqueueEventsWaitWithBarrierExt
429-
UR_FUNCTION_ENQUEUE_EVENTS_WAIT_WITH_BARRIER_EXT = 246,
427+
UR_FUNCTION_COMMAND_BUFFER_UPDATE_WAIT_EVENTS_EXP = 245,
428+
/// Enumerator for ::urEnqueueKernelLaunchCustomExp
429+
UR_FUNCTION_ENQUEUE_KERNEL_LAUNCH_CUSTOM_EXP = 246,
430+
/// Enumerator for ::urEnqueueNativeCommandExp
431+
UR_FUNCTION_ENQUEUE_NATIVE_COMMAND_EXP = 247,
430432
/// Enumerator for ::urPhysicalMemGetInfo
431-
UR_FUNCTION_PHYSICAL_MEM_GET_INFO = 249,
433+
UR_FUNCTION_PHYSICAL_MEM_GET_INFO = 248,
434+
/// Enumerator for ::urEnqueueEventsWaitWithBarrierExt
435+
UR_FUNCTION_ENQUEUE_EVENTS_WAIT_WITH_BARRIER_EXT = 249,
432436
/// @cond
433437
UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
434438
/// @endcond
@@ -1390,6 +1394,80 @@ typedef enum ur_adapter_backend_t {
13901394

13911395
} ur_adapter_backend_t;
13921396

1397+
///////////////////////////////////////////////////////////////////////////////
1398+
/// @brief Minimum level of messages to be processed by the logger.
1399+
typedef enum ur_logger_level_t {
1400+
/// Debugging messages used for development purposes.
1401+
UR_LOGGER_LEVEL_DEBUG = 0,
1402+
/// General messages not related to debugging, warnings or errors.
1403+
UR_LOGGER_LEVEL_INFO = 1,
1404+
/// Used to warn users about potential problems.
1405+
UR_LOGGER_LEVEL_WARN = 2,
1406+
/// Used when an error has occurred.
1407+
UR_LOGGER_LEVEL_ERROR = 3,
1408+
/// Restrict logger processing any messages.
1409+
UR_LOGGER_LEVEL_QUIET = 4,
1410+
/// @cond
1411+
UR_LOGGER_LEVEL_FORCE_UINT32 = 0x7fffffff
1412+
/// @endcond
1413+
1414+
} ur_logger_level_t;
1415+
1416+
///////////////////////////////////////////////////////////////////////////////
1417+
/// @brief Callback function to retrieve output from the logger.
1418+
typedef void (*ur_logger_callback_t)(
1419+
/// [out] Minimum level of messages to be processed by the logger.
1420+
ur_logger_level_t level,
1421+
/// [in][out] pointer to data to be passed to callback
1422+
const char *pLoggerMsg,
1423+
/// [in][out] pointer to data to be passed to callback
1424+
void *pUserData);
1425+
1426+
///////////////////////////////////////////////////////////////////////////////
1427+
/// @brief Set a callback function for use by the logger to retrieve logging
1428+
/// output.
1429+
/// It is a requirement that the callback function is thread safe and the
1430+
/// creator of the function will be responsible for this.
1431+
///
1432+
/// @returns
1433+
/// - ::UR_RESULT_SUCCESS
1434+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
1435+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
1436+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
1437+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
1438+
/// + `NULL == hAdapter`
1439+
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
1440+
/// + `NULL == pfnLoggerCallback`
1441+
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
1442+
/// + `::UR_LOGGER_LEVEL_QUIET < level`
1443+
UR_APIEXPORT ur_result_t UR_APICALL urAdapterSetLoggerCallback(
1444+
/// [in] handle of the adapter
1445+
ur_adapter_handle_t hAdapter,
1446+
/// [in] Function pointer to callback from the logger.
1447+
ur_logger_callback_t pfnLoggerCallback,
1448+
/// [in][out][optional] pointer to data to be passed to callback
1449+
void *pUserData,
1450+
/// [in] logging level
1451+
ur_logger_level_t level);
1452+
1453+
///////////////////////////////////////////////////////////////////////////////
1454+
/// @brief Set the minimum logging level for the logger Callback function.
1455+
///
1456+
/// @returns
1457+
/// - ::UR_RESULT_SUCCESS
1458+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
1459+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
1460+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
1461+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
1462+
/// + `NULL == hAdapter`
1463+
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
1464+
/// + `::UR_LOGGER_LEVEL_QUIET < level`
1465+
UR_APIEXPORT ur_result_t UR_APICALL urAdapterSetLoggerCallbackLevel(
1466+
/// [in] handle of the adapter
1467+
ur_adapter_handle_t hAdapter,
1468+
/// [in] logging level
1469+
ur_logger_level_t level);
1470+
13931471
#if !defined(__GNUC__)
13941472
#pragma endregion
13951473
#endif
@@ -12136,6 +12214,26 @@ typedef struct ur_loader_config_set_mocking_enabled_params_t {
1213612214
ur_bool_t *penable;
1213712215
} ur_loader_config_set_mocking_enabled_params_t;
1213812216

12217+
///////////////////////////////////////////////////////////////////////////////
12218+
/// @brief Function parameters for urAdapterSetLoggerCallback
12219+
/// @details Each entry is a pointer to the parameter passed to the function;
12220+
/// allowing the callback the ability to modify the parameter's value
12221+
typedef struct ur_adapter_set_logger_callback_params_t {
12222+
ur_adapter_handle_t *phAdapter;
12223+
ur_logger_callback_t *ppfnLoggerCallback;
12224+
void **ppUserData;
12225+
ur_logger_level_t *plevel;
12226+
} ur_adapter_set_logger_callback_params_t;
12227+
12228+
///////////////////////////////////////////////////////////////////////////////
12229+
/// @brief Function parameters for urAdapterSetLoggerCallbackLevel
12230+
/// @details Each entry is a pointer to the parameter passed to the function;
12231+
/// allowing the callback the ability to modify the parameter's value
12232+
typedef struct ur_adapter_set_logger_callback_level_params_t {
12233+
ur_adapter_handle_t *phAdapter;
12234+
ur_logger_level_t *plevel;
12235+
} ur_adapter_set_logger_callback_level_params_t;
12236+
1213912237
///////////////////////////////////////////////////////////////////////////////
1214012238
/// @brief Function parameters for urPlatformGet
1214112239
/// @details Each entry is a pointer to the parameter passed to the function;

‎include/ur_api_funcs.def‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@
1717

1818
// Auto-generated file, do not edit.
1919

20+
_UR_API(urAdapterSetLoggerCallback)
21+
_UR_API(urAdapterSetLoggerCallbackLevel)
2022
_UR_API(urPlatformGet)
2123
_UR_API(urPlatformGetInfo)
2224
_UR_API(urPlatformGetNativeHandle)

‎include/ur_ddi.h‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,43 @@
2323
extern "C" {
2424
#endif
2525

26+
///////////////////////////////////////////////////////////////////////////////
27+
/// @brief Function-pointer for urAdapterSetLoggerCallback
28+
typedef ur_result_t(UR_APICALL *ur_pfnAdapterSetLoggerCallback_t)(
29+
ur_adapter_handle_t, ur_logger_callback_t, void *, ur_logger_level_t);
30+
31+
///////////////////////////////////////////////////////////////////////////////
32+
/// @brief Function-pointer for urAdapterSetLoggerCallbackLevel
33+
typedef ur_result_t(UR_APICALL *ur_pfnAdapterSetLoggerCallbackLevel_t)(
34+
ur_adapter_handle_t, ur_logger_level_t);
35+
36+
///////////////////////////////////////////////////////////////////////////////
37+
/// @brief Table of Adapter functions pointers
38+
typedef struct ur_adapter_dditable_t {
39+
ur_pfnAdapterSetLoggerCallback_t pfnSetLoggerCallback;
40+
ur_pfnAdapterSetLoggerCallbackLevel_t pfnSetLoggerCallbackLevel;
41+
} ur_adapter_dditable_t;
42+
43+
///////////////////////////////////////////////////////////////////////////////
44+
/// @brief Exported function for filling application's Adapter table
45+
/// with current process' addresses
46+
///
47+
/// @returns
48+
/// - ::UR_RESULT_SUCCESS
49+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
50+
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
51+
/// - ::UR_RESULT_ERROR_UNSUPPORTED_VERSION
52+
UR_DLLEXPORT ur_result_t UR_APICALL urGetAdapterProcAddrTable(
53+
/// [in] API version requested
54+
ur_api_version_t version,
55+
/// [in,out] pointer to table of DDI function pointers
56+
ur_adapter_dditable_t *pDdiTable);
57+
58+
///////////////////////////////////////////////////////////////////////////////
59+
/// @brief Function-pointer for urGetAdapterProcAddrTable
60+
typedef ur_result_t(UR_APICALL *ur_pfnGetAdapterProcAddrTable_t)(
61+
ur_api_version_t, ur_adapter_dditable_t *);
62+
2663
///////////////////////////////////////////////////////////////////////////////
2764
/// @brief Function-pointer for urPlatformGet
2865
typedef ur_result_t(UR_APICALL *ur_pfnPlatformGet_t)(ur_adapter_handle_t *,
@@ -1866,6 +1903,7 @@ typedef ur_result_t(UR_APICALL *ur_pfnGetDeviceProcAddrTable_t)(
18661903
///////////////////////////////////////////////////////////////////////////////
18671904
/// @brief Container for all DDI tables
18681905
typedef struct ur_dditable_t {
1906+
ur_adapter_dditable_t Adapter;
18691907
ur_platform_dditable_t Platform;
18701908
ur_context_dditable_t Context;
18711909
ur_event_dditable_t Event;

‎include/ur_print.h‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,16 @@ UR_APIEXPORT ur_result_t UR_APICALL
142142
urPrintAdapterBackend(enum ur_adapter_backend_t value, char *buffer,
143143
const size_t buff_size, size_t *out_size);
144144

145+
///////////////////////////////////////////////////////////////////////////////
146+
/// @brief Print ur_logger_level_t enum
147+
/// @returns
148+
/// - ::UR_RESULT_SUCCESS
149+
/// - ::UR_RESULT_ERROR_INVALID_SIZE
150+
/// - `buff_size < out_size`
151+
UR_APIEXPORT ur_result_t UR_APICALL
152+
urPrintLoggerLevel(enum ur_logger_level_t value, char *buffer,
153+
const size_t buff_size, size_t *out_size);
154+
145155
///////////////////////////////////////////////////////////////////////////////
146156
/// @brief Print ur_platform_info_t enum
147157
/// @returns
@@ -1465,6 +1475,26 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigSetMockingEnabledParams(
14651475
const struct ur_loader_config_set_mocking_enabled_params_t *params,
14661476
char *buffer, const size_t buff_size, size_t *out_size);
14671477

1478+
///////////////////////////////////////////////////////////////////////////////
1479+
/// @brief Print ur_adapter_set_logger_callback_params_t struct
1480+
/// @returns
1481+
/// - ::UR_RESULT_SUCCESS
1482+
/// - ::UR_RESULT_ERROR_INVALID_SIZE
1483+
/// - `buff_size < out_size`
1484+
UR_APIEXPORT ur_result_t UR_APICALL urPrintAdapterSetLoggerCallbackParams(
1485+
const struct ur_adapter_set_logger_callback_params_t *params, char *buffer,
1486+
const size_t buff_size, size_t *out_size);
1487+
1488+
///////////////////////////////////////////////////////////////////////////////
1489+
/// @brief Print ur_adapter_set_logger_callback_level_params_t struct
1490+
/// @returns
1491+
/// - ::UR_RESULT_SUCCESS
1492+
/// - ::UR_RESULT_ERROR_INVALID_SIZE
1493+
/// - `buff_size < out_size`
1494+
UR_APIEXPORT ur_result_t UR_APICALL urPrintAdapterSetLoggerCallbackLevelParams(
1495+
const struct ur_adapter_set_logger_callback_level_params_t *params,
1496+
char *buffer, const size_t buff_size, size_t *out_size);
1497+
14681498
///////////////////////////////////////////////////////////////////////////////
14691499
/// @brief Print ur_platform_get_params_t struct
14701500
/// @returns

0 commit comments

Comments
 (0)