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.

Author: martygrant

include/ur_api.h

@@ -230,6 +230,8 @@ typedef enum ur_function_t {
     UR_FUNCTION_COMMAND_BUFFER_UPDATE_SIGNAL_EVENT_EXP = 243,             ///< Enumerator for ::urCommandBufferUpdateSignalEventExp
     UR_FUNCTION_COMMAND_BUFFER_UPDATE_WAIT_EVENTS_EXP = 244,              ///< Enumerator for ::urCommandBufferUpdateWaitEventsExp
     UR_FUNCTION_BINDLESS_IMAGES_MAP_EXTERNAL_LINEAR_MEMORY_EXP = 245,     ///< Enumerator for ::urBindlessImagesMapExternalLinearMemoryExp
+    UR_FUNCTION_SET_LOGGER_CALLBACK = 246,                                ///< Enumerator for ::urSetLoggerCallback
+    UR_FUNCTION_SET_LOGGER_CALLBACK_LEVEL = 247,                          ///< Enumerator for ::urSetLoggerCallbackLevel
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -1025,6 +1027,70 @@ typedef enum ur_adapter_backend_t {
 
 } ur_adapter_backend_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Minimum level of messages to be processed by the logger.
+typedef enum ur_logger_level_t {
+    UR_LOGGER_LEVEL_DEBUG = 0, ///< Debugging messages used for development purposes.
+    UR_LOGGER_LEVEL_INFO = 1,  ///< General messages not related to debugging, warnings or errors.
+    UR_LOGGER_LEVEL_WARN = 2,  ///< Used to warn users about potential problems.
+    UR_LOGGER_LEVEL_ERR = 3,   ///< Used when an error has occurred.
+    UR_LOGGER_LEVEL_QUIET = 4, ///< Restrict logger processing any messages.
+    /// @cond
+    UR_LOGGER_LEVEL_FORCE_UINT32 = 0x7fffffff
+    /// @endcond
+
+} ur_logger_level_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Callback function to retrieve output from the logger.
+typedef void (*ur_logger_output_callback_t)(
+    ur_logger_level_t level, ///< [out] Minimum level of messages to be processed by the logger.
+    const char *pLoggerMsg,  ///< [in][out] pointer to data to be passed to callback
+    void *pUserData          ///< [in][out] pointer to data to be passed to callback
+);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Set a callback function for use by the logger to retrieve logging output.
+///        It is a requirement that the callback function is thread safe and the
+///        creator of the function will be responsible for this.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hAdapter`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pfnLoggerCallback`
+///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+///         + `::UR_LOGGER_LEVEL_QUIET < level`
+UR_APIEXPORT ur_result_t UR_APICALL
+urSetLoggerCallback(
+    ur_adapter_handle_t hAdapter,                  ///< [in] handle of the adapter
+    ur_logger_output_callback_t pfnLoggerCallback, ///< [in] Function pointer to callback from the logger.
+    void *pUserData,                               ///< [in][out][optional] pointer to data to be passed to callback
+    ur_logger_level_t level                        ///< [in] logging level
+);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Set the minimum logging level for the logger Callback function.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hAdapter`
+///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+///         + `::UR_LOGGER_LEVEL_QUIET < level`
+UR_APIEXPORT ur_result_t UR_APICALL
+urSetLoggerCallbackLevel(
+    ur_adapter_handle_t hAdapter, ///< [in] handle of the adapter
+    ur_logger_level_t level       ///< [in] logging level
+);
+
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
@@ -10997,6 +11063,26 @@ typedef struct ur_adapter_get_info_params_t {
     size_t **ppPropSizeRet;
 } ur_adapter_get_info_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urSetLoggerCallback
+/// @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_set_logger_callback_params_t {
+    ur_adapter_handle_t *phAdapter;
+    ur_logger_output_callback_t *ppfnLoggerCallback;
+    void **ppUserData;
+    ur_logger_level_t *plevel;
+} ur_set_logger_callback_params_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urSetLoggerCallbackLevel
+/// @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_set_logger_callback_level_params_t {
+    ur_adapter_handle_t *phAdapter;
+    ur_logger_level_t *plevel;
+} ur_set_logger_callback_level_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urEnqueueKernelLaunch
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_api_funcs.def

@@ -101,6 +101,8 @@ _UR_API(urAdapterRelease)
 _UR_API(urAdapterRetain)
 _UR_API(urAdapterGetLastError)
 _UR_API(urAdapterGetInfo)
+_UR_API(urSetLoggerCallback)
+_UR_API(urSetLoggerCallbackLevel)
 _UR_API(urEnqueueKernelLaunch)
 _UR_API(urEnqueueEventsWait)
 _UR_API(urEnqueueEventsWaitWithBarrier)

include/ur_ddi.h

@@ -1038,6 +1038,20 @@ typedef ur_result_t(UR_APICALL *ur_pfnAdapterGetInfo_t)(
     void *,
     size_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urSetLoggerCallback
+typedef ur_result_t(UR_APICALL *ur_pfnSetLoggerCallback_t)(
+    ur_adapter_handle_t,
+    ur_logger_output_callback_t,
+    void *,
+    ur_logger_level_t);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urSetLoggerCallbackLevel
+typedef ur_result_t(UR_APICALL *ur_pfnSetLoggerCallbackLevel_t)(
+    ur_adapter_handle_t,
+    ur_logger_level_t);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Table of Global functions pointers
 typedef struct ur_global_dditable_t {
@@ -1046,6 +1060,8 @@ typedef struct ur_global_dditable_t {
     ur_pfnAdapterRetain_t pfnAdapterRetain;
     ur_pfnAdapterGetLastError_t pfnAdapterGetLastError;
     ur_pfnAdapterGetInfo_t pfnAdapterGetInfo;
+    ur_pfnSetLoggerCallback_t pfnSetLoggerCallback;
+    ur_pfnSetLoggerCallbackLevel_t pfnSetLoggerCallbackLevel;
 } ur_global_dditable_t;
 
 ///////////////////////////////////////////////////////////////////////////////

include/ur_print.h

@@ -114,6 +114,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintAdapterInfo(enum ur_adapter_info_t va
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintAdapterBackend(enum ur_adapter_backend_t value, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_logger_level_t enum
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintLoggerLevel(enum ur_logger_level_t value, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_platform_info_t enum
 /// @returns
@@ -1826,6 +1834,22 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintAdapterGetLastErrorParams(const struc
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintAdapterGetInfoParams(const struct ur_adapter_get_info_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_set_logger_callback_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintSetLoggerCallbackParams(const struct ur_set_logger_callback_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_set_logger_callback_level_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintSetLoggerCallbackLevelParams(const struct ur_set_logger_callback_level_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_enqueue_kernel_launch_params_t struct
 /// @returns

include/ur_print.hpp

@@ -230,6 +230,7 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_loader_config_info_t v
 inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_code_location_t params);
 inline std::ostream &operator<<(std::ostream &os, enum ur_adapter_info_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_adapter_backend_t value);
+inline std::ostream &operator<<(std::ostream &os, enum ur_logger_level_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_platform_info_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_api_version_t value);
 inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_platform_native_properties_t params);
@@ -954,6 +955,12 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
     case UR_FUNCTION_BINDLESS_IMAGES_MAP_EXTERNAL_LINEAR_MEMORY_EXP:
         os << "UR_FUNCTION_BINDLESS_IMAGES_MAP_EXTERNAL_LINEAR_MEMORY_EXP";
         break;
+    case UR_FUNCTION_SET_LOGGER_CALLBACK:
+        os << "UR_FUNCTION_SET_LOGGER_CALLBACK";
+        break;
+    case UR_FUNCTION_SET_LOGGER_CALLBACK_LEVEL:
+        os << "UR_FUNCTION_SET_LOGGER_CALLBACK_LEVEL";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -1981,6 +1988,33 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_adapter_backend_t valu
     return os;
 }
 ///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_logger_level_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, enum ur_logger_level_t value) {
+    switch (value) {
+    case UR_LOGGER_LEVEL_DEBUG:
+        os << "UR_LOGGER_LEVEL_DEBUG";
+        break;
+    case UR_LOGGER_LEVEL_INFO:
+        os << "UR_LOGGER_LEVEL_INFO";
+        break;
+    case UR_LOGGER_LEVEL_WARN:
+        os << "UR_LOGGER_LEVEL_WARN";
+        break;
+    case UR_LOGGER_LEVEL_ERR:
+        os << "UR_LOGGER_LEVEL_ERR";
+        break;
+    case UR_LOGGER_LEVEL_QUIET:
+        os << "UR_LOGGER_LEVEL_QUIET";
+        break;
+    default:
+        os << "unknown enumerator";
+        break;
+    }
+    return os;
+}
+///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_platform_info_t type
 /// @returns
 ///     std::ostream &
@@ -13021,6 +13055,56 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
     return os;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_set_logger_callback_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_set_logger_callback_params_t *params) {
+
+    os << ".hAdapter = ";
+
+    ur::details::printPtr(os,
+                          *(params->phAdapter));
+
+    os << ", ";
+    os << ".pfnLoggerCallback = ";
+
+    os << reinterpret_cast<void *>(
+        *(params->ppfnLoggerCallback));
+
+    os << ", ";
+    os << ".pUserData = ";
+
+    ur::details::printPtr(os,
+                          *(params->ppUserData));
+
+    os << ", ";
+    os << ".level = ";
+
+    os << *(params->plevel);
+
+    return os;
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_set_logger_callback_level_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_set_logger_callback_level_params_t *params) {
+
+    os << ".hAdapter = ";
+
+    ur::details::printPtr(os,
+                          *(params->phAdapter));
+
+    os << ", ";
+    os << ".level = ";
+
+    os << *(params->plevel);
+
+    return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_enqueue_kernel_launch_params_t type
 /// @returns
@@ -18317,6 +18401,12 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os, ur_function_
     case UR_FUNCTION_ADAPTER_GET_INFO: {
         os << (const struct ur_adapter_get_info_params_t *)params;
     } break;
+    case UR_FUNCTION_SET_LOGGER_CALLBACK: {
+        os << (const struct ur_set_logger_callback_params_t *)params;
+    } break;
+    case UR_FUNCTION_SET_LOGGER_CALLBACK_LEVEL: {
+        os << (const struct ur_set_logger_callback_level_params_t *)params;
+    } break;
     case UR_FUNCTION_ENQUEUE_KERNEL_LAUNCH: {
         os << (const struct ur_enqueue_kernel_launch_params_t *)params;
     } break;

scripts/core/INTRO.rst

@@ -202,9 +202,9 @@ By default, no messages are printed.
 
 By default, there is a guarantee that *error* messages are flushed immediately. One can change this behavior to flush on lower-level messages.
 
-Loggers redirect messages to *stdout*, *stderr*, or a file (default: *stderr*).
+Loggers redirect messages to *stdout*, *stderr*, a file or a user configurable callback function (default: *stderr*).
 
-All of these logging options can be set with **UR_LOG_LOADER** and **UR_LOG_NULL** environment variables described in the **Environment Variables** section below.
+All of these logging options (except the callback) can be set with **UR_LOG_LOADER** and **UR_LOG_NULL** environment variables described in the **Environment Variables** section below.
 Both of these environment variables have the same syntax for setting logger options:
 
   "[level:debug|info|warning|error];[flush:<debug|info|warning|error>];[output:stdout|stderr|file,<path>]"
@@ -232,6 +232,10 @@ An example of an environment variable for setting up the null adapter library wi
 
   UR_LOG_NULL="level:warning;output:stdout"
 
+Logging callback
+^^^^^^^^^^^^^^^^^^^^^
+An API is available to configure the logging callback function :ref:`urSetLoggerCallback`. Additionally, the logging level can be set using :ref:`urSetLoggerCallbackLevel`.
+
 Adapter Discovery
 ---------------------
 UR is capable of discovering adapter libraries in the following ways in the listed order: